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": [
                { "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 }
            ],
            "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": [
                { "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 }
            ]
        }
    }
}

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 of description object).
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. This object 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.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.

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

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!