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 or via the link/unlinkToVideoPlayback APIs, and exposes an API that allows playing short sounds at any time.
This plugin uses the sonorousjs library, an opensource webaudio library developed by eko.

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
  - linkToVideoPlayback m
  - unlinkFromVideoPlayback 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 (Sonor).
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 Sonor 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 sonor 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 Sonor constructor, so see Sonorous’s 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 Sonor 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 Sonorous’s 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 Sonor 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, [options]) ⇒ `Sonor`
method

Returns the Sonor instance associated with id. By default, we wrap the sonor as a howler object, with most of the howl functions supported.
If you would like to use the sonor (no howler wrapper), then you can specify that using the options parameter. See below.
Use reserved id all in order to get an array of all added sounds.

Returns: Sonor - The sonor instance. Could be wrapped as howl, which means the sonor will use the same apis as the ones defined in Howler.

Param	Type	Default	Description
id	`string`		The sound id.
[options]	`object`		Options object, used to determine which format you would like the sonor returned as.
[options.format]	`string`	`"howler"`	Can either be ‘sonor’ or ‘howler’. By default, we will return the sonor wrapped as a howler object.

Example

var mysoundObject = player.audio.get('mysound');
mysoundObject.fade(0, 1, 2000);
// OR to use the native sonor object:
var mysoundObject = player.audio.get('mysound', {format: 'sonor'});
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']);

player.audio.linkToVideoPlayback(id, [options])
method

Links a sound to video playback, so whenever the video plays, the audio will play and whenever the video pauses, the audio will pause.
Once linked, a sound will immediately adopt the state of the player - if video is currently playing, the sound will automatically be played.
The sound can still be manipulated manually while it is linked to playback. If the sound is linked and begins to play, then is manually stopped, the sound will stop.
However if the player is paused, then resumed, the sound will immediately start playing again. By default, any soundtracks will be linked to video playback.
NOTE: If you link a sound to video playback, its pool size will automatically be set to 1. When the sound is unlinked, it will reset the pool size to its previous size.

See: unlinkFromVideoPlayback

Param	Type	Default	Description
id	`string`		the sound id (or array of ids)
[options]	`*`		Optional. Additional behaviors that can be configured.
[options.waitUntilLoaded]	`boolean`	`false`	Optional. If true, will cause buffering until the audio is loaded. Defaults to false - if video is playing, audio will automatically start playing once loaded.
[options.startOnInteraction]	`boolean`	`false`	Optional. If true, will only play once the first interaction in a project occurs. Note that this means the first interaction in the entire project, not the first interaction after the sonor has been linked to video playback. If waitUntilLoaded is also true, we will trigger buffering on first interaction. Defaults to false.
[options.pauseOnSeek]	`boolean`	`false`	Optional. If true, will pause the sound whenever the player is seeking. Defaults to false.

Example

// Link 'mySound' to video playback after the first interaction of the project
player.audio.linkToVideoPlayback('mysound', {startOnInteraction: true});

player.audio.unlinkFromVideoPlayback(id) ⇒ `Sonor`
method

Unlinks a sound from video playback. Will immediately stop the sound and no longer follow the video playback. Note that the sound will still be available for manual play/pause.

Returns: Sonor - the sonor that was unlinked from playback
See: linkToVideoPlayback

Param	Type	Description
id	`string`	the sound id (or array of ids)

Example

// Unlink 'mySound' from video playback
player.audio.unlinkFromVideoPlayback('mysound');

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, [options]) ⇒ Sonormethod

player.audio.has(id) ⇒ booleanmethod

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

player.audio.setPreload(id, value)method

player.audio.linkToVideoPlayback(id, [options])method

player.audio.unlinkFromVideoPlayback(id) ⇒ Sonormethod

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, [options]) ⇒ `Sonor`
method

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

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

player.audio.setPreload(id, value)
method

player.audio.linkToVideoPlayback(id, [options])
method

player.audio.unlinkFromVideoPlayback(id) ⇒ `Sonor`
method

“audio.volumechange”
event