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 get a Consumer Key by registering your app. 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 get a Consumer Key by registering your app. 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

FunctionEndpoint
Request tokenhttp://api.musescore.com/oauth/request_token
Authorize tokenhttp://musescore.com/oauth/authorize
Access tokenhttp://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"
      },
      "secret":"b364acd291",
      "uri":"http:\/\/api.musescore.com\/services\/rest\/score\/1111",
      "permalink":"http:\/\/musescore.com\/score\/1111",
      "user":{
         "uid":"400",
         "username":"Mozart"
      },
      "status":"ready",
      "sharing":"public",
      "comment_count":"0",
      "favoriting_count":0,
      "view_count":"14",
      "playback_count":"6",
      "download_count":4,
      "genre":"",
      "format":"",
      "license":"all-rights-reserved",
      "language":null,
      "title":"Title of my score",
      "description":"Galactic score",
      "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.
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
uid
The unique identifier of the owner of this score
username
The user screen name of the owner of this score
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
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 :

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 /score 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

NameTypeDescription
textstringa string to search for (use double quotes to do literal string matching)
partinteger[-1;-128] a midi program number, zero based indexed. Drumset is 128 and -1 is undefined
partsintegerthe number of parts in the score. 1 for solo scores. 2 for duo etc
language2 letters language codeLyric language
pageintegerZero based index of the result page. Pages contain 20 results.
licenselicenseto_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.

NameDescription
view_countsort the score with the most viewed one first
date_uploadedmost recent score first
comment_countsort 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=musichackday&part=0,73

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

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

GET /score/{id} Get a score

Retrieves a given score.

Parameters

NameTypeDescription
idintegerunique id of the score
secretstringoptional

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=musichackday
< HTTP/1.1 200 OK

GET /score/time/{id} Get score time info

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

Parameters

NameTypeDescription
idintegerunique id of the score
secretstringoptional

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 /score/space/{id} 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

NameTypeDescription
idintegerunique id of the score
secretstringoptional

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 /score 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

NameTypeDescription
score_datafile, requiredThe score file, mscz format only
titlestring, requiredTitle of the score
descriptionstringDescription for the score
privateboolean1: private ; 0: public
licensestringall-rights-reserved, cc-by, cc-by-sa, cc-by-nd, cc-by-nc, cc-by-nc-sa, cc-by-nc-nd, publicdomain, cc-zero
tagsstringcomma separated list of tags

DELETE /score/{id} Delete a score

This method allows the user to delete a score.

Parameters

NameTypeDescription
idintegerunique 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"
}
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

GET /me 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 /user/{id} Get a user

Retrieves a given user.

Parameters

NameTypeDescription
idstringunique id of the user to retrieve

Response

A user object

Example

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

GET /user/{id}/score Search user scores

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

Parameters

NameTypeDescription
idstringUnique 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=musichackday
< HTTP/1.1 200 OK

GET /resolve 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).

ArgumentDefinition
urlThe 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"});