Overview

The API is built with the design principles of REST in mind, exposing resources which can be manipulated using the HTTP methods GET, POST, PUT and DELETE. Every call requires a valid Consumer Key to be passed with all requests. You can request a Consumer Key via email: api@musescore.com. Once you have a key, you can pass it as a parameter into your requests. With your consumer key, you can access all the public resources. To access private resources, you need to authenticate the user with OAuth.

Endpoint

All the resources on MuseScore.com are accessible via the following endpoint http://api.musescore.com/services/rest

Return format

The return format for every call is specified as an extension. MuseScore.com currently supports XML, JSON and JSONP.

File Urls

Score Files URLs

You can construct the source URL to score files once you know its ID and its secret, as returned by many API methods.

The URL takes the following format: http://static.musescore.com/{id}/{secret}/score.{extension} Where extension can be anything in pdf, mid (General MIDI), mxl (Compressed MusicXML), mscz (MuseScore file), mp3.

For sets of files, such as PNGs the URL takes the following format: http://static.musescore.com/{id}/{secret}/score_{page_number}.png Where {page_number} is a zero-indexed integer.

A thumbnail is available for each score at: http://static.musescore.com/{id}/{secret}/thumb.png

PNG files are transparent and with 100dpi resolution.

Authentication

Public resources

A number of resources do not require a user to be a authenticated. Only the application needs a valid Consumer Key. You can request a Consumer Key via email: api@musescore.com. Once you have a key, you can pass it as a parameter in a cURL request, or connect to MuseScore.com using just the key.

Examples:

Using cURL: $ curl 'http://api.musescore.com/services/rest/score?oauth_consumer_key=your_consumer_key

Note that this won’t let you access protected resources. To do that, you’ll need OAuth.

OAuth

To access protected resources you must authenticate with MuseScore.com using OAuth 1.0, a standard to give third party applications the authority to act on a user’s behalf.

If you’re not already familiar with OAuth, please read more on oauth.net, where there is also a Getting started.

MuseScore.com API is currently private. If you need an OAuth keypair let us know

Terminology

Service Provider
MuseScore.com
Consumer
Your Application
User
The user registered with MuseScore.com using your application

Endpoints

Function Endpoint
Get a request token http://api.musescore.com/oauth/request_token
User authorization page http://musescore.com/oauth/authorize
Get an access token http://api.musescore.com/oauth/access_token

The Score object

The score object is represented in XML or in JSON and GET calls to the MuseScore.com API will send back a single object or an array.

JSON example

{
   "id":"1111",
   "vid":"152152",
   "dates":{
      "posted":"1370593443",
      "lastupdate":"1370593602",
      "revised":"1370593603"
   },
   "secret":"b364acd291",
   "uri":"https:\/\/api.musescore.com\/services\/rest\/score\/1111",
   "permalink":"https:\/\/musescore.com\/score\/1111",
   "custom_url":"https://musescore.com\/nicolas\/great-score",
   "user":{
      "uid":"400",
      "username":"Mozart",
      "custom_url":"https://musescore.com\/nicolas"
   },
   "status":"ready",
   "sharing":"public",
   "comment_count":"0",
   "favoriting_count":0,
   "user_favorite":0,
   "view_count":"14",
   "playback_count":"6",
   "download_count":4,
   "genre":"",
   "format":"",
   "tags":"tag1, tag2",
   "license":"publicdomain",
   "language":null,
   "title":"Wilder Reiter",
   "description":"Album f\u00fcr die Jugend (Album for the Young), Op. 68, was composed by Robert Schumann in 1848 for his three daughters. The album consists of a collection of 43 short works. The Wild Rider (Wilder Reiter) in A minor is more commonly known in English as The Wild Horseman.",
   "metadata":{
      "title":"My First score",
      "subtitle":null,
      "composer":"WA Mozart",
      "poet":null,
      "pages":"9",
      "measures":"102",
      "lyrics":"0",
      "chordnames":"0",
      "keysig":"0",
      "duration":"474",
      "dimensions":"210x297",
      "parts":[
         {
            "part":{
               "name":"Flute",
               "program":"73"
            }
         },
         {
            "part":{
               "name":"Piano",
               "program":"0"
            }
         }
      ]
   }
}
id
The score id, an integer. It’s a unique identifier for the score
vid
Version id of the score, an integer. It will change if the score is updated.
posted
The date when the score has been posted in seconds, unix time.
lastupdate
The date when score was last updated. The score file has changed or any metadata such as title.
revised
The date when score file was last updated.
secret
The secret of the score, a unique string
uri
API endpoint for this score
permalink
Permalink to the score page on MuseScore.com, suitable for human
custom_url
the current nice url for the score
uid
The unique identifier of the owner of this score
username
The user screen name of the owner of this score
custom_url
the current nice url for the user
status
The status of the score, currently only “ready” scores are presented through the API
sharing
either public or private
comment_count
Number of comments on this score
favoriting_count
Number of users who favorited this score
user_favorite
If a user is authentified, 1 if the scores if favorited. Otherwise 0.
view_count
Number of views for this score
playback_count
Number of plays for this score
download_count
Number of downloads for this score

genre :

format :

tags
The comma separated list of tags
license
The license of the score * all-rights-reserved * publicdomain * cc-zero * cc-by * cc-by-sa * cc-by-nd * cc-by-nc * cc-by-nc-sa * cc-by-nc-nd
language
Language of the lyrics as provided by the user. It’s a 2 letters language code, null or empty if the user did not provide it
title
Title of the score, as filed by the user when uploading the score. This title can be different from the one in metadata
description
Description of the score, as file by the user when uploading or updating the score

Metadata

Metadata are automatically extracted from the score file

title
The first title text of the score file
subtitle
The first subtitle text in the score file
composer
The first composer text in the score file
poet
The first poet/lyricist text in the score file
pages
The number of pages in the score, when the score is displayed as the user sees it in MuseScore
measures
The number of measures in the score
lyrics
0 if the score has no lyrics, 1 otherwise
chordnames
0 if the score has no chord names, 1 otherwise
keysig
The first key signature of the score. [-7;+7] it’s the number of flat/sharps for the first key signature, first staff of the score.
duration
duration of the score in seconds, including repeats
dimensions
paper size of the score in mm and formatted widthxheight
parts
An array describing the parts of the score. Each part has a name and a midi program number, zero based indexed.

GET _posts/2012-12-25-search-scores.md Search scores

This method will retrieves all scores or search for scores with the following criteria

Request

An unauthenticated request shows only public scores while an authenticated one will show all the scores the logged user has access to.

Filters

Name Type Description
text string a string to search for (use double quotes to do literal string matching)
part integer [-1;-128] a midi program number, zero based indexed. Drumset is 128 and -1 is undefined
parts integer the number of parts in the score. 1 for solo scores. 2 for duo etc…
language 2 letters language code Lyric language
page integer Zero based index of the result page. Pages contain 20 results.
license license to_modify_commercially, to_use_commercially, to_share, to_play (default)

Sort criteria

A sort parameter can be used to sort the scores according to one of the following criteria.

Name Description
view_count sort the score with the most viewed one first
date_uploaded most recent score first
comment_count sort the score with the most commented one first
relevance (default) sort the score with the most relevant according to the filters first

Response

An array of score objects.

Example

  • Piano + Flute http://api.musescore.com/services/rest/score.xml?oauth_consumer_key=your_consumer_key&part=0,73

  • Sorted by view count http://api.musescore.com/services/rest/score.xml?oauth_consumer_key=your_consumer_key&part=0,73&sort=view_count

  • Filtering by licence http://api.musescore.com/services/rest/score.xml?oauth_consumer_key=your_consumer_key&license=to_modify_commercially

GET _posts/2012-12-23-get-a-score.md Get a score

Retrieves a given score.

Parameters

Name Type Description
id integer unique id of the score
secret string optional

If the user is authenticated, the secret is not needed to access public resources. See OAuth for authentication.

Response

A score object

Example

$ curl http://api.musescore.com/services/rest/score/583.xml?oauth_consumer_key=your_consumer_key
< HTTP/1.1 200 OK

GET _posts/2012-12-22-get-a-score-time.md Get score time info

Send back time position in the audio or midi file for each measure.

Parameters

Name Type Description
id integer unique id of the score
secret string optional

If the user is authenticated, the secret is not needed to access public resources. See OAuth for authentication.

Response

$ curl http://api.musescore.com/services/rest/score/583/time.xml?oauth_consumer_key=your_consumer_key
< HTTP/1.1 200 OK
<?xml version="1.0" encoding="utf-8"?>
<events is_array="true">
    <event>
      <elid>0</elid>
      <position>0</position>
    </event>
    <event>
      <elid>1</elid>
      <position>250</position>
    </event>
    <event>
       <elid>2</elid>
       <position>1159.090909090909</position>
    </event>
   ...
 </events>

elid is the zero based index of the measure. The same id is used in the space representation. position is a time position in ms and is in sync with the MP3 and the MIDI file provided by the API

GET _posts/2012-12-20-get-a-score-space.md Get score space info

Send back the bounding boxes around the measures in the graphical representation. A scaling factor may apply. (12 for PNG).

Parameters

Name Type Description
id integer unique id of the score
secret string optional

If the user is authenticated, the secret is not needed to access public resources. See OAuth for authentication.

Response

$ curl http://api.musescore.com/services/rest/score/583/space.xml?oauth_consumer_key=your_consumer_key
< HTTP/1.1 200 OK
<?xml version="1.0" encoding="utf-8"?>
  <elements is_array="true">
    <element>
       <id>0</id>
       <x>1183.1868963254592</x>
       <y>2356.5019173228343</y>
       <sx>1014.2236806299212</sx>
       <sy>1321.9491732283464</sy><page>0</page>
    </element>
    <element><id>1</id>...</element>
  </elements>

id is the unique id of the measure x and y are the coordinates of the measures in the page. sx and sy are the width and the height of a measure.

POST _posts/2012-12-02-post-a-score.md Post a score

Creates a score belonging to the logged in user. Since a file asset is attached the request must be a multipart/form-data request. This method is only available if the user is logged in. See Authentication

Parameters

Name Type Description
score_data file, required The score file, mscz format only
title string, required Title of the score
description string Description for the score
private boolean 1: private ; 0: public
license string all-rights-reserved, cc-by, cc-by-sa, cc-by-nd, cc-by-nc, cc-by-nc-sa, cc-by-nc-nd, publicdomain, cc-zero
tags string comma separated list of tags

DELETE _posts/2012-12-01-delete-a-score.md Delete a score

This method allows the user to delete a score.

Parameters

Name Type Description
id integer unique id of the score

Response

$ curl 'http://api.musescore.com/score/17?oauth_consumer_key=your_consumer_key' -X DELETE
< HTTP/1.1 200 OK

The User object

The user object is represented in XML or in JSON and GET calls to the MuseScore.com API will send back a single object or an array.

JSON example

{
   "id":"5",
   "name":"Nicolas",
   "permalink":"http:\/\/musescore.com\/nicolas",
   "uri":"http:\/\/api.musescore.com\/services\/rest\/user\/5"
   "avatar_url":"http:\/\/musescore.com\/files\/imagecache\/avatar-48\/pictures\/picture-1.jpg"
}
id
The user id, an integer. It’s a unique identifier for the user
name
User name on MuseScore.com
uri
API endpoint for this user
permalink
Permalink to the user page on MuseScore.com, suitable for human
avatar_url
link to the avatar of the user as displayed on her profile, always 48x48

GET _posts/2011-12-23-get-me.md Get the current user

Retrieves the current user when logged in.

Parameters

No parameter

the user has to be authenticated, for this call to work. See Authentication.

Response

A user object

Example

$ curl 'http://api.musescore.com/services/rest/me.xml?oauth_consumer_key=your_consumer_key'
< HTTP/1.1 200 OK
<?xml version="1.0" encoding="UTF-8"?>
<user>
  <id>5</id>
  <name>toto</name>
  ...
</user>

GET _posts/2011-12-22-get-a-user.md Get a user

Retrieves a given user.

Parameters

Name Type Description
id string unique id of the user to retrieve

Response

A user object

Example

$ curl http://api.musescore.com/services/rest/score/583.xml?oauth_consumer_key=your_consumer_key
< HTTP/1.1 200 OK

GET _posts/2011-12-21-get-a-user-score.md Search user scores

Retrieves the list of scores published by a given user. This resource is searchable just like /score

Parameters

Name Type Description
id string Unique id of the user

If the user is authenticated, the call will also list the private scores of this user.

Response

An array of score objects

Example

$ curl http://api.musescore.com/services/rest/score/583.xml?oauth_consumer_key=your_consumer_key
< HTTP/1.1 200 OK

GET _posts/2010-12-27-resolve.md Resolve a resource

The resolve resource allows you to lookup and access API resources when you only know the MuseScore.com URL.

$ curl http://api.musescore.com/services/rest/resolve.xml?url=http://musescore.com/nicolas/scores/583&oauth_consumer_key=your_consumer_key
< HTTP/1.1 302 Moved Temporarily
< Location: http://api.musescore.com/services/rest/score/583.xml?oauth_consumer_key=your_consumer_key

This request will resolve and redirect to the API resource URL for the score http://musescore.com/nicolas/scores/583. Just follow the redirect and you will get the representation you want.

The resolver supports URLs for:

  • Score
  • User

Oembed API

oEmbed is an open standard for embedding external content into a website. In the case of MuseScore.com, it will embed the score player for a given score. You can use any URL of any score to obtain the embed code for it. To find out more about oEmbed, view the spec or check out Webmonkey’s Get Started With oEmbed tutorial.

API Endpoints

You can use the API endpoint to request the embed code for a score from its URL. The response format can be either xml, json or js (for JSONP).

http://musescore.com/oembed/endpoint

MuseScore.com currently supports embedding of scores only. The accepted URL schemes are:

http://musescore.com/* http://mus.cr/*

Discovery

No discovery yet

Arguments

All arguments are sent as query parameters and must be urlencoded (as per RFC 1738).

Argument Definition
url The MuseScore.com URL for a score.
format (optional) Either json, xml or jsonp. Defaults to json.
maxwidth (optional) The maximum width for the player. Defaults to 100%
maxheight (optional) The maximum height for the player. Defaults to 394.
callback (optional) In case you request a jsonp response by setting format=jsonp, this callback function will be executed

Example Call

http://musescore.com/oembed/endpoint?url=http://musescore.com/nicolas/scores/439&format=xml

A simple example, using jQuery, is available. Check and fork the code.

Example Responses

As mentioned above, the default width for the player is 100%. The current oembed specification requires the returned data to specify the width in pixels, which is not practical. Therefore if you did not specify a maxwidth the returned width parameter will be 100%. If you require the width to be correctly set to an integer, please provide a maxwidth.

XML

Call:

http://musescore.com/oembed/endpoint?url=http://musescore.com/nicolas/scores/439&format=xml

Response:

<oembed>
  <type>rich</type>
  <version>1.0</version>
  <provider_name>MuseScore.com</provider_name>
  <width>100%</width>
  <height>394</height>
  <provider_url>http://musescore.com</provider_url>
  <html>
  <iframe width="100%" height="394" src="http://musescore.com/node/439/embed" frameborder="0"></iframe><span><a    href="http://musescore.com/nicolas/scores/439">Héléna</a> by <a href="http://musescore.com/user/5">Nicolas</a></span>
  </html>
  <title>Héléna</title>
  <author_name>Nicolas</author_name>
  <author_url>http://musescore.com/nicolas</author_url>
  <original_url>http://musescore.com/nicolas/scores/439</original_url>
</oembed>

JSON

Call:

http://musescore.com/oembed/endpoint?url=http://musescore.com/nicolas/scores/439&format=json

Response:

{"type":"rich",
  "version":"1.0",
  "provider_name":"MuseScore.com",
  "width":"100%",
  "height":394,
  "provider_url":"http:\/\/musescore.com",
  "html":"<iframe width=\"100%\" height=\"394\" src=\"http:\/\/musescore.com\/node\/439\/embed\" frameborder=\"0\"><\/iframe><span><a href=\"http:\/\/musescore.com\/nicolas\/scores\/439\">H\u00e9l\u00e9na<\/a> by <a  href=\"http:\/\/musescore.com\/user\/5\">Nicolas<\/a><\/span> ",
  "title":"Héléna",
  "author_name":"Nicolas",
  "author_url":"http:\/\/musescore.com\/nicolas",
  "original_url":"http:\/\/musescore.com\/nicolas\/scores\/439"}

JSONP

Call:

http://musescore.com/oembed/endpoint?url=http://musescore.com/nicolas/scores/439&format=jsonp&callback=MyCallback

Response:

MyCallback({"type":"rich",
  "version":"1.0",
  "provider_name":"MuseScore.com",
  "width":"100%",
  "height":394,
  "provider_url":"http:\/\/musescore.com",
  "html":"<iframe width=\"100%\" height=\"394\" src=\"http:\/\/musescore.com\/node\/439\/embed\" frameborder=\"0\"><\/iframe><span><a href=\"http:\/\/musescore.com\/nicolas\/scores\/439\">H\u00e9l\u00e9na<\/a> by <a  href=\"http:\/\/musescore.com\/user\/5\">Nicolas<\/a><\/span> ",
  "title":"Héléna",
  "author_name":"Nicolas",
  "author_url":"http:\/\/musescore.com\/nicolas",
  "original_url":"http:\/\/musescore.com\/nicolas\/scores\/439"});