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
- 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
Init Options
options : object
Initialization options for the audio plugin.
- options :
object
- .sounds :
object
|Array.<object>
- .bindVolumeToPlayer :
boolean
- .videoVolume :
number
- .sounds :
options.sounds : object
| Array.<object>
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
Initial value for the bindVolumeToPlayer property.
Default: true
See: bindVolumeToPlayer
Example
// playerOptions.json
{
"plugins": {
"audio": {
"bindVolumeToPlayer": false
}
}
}
options.videoVolume : number
Initial value for the videoVolume property.
Default: 1.0
See: videoVolume
Example
// playerOptions.json
{
"plugins": {
"audio": {
"videoVolume": 0.5
}
}
}
Properties
player.audio.bindVolumeToPlayer : boolean
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
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
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
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
The audio plugin’s version string.
Example
console.log('The audio plugin version is', player.audio.version);
Methods
player.audio.add(descObj)
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)
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)
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)
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)
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
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
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>
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)
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])
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.
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
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”
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);
});