<commit_before># Jouele
Jouele is a simple and beautiful audio player for the web. 

[Project page](http://ilyabirman.net/projects/jouele/)

[Russian translation of the documentation](https://github.com/ilyabirman/Jouele/blob/master/README-ru.md)

## Famous 2-step Setup
```html
<!-- Include dependencies that are mandatory for Jouele: jQuery and jPlayer -->
<script src="http://code.jquery.com/jquery-1.12.4.min.js"></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:
```html
<a href="http://audio.ilyabirman.ru/Ilya%20Birman%20-%20News.mp3" class="jouele">Ilya Birman: News</a>
```

### Playlists
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:
```html
<div class="jouele-playlist">
    <p><a href="http://audio.ilyabirman.ru/Ilya%20Birman%20-%20The%20Endgame.mp3" class="jouele">The Endgame</a></p>
    <p><a href="http://audio.ilyabirman.ru/Ilya%20Birman%20-%20Tastes%20Like%20Steel.mp3" class="jouele">Tastes Like Steel</a></p>
    <p><a href="http://audio.ilyabirman.ru/Ilya%20Birman%20-%20Glass.mp3" class="jouele">Glass</a></p>
    <p><a href="http://audio.ilyabirman.ru/Ilya%20Birman%20-%20I%20Will%20Always.mp3" class="jouele">I Will Always</a></p>
</div>
```

Check [`dist/example.html`](dist/example.html) to see more examples of usage.

## Advanced Features

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

#### `data-repeat`
Is applied to the playlist.  
Type: `boolean`  
Default value: `false`

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

#### `data-length`
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"`

#### `data-space-control`
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.

#### `data-hide-timeline-on-pause`
Type: `boolean`  
Default value: `false`

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

### Skin
Adding `jouele-skin-dark` class to the link initialized by Jouele changes to predefined "dark" theme. For example:
```html
<a href="http://audio.ilyabirman.ru/Ilya%20Birman%20-%20News.mp3" class="jouele jouele-skin-dark"><NAME>: News</a>
```

A developer can create a custom theme having examined the CSS-file [`jouele.skin.css`](dist/jouele.skin.css).
Follow these steps to install a new theme:
- In [`jouele.skin.css`](dist/jouele.skin.css) 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 [`jouele.skin.css`](dist/jouele.skin.css) file to the page after [`jouele.css`](dist/jouele.css).

## Dynamic Initialization

#### `$(selector).jouele()`
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:

#### `$.Jouele.playlist`
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.

#### `$.Jouele.lastPlayed`
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.

#### `$.Jouele.$jPlayer`
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.

#### `$.Jouele.options`
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.

## API
Recommended way to access API:
```javascript
var JoueleInstance = $(".jouele").data("jouele") // Get an instance of Jouele
```

### API Methods

#### `JoueleInstance.play()` 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

#### `JoueleInstance.$link`
Type: `jQuery-object`

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

#### `JoueleInstance.$playlist`
Type: `jQuery-объект`

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

#### `JoueleInstance.playlist`
Type: `array`

Stores link to the element of `$.Jouele.playlist` array — playlist containing the track.

#### `JoueleInstance.isPlaying`
Type: `boolean`
<commit_msg>Documentation is updated<commit_after># Jouele
Jouele is a simple and beautiful audio player for the web. 

[Project page](http://ilyabirman.net/projects/jouele/)

[Russian translation of the documentation](https://github.com/ilyabirman/Jouele/blob/master/README-ru.md)

## Famous 2-step Setup
```html
<!-- Include dependencies that are mandatory for Jouele: jQuery and jPlayer -->
<script src="http://code.jquery.com/jquery-1.12.4.min.js"></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:
```html
<a href="http://audio.ilyabirman.ru/Ilya%20Birman%20-%20News.mp3" class="jouele">Ilya Birman: News</a>
```

### Playlists
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:
```html
<div class="jouele-playlist">
    <p><a href="http://audio.ilyabirman.ru/Ilya%20Birman%20-%20The%20Endgame.mp3" class="jouele">The Endgame</a></p>
    <p><a href="http://audio.ilyabirman.ru/Ilya%20Birman%20-%20Tastes%20Like%20Steel.mp3" class="jouele">Tastes Like Steel</a></p>
    <p><a href="http://audio.ilyabirman.ru/Ilya%20Birman%20-%20Glass.mp3" class="jouele">Glass</a></p>
    <p><a href="http://audio.ilyabirman.ru/Ilya%20Birman%20-%20I%20Will%20Always.mp3" class="jouele">I Will Always</a></p>
</div>
```

Check [`dist/example.html`](dist/example.html) to see more examples of usage.

## Advanced Features

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

#### `data-repeat`
Is applied to the playlist.  
Type: `boolean`  
Default value: `false`

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

#### `data-length`
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"`

#### `data-space-control`
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.

#### `data-hide-timeline-on-pause`
Type: `boolean`  
Default value: `false`

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

### Skin
Adding `jouele-skin-dark` class to the link initialized by Jouele changes to predefined "dark" theme. For example:
```html
<a href="http://audio.ilyabirman.ru/Ilya%20Birman%20-%20News.mp3" class="jouele jouele-skin-dark"><NAME>: News</a>
```

A developer can create a custom theme having examined the CSS-file [`jouele.skin.css`](dist/jouele.skin.css).
Follow these steps to install a new theme:
- In [`jouele.skin.css`](dist/jouele.skin.css) 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 [`jouele.skin.css`](dist/jouele.skin.css) file to the page after [`jouele.css`](dist/jouele.css).

## Dynamic Initialization

#### `$(selector).jouele()`
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:

#### `$.Jouele.playlist`
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.

#### `$.Jouele.lastPlayed`
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.

#### `$.Jouele.$jPlayer`
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.

#### `$.Jouele.options`
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.

## API
Recommended way to access API:
```javascript
var JoueleInstance = $(".jouele").data("jouele") // Get an instance of Jouele
```

### API Methods

#### `JoueleInstance.play()` 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

#### `JoueleInstance.$link`
Type: `jQuery-object`

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

#### `JoueleInstance.$playlist`
Type: `jQuery-object`

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

#### `JoueleInstance.playlist`
Type: `array`

Stores link to the element of `$.Jouele.playlist` array — playlist containing the track.

#### `JoueleInstance.isPlaying`
Type: `boolean`

{'fraction_non_alphanumeric': 0.13426259713209965, 'fraction_numerical': 0.011055034847392453, 'mean_word_length': 4.874823529411764, 'pattern_counts': {'":': 0, '<': 67, '<?xml version=': 0, '>': 67, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 12, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1581132', 'n_tokens_mistral': 4085, 'n_tokens_neox': 3915, 'n_words': 1416}