Events in the Soundslice JavaScript API
The Soundslice player dispatches several events, which you can listen for in the parent page using addEventListener()
.
In each case, the message contents are a serialized JSON object, with the following keys:
JSON key | Availability | Description | Example |
---|---|---|---|
"method" |
Always present | The name of the event. | "ssPlayerReady" , "ssPlay" |
"sliceId" |
Always present, but might be an empty string | The ID of the current slice. This is useful to disambiguate if you use multiple Soundslice players in the same web page. Note it might be an empty string if the slice’s data hasn’t loaded yet. | "cNNNc" |
"arg" |
Depends on the event | Some events include additional, event-specific data. It’s always in the "arg" . |
|
"state" |
Depends on the event | Some API methods let you pass a state variable. For those method responses, we pass it back to you untouched. This can make it easier to write asynchronous code. |
The methods are:
ssPlayerReady
— triggered when the player and API are ready. This is useful if you want to take some action at time of page load.ssNotationLoaded
— triggered when the notation is loaded. This will be some time afterssPlayerReady
, because notation data is loaded asynchronously.ssPlay
— triggered when play starts. Gets anarg
key with the current time (as inssCurrentTime
), in seconds as a float.ssPause
— triggered when play pauses.ssAudioEnd
— triggered when play stops due to reaching the end of the audio/video.ssOneTimeLoopEnd
— triggered when play stops due to reaching the end of a loop in “loop only once” mode.ssSeek
— triggered when the user seeks to a given time. Gets anarg
key with the time, in seconds as a float.ssLoopChange
— triggered when the loop changes. Gets anarg
key, an array with two values (start time code and end time code, both in seconds). If the loop has become empty, these values arenull
.ssCurrentTime
— triggered as a response to thegetCurrentTime
message. Gets anarg
key with the time, in seconds as a float.ssDuration
— triggered as a response to thegetDuration
message. Gets anarg
key with the time, in seconds as a float.ssCurrentBar
— triggered as a response to thegetCurrentBar
message. Gets anarg
key with the zero-based bar number, as an integer.ssBarCount
— triggered as a response to thegetBarCount
message. Gets anarg
key with the bar count, as an integer.ssSpeed
— triggered as a response to thegetSpeed
message. Gets anarg
key with the speed, as a float.ssVolume
— triggered as a response to thegetVolume
message. Gets anarg
key with the volume, as a float between0
and1
.ssVolumeChange
— triggered whenever the player’s volume changes. Gets anarg
key with the volume, as a float between0
and1
.ssAudioLoaded
— triggered when a recording loads. Gets anarg
key with the zero-based index of the recording that has loaded, as an integer.ssAudioSourceChanged
— triggered when the recording changes. Gets anarg
key with the zero-based index of the new recording, as an integer.ssToggleSettings
— triggered when the user toggles the Settings menu. Gets anarg
key that specifies whether the settings menu was turned on or off;1
means on and0
means off.ssLayoutChange
— triggered when the layout changes. Gets anarg
key that specifies the new layout; see layout for the possible numeric values.ssPrint
— triggered when the user clicks the “Print” button in settings, to print the slice.ssZoom
— triggered when the notation is zoomed in or out. Gets anarg
key with the new zoom level, an integer between -25 and 25 inclusive.ssNotationVisibility
— triggered whenever the notation visibility changes. Also gets triggered if you explicitly callgetNotationVisibility
. Gets anarg
key with the new visiblity, as a boolean.ssFullscreenSupport
— triggered as a response to thegetFullscreenSupport
message. Gets anarg
key, a boolean, which tells you whether the current browser/device supports web pages going fullscreen.
Example usage:
window.addEventListener('message', function(event) {
var cmd = JSON.parse(event.data);
switch (cmd.method) {
case 'ssPlayerReady':
console.log('Player is ready.');
break;
case 'ssPlay':
console.log('Play has started.');
break;
case 'ssPause':
console.log('Play has stopped.');
break;
case 'ssAudioEnd':
console.log('Play has stopped due to reaching the end.');
break;
case 'ssSeek':
console.log('Play has seeked to ' + cmd.arg + ' seconds.');
break;
case 'ssLoopChange':
console.log('Loop has changed to ' + cmd.arg);
break;
case 'ssCurrentTime':
console.log('Current time is ' + cmd.arg + ' seconds.');
break;
case 'ssDuration':
console.log('Duration is ' + cmd.arg + ' seconds.');
break;
case 'ssCurrentBar':
console.log('Current bar is ' + cmd.arg);
break;
case 'ssBarCount':
console.log('Bar count is ' + cmd.arg);
break;
case 'ssAudioLoaded':
console.log('Recording ' + cmd.arg + ' has loaded.');
break;
case 'ssAudioSourceChanged':
console.log('Recording changed to ' + cmd.arg);
break;
case 'ssSpeed':
console.log('Speed is ' + (cmd.arg * 100) + ' percent.');
break;
case 'ssVolume':
console.log('Volume is ' + (cmd.arg * 100) + ' percent.');
break;
case 'ssToggleSettings':
if (cmd.arg === 1) {
console.log('Settings were toggled on.');
}
else if (cmd.arg === 0) {
console.log('Settings were toggled off.');
}
break;
case 'ssPrint':
console.log('User clicked Print');
break;
case 'ssZoom':
console.log('Zoom is now ' + cmd.arg);
break;
case 'ssNotationVisibility':
console.log('Notation visibility is now ' + cmd.arg);
break;
case 'ssFullscreenSupport':
console.log('Does this browser support full screen? ' + cmd.arg);
break;
}
});