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');

Init Options

options : object

Initialization options for the audio plugin.

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);
});
Rate this page: X
Tell us more!