Soundslice JavaScript API

Here’s how to customize and control the Soundslice player when it’s embedded in your site via an <iframe>.

URL parameters

The easiest way to customize your player is with URL parameters. With no programming necessary, this lets you enable/disable various bits of the player simply by changing the URL of your embed code.

How to use URL parameters

To use the URL parameters documented below, append them to the URL in your Soundslice <iframe>, directly after /embed/. The list of URL parameters must start with a question mark, and separate URL parameters must be split with ampersands. Here are some examples:

Original <iframe> URL (with no URL parameters):

https://www.soundslice.com/scores/TEST/embed/

Hide tab by default (for scores that have tab):

https://www.soundslice.com/scores/TEST/embed/?show_tab=0

Hide tab and default to half speed:

https://www.soundslice.com/scores/TEST/embed/?show_tab=0&speed=50

Hide tab, default to half speed and display keyboard by default:

https://www.soundslice.com/scores/TEST/embed/?show_tab=0&speed=50&keyboard=1

Hint: you can always test this by visiting your embed URL directly in a web browser.

Below are all the available URL parameters. Note that we add new ones regularly; follow our blog for updates. We also send regular feature-announcement emails to our partners.

Notation options

show_track_names
Controls visibility of track names (aka part names) to the left of every stave. Use show_track_names=0 to hide the track names. Note this means your users won’t be able to access track controls. Track names are visible by default.
zoom
Controls the score’s default zoom level, e.g., zoom=50. Default zoom is 0, and allowed values are integers between -25 and 25. The bigger the number, the bigger the notation. Users can still change zoom in the settings.

Showing/hiding notation score-wide

You can use URL parameters to toggle default display of bits of notation — standard notation, tablature, chords and lyrics. This first group of parameters lets you toggle all tracks at the same time.

notationless
Controls the default display of notation. Use notationless=1 to hide all notation, leaving only a full-screen video view (assuming your score’s default recording is a video). If your score has notation despite notationless=1, users will still be able to toggle notation view by clicking the arrow icon at the top-right of the video. If your score has no notation, you don’t have to use notationless=1 — Soundslice will automatically use its notationless view for the score.
show_staff
Controls the default display of standard notation on all tracks. Use show_staff=0 to hide all standard notation. Users can still toggle notation display in track controls.
show_tab
Controls the default display of tablature on all tracks. Use show_tab=0 to hide all tablature; use show_tab=2 to show tablature with stems. If this parameter isn’t given, Soundslice will display tablature without stems (default behavior). Users can still toggle tab display in track controls. Note that this parameter is unnecessary for scores that don’t have tab.
show_chords
Controls the default display of chords on all tracks. Use show_staff=0 to hide all chord names and diagrams; use show_chords=1 to show only the chord names (not diagrams). If this parameter isn’t given, Soundslice will display names and diagrams. There is intentionally no way to display diagrams without names. Users can still toggle notation display in track controls.
show_lyrics
Controls the default display of lyrics on all tracks. Use show_lyrics=0 to hide all lyrics. For scores without lyrics, this has no effect. Users can still toggle lyrics display in track controls.

Showing/hiding notation for certain tracks

If you’d like to toggle default display for only certain tracks, use the following parameters. Each one works exactly as the above versions, except you should substitute a zero-based track number for X. For example, to hide tablature for the first track, use show_tab_t0=0.

show_staff_tX
Controls default display of standard notation in track X. Same values as show_staff.
show_tab_tX
Controls default display of tablature in track X. Same values as show_tab.
show_chords_tX
Controls default display of chords in track X. Same values as show_chords.
show_lyrics_tX
Controls default display of lyrics in track X. Same values as show_lyrics.

Audio options

defer
Use defer=1 to tell Soundslice not to auto-load the default audio source. Without this, the default audio source’s audio will be loaded immediately at page load. See Audio loading.
recording_idx
Specifies the initial recording to use, e.g. recording_idx=1. By default, Soundslice uses the last recording in the score’s recording list, according to their order in the score manager; this parameter lets you override that. Note this is is a zero-based integer index, where 0 is the first recording (likely the synthetic recording, unless you’ve disabled it), 1 is the second recording (if available), and so on.
enable_synth
Use enable_synth=0 to disable the “Synthetic” audio source that’s available by default. If you use this, make sure your score has at least one recording! Otherwise the Play button won’t do anything, which might confuse your users.
speed
Specifies the initial playback speed, where 100 is normal speed, 50 is half speed, etc. Any integer between 25 and 125 is valid. Default is 100. Note that video can only be slowed to 50% speed, and some browsers limit audio slowdown to 50%; if you use 25 in these cases, Soundslice will automatically use 50% (the lowest available speed).

Video options

force_side_video
Use force_side_video=1 to force video to always be displayed to the left of notation, regardless of embed width. By default, Soundslice will move videos above notation for small embed widths (≤ 768px wide). This parameter disables that behavior.
force_top_video
Use force_top_video=1 to force video to always be displayed above notation, regardless of embed width. By default, Soundslice will only display videos above notation for small embed widths (≤ 768px wide). This parameter disables that behavior.
narrow_video_height
Specifies the video’s height, in pixels, when the video is above notation — i.e., when the player has a narrow width (≤ 768 pixels wide) or you set force_top_video. By default, this is 225. For example: narrow_video_height=150 sets the video’s height to 150 pixels.
side_video_width
Specifies the video’s width, in pixels, when the video is on the left of notation. By default, this is 320. For example: side_video_width=500 sets the video’s width to 500 pixels. The minimum allowed value is 150.

Display options

top_controls
Use top_controls=1 to place the main controls (the horizontal bar with the play button, etc.) above the notation instead of at the bottom. If a video is visible and it’s displayed above notation (see force_top_video), then the controls will be between the video and the notation.
show_title
Use show_title=0 to hide the score title. This results in a shorter control bar (a vertical savings of about 30 pixels), leaving more room for your notation.
synth_display_name
Lets you specify a different label for the synth player. By default, it’s “Synthetic”. Example: synth_display_name=Piano.
play_type
Lets you specify the default play type. play_type=1 is “Play looped,” play_type=2 is “Play once,” play_type=3 is “Play with count-in.” Default is 1.
enable_transposition
Use enable_transposition=0 to disable the score-wide transposition slider, which is in the settings menu.

Scrolling options

scroll_type
Soundslice automatically scrolls notation during playback. By default, we ensure the currently playing bar and the next bar are both visible on the screen at all times; in practice, this results in the playhead being near the bottom of the screen. Use scroll_type=2 to change the algorithm to always put the currently playing bar/stave at the top of the screen. You may prefer this second algorithm if you’re used to reading from paper sheet music.

Visualization options

fretboard
Use fretboard=1 to display the fretboard at time of page load, if the score has any tab tracks. Users can still toggle it off as desired.
keyboard
Use keyboard=1 to display the piano keyboard at time of page load. Users can still toggle it off as desired.
violin
Use violin=1 to display the violin fingerboard at time of page load. Users can still toggle it off as desired.
enable_fretboard
Use enable_fretboard=0 to disable the fretboard. Users will not see a fretboard icon and won’t be able to toggle fretboard display. Otherwise, it’s available on all scores that have at least one tab track.
enable_keyboard
Use enable_keyboard=0 to disable the piano keyboard. Otherwise, it’s available by default on all scores, regardless of instrument.
enable_mixer
Use enable_mixer=0 to disable the Mixer. Otherwise, it’s available by default.
enable_violin
Use enable_violin=0 to disable the violin fingerboard. Otherwise, it’s available by default on all scores that have at least one track with the virtual violin enabled.
enable_waveform
Use enable_waveform=0 to disable the waveform. Otherwise, it’s available by default.

Branding options

branding
By default, the player displays “Powered by Soundslice” in the main controls, under the score’s title. If you’d like a more compact control bar, use branding=2. This moves the “Powered by Soundslice” branding from the control bar to an overlay at the bottom right of the notation. This works particularly well with top_controls=1.

Activating the JavaScript API

Beyond the URL parameters, our player has a JavaScript API. Use this if you want to control our player from within your own page — for example, to provide your own play UI.

For performance reasons, our player doesn’t have an API by default. To activate it, add the URL parameter api=1 to your iframe, like this:

<iframe src="https://www.soundslice.com/scores/TEST/embed/?api=1" ...>

You’ll also probably want to add an id attribute to the <iframe>, so that your own JavaScript can reference it. For example:

<iframe id="ssembed" ...>

Controlling the player via JavaScript

We use the standard postMessage API. In each case, JavaScript code from your own page (the parent page) calls postMessage() on the iframe’s contentWindow attribute, passing a serialized JSON object with a method key. In some cases, there’s an additional arg key.

Each example below assumes you have a reference to the Soundslice iframe window, like so:

var ssiframe = document.getElementById('ssembed').contentWindow;

Also note that you need to pass the proper target origin parameter, which is 'https://www.soundslice.com', to avoid cross-site scripting attacks.

Playing

ssiframe.postMessage('{"method": "play"}', 'https://www.soundslice.com');

Pausing

ssiframe.postMessage('{"method": "pause"}', 'https://www.soundslice.com');

Seeking

// Seek to 3.5 seconds
ssiframe.postMessage('{"method": "seek", "arg": 3.5}', 'https://www.soundslice.com');

Clearing the loop

If the user has selected a portion of notation to loop it, this method will clear that loop. Note that this is a no-op if there’s no active loop.

ssiframe.postMessage('{"method": "clearLoop"}', 'https://www.soundslice.com');

Changing speed

Here, you specify the desired speed as a float, where 1 is normal speed and 0.5 is half speed.

Note that the minimum and maximum allowed speeds depend on the user’s browser and the type of audio source. If you try setting a speed that’s slower than the minimum speed or faster than the maximum speed, the player will use the minimum or maximum speeds, respectively.

// Change speed to 50%
ssiframe.postMessage('{"method": "setSpeed", "arg": 0.5}', 'https://www.soundslice.com');

Changing audio sources

Here, you specify the zero-based index of the desired audio source. You control the order of audio sources in the partner admin.

// Change audio source to the second one (index 1)
ssiframe.postMessage('{"method": "changeAudioByIndex", "arg": 1}', 'https://www.soundslice.com');

Loading audio sources

Here, you specify the zero-based index of the desired audio source. You control the order of audio sources in the partner admin. Note that loading an audio source doesn’t start playback and doesn’t change the currently active audio source; loading happens in the background. See Audio loading.

For audio sources that are videos, Soundslice doesn’t do any preloading, because videos are always streamed in real time, rather than preloaded into memory. If you call this method for a video, it will just be a no-op.

// Load audio for the second audio source (index 1)
ssiframe.postMessage('{"method": "loadAudioByIndex", "arg": 1}', 'https://www.soundslice.com');

Zooming notation

Here, you specify the zoom level, as an integer, in order to increase or decrease the size of notation. Default zoom is 0, and allowed values are integers between -25 and 25. The bigger the number, the bigger the notation.

// Set zoom level to 25
ssiframe.postMessage('{"method": "setZoom", "arg": 25}', 'https://www.soundslice.com');

Getting player data

Getting data from the player is a bit more complicated due to the way postMessage() works. In each case here, you post a message to the iframe, then listen for the appropriate event response and get its arg.

Note you should set up event listeners before calling postMessage(), to avoid a possible race condition where the iframe sends you a message before you’re listening for it.

Here is a full example, using current time:

// Handle inbound current time messages.
window.addEventListener('message', function(event) {
    var cmd = JSON.parse(event.data);
    if (cmd.method === 'ssCurrentTime') {
        console.log('Current time is ' + cmd.arg + ' seconds.');
    }
});

// Request current time.
ssiframe.postMessage('{"method": "getCurrentTime"}', 'https://www.soundslice.com');

Current time

Post a getCurrentTime message, then listen for ssCurrentTime. The arg will be in seconds as a float.

Note: If your score has multiple audio sources, duration and current time will likely change as the user switches audio sources. When a user switches audio sources, the Soundslice player maintains the current bar and percentage into that bar, seeking the underlying audio appropriately.

Total time (duration)

Post a getDuration message, then listen for ssDuration. The arg will be in seconds as a float.

See the note about multiple audio sources in the “Current time” section above.

Current bar number

Post a getCurrentBar message, then listen for ssCurrentBar. The arg will be the current bar (measure) number, zero-based, as an integer.

Note: For scores that have any sort of repeat — repeat bars, “Da Segno,” “D.C. al Fine,” etc. — this number represents the “flattened” bar number, which does not necessarily correspond to the displayed bar number that musicians refer to when reading the score. For example, in a score comprised of five bars, with a repeat bar at the end, the bar count would be 10 and the current bar number for the first bar would be 0 at start and 5 the second time through.

Total bar count

Post a getBarCount message, then listen for ssBarCount. The arg will be the total number of bars (measures), as an integer.

See the note about bar repeats in the “Current bar number” section above.

Current speed

Post a getSpeed message, then listen for ssSpeed. The arg will be the current speed, as a float, where 1 is normal speed and 0.5 is half speed.

Player events

The player dispatches a few events, which you can listen for in the parent page using addEventListener(). In each case, the message contents are serialized JSON, with a method key. 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.
  • ssPlay — triggered when play starts.
  • ssPause — triggered when play pauses.
  • ssSeek — triggered when the user seeks to a given time. Gets an arg key with the time, in seconds as a float.
  • ssCurrentTime — triggered as a response to the getCurrentTime message (see above). Gets an arg key with the time, in seconds as a float.
  • ssDuration — triggered as a response to the getDuration message (see above). Gets an arg key with the time, in seconds as a float.
  • ssCurrentBar — triggered as a response to the getCurrentBar message (see above). Gets an arg key with the zero-based bar number, as an integer.
  • ssBarCount — triggered as a response to the getBarCount message (see above). Gets an arg key with the bar count, as an integer.
  • ssSpeed — triggered as a response to the getSpeed message (see above). Gets an arg key with the speed, as a float.
  • ssAudioLoaded — triggered when an audio source loads. Gets an arg key with the zero-based index of the audio source that has loaded, as an integer.
  • ssAudioSourceChanged — triggered when the audio source changes. Gets an arg key with the zero-based index of the new audio source, as an integer.
  • ssPrint — triggered when the user clicks the “Print” button in settings, to print the score.
  • ssZoom — triggered when the notation is zoomed in or out. Gets an arg key with the new zoom level, an integer between -25 and 25 inclusive. See “Zooming notation” above.

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 'ssSeek':
            console.log('Play has seeked to ' + cmd.arg + ' seconds.');
            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('Audio source ' + cmd.arg + ' has loaded.');
            break;
        case 'ssAudioSourceChanged':
            console.log('Audio source changed to ' + cmd.arg);
            break;
        case 'ssSpeed':
            console.log('Speed is ' + (cmd.arg * 100) + ' percent.');
            break;
        case 'ssPrint':
            console.log('User clicked Print');
            break;
        case 'ssZoom':
            console.log('Zoom is now ' + cmd.arg);
            break;
    }
});
    

Audio loading

Our API lets you control the loading of audio sources’ underlying MP3s. The default Soundslice behavior is:

  • Automatically load the default audio source (the last one in the list), on page load.
  • For every other audio source, defer loading until the user selects it and presses play.

You can change this behavior in two ways:

  • Use the defer=1 URL parameter to stop automatic loading of the default audio source on page load.
  • Use the loadAudioByIndex() JavaScript API method to load a given audio source at any time.