Noteflight Client API v2.0 Developers' Guide

October 10, 2013
© Copyright 2013 Noteflight, LLC. All Rights Reserved.

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:

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.

Accessing the Client API

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:

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.

Creating embedded documents

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

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:

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

Configuring embedded documents

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:

Mode Purpose Score playback Echo notes on selection? Instrument sounds loaded?
normal Internal wavetable synthesis, combined with wavetable selection feedback for interaction with score objects or note entry. Wavetable Yes Yes
audioTrack Synchronized audio track playback inside Noteflight (if available), combined with wavetable selection feedback for interaction with score objects or note entry. Synchronized audio Yes Yes
echo Audio playback outside Noteflight, combined with wavetable selection feedback for interaction with score objects or note entry. None Yes Yes
silent Audio playback outside Noteflight and/or faster download due to no instrument or audio loading. None No No

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:

Role Permissions
reader
User may view and select objects in the score (the default setting).
template
User may view and freely modify the score, but may not save it.

displayMode

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

Value Layout
strip
The score is displayed as a horizontal scrolling strip.
paginated
The score is displayed as a vertically scrollable sequence of numbered pages.
flow (HTML5 editor only)
The score is displayed as a vertically scrollable sequence of systems without page boundaries, fit to the embed's width.

app

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

Value Layout
flash
The score is displayed using Noteflight in the Adobe Flash Player.
html5
The score is displayed using Noteflight in HTML5.

watermark

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

Value Layout
https://mySite/myImage.png
The image 'myImage.png' will be displayed as a watermark.

watermarkScale

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

Value Layout
0.7
The watermark will be scaled at the 70% of the page.

hidePlaybackControls

This parameter hides the playback controls

Value Layout
false
Shows the playback controls as always. This is the value by default.
true
Hides the playback controls. The score will not have any 'play' button.

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.

Value Layout
false
Shows the Full Window control as always. This is the value by default.
true
Hides the Full Window control.

Handling document events

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:

Name Type Description
type String A string value that identifies the kind of event that was dispatched.
target ScoreView The NFClient.ScoreView object that generated this event.
embedId String (optional) If present, this corresponds to the DOM element ID of the frame that was created to hold the embedded document.

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:

Name Type Description
scoreId String The Noteflight score identifier for the loaded score.

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:

Name Type Description
kind String If this property is absent, indicates that there is no active selection. Otherwise, has one of the following values:
  • object: one or more individual objects are selected
  • measure: one or more measures are selected
  • range: a time range is selected in some set of staves
startIndex integer The zero-based index of the measure at the start of the selected range.
startOffset float The offset in quarter notes from the beginning of the start measure at which the range begins. This value may range from zero to the number of quarter notes in the measure.
endIndex integer The zero-based index of the measure which includes the end of the selected range. When kind has the value "measure" this will be a exclusive end index analogous to the argument to selectMeasures().
endOffset float The offset in quarter notes from the beginning of the end measure at which the range ends. This offset may range from zero to the number of quarter notes in the measure.
staffIndices Array Optional property only present when kind has the value "object" or "range", providing an array of zero-based staff indices, counting down from the topmost staff in the score. If given, only the given staves are included in the selection.
fragment String A deep-linking fragment representing the selection which can be passed to the selectFragment() function if desired.

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:

Name Type Description
index integer The zero-based index of the measure at which playback should start.
offset float The offset in quarter notes from the beginning of the start measure at which playback is to start. This value may range from zero to the number of quarter notes in the measure.

type="playbackStop"

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

Event-specific properties:

Name Type Description
index integer The zero-based index of the measure at which playback should start.
offset float The offset in quarter notes from the beginning of the start measure at which playback is to start. This value may range from zero to the number of quarter notes in the measure.

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.

Calling document methods

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:

Name Type Description
startIndex integer The inclusive zero-based index of the measure that begins the selected range.
endIndex integer If positive, the exclusive zero-based index of the measure following the selected range. If -1, this parameter is taken as the number of measures in the score, as a convenience for selecting the entire score.

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:

Name Type Description
startIndex integer The zero-based index of the measure at the start of the selected range.
startOffset float The offset in quarter notes from the beginning of the start measure at which the range begins. This value may range from zero to the number of quarter notes in the measure.
endIndex integer The zero-based index of the measure which includes the end of the selected range.
endOffset float The offset in quarter notes from the beginning of the end measure at which the range ends. This offset may range from zero to the number of quarter notes in the measure.
staffIndices Array Optional argument providing an array of zero-based staff indices, counting down from the topmost staff in the score. If given, only the given staves are included in the selection.

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:

Name Type Description
fragment string A URI fragment identifier encoding a Noteflight selection. Must begin with "#".

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:

Name Type Description
staves Array an array of Objects representing each staff in the score

Staff objects have this structure:

Name Type Description
measures Array an array of Objects representing the measures in each staff

Measure objects have this structure:

Name Type Description
noteSets Array an array of Objects representing the note sets in each measure. Each note set represents a rest, a note or a chord in the measure.

Note set objects have this structure:

Name Type Description
notes Array an array of Objects representing the notes in a note set. If empty, this indicates that the note set is a rest. If one element is present, indicates a regular note. If multiple elements, indicates a chord.
position float The fractional offset of this note set from measure start in quarter notes
duration float The fractional duration of this note set expressed in quarter notes
voice integer The index of the voice to which this note set belongs, where zero indicates the top voice in a polyphonic score.
beam boolean Flag indicating whether this note has a beam extending to the following note.

Note objects have this structure:

Name Type Description
pitch integer The ordinal of this pitch in the standard MIDI chromatic scale numbering, at concert pitch. The number may be negative.
step integer A number between 0 and 6 corresponding to the note spellings C, D, E, F, G, A, B respectively.
alteration integer The number of half steps distance this note lies from the unaltered step.
accidental String A string indicating the type of accidental shown visually for this note, or null if none is specified. Values include "flat", "sharp", "natural", "doubleFlat" and "doubleSharp".
tied boolean Flag indicating whether this note is tied to the following note.
noteHead String Type of note head: normal, stemless, slash, hit, cross, square, diamond, triangle, or harmonic.

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:

Name Type Description
startIndex integer The zero-based index of the measure at which playback is to begin.

Return Value: None.

stopPlayback()

Description: Stops any playback currently in progress.

the

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:

Name Type Description
index integer The zero-based index of the measure at which the cursor is displayed.
offset float The offset from measure start at which the cursor is displayed, in quarter notes.

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:

Name Type Description
flag boolean True if the default behavior of auto-advance on note entry is enabled.

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:

Name Type Description
mode String See description of playback embed parameter above.

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:

Name Type Description
partIndices String An array containing one or more zero-based indices of parts in the score to be shown. If an empty array is given, all parts in the score are displayed.

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:

Name Type Description
xmlString String A complete MusicXML document provided as a String.

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:

Name Type Description
xmlString String A complete NoteflightXML document provided as a String.

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:

Name Type Description
noteSets Array An array of note set objects, as described below. Each note set's position property is taken as relative to the starting musical position at which notes are to be pasted.
staffIndex integer A zero-based index of the staff in which the notes are to be pasted.
measureIndex integer A zero-based index of the starting measure in which the notes are to be pasted.
offset float An offset within the starting measure expressed in quarter notes.

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:

Name Type Description
gain float Per-part volume adjustment, with 0 corresponding to no adjustment.
muted boolean Whether the part is muted and will be left out during playback.
name string The full name of the instrument.
octaveShift integer Number of octaves above concert pitch by which the part's notation is transposed.
pan float Instrument's left or right pan when playing.
transposition integer Transposition of the part's score relative to concert pitch, measured in semitones upward.
alternateKey boolean Forces selection of an alternate enharmonic key signature in a transposed part, if one is available.
visible boolean Whether the part is shown in the score.

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:

Name Type Description
partIndex integer The index of the part whose properties will be set (same as its index in the array returned by getParts()).
properties object An object all of whose properties will be copied onto the part.

Return Value: None.

setZoom(zoomFactor)

Description: Sets the zoom factor.

Example Code:

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

Parameters:

Name Type Description
startIndex integer The zero-based index of the measure at the start of the selected range.

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:

Name Type Description
masterGain float The gain in volume applied to all tracks in the score, with 0 indicating no gain.

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:

Name Type Description
mode string the mode of the key signature: one of "major", "minor", "ionian", "dorian", "phrygian", "lydian", "mixolydian", "aeolian", or "locrian". Left undefined if the score's mode is unknown.
tonic string the first note of the key signature's scale. Left undefined if the score's mode is unknown.
fifths integer the key signature's distance from C major / A minor by fifths, expressed as a number between -7 and 7. If positive, equal to the number of sharps in the key signature; if negative, equal to the number of flats.

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:

Name Type Description
transposeParts boolean If false, the embed will show parts at concert pitch; if true, with their per-part transposition applied.

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):

Name Type Description
semitones integer An integral number of semitones to transpose the whole score.
partSemitones Array of integers An array each of whose elements corresponds to a part in the score and supplies the number of semitones by which to transpose that part.
resumePlayback boolean (optional) if true, automatically resumes playback of the currently playing measure following transposition.
ignoreStemDirection boolean (optional) if true, suppresses any forced stem directions in the score.
ignoreSlurDirection boolean (optional) if true, suppresses any forced slur directions in the score.
alternateKey boolean (optional) if true, uses alternate enharmonic key spellings reported by getTranspositions() for this pitch change.
hideChordSymbols boolean (optional) if true, hide chord symbols after transposing.
hideFretboards boolean (optional) if true, hide fretbroards after transposing.

Return Value: None.

setNoteSize(noteSize)

Description: Sets the note size, in points.

Example Code:

  s.setNoteSize(8);

Parameters:

Name Type Description
noteSize integer The note size, in points.

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 log2(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:

Name Type Description
speedGain float The playback speed gain. 0 indicates no gain; each increment of 1 doubles or halves the speed.

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:

Name Type Description
tempo int The playback tempo in beats per minute.

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:

Name Type Description
imageUri string The URI of the image to load.

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});
Name Type Description
usePrinter (optional) boolean Print the score using a real printer or download a PDF. Available only in HTML5.

Return Value: None.




© Copyright 2016 Noteflight, LLC. All Rights Reserved.

Noteflight® is a registered trademark of Noteflight, LLC.