Noteflight Client API v2.0 Developers' Guide

Noteflight® is a registered trademark of Noteflight, LLC.

Introduction

Noteflight documents may be embedded in HTML pages using the Notelight Client API, which creates one or more <iframe> elements. The API permits developers to interact with these frames using the methods described in this document, and to receive different types of events from the embedded documents.

It is also possible for web developers to create such <iframe> elements themselves dynamically, without using the API, based on this documentation. Frames created in this way can optionally be manipulated with the Client API if desired.

This document describes the the following aspects of the Client API:

• Accessing the Client API
• Creating embedded documents
• Configuring embedded documents
• Handling document events
• Calling document methods

Disclaimer

The 2.0 version of the Client API is still in an early release phase. Noteflight, LLC reserves the right to change the API features described in this document at any time, without prior notice.

The Noteflight features in this document are not covered under the standard Noteflight Terms Of Use. Non-commercial, unsupported use by anyone is permitted. Commercial use of these features with accompanying support must be directly arranged between the user and Noteflight, LLC.

To make use of the API in a web page, include the following element in your document's head:

  <script src="https://www.noteflight.com/clientapi/2.0.0/nfclient.js"></script>

After the page has loaded, you must call the NFClient.init() function to initialize the Client API before using any other functions. The init() function performs additional API initialization and then invokes an optional callback function that is passed to it. The callback function, when called, is in turn passed an object that describes the API's properties and capabilities.

  // Initialize the Noteflight client API.
  NFClient.init(function(info) {
    alert("Noteflight API is ready, version " + info.version);
  });

The API is not ready to use until the callback to the init() function has occurred. The informational object passed to the callback includes the following properties:

• version: the version number of the API

Restrictions on API Usage

Some document methods are considered content injection techniques, allowing external data to be displayed in an embedded Noteflight score. Because these methods allow the Noteflight platform to display virtually any MusicXML score from any source, the use of these methods is restricted to approved parties. Please contact Noteflight LLC to arrange the use of these methods.

There are two ways to embed Noteflight documents in a page:

• Via API calls. The easy dynamic approach is to use the Client API to create an NFClient.ScoreView object and pass it the ID of an existing DOM element of your choosing. This element will be automatically replaced with a new<iframe> that displays an embedded score. This frame has the same ID as the element it replaces. After the frame is created, the Client API automatically establishes API communication with its score for invoking methods and dispatching events.
• <iframe> HTML elements. The static approach to embedding is to include or insert your own <iframe> elements into your HTML page, with URLs for score display as described below. If you do not need to communicate with these embedded scores using methods and events, then constructing the iframe elements alone is sufficient (and you need not even include the Client API in the containing page). Otherwise you must wrap each frame in an NFClient.ScoreView object to establish communication with it.

Using the Client API for dynamic embedding

To dynamically embed a score, your page must already have an existing DOM element with a unique ID, for example:

  <div id="score1"></div>

To replace this element with a Noteflight embedded document, use the API to create a new NFClient.ScoreView object, passing the element ID of the score and a special options object that describes the score to be created:

  var options = {
    width: 800,
    height: 400
  };
  var scoreView = new NFClient.ScoreView('score1', 'fcfd6d0bc0770f67cdbe1b8129456521fec090a0', options);

The above code will replace the example <div id="score1"> element above with an 800x400 frame displaying the embedded score with Noteflight ID fcfd6d0bc0770f67cdbe1b8129456521fec090a0 from site www.noteflight.com.

The options argument is not required, although it is recommended. It may contain any of the following properties:

• width: The width of the embedded score in pixels. Default value: 800.
• height: The height of the embedded score in pixels. Default value: 600.
• host: The hostname of the Noteflight site containing the embedded score. The default hostname is "www.noteflight.com".
• protocol (Deprecated): The protocol to use for accessing the embedded score. The only allowed value is "https". Default value: "https".
• viewParams: An object containing optional configuration parameters for the embedded score. These are described in a later section of this document.

Here is an example of code constructing an embedded score that employs some of the above options in more detail. It also illustrates the attachment of an event handler function that will be called when the document is ready for API interaction.

  function handleEditorReady(event) {...}

  var options = {
    host: 'www.noteflight.com',
    width: 800,
    height: 400,
    viewParams: {
      scale: 1.5,
      role: 'template',
      app: 'html5'
    }
  }

  var scoreView = new NFClient.ScoreView('score1', 'fcfd6d0bc0770f67cdbe1b8129456521fec090a0', options);
  scoreView.addEventListener('editorReady', handleEditorReady);   // wait for ready event

Manually creating embedded documents

It is also possible to create HTML <iframe> elements that embed Noteflight documents, either by including these elements directly in a page's HTML or by using a library such as jQuery to programmatically insert them.

The URL specified by the src attribute of such a frame must have a path of the form /embed/SCORE_ID where SCORE_ID is the Noteflight ID of the score. For example, the following iframe would embed the same score as in the first example given above:

  <iframe src="https://www.noteflight.com/embed/fcfd6d0bc0770f67cdbe1b8129456521fec090a0"
          width="800" height="400" style="border: none;"></iframe>

Any configuration parameters for the embedded document can be provided as query arguments in the URL. The following example includes the same viewParams that were given in the second example from above:

  <iframe id="score1"
          src="https://www.noteflight.com/embed/fcfd6d0bc0770f67cdbe1b8129456521fec090a0?scale=1.5&role=template&app=html5"
          width="800" height="400" style="border: none;"></iframe>

It is also possible to establish API communication with an embedded document that was created by a standalone iframe element like the one shown above, by constructing an NFClient.ScoreView object referencing the frame's DOM element. In such a case, the additional scoreId and options arguments to the constructor are unnecessary:

    var frame = document.getElementById('score1');   // find the DOM element for our iframe
    var score1 = new NFClient.ScoreView(frame);      // construct a ScoreView object
    score1.addEventListener('editorReady', handleEditorReady);   // wait for ready event

This section describes the parameters that determine the configuration of embedded Noteflight documents. These may be specified in two ways: as an object provided via the viewParams creation option (for API-driven embedding) or as query arguments in an <iframe> URL (for direct management of iframes). See the preceding section for examples of both techniques.

scale

This parameter optionally provides the visual magnification factor to be applied to the score in the embedded view. A value of 1 indicates no magnification (equivalent to a Zoom value of 100%). A value of 1.5 would make the score view larger (equivalent to 150%) while a value of 0.5 would make it smaller (50%). This magnification overrides any Zoom slider settings in the regular Noteflight view of the score.

If omitted, the default factor is 1 (again, not necessarily the factor chosen in the Noteflight full page view).

playback

This optional parameter may be used to control how playback is handled in the embed, and also whether instrument sounds are downloaded or not. There are three settings for this parameter:

As can be seen from the above table, the normal setting behaves as Noteflight normally does. The silent playback mode completely disables all internal Noteflight synthesis, and is intended for cases where Noteflight is exclusively used to drive external audio playback, or when playback is to be entirely disabled. It allows faster startup of the embed because instrument sounds are not downloaded at all. The echo mode offers a compromise in which normal playback is suppressed (allowing external audio), but echo playback in response to user interaction with the score is still heard.

The audioTrack option serves to force the use of a synchronized audio track if available.

If this option is not provided, then the playback mode is determined by the default setting in the score.

role

This optional parameter specifies the user's role with respect to the document. Only two settings are permitted:

displayMode

This optional parameter specifies the mode in which the document is displayed. The following settings are permitted:

app

This parameter specifies the technology used to display the document. If omitted, the document is displayed with Flash if present, otherwise with HTML5.

watermark

This parameter shows a watermark in the embed score. The URL of the watermark has to be passed in this parameter.

watermarkScale

This parameter scales the watermark image. It has to be a number.

hidePlaybackControls

This parameter hides the playback controls

hideFullWindow

This parameter hides the full window button in the header of an embed. It also suppresses the display of links to the full score in the Sharing panel.

showScoreInfo

This parameter, if set to false, hides the score's title, supertitle, subtitle, composer, and lyricist. Default is true.

showMediaTab

Determines whether the window for synced media, if present, displays. Default is true.

Your web pages can be notified whenever one of various events occurs in an embedded Noteflight document. This section describes the basic technique for event notification, as well as including details on the various event types dispatched by Noteflight.

Using addEventListener() to handle events

To be notified of events occurring for an embedded document, you must call the addEventListener(type, handler) method on an NFClient.ScoreView object, specifying an event type and a callback function. This function will be called whenever an event of the given type occurs, with a single argument that is a JavaScript object describing the event that occurred. The special event type "any" will trigger the callback for any document event, regardless of its type.

This example illustrates a simple event handler that logs event properties to the browser console for an embedded document:

  var scoreView = new NFClient.ScoreView(elementId, scoreId);
  scoreView.addEventListener('any', function(event) {
    console.log("---- event received ----")
    for (var prop in event) {
      console.log(prop + ":", event[prop]);
    }
  });

Using removeEventListener() to handle events

To stop being notified of events occurring for an embedded document, call the removeEventListener(type, handler) method on an NFClient.ScoreView object, specifying an event type and a callback function previously provided to addEventListener():

  function handleScoreDataLoaded() {...}

  function setupScore() {
    var scoreView = new NFClient.ScoreView(elementId, scoreId);
    scoreView.addEventListener('scoreDataLoaded', handleScoreDataLoaded);
  }

  function teardownScore() {
    scoreView.removeEventListener('scoreDataLoaded', handleScoreDataLoaded);
  }

Generic Event Properties

All Noteflight event objects may contain the following properties:

Document Event Reference

type="editorReady"

Description: This event is dispatched when an embed instance has begun communication with its containing page and is able to receive method invocations. It occurs before the requested score is loaded.

type="scoreDataLoaded"

Description: This event is dispatched whenever an embed instance finishes loading a score from the Noteflight server and is ready to accept user interaction.

Document methods should not be called until this event has been received.

Event-specific properties:

type="selectionChange"

Description: This event is dispatched whenever the selection changes in an embed instance. It is dispatched regardless of whether the selection change is initiated by an API call in the page, or whether it originates from user interaction directly with the score.

Event-specific properties:

type="playbackRequest"

Description: This event is dispatched whenever the user requests playback from an embedded score. It is dispatched regardless of whether the playback is initiated by an API call in the page, or whether it originates from user interaction directly with the score. It also occurs independently of whether the playback configuration parameter enables internal Noteflight playback for a given score.

Event-specific properties:

type="playbackStop"

Description: This event is dispatched whenever playback stops in an embedded score.

Event-specific properties:

type="noteSizeChange"

Description: This event is dispatched whenever the note size changes in the embedded document.

type="pageSizeChange"

Description: This event is dispatched whenever the note size changes in the embedded document.

type="partsTransposed"

Description: This event is dispatched whenever the part transposition changes in the embedded document.

A set of JavaScript methods may be called on embedded score documents. These methods are asynchronous JavaScript functions: they never occur immediately, because they must be communicated to Noteflight within the embedded document's iframe. The results of calling a method are provided later, via one or more callback functions that are invoked after the method has completed.

After an NFClient.ScoreView object has dispatched the scoreDataLoaded event, document methods may be called on the ScoreView directly.

Invoking document methods

Document methods are regular JavaScript functions, with one very important characteristic: a call to a document method returns immediately before the method has actually performed its action. A method is never able to return a result right away. Instead, every document method returns an object called a Promise, which can accept one or more callback functions via its done() method. If you don't care about the result of the function, and you don't need to know when it has actually completed its work, you can ignore the returned Promise.

For example, let's say you want to select the first two measures in some score after it is loaded. The document method selectMeasures(0, 2) is documented as selecting the first two measures of a score. To achieve the desired results, one might do this:

  // Create an embedded score.
  var score1 = new NFClient.ScoreView('score1', scoreId);

  // Create an event handler that selects the first two measures of a score
  function selectOnLoad(evt) {
    score1.selectMeasures(0, 2);
  }

  // After the score loads up, select its first two measures.
  score1.addEventListener('scoreDataLoaded', selectOnLoad);

Waiting for document methods to return

As mentioned above, all document methods are asynchronous. To wait for a method to complete or to obtain its return value if it has one, call done() on the Promise object returned by the method and pass a callback that will receive the return value of the method (if any):

  // Create an embedded score.
  var score1 = new NFClient.ScoreView('score1', scoreId);

  // Displays the note size of a loaded score
  function showNoteSize() {
    var promise = score1.getNoteSize();
    promise.done(function(size) {
      alert('The note size is: ' + size);
    });
  }

Promises are often used immediately to specify a callback and then discarded. So it's common to see the above code in this more abbreviated form:

  // Displays the note size of a loaded score
  function showNoteSize() {
    score1.getNoteSize().done(function(size) {
      alert('The note size is: ' + size);
    });
  }

Document function reference

selectMeasures(startIndex, endIndex)

Description: Causes a contiguous run of measures in the document to be selected, starting with the measure at startIndex and ending at the measure just before endIndex. If endIndex is -1, it is interpreted as the number of measures in the score.

Example Code:

  s.selectMeasures(2, 3);   // select the third measure of the score
  s.selectMeasures(0, 5);   // select the first five measures of the score
  s.selectMeasures(0, -1);   // select the entire score

Parameters:

Return Value: None.

selectRange(startIndex, startOffset, endIndex, endOffset[, staffIndices])

Description: Causes a contiguous time range in the document to be selected, covering some or all of the staves in the document. The starting point of the range is defined by startIndex and startOffset, while the end is defined by endIndex and endOffset. The optional staffIndices argument allows specification of a specific set of staves to be selected.

Example Code:

  s.selectRange(2, 0, 2, 1);   // select the first quarter note of the third measure, in all scores

  s.selectRange(2, 0, 3, 4, [1, 2]);   // select from the start of the third measure
                                       // through the 4th beat of the 4th measure in the
                                       // second and third staves only.

Parameters:

Return Value: None.

selectFragment(fragment)

Description: Causes a set of objects in the document to be selected according to the URI fragment identifier given. The meanings of these fragment IDs are not documented, but they are guaranteed to correspond to the fragment IDs used for deep links that are generated using the "Link URL To Selection" command in the Score Editor. They also correspond to the fragment IDs passed in selection-change event callbacks from an embed.

Example Code:

  s.selectFragment("#m2");   // select a previously determined fragment of the score

Parameters:

Return Value: None.

clearSelection()

Description:Deselects all selected objects, ranges or measures in the score.

Example Code:

  s.clearSelection();

Parameters: None.

Return Value: None.

getScore()

Description: Returns a JSON-like structure describing the entire score in the embed. For modifiable embeds, permits programmatic access to their contents.

The returned data is a copy of the score in the embed; it has no live connection to the actual score. Therefore, modifying the returned objects has no effect on the embed instance's score.

Example Code:

  s.getScore().done(function(scoreData) {
    // do something with the returned score data
  });

Parameters: None.

Return Value: A JavaScript Object with the following property structure:

Staff objects have this structure:

Measure objects have this structure:

Note set objects have this structure:

Note objects have this structure:

getMusicXML()

Description:Returns the score contents in the embed client as a MusicXML string.

Usage Restrictions:Unless used by the score's author, this function requires the score to allow copy and export.

Parameters: None.

Return Value: A MusicXML string.

getNoteflightXML()

Description:Returns the score contents in the embed client as a NoteflightXML string.

Usage Restrictions:Unless used by the score's author, this function requires the score to allow copy and export.

Parameters: None.

Return Value: A NoteflightXML string representation of the score.

playFromSelection()

Description: Begins playback from the measure containing the first selected object in the score.

Example Code:

  s.playFromSelection();

Parameters: None.

Return Value: None.

playFromMeasure(index)

Description: Begins playback from the measure whose zero-based index is index.

Example Code:

  s.playFromMeasure(8);  // Begin playback at the ninth measure of the score

Parameters:

Return Value: None.

seekTo(time)

Description: Moves synced media playback to time in seconds. Decimals are allowed.

Example Code:

  s.seekTo(20.5);  // Moves the synced media playback to time index 20.5 seconds.

Parameters:

Return Value: None.

muteSyncedMedia

Description: If called, this will mute the audio for any synced media. It's safe to call even if there is no synced media.

Example Code:

  s.muteSyncedMedia();

Return Value: None.

unmuteSyncedMedia

Description: If called, this will unmute the audio for any synced media. It's safe to call even if there is no synced media.

Example Code:

  s.unmuteSyncedMedia();

Return Value: None.

stopPlayback()

Description: Stops any playback currently in progress.

Example Code:

  s.stopPlayback();

Parameters: None.

Return Value: None.

showPositionCursor(index, offset)

Description: Displays a vertical position cursor at the given quarter-note offset within the given measure.

Example Code:

  s.showPositionCursor(8, 0.5);  // Display the cursor one 8th-note after the start of bar 9

Parameters:

Return Value: None.

hidePositionCursor()

Description: Hides any currently visible position cursor.

Example Code:

  s.hidePositionCursor();

Parameters: None.

Return Value: None.

setAdvanceAfterNoteEntry(flag)

Description: Controls the behavior whereby Noteflight automatically advances the note entry location after a note is entered (the default, corresponding to an argument of true). This can be selectively disabled in situations where the focus is on chord entry.

Example Code:

  s.setAdvanceAfterNoteEntry(false);   // disable the default position-advance behavior

Parameters:

Return Value: None.

setPlaybackMode(mode)

Description: Changes the playback mode setting after an embed has started and loaded its score.

Example Code:

  s.setPlaybackMode("silent");   // disable playback of the score

Parameters:

Return Value: None.

setVisibleParts(partIndices)

Description: Determines the set of parts that will be shown in the embed.

Example Code:

  s.setVisibleParts([0,1]);   // Show only the first and second parts in the score
  s.setVisibleParts([]);      // Special case: show all parts in the score

Parameters:

Return Value: None.

loadMusicXML(xmlString)

Description: Loads an entire MusicXML score into the embed client.

Usage Restrictions: This function is only available to communities that are enabled for content injection into Noteflight embeds.

Parameters:

Return Value: None.

loadNoteflightXML(xmlString)

Description: Loads an entire NoteflightXML score into the embed client.

Usage Restrictions: This function is only available to communities that are enabled for content injection into Noteflight embeds.

Parameters:

Return Value: None.

pasteNoteSets(noteSets, staffIndex, measureIndex, offset)

Description: Pastes a sequence of note sets into the document at a given staff, measure and metrical offset. Notes will be automatically split and tied as needed to fit the metrical structure of the score, which will also extend to accommodate the pasted sequence. Accidentals will be adjusted automatically.

Usage Restrictions: This function is only available to communities that are enabled for content injection into Noteflight embeds.

Parameters:

Return Value: None.

deleteSelection()

Description:Deletes any selected objects, staves or measures from the score. Note that attempting to delete the entire score will retain a single empty measure at the start of the score.

Example Code:

  s.selectMeasures(0, -1); s.deleteSelection();   // clears the entire score

Parameters: None.

Return Value: None.

getParts()

Description: Supplies information about the parts in the score.

Example Code:

  s.getParts().done(function(parts) {
    var part_0 = parts[0];
    alert("part 0 is named " + part_0.name);
  });

Parameters: None.

Return Value: An array of JavaScript Objects, each of which has the following property structure:

setPartProperties(partIndex, properties)

Description: Sets properties of a part in the score.

Example Code:

  s.setPartProperties(0, {visible:false}); //hide part 0
  //transpose part 1 down a perfect fourth and show it
  s.setUseConcertPitch(false);
  s.getParts().done(function(parts) {
    var p1 = parts[1];
    p1.transposition -= 5;
    p1.visible = true;
    s.setPartProperties(1, p1);
  });

Parameters:

Return Value: None.

setZoom(zoomFactor)

Description: Sets the zoom factor.

Example Code:

  s.setZoom(2) //zoom in
  s.setZoom(1) //back to normal

Parameters:

Return Value: None.

getZoom()

Description: Gets the zoom factor.

Example Code:

  s.getZoom().done(function(zoom) {
    s.setZoom(zoom * 2);  // Increase zoom by a factor of 2
  });

Parameters: None

Return Value: A float representing the current zoom factor.

setMasterGain(masterGain)

Description: Sets the master gain.

Example Code:

  s.setMasterGain(2) //volume up

Parameters:

Return Value: None.

getMasterGain()

Description: Gets the master gain.

Example Code:

  s.getMasterGain().done(function(gain) {...});

Parameters: None

Return Value: A float indicating the current master gain.

getKeySignature()

Description: Returns the key signature of the embed's score.

Example Code:

  s.getKeySignature().done(function(gain) {...});

Parameters: None.

Return Value: A JavaScript Object with the following property structure:

getTranspositions()

Description: Returns an array of key signatures for each half-step transposition from concert pitch.

Example Code:

  s.getTranspositions().done(function(transpositions) {
    var upPerfectFifth = transpositions[7];
    // ...
  });

Parameters: None.

Return Value: A JavaScript Array of objects with a key signature property structure. Additionally an optional alternateKey property may be present, pointing to an alternate, enharmonic key signature that may be obtained by setting the alternateKey option when calling setTransposeParts().

getInitialTempo()

Description: Gets the initial tempo of the piece.

Parameters: None

Return Value: An integer indicating the initial tempo of the piece in beats per minute.

setTransposeParts(transposeParts)

Description: Sets whether to show parts' transpositions.

Example Code:

  s.setTransposeParts(false) //use concert pitch

Parameters:

Return Value: None.

getTransposeParts()

Description: Gets whether the parts are being shown transposed.

Parameters: None

Return Value: A boolean indicating whether parts are being shown transposed.

transpose(options)

Description: Applies a global transposition in semitones to the whole score or to selected parts.

Example Code:

  s.transpose({semitones: 7}) //transpose up a perfect fifth

Option Values (properties of the options Object parameter):

Return Value: None.

setNoteSize(noteSize)

Description: Sets the note size, in points.

Example Code:

  s.setNoteSize(8);

Parameters:

Return Value: None.

getNoteSize()

Description: Gets the note head size.

Parameters: None

Return Value: An integer indicating the current note head size, in points.

getPlaybackSpeed()

Description: Gets the playback speed.

Parameters: None

Return Value: A float indicating the current playback speed adjustment, as log₂(k) where k is the speed scaling factor. Thus 0 indicates no speed adjustment, -1 is 50%, and +1 is 200%.

setPlaybackSpeed(speedGain)

Description: Sets the playback speed.

Example Code:

  s.setPlaybackSpeed(1); // double speed

Parameters:

Return Value: None.

getPlaybackTempo()

Description: Gets the playback tempo of the initial measure of the score.

Parameters: None

Return Value: A tempo in beats per minute

setPlaybackTempo(tempo)

Description: Sets the playback tempo of the initial measure of the score.

Example Code:

  s.setPlaybackTempo(120);

Parameters:

Return Value: None.

setBackground(imageUri)

Description: Sets a background image for the score. If smaller than the score, the image will be tiled.

Note: in order to load an image from your a domain, the domain must allow cross-domain image data by serving a crossdomain.xml from its root. See Adobe's documentation for more detail.

Example Code:

  s.setBackground("https://your.domain.here/path/to/img.jpg");

Parameters:

Return Value: None.

getPlaybackMode()

Description: Returns whether the score is playing from synthesized sound or a synchronized track.

Parameters: None.

Return Value: A string: "normal" for internal synthesis, "audioTrack" for a synchronized track, "silent" for no playback, or "echo" for playing selection only.

printScore()

Description: Prints the score displayed in the client.

Example Code:

  s.printScore({usePrinter: true});

Return Value: None.

© Copyright Noteflight, LLC. All Rights Reserved.

Noteflight® is a registered trademark of Noteflight, LLC.