Eko | api | audio

The audio plugin enables overlaying external audio streams on top of the video.
It takes care of the hassle of syncing external audio (pausing sound when video pauses/buffers) via the soundtrack feature, and exposes an API that allows playing short sounds at any time.
This plugin uses the howlerjs library, so you should also check out their documentation for more features and supported properties: https://github.com/goldfire/howler.js.

Example

// playerOptions.json
{
    "plugins": {
        "audio": {
            "sounds": {
                "ping": {
                     "src": ["https://mydomain.com/ping.ogg", "https://mydomain.com/ping.mp3"],
                     "volume": 0.3
                },
                "soundtrack": {
                     "src": ["https://mydomain.com/song.ogg", "https://mydomain.com/song.mp3"],
                     "volume": 1.0,
                     "loop": true,
                     "fadeInDuration": 3
                }
            },
            "videoVolume": 1.0
        }
    }
}

// app.js
player.audio.play('ping');

Table of Contents
- Init Options
  - sounds p
  - bindVolumeToPlayer p
  - videoVolume p
- Properties
  - bindVolumeToPlayer p
  - videoVolume p
  - volume p
  - muted p
  - version pro
- Methods
  - add m
  - remove m
  - play m
  - pause m
  - stop m
  - get m
  - has m
  - getPreload m
  - setPreload m
- Events
  - audio.volumechange e

Init Options

options : `object`

Initialization options for the audio plugin.

options : object
- .sounds : object | Array.<object>
- .bindVolumeToPlayer : boolean
- .videoVolume : number

options.sounds : `object` | `Array.<object>`
property

The sounds option will cause player.audio.add() to be invoked at plugin intialization with this value.

Default: []
See: add
Example

// playerOptions.json
{
    "plugins": {
        "audio": {
            "sounds": {
                "ping": {
                     "src": ["https://mydomain.com/ping.ogg", "https://mydomain.com/ping.mp3"],
                     "volume": 0.3
                },
                "soundtrack": {
                     "src": ["https://mydomain.com/song.ogg", "https://mydomain.com/song.mp3"],
                     "volume": 1.0,
                     "loop": true,
                     "fadeInDuration": 3
                }
            }
        }
    }
}

options.bindVolumeToPlayer : `boolean`
property

Initial value for the bindVolumeToPlayer property.

Default: true
See: bindVolumeToPlayer
Example

// playerOptions.json
{
    "plugins": {
        "audio": {
            "bindVolumeToPlayer": false
        }
    }
}

options.videoVolume : `number`
property

Initial value for the videoVolume property.

Default: 1.0
See: videoVolume
Example

// playerOptions.json
{
    "plugins": {
        "audio": {
            "videoVolume": 0.5
        }
    }
}

Properties

player.audio.bindVolumeToPlayer : `boolean`
property

When set to true, any volume change in the player will also affect all sounds in the audio plugin and vice-versa.
This also applies to player.muted and player.audio.muted properties.
Setting this property to false allows different muted/volume states between the player and the audio plugin.

Default: true
Example

player.audio.bindVolumeToPlayer = true;
player.muted = true; // Mutes both video and audio plugin
player.audio.volume = 0.75; // Also sets player.volume to 0.75
player.audio.bindVolumeToPlayer = false;
player.audio.muted = false; // Audio plugin is unmuted, but player remains muted

player.audio.videoVolume : `number`
property

Getter and setter for the relative volume of the video stream.
This is a number in the range [0, 1] where 0 is silent and 1 is loudest.
This property is unaffected by the bindVolumeToPlayer property.
Default is 1.0.

Example

player.audio.videoVolume = 0.5;

player.audio.volume : `number`
property

The audio plugin’s global volume (affects all sounds played via the audio plugin).
It’s a number from 0.0 (silent) to 1.0 (loudest).
Note that when bindVolumeToPlayer is set to true (default), setting this volume property will also affect the player.volume property.

Example

player.audio.play('mysound1');
player.audio.play('mysound2');
player.audio.volume = 0.5; // Volume will affect all sounds

player.audio.muted : `boolean`
property

The audio plugin’s global muted state (affects all sounds played via the audio plugin).
Set it to true in order to mute all sounds played via the audio plugin.
Note that when bindVolumeToPlayer is set to true (default), setting this muted property will also affect the player.muted property.

Default: false
Example

player.audio.play('mysound1');
player.audio.play('mysound2');
player.audio.muted = true; // All sounds will be muted

player.audio.version : `string`
propertyreadonly

The audio plugin’s version string.

Example

console.log('The audio plugin version is', player.audio.version);

Methods

player.audio.add(descObj)
method

Add/define (or replace) a sound object (Howl).
This method accepts a description object as parameter (or an array/map of description objects).
Every description object should contain at the very least an id and src params.
If the id provided already exists, the Howl object associated with that id will be replaced.
The plugin initialization option sounds is just a proxy for this method.

Param	Type	Description
descObj	`object` \| `Array.<object>`	A howl description object. At the very least the object must contain `id` and `src` params. Also accepts an array of objects or a map of objects. In case a map object is used, the keys will be the IDs, so there’s no need to also provide an `id` to each description object. The description object/objects will be passed on to the Howl constructor, so see Howl documentation for additional options not listed here.
descObj.id	`string`	Required. A unique string ID that can later be used to play or get the Howl instance. Use the reserved id `soundtrack` for a default soundtrack behavior (where `soundtrack` audio follows video playback).
descObj.src	`string` \| `Array.<string>`	Required. Audio source URL (or array of URLs in descending order of preference). See Howler’s src documentation.
[descObj.followVideoPlayback]	`boolean`	Optional. Default `false`. When true, audio playback will follow the video playback (pause when video is paused, resume when video is resumed). Using the reserved id `soundtrack` will set this to true.
[descObj.startOnInteraction]	`boolean`	Optional. Default `false`. When true, audio will start on first interaction (on the first interactions.report event)
[descObj.pauseOnSeek]	`boolean`	Optional. Default `false`. When true (and `followVideoPlayback` is also true), will pause the audio while video is being seeked to a new position.
[descObj.waitUntilLoaded]	`boolean`	Optional. Default `false`. When true (and `followVideoPlayback` is also true), will force the player into buffering mode if video started but audio has not yet loaded (by triggering the player’s `waiting` event).
[descObj.fadeInDuration]	`number`	Optional. Default `undefined`. When `followVideoPlayback` is true, setting a numeric value will cause audio to fade in for `fadeInDuration` seconds.
[descObj.fadeOutDuration]	`number`	Optional. Default `undefined`. When `followVideoPlayback` is true, setting a numeric value will cause audio to fade out for `fadeOutDuration` seconds.
[descObj.preload]	`boolean` \| `Array.<string>` \| `Array.<Node>`	Optional. Default `true`. When a boolean value is given, it’ll be passed on as-is to the Howl constructor. An array of node IDs (or node objects) will cause lazy load mode to kick in - sound will be loaded and available for playback only on the specified nodes and will be unloaded when no longer needed. See setPreload.

Example

player.audio.add([
    { id: 'ping', src: ['https://mydomain.com/ping.ogg', 'https://mydomain.com/ping.mp3'], volume: 0.3 },
    { id: 'soundtrack', src: ['https://mydomain.com/song.ogg', 'https://mydomain.com/song.mp3'], volume: 1.0, loop: true, fadeInDuration: 3 }
]);
// == SAME AS ==
player.audio.add({
    ping: { src: ['https://mydomain.com/ping.ogg', 'https://mydomain.com/ping.mp3'], volume: 0.3 },
    soundtrack: { src: ['https://mydomain.com/song.ogg', 'https://mydomain.com/song.mp3'], volume: 1.0, loop: true, fadeInDuration: 3 }
});
// == SAME AS ==
player.audio.add({ id: 'ping', src: ['https://mydomain.com/ping.ogg', 'https://mydomain.com/ping.mp3'], volume: 0.3 });
player.audio.add({ id: 'soundtrack', src: ['https://mydomain.com/song.ogg', 'https://mydomain.com/song.mp3'], volume: 1.0, loop: true, fadeInDuration: 3 });

// Once we've added the "ping" sound, we can now play it
player.audio.play('ping');

player.audio.remove(id)
method

Remove a sound from audio plugin (by id).
Use reserved id all in order to remove all added sounds.

Param	Type	Description
id	`string` \| `Array.<string>`	The sound id (or an array of ids).

Example

player.audio.remove('mysound');

player.audio.play(id)
method

Play a sound (by id).
Use reserved id all in order to play all added sounds.

Param	Type	Description
id	`string` \| `Array.<string>`	The sound id (or an array of ids).

Example

player.audio.play('ping');

player.audio.pause(id)
method

Pause a sound (by id).
Use reserved id all in order to pause all added sounds.

Param	Type	Description
id	`string` \| `Array.<string>`	The sound id (or an array of ids).

Example

player.audio.pause('mysound');

player.audio.stop(id)
method

Stops a sound (by id) and seeks to beginning.
Use reserved id all in order to stop all added sounds.

Param	Type	Description
id	`string` \| `Array.<string>`	The sound id (or an array of ids).

Example

player.audio.stop('mysound');

player.audio.get(id) ⇒ `Howl`
method

Returns the Howl instance associated with id.
Use reserved id all in order to get an array of all added sounds.
See https://github.com/goldfire/howler.js.

Returns: Howl - The howl instance.

Param	Type	Description
id	`string`	The sound id.

Example

var mysoundObject = player.audio.get('mysound');
mysoundObject.fade(0, 1, 2000);

player.audio.has(id) ⇒ `boolean`
method

Returns true if sound with given id exists (has been added).

Returns: boolean - True if sound exists, false otherwise.

Param	Type	Description
id	`string`	The sound id.

Example

if (player.audio.has('mysound')) {
    player.audio.play('mysound');
}

player.audio.getPreload(id) ⇒ `boolean` | `Array.<string>`
method

Get the preload value of a sound.

Returns: boolean | Array.<string> - Preload value of the sound (true, false or array of node IDs).
See: setPreload

Param	Type	Description
id	`string`	The sound id.

player.audio.setPreload(id, value)
method

Set the preload value of a sound.
Setting preload value to true will cause a sound to immediately be loaded.
Setting preload value to false will cause sound to immediately be unloaded.
Setting preload value to an array of nodes (or node IDs) will cause lazy load mode to kick in.
Sound will automatically be loaded when associated nodes are pushed into the playlist and unloaded when it is no longer needed (no associated nodes in future playlist).

See: getPreload

Param	Type	Description
id	`string`	The sound id.
value	`boolean` \| `Array.<string>` \| `Array.<Node>`	Preload value for this sound (`true`, `false` or array of nodes).

Example

// Set "mysound" to be lazy loaded and available for playback on specific nodes
player.audio.setPreload('mysound', ['node_a', 'node_b', 'node_c']);

Events

“audio.volumechange”
event

Triggered when the audio plugin’s global volume changes (both when the volume is set and when the muted attribute is changed).

Example

player.on('audio.volumechange', function() {
    console.log('Audio plugin current volume:', player.audio.volume);
    console.log('Audio plugin current muted state:', player.audio.muted);
});

Init Options

options : object

options.sounds : object | Array.<object>property

options.bindVolumeToPlayer : booleanproperty

options.videoVolume : numberproperty

Properties

player.audio.bindVolumeToPlayer : booleanproperty

player.audio.videoVolume : numberproperty

player.audio.volume : numberproperty

player.audio.muted : booleanproperty

player.audio.version : stringpropertyreadonly

Methods

player.audio.add(descObj)method

player.audio.remove(id)method

player.audio.play(id)method

player.audio.pause(id)method

player.audio.stop(id)method

player.audio.get(id) ⇒ Howlmethod

player.audio.has(id) ⇒ booleanmethod

player.audio.getPreload(id) ⇒ boolean | Array.<string>method

player.audio.setPreload(id, value)method

Events

“audio.volumechange”event

options : `object`

options.sounds : `object` | `Array.<object>`
property

options.bindVolumeToPlayer : `boolean`
property

options.videoVolume : `number`
property

player.audio.bindVolumeToPlayer : `boolean`
property

player.audio.videoVolume : `number`
property

player.audio.volume : `number`
property

player.audio.muted : `boolean`
property

player.audio.version : `string`
propertyreadonly

player.audio.add(descObj)
method

player.audio.remove(id)
method

player.audio.play(id)
method

player.audio.pause(id)
method

player.audio.stop(id)
method

player.audio.get(id) ⇒ `Howl`
method

player.audio.has(id) ⇒ `boolean`
method

player.audio.getPreload(id) ⇒ `boolean` | `Array.<string>`
method

player.audio.setPreload(id, value)
method

“audio.volumechange”
event