Soundslice data API

You can use our data API to manage the slices in your account programmatically. Here’s the full documentation.

Note: in January 2018, we changed our terminology from “scores” to “slices.” This API and its documentation still use the old term “score.” For our purposes here, the terms are interchangeable.

API keys

To get started, you’ll need an API key.

API keys are only available to paying Soundslice customers — either in the Teacher or Licensing plans.

A Soundslice API key consists of two strings — an application ID and associated password. You can have multiple API keys, in case you’d like to keep separate applications separate.

API endpoints

This API is REST-based and works over HTTP. For each API call, you’ll need to authenticate with your API key, using HTTP Basic Authentication.

Here’s an example API call, using the open-source curl library on the Unix command line:

curl -X GET -u 'my_app_id:my_password' https://www.soundslice.com/api/v1/scores/auld-lang-syne/

In our API responses, you should check the HTTP status code to determine success. The content of responses is in JSON format.

Here are all the currently implemented API endpoints:

POST /api/v1/scores/

Creates a score. Note this only creates the metadata for the score, not the notation.

Use these POST parameters:

name Optional The name of the score. Limit 255 characters. If not given, we’ll use the name “Untitled” for this score.
artist Optional The artist/composer of the score. Limit 255 characters.
status Optional

An integer specifying who can view the score on soundslice.com. (Embeds ignore this and use embed_status.)

  • 1 — “Only me” (default value, if not provided)
  • 3 — “Anybody who knows its URL”
embed_status Optional

An integer specifying embed options. For more, see embedding docs.

  • 1 — Disabled (default value, if not provided)
  • 2 — Allowed on any domain
  • 4 — Allowed on whitelist domains
print_status Optional

Whether the score can be printed.

  • 1 — Printing is disabled (default)
  • 3 — Printing is allowed
folder_id Optional A string specifying the ID of the folder in which to put this score, e.g., "123". (Note that folder IDs are not necessarily always integers.) If you don’t specify this, the score will be placed in the account’s root folder.

To parse the response, check the HTTP status code. Here are the possible responses:

HTTP status 201

Success. Response is a JSON object containing these keys:

  • "slug" — The score’s slug. A slug is a unique identifier with a maximum size of 100 characters.
  • "url" — The score’s URL on soundslice.com. Note this URL will return a 404 until the score has notation.
  • "embed_url" — Only included if the score has embedding enabled. This is the URL to put in your <iframe>. Note this URL will return a 404 until the score has notation.
HTTP status 422

Error. Response is a JSON object containing one key:

  • "errors" — An object mapping field names to lists of error message strings. Example:

{"folder_id": ["This folder ID is invalid."]}

DELETE /api/v1/scores/SLUG/

Deletes the score with slug SLUG, including all its associated data such as recordings.

To parse the response, check the HTTP status code. Here are the possible responses:

HTTP status 201

Success. Response is a JSON object containing these keys:

  • "name" — String. The score’s name.
  • "artist" — String. The score’s artist. Might be an empty string, but it will always exist in the JSON.
HTTP status 403

Error. You don’t own this score.

GET /api/v1/scores/

Retrieves metadata for all scores in your account.

The order of scores in the result is undefined.

To parse the response, check the HTTP status code. Here are the possible responses:

HTTP status 200

Success. Response is a JSON list of objects, with each object containing these keys:

  • "slug" — String. The score’s slug.
  • "name" — String. The score’s name.
  • "artist" — String. The score’s artist. Might be an empty string, but it will always exist in the JSON.
  • "status" — Integer. The score’s view status. (See here.)
  • "embed_status" — Integer. The score’s embed status. (See here.)
  • "can_print" — Boolean. Whether the score can be printed.
  • "has_notation" — Boolean. Whether the score has notation.
  • "show_notation" — Boolean. Whether the score can show its notation. This is true except when you’ve manually disabled notation for the score, in the score manager.
  • "recording_count" — Integer. The number of recordings the score has.

GET /api/v1/scores/SLUG/

Retrieves metadata for the score with slug SLUG.

To parse the response, check the HTTP status code. Here are the possible responses:

HTTP status 201

Success. Response is a JSON object containing these keys:

  • "url" — String. The score’s URL on soundslice.com. Note this URL will return a 404 if the score has no notation.
  • "name" — String. The score’s name.
  • "artist" — String. The score’s artist. Might be an empty string, but it will always exist in the JSON.
  • "status" — Integer. The score’s view status. (See here.)
  • "embed_status" — Integer. The score’s embed status. (See here.)
  • "can_print" — Boolean. Whether the score can be printed.
  • "has_notation" — Boolean. Whether the score has notation.
  • "show_notation" — Boolean. Whether the score can show its notation. This is true except when you’ve manually disabled notation for the score, in the score manager.
  • "recording_count" — Integer. The number of recordings the score has.
  • "embed_url" — String. The score’s embed URL. Note this URL will return a 404 if the score has no notation, and this key will not exist in the JSON if the score cannot be embedded.
HTTP status 403

Error. You don’t own this score.

GET /api/v1/scores/SLUG/notation/

Retrieves the original notation file for the score with slug SLUG.

To parse the response, check the HTTP status code. Here are the possible responses:

HTTP status 200

Success. Response is a JSON object containing a single key, "url". This is a URL where you can download the original notation file within the next 15 minutes.

Note "url" might be set to the empty string, for scores that don’t have an original notation file.

HTTP status 403

Error. You don’t have permission to edit this score.

Upload a score’s notation

Uploading notation is a multi-step process, because notation files can take a while to process depending on size and current server load:

  1. Initiate an upload via POST. We’ll give you a temporary URL to PUT the notation to.
  2. PUT the notation file to that URL.
  3. We’ll notify you when the upload has processed via making a POST to a callback of your choosing.

Step 1: POST /api/v1/scores/SLUG/notation/

Make sure to replace SLUG with your score’s slug. One optional POST parameter is supported:

callback_url Optional A URL that Soundslice will POST to when the upload is processed. Should be a full path, starting with http:// or https://.

To parse the response, check the HTTP status code. Here are the possible responses:

HTTP status 200

Success. Response is a JSON object containing this key:

  • "url" — A one-time, expiring URL that you should PUT the notation to. The URL expires within a few minutes, so make sure to start the PUT right away. (Once you’ve started the PUT, you don’t have to worry about the expiration.)
HTTP status 403

Error. You don’t have permission to edit this score.

HTTP status 422

Error. Your callback_url was invalid.

Step 2: PUT [put_url]

Next, make a PUT request to the URL you received in step 1. The data of this PUT request should be the raw data of the notation file, in one of our supported formats (MusicXML, Guitar Pro, PowerTab, TuxGuitar).

Do not include HTTP authentication (username and password) with this request.

Important note: This URL will expire after a few minutes. You can always regenerate a new one by doing step 1 again.

Step 3: Handle the callback (optional)

If you specified a callback_url in step 1, we’ll POST to that URL when the notation file is done processing. The POST data will include these keys:

score_slug

The slug of the score, as a string.

success

'1' if it was successfully processed. '2' if there was an error.

error

This error string will exist in case of errors. Example:

"We couldn't parse the given file."

POST /api/v1/scores/SLUG/move/

Moves the score (with slug SLUG) to a given folder.

Use these POST parameters:

folder_id Required The ID of the new folder. Use folder_id 0 (zero) to move the score to your account’s root folder.

To parse the response, check the HTTP status code. Here are the possible responses:

HTTP status 201

Success. Response is a JSON object containing one key:

  • "id" — The ID of the folder, or 0 (zero) for the root folder.
HTTP status 403

Error. You don’t have permission to edit this score.

HTTP status 422

Error. Response is a JSON object containing one key:

  • "error" — A string with an error message. This will happen if you specify an invalid folder_id.

POST /api/v1/scores/SLUG/recordings/

Creates a recording in the score with slug SLUG.

Use these POST parameters:

name Required The name of the recording. Limit 100 characters.
source Required

An integer specifying the type of recording.

  • 2 — MP3 uploaded to Soundslice
  • 4 — Video uploaded to Soundslice
  • 3 — Video URL
  • 1 — YouTube video
  • 6 — Vimeo video (only allowed if your Soundslice account has been linked with Vimeo)
  • 7 — Wistia video (only allowed if your Soundslice account has been linked with Wistia)
source_data Depends

Extra data, depending on the value of source.

  • If source is 1 — The URL or ID of the YouTube video. Required.
  • If source is 3 — The URL of the video. Either this or hls_url is required. (You can also provide both.)
  • If source is 6 — The ID of the Vimeo video. Required.
  • If source is 7 — The ID of the Wistia video. Required.
hls_url Depends

The URL for an HLS playlist for this recording, if source is 3.

The value is not required if you provide source_data. You can provide both hls_url and source_data; in that case, our player will use the hls_url for users whose browsers support HLS and source_data otherwise.

To parse the response, check the HTTP status code. Here are the possible responses:

HTTP status 201

Success. Response is a JSON object containing one key:

  • "id" — The ID of the newly created recording.
HTTP status 403

Error. You don’t have permission to edit this score.

HTTP status 422

Error. Response is a JSON object containing one key:

  • "errors" — An object mapping field names to lists of error message strings. Example:

{"name": ["This field is required."],
"source": ["This field is required."]}

If your recording’s source is 2 or 4 (audio/video uploaded to Soundslice), you’ll need to upload the audio/video in a separate step.

GET /api/v1/scores/SLUG/recordings/

Gets data about all recordings in the slice with slug SLUG.

To parse the response, check the HTTP status code. Here are the possible responses:

HTTP status 201

Success. Response is a JSON array, in which each element has these keys:

  • "id" — The recording’s ID.
  • "name" — The recording’s name.
  • "source" — The recording’s source (see above for details).
  • "source_data" — The recording’s source_data (see above for details).
  • "hls_url" — The recording’s HLS URL, or an empty string.
  • "syncpoint_count" — The recording’s number of syncpoints.
HTTP status 403

Error. You don’t have permission to edit this score.

POST /api/v1/recordings/RECORDING_ID/

Changes data for the recording with ID RECORDING_ID.

Use these POST parameters. All are optional; if you don’t want to change a particular value, simply don’t send its key the request.

name Optional The name of the recording. Limit 100 characters.
source_data Optional

Extra data, depending on the value of source. (See above for details.)

hls_url Optional

The URL for an HLS playlist for this recording, if source is 3.

To parse the response, check the HTTP status code. Here are the possible responses:

HTTP status 200

Success. Response is a JSON object containing these keys:

  • "id" — The recording’s ID.
  • "name" — The recording’s name.
  • "source_data" — The recording’s source_data.
  • "hls_url" — The recording’s HLS URL.
HTTP status 403

Error. You don’t have permission to edit this slice.

HTTP status 422

Error. Response is a JSON object containing one key:

  • "errors" — An object mapping field names to lists of error message strings. Example:

{"hls_url": ["Enter a valid URL."]}

DELETE /api/v1/recordings/RECORDING_ID/

Deletes the recording with the given RECORDING_ID, including all its associated data such as syncpoints and uploaded audio.

To parse the response, check the HTTP status code. Here are the possible responses:

HTTP status 201

Success. Response is a JSON object containing one key:

  • "name" — String. The recording’s name.
HTTP status 403

Error. You don’t have permission to edit this recording.

Upload a recording’s audio/video

This applies to recordings with a source of either 2 (MP3 uploaded to Soundslice) or 4 (video uploaded to Soundslice).

Uploading audio/video is a multi-step process:

  1. Initiate an upload via POST. We’ll give you a temporary URL to PUT the notation to.
  2. PUT the notation file to that URL.

Step 1: POST /api/v1/recordings/RECORDING_ID/media/

Make sure to replace RECORDING_ID with the recording ID.

To parse the response, check the HTTP status code. Here are the possible responses:

HTTP status 201

Success. Response is a JSON object containing this key:

  • "url" — A one-time, expiring URL that you should PUT the media file to. The URL expires within a few minutes, so make sure to start the PUT right away. (Once you’ve started the PUT, you don’t have to worry about the expiration.)
HTTP status 403

Error. You don’t have permission to edit this recording.

HTTP status 422

Error. This recording’s source isn’t 2 or 4.

Step 2: PUT [put_url]

Next, make a PUT request to the URL you received in step 1. The data of this PUT request should be the raw data of the media file (an MP3 or a video file). Do not include HTTP authentication (username and password) with this request.

Important note: This URL will expire after a few minutes. You can always regenerate a new one by doing step 1 again.

GET /api/v1/recordings/RECORDING_ID/syncpoints/

Retrieves the syncpoints for the recording with ID RECORDING_ID.

To parse the response, check the HTTP status code. Here are the possible responses:

HTTP status 200

Success. Response is a JSON list representing the syncpoints. See Syncpoint data format below.

HTTP status 403

Error. You don’t have permission to read this recording.

POST /api/v1/recordings/RECORDING_ID/syncpoints/

Sets the syncpoints for the recording with ID RECORDING_ID.

Use these POST parameters:

syncpoints Required The syncpoints, as a string in JSON format. See Syncpoint data format below.
crop_start Optional Number of seconds into the recording to start cropping (a float). For example, if this is 12, then the recording will begin playback at 12 seconds, and seconds 0-12 will be inaccessible.
crop_end Optional Number of seconds into the recording to end cropping (a float). For example, if this is 60, then the recording will end playback at the timecode 60 seconds, and any audio after timecode 60 seconds will be inaccessible. Note this is relative to the absolute recording, so crop_start has no effect on crop_end.

To parse the response, check the HTTP status code. Here are the possible responses:

HTTP status 200

Success. Response is a JSON object containing these keys:

  • "id" — The recording ID, as an integer.
HTTP status 422

Error. Response is a JSON object containing one key:

  • "errors" — An object mapping field names to lists of error message strings. Example:

{"syncpoints": ["Invalid JSON"]}

Syncpoint data format

Syncpoints provide the mapping between notation and an audio/video recording. In Soundslice, syncpoints are stored as a simple JSON array. Example:

[[0, 0], [1, 0.57], [1, 0.8, 240], [2, 1.3]]

Each element in the array represents one syncpoint. A syncpoint is an array of two or three values:

Value 1: Bar

Required. The zero-based bar number in the score, as an integer.

For example, the first bar in the score will always be 0 — regardless of how it’s actually labeled in the visual notation.

If the score has repeats and/or jumps, this syncpoint bar value corresponds to the bar number in absolute terms — as if the notation were rewritten to expand all repeats and jumps. For example, in a two-bar score that has a repeat line at the end, we’d consider that to have four bars for the purposes of syncpoints: 0, 1, 2 and 3.

Value 2: Time

Required. Timecode in the audio, in seconds, as a float.

Value 3: Percentage into the bar

Optional. Distance into the bar.

This lets you have “inner-bar syncpoints,” in cases where a performance is particularly expressive and does not maintain consistent rhythm within a particular bar.

The value is a number (integer or float) between 0 and 480, where 0 is the start of the bar and 480 is the end of the bar.

For example, to specify a syncpoint exactly in the middle of the bar — on beat three of a four-beat bar — use 240 (50% of 480).

If this value isn’t given, it’s assumed to be 0 (the start of the bar, aka the downbeat).

The first syncpoint must represent the start of the very first bar. But after that, you can skip bars as you see fit. The Soundslice player will extrapolate syncpoints evenly if they’re not defined for a given bar.

For example, in a piece that lasts 12 bars, starts at timecode 0.0 seconds and was recorded with a metronome at 120 bpm (2 seconds per bar, assuming 4/4 time), you can simply create the first and last syncpoints:

[[0, 0], [12, 24.0]]

Note in this example that we define a syncpoint for bar 13 (index 12), even though the music only has 12 bars — because the syncpoint maps to the end of the performance.

POST /api/v1/folders/

Creates a folder within your account’s score manager.

Use these POST parameters:

name Required The name of the folder.
parent_id Optional Integer. The folder’s parent ID. Use this if you want to nest a folder within another one.

To parse the response, check the HTTP status code. Here are the possible responses:

HTTP status 201

Success. Response is a JSON object containing one key:

  • "id" — The ID of the newly created folder.
HTTP status 422

Error. Response is a JSON object containing one key:

  • "error" — A string with an error message. This will happen if you don’t specify a name or if your parent_id is invalid.

DELETE /api/v1/folders/FOLDER_ID/

Deletes the given folder within your account’s score manager.

The folder must be empty. It can’t contain any scores or other folders.

To parse the response, check the HTTP status code. Here are the possible responses:

HTTP status 200

Success. Response is a JSON object containing one key:

  • "parent_id" — The ID of the deleted folder’s parent folder, or null if the deleted folder was in the root.
HTTP status 403

Error. You don’t own this folder.

HTTP status 422

Error. Response is a JSON object containing one key:

  • "error" — A string with an error message. This will happen if try to delete a non-empty folder.