Sheet music Embed JavaScript client

Use this JavaScript Client to interact and receive events from our Sheet Music Embed.

This API requires an API Key, please contact us for more information.


You can install our Embed Client using npm or bower:

npm install flat-embed


bower install flat-embed

Getting Started

The simplest way to get started is the pass a DOM element to our embed that will be used as container. By default, this one will completely fit its container:

<div id="embed-container"></div>
<script src="./embed.min.js"></script>
  var container = document.getElementById('embed-container');
  var embed = new Flat.Embed(container, {
    score: '<score-id-you-want-to-load>',
    embedParams: {
      appId: '<your-app-id>',
      controlsFloating: false

Embed construction

DOM element or existing iframe

When instantiating Flat.Embed, the first argument will always refer to a DOM element. It can take:

  • A DOM element (e.g. selected using document.getElementById('embed-container')).
  • The string identifier of the element (e.g. "embed-container").
  • A jQuery element (e.g. selected using $('#embed-container')). If multiple elements match the selection, the client will take the first one selected.
  • An existing embed iframe element. In this case, this one will need to have our JS API loaded using the query string jsapi=true.

If you instance different Flat.Embed for the same element, you will always get the same instance of the object.

Options and URL parameters

When instantiating Flat.Embed, you can pass options in the second parameter. In order to use the different methods available and events subscriptions, you will need to pass at least embedParams.appId.

Option Description Values Default
score The score identifier that will load initially Unique score id blank
width The width of your embed A width of the embed 100%
height The height of your embed A height of the embed 100%
embedParams Object containing the loading options for the embed Any URL parameters {}

JavaScript API


You can call the methods using any Flat.Embed object. By default, the methods (except on and off) return a Promise that will be resolved once the method is called, the value is set or get:

var embed = new Flat.Embed('container');
embed.loadFlatScore('12234').then(function () {
  console.log('Score loaded');
}).catch(function (err) {
  console.log('Error', err);

ready(): Promise<void, Error>

Promises resolved when the embed is loaded and the JavaScript API is ready to use. All the methods will implicitly use this method, so you don’t have to worry about waiting the loading before calling the different methods.

embed.ready().then(function() {
 // You can use the embed

on(event: string, callback: function): void

Add an event listener for the specified event. When receiving the event, the client will call the specified function with zero or one parameters depending of the event received.

embed.on('playbackPosition', function (position) {

off(event: string, callback?: function): void

Remove an event listener for the specified event. If no callback is specified, all the listener for the event will be removed.

function positionChanged(position) {
  // Print position

  // You can remove the listener later (e.g. here, once the first event is received)'play', positionChanged);

  // Alternatively, you can remove all the listeners for the event:'play');

// Subscribe to the event
embed.on('positionChanged', positionChanged);

loadFlatScore(id: string): Promise<void, ApiError>

Load a score hosted on Flat using its identifier. For example to load, you can call:

embed.loadFlatScore('56ae21579a127715a02901a6').then(function () {
  // Score loaded in the embed
}).catch(function (error) {
  // Unable to load the score

loadMusicXML(score: mixed): Promise<void, Error>

Load a MusicXML score, compressed (MXL) or not (plain XML):

.then(function (response) {
  return response.arrayBuffer();
.then(function (mxl) {
  return embed.loadMusicXML(mxl);
.then(function () {
  // Score loaded in the embed
.catch(function (error) {
  // Unable to load the score

loadJSON(score: object): Promise<void, Error>

Load a score using Flat’s JSON Format

.then(function (response) {
  return response.json();
.then(function (json) {
  return embed.loadJSON(json);
.then(function () {
  // Score loaded in the embed
.catch(function (error) {
  // Unable to load the score

getMusicXML(options: object): Promise<string|Uint8Array, Error>

Convert the current displayed score into a MusicXML file, compressed (.mxl) or not (.xml).

// Uncompressed MusicXML
embed.getMusicXML().then(function (xml) {
  // Plain XML file (string)

Example: Retrieve the score as a compressed MusicXML, then convert it to a Blob and download it:

// Uncompressed MusicXML
embed.getMusicXML({ compressed: true }).then(function (buffer) {
  // Create a Blob from a compressed MusicXML file (Uint8Array)
  var blobUrl = window.URL.createObjectURL(new Blob([buffer], {
    type: 'application/vnd.recordare.musicxml+xml'

  // Create a hidden link to download the blob
  var a = document.createElement('a');
  a.href = blobUrl; = 'My Music Score.mxl';
  document.body.appendChild(a); = 'display: none';;

getJSON(): object

Get the data of the score in the “Flat JSON” format (a MusicXML-like as a JavaScript object).

embed.getJSON().then(function (data) {
}).catch(function (error) {
  // Unable to get the data

getScoreMeta(): object

Get the score metadata of the hosted score. The object will have the same format that the one returned by our API GET /v2/scores/{score}.

embed.getScoreMeta().then(function (metadata) {
}).catch(function (error) {
  // Unable to get the metadata

fullscreen(state: bool): Promise<void, Error>

Display the embed in fullscreen (state = true) or return to the regular display (state = false).

embed.fullscreen(true).then(function () {
  // The score is now displayed in fullscreen

play(): Promise<void, Error>

Load the playback and play the score. () {
  // The score is playing

pause(): Promise<void, Error>

Pause the playback

embed.pause().then(function () {
  // The playback is paused

stop(): Promise<void, Error>

Stop the playback

embed.stop().then(function () {
  // The playback is stopped

Print the score

embed.print().then(function () {
  // The score is being printed (the browser opens the print prompt)
}).catch(function (error) {
  // Error when printing

getZoom(): Promise<number, Error>

Get the current zoom ration applied for the score (between 0.5 and 3).

embed.getZoom().then(function (zoom) {
  // The zoom value

setZoom(number): Promise<number, Error>

Set a new zoom ration for the display (between 0.5 and 3).

embed.setZoom(2).then(function (zoom) {
  // The zoom value applied

getAutoZoom(): Promise(<boolean, Error>)

Get the state of the auto-zoom mode. Auto-zoom is enabled by default for page mode or when the URL parameter zoom is set to auto.

This getter will return true if the auto-zoom is enabled, and false when disabled. Setting a zoom value with setZoom will disable this mode.

embed.getAutoZoom().then(function (state) {
  // The auto-zoom state

setAutoZoom(boolean): Promise(<boolean, Error>)

Enable (true) or disable (false) the auto-zoom. Auto-zoom is enabled by default for page mode or when the URL parameter zoom is set to auto. Setting a zoom value with setZoom will disable this mode.

embed.setAutoZoom(false).then(function (state) {
  // Auto-zoom mode is disabled

Events API

Events are broadcasted following actions made by the end user or you with the JavaScript API. You can subscribe to an event using the method on, and unsubscribe using off. When an event includes some data, this data will be available in the first parameter of the listener callback.

Event: scoreLoaded

This event is triggered once a new score has been loaded. This event doesn’t include any data.

Event: cursorPosition

This event is triggered when the position of the user’s cursor changes.

    "partIdx": 0,
    "staffIdx": 1,
    "voiceIdx": 0,
    "measureIdx": 2,
    "noteIdx": 1

Event: rangeSelection

This event is triggered when a range of notes is selected or the selection changed.

    "from": {
        "partIdx": 0,
        "measureIdx": 1,
        "staffIdx": 0,
        "voiceIdx": 0,
        "noteIdx": 2
    "to": {
        "partIdx": 0,
        "measureIdx": 3,
        "staffIdx": 0,
        "voiceIdx": 0,
        "noteIdx": 5

Event: fullscreen

This event is triggered when the state of the fullscreen changed. The callback will take a boolean as the first parameter that will be true if the fullscreen mode is enabled, and false is the display is back to normal (fullscreen exited).

Event: print

This event is triggered when you or the end-user prints the score. This event doesn’t include any data.

Event: play

This event is triggered when you or the end-user starts the playback. This event doesn’t include any data.

Event: pause

This event is triggered when you or the end-user pauses the playback. This event doesn’t include any data.

Event: stop

This event is triggered when you or the end-user stops the playback. This event doesn’t include any data.

Event: playbackPosition

This event is triggered when the playback slider moves. It is usually triggered at the beginning of every measure and will contain an object with information regarding the position of the playback in the score:

    "beat": "4",
    "beatType": "4",
    "tempo": 120,
    "currentMeasure": 1,
    "timePerMeasure": 2
Support Chat with us