Jouele
Setup
Add the following to the <head> of your page:
<script src="/path/to/
<script src="jouele/
<link rel="stylesheet" type="text/css" href="jouele/jouele.css" />
Basic usage
Every link with a class jouele will automatically become a player for the linked MP3:
<p>
<a href="news.mp3" class="jouele">
Ilya Birman: News
</a>
</p>
Player shows track length only when playback starts. If you want it to be displayed when a page opens, specify if with the data-length attribute:
class="jouele" data-length="9:54"Playlists
To make several tracks on a page play one after another, make them a playlist:
<div class="jouele-playlist">
<p><a href="news.mp3" class="jouele">
Ilya Birman: News
</a></p>
<p><a href="news-remix.mp3" class="jouele">
Ilya Birman: News (Ninth Of Kin Remix)
</a></p>
</div>
To loop a playlist:
class="jouele-playlist" data-repeat="true"
The class jouele-playlist can be used on html or body. This will make all tracks on a page play continuosly.
Controlling playback with the Space key
To make the Space key play and pause the playback, add this to any track or playlist:
class="jouele..." data-space-control="true"The Space key will no longer scroll the page and will control playback. If nothing is playing, pressing Space will continue playback from where it finished (or start the first track on the page). If something is playing, pressing Space will pause it. This is so regardless of where this attribute is used.
To make a specific track play first:
class="jouele..." data-first="true"Changing the look
The player is designed for use on a light background. If you have a dark background, add the class jouele-skin-dark, and the black elemets will become white:
<p>
<a href="news.mp3" class="jouele jouele-skin-dark">
Ilya Birman: News
</a>
</p>
You can use the class on any of the predecessors, and it will apply to all the copies of the player within that predecessor.
In the package, there is a file jouele.skin.css that contains the code for the class jouele-skin-dark. Use it as an example to to create your custom theme and link your CSS to the page after the default one.
Controls
The class jouele-control makes any page element a player’s playback control. For examples, here is how to make a cover art play and pause the track:
<img
src="cover.jpg"
class="jouele-control"
data-type="play-pause"
/>
If there are several players on a page, the controls control the one that was playing previously, or the first one on the page, if nothing was playing before.
With the attribute data-href you can link the control to a particular audio track:
<img
src="cover.jpg"
class="jouele-control"
data-type="play-pause"
data-href="news.mp3"
/>
The link to the file should match exactly the one that is specified in the player.
Using controls, you can build a completely custom player:
If you are using data-href in a control, a separate player, i. e. an a element is not necessary. The control is sufficient for the playback to work.
To make a custom-built player reflect the current playback status, all used controls are dynamically given CSS classes that you can stylise. For example, all elements get a jouele-is-playing class when the music is playing. Here is how this is used to colorise the player above:
.jouele-sample-player {
background: #fff;
}
.jouele-sample-player.jouele-is-playing {
background: #e0e0e0;
}
The following controls are available:
play-pause
Starts or pauses playback on click.
play
Starts playback on click.
pause
Pauses playback on click.
title
A container to display a track’s title.
time-total
A container to display a track’s duration.
time-elapsed
A container to display a track’s elapsed time.
time-remaining
A container to display a track’s remaining time.
time-toggle
A container to display a track’s elapsed time. Switches to remaining time and back on click. If several such controls are linked to the same track, the toggle together.
timeline
Clicking or dragging inside this control are interpreted as seeking to the corresponding track position (horisontally). An elapsed element is supposed to be used inside this element, see next.
elapsed
An element, whose width is dynamically changed to display the played part of the track, in percent. This element is supposed to be put inside the timeline element, so that it would “fill” it during playback.
position
An element, whose left is dynamically changed to display the played part of the track, in percent. This element is supposed to be put inside the timeline element, so that it would move inside it during playback. The width of this element itself is taken into account.
seek
An element to jump to a particular position and to highlight a fragment in text during its playback (there is an example below). If there is an attribute data-to="3:57", then clicking this element will seek the specified time and start playback (by default jumps to zero). If there is only an attribute data-range="13:57...18:19", then clicking this element will seek the beginning of the specified range and start playback. When the track is playing within the specified range, the control gets the class jouele-is-within, whose apperance could be controlled with CSS.
These controls get the following classes depending on the playback status of their linked track:
jouele-is-paused
When the track is paused.
jouele-is-playing
When the track is playing or being buffered.
jouele-is-buffering
When the track is being buffered (the class jouele-is-playing remains).
jouele-is-within
When the track is withing a specified range (for seek controls).
jouele-is-loaded
When the track is loaded and ready to play.
jouele-is-available
When the track hasn’t played or have finished playing, but is definitely available for playback.
jouele-is-unavailable
When playback failed.
Example use of seek control
Let’s say we have a long DJ mix. We mention one of the songs in a text:
<span
class="jouele-control"
data-type="seek"
data-range="13:57…18:19"
>
The Beatles: Yesterday
</span>
When the user clicks this span, the playhead jumps to 13:57 and the playback starts. If the playhead reaches the range 13:57...18:19 during continuous playback, or the user drags it into this range, the span gets the class jouele-is-within so that you can highlight it when this range is playing. So, independently on how the range was reached, by clicking the span or otherwise, if it’s being played, the span is highlighted.
Developers
See GitHub for technical JavaScript API documentation.