The best web audio player on the planet
JavaScript CSS HTML


Jouele is a simple and beautiful audio player for the web.

Project page

Russian translation of the documentation πŸ‡·πŸ‡Ί

Famous 2-step Setup

<!-- Include dependencies that are mandatory for Jouele: jQuery and jPlayer -->
<script src=""></script>
<script src="jquery.jplayer.min.js"></script>

<!-- Include Jouele -->
<script src="jouele.js"></script>
<link href="jouele.css" rel="stylesheet"/>

Basic Usage

Single track

Each link with href attribute and jouele class automatically becomes a player for the linked MP3. For example:

<a href="" class="jouele">Ilya Birman: News</a>


Add jouele-playlist class to the element, which contains links with jouele class, to create a playlist of files corresponding to these link. For example:

<div class="jouele-playlist">
    <p><a href="" class="jouele">The Endgame</a></p>
    <p><a href="" class="jouele">Tastes Like Steel</a></p>
    <p><a href="" class="jouele">Glass</a></p>
    <p><a href="" class="jouele">I Will Always</a></p>

Check dist/example.html to see more examples of usage.

Advanced Features


Adding some data-attributes changes the behavior or appearance of the player (or of the playlist).


Is applied to the playlist.
Type: boolean
Default value: false

Defines whether to repeat the playback of playlist after the last track is finished.


Type: string
Default value: 0

Shows the total length of the track, so that it is displayed immediately without pressing the "play" button. Examples for track of 9 minutes 54 seconds length: data-length="9:54", data-length="954"


Type: boolean
Default value: false

Specifies globally whether to handle pressing the space bar and to stop/start the playback. If you turn on this data-attribute at least on one of the playlists or one instance of the player, the setting will apply to all players on the page.


Type: boolean
Default value: false

Specifies whether to hide timeline of the track, when track is not playing.


Type: boolean

Defines if the track should play first when the spacebar is pressed (works only if data-space-control option is on).


Adding jouele-skin-dark class to the link initialized by Jouele changes to predefined "dark" theme. For example:

<a href="" class="jouele jouele-skin-dark">Ilya Birman: News</a>

A developer can create a custom theme having examined the CSS-file Follow these steps to install a new theme:

  • In change all jouele-skin-dark selectors to the new name following the pattern jouele-skin-{skin_name} (for example, jouele-skin-blue).
  • Change colors with your preferred ones.
  • Add jouele-skin-{skin_name}class to the link initialized by Jouele.
  • Link the changed file to the page after jouele.css.

Dynamic Initialization


Turns selector link into a player. Returns a jQuery-object modified by $(selector) method. If everything is correct, this jQuery-object $(selector) gets a data attribute with an additional jouele property, which contains an instance of Jouele player (the entire API works with this instance, see below). selector DOM-element is excluded from DOM using jQuery.detach() method. The player block is added to DOM instead of excluded element and also has an instance of Jouele player in its data.jouele.

Global Object $.Jouele

The object contains 3 properties and one extended object of options:


Type: array
Default value: []

Array containing all playlists on the page arranged in order of their position in DOM. Each playlist contains an array of Jouele player instances. Empty if there is no active instance on the page.


Type: Jouele
Default value: null

Link to the last played or now playing instance of Jouele player. null if nothing has been played yet or if the last played track has been destroyed with the destroy method.


Type: Jouele
Default value: null

jQuery-object with jPlayer instance binded. null, if none of Jouele player instances has been initialized or if jPlayer is unavailable.


Type: object

Object with a set of properties: pauseOnSpace (false by default), playOnSpace (false by default), scrollOnSpace (true by default). Manually toggling each of the property globally changes the behaviour of the spacebar to control the playback and scroll.


Recommended way to access API:

var JoueleInstance = $(".jouele").data("jouele") // Get an instance of Jouele

API Methods or $(".jouele").jouele("play")

Starts the playback. Returns an instance of Jouele player.

JoueleInstance.pause() or $(".jouele").jouele("pause")

Pauses the playback. Returns an instance of Jouele player.

JoueleInstance.destroy() or $(".jouele").jouele("destroy")

Destroys the player, then adds back to the DOM the link, which has created the player. Returns the jQuery-object of the link.

API Properties


Type: jQuery-object

Stores jQuery-object of the link from which the player was created.


Type: jQuery-object

Stores link to jQuery-object of the playlist containing the player.


Type: array

Stores link to the element of $.Jouele.playlist array β€” playlist containing the track.


Type: boolean

Indicates whether the track is currently playing.


Type: boolean

Indicates whether the track has been played.


Type: number

Stores the track length in seconds. Can be a floating-point number.



MIT License