API Reference
The Flat Embed SDK provides 61 methods to control and interact with embedded sheet music.
Quick Navigation
Press ⌘ + K (Mac) or Ctrl + K (Windows/Linux) to search for specific methods.
Browse by Category
Core Methods
Essential methods for embed initialization and configuration (3 methods)
| Method | Description |
|---|---|
ready() | Wait for the embed to be ready Returns a promise that resolves when the embed iframe has fully loaded and communication with the Flat embed has been established |
getEmbedConfig() | Get the embed configuration Retrieves the complete configuration object for the embed, including display settings, permissions, editor configuration, and enabled features |
setEditorConfig() | Set the editor configuration Updates the editor configuration for the embed |
Event System
Subscribe to and handle embed events (2 methods)
| Method | Description |
|---|---|
on() | Subscribe to a specific event |
off() | Unsubscribe to a specific event |
Score Management
Methods for loading and exporting scores in various formats (9 methods)
| Method | Description |
|---|---|
loadFlatScore() | Load a score hosted on Flat Loads a Flat score by its unique identifier |
loadMusicXML() | Load a MusicXML score Loads a MusicXML score from a string or binary data |
loadMIDI() | Load a MIDI score Loads a MIDI file and converts it to sheet music notation |
loadJSON() | Load a Flat JSON score Loads a score from Flat's native JSON format |
getJSON() | Get the score in Flat JSON format Exports the currently loaded score as Flat's native JSON format |
getMusicXML() | Convert the displayed score to MusicXML Exports the currently loaded score as MusicXML, the standard format for sheet music notation exchange |
getPNG() | Convert the displayed score to PNG image Exports the currently loaded score as a PNG image |
getMIDI() | Convert the displayed score to MIDI Exports the currently loaded score as a MIDI file |
getFlatScoreMetadata() | Get the metadata of the score (for scores hosted on Flat) Retrieves metadata for scores that are hosted on Flat, including title, composer, collaborators, creation date, and other information available through Flat's API |
Display & View
Control the visual presentation of the score (6 methods)
| Method | Description |
|---|---|
fullscreen() | Toggle fullscreen mode Switches the embed in or out of fullscreen mode |
print() | Print the score Opens the browser's print dialog to print the currently loaded score |
getZoom() | Get the current zoom ratio Retrieves the current zoom level of the score display |
setZoom() | Set the zoom ratio Sets a specific zoom level for the score display |
getAutoZoom() | Get the auto-zoom status Checks whether auto-zoom mode is currently enabled |
setAutoZoom() | Enable or disable auto-zoom Controls the auto-zoom feature |
Playback Control
Control playback, volume, speed, and metronome settings (10 methods)
| Method | Description |
|---|---|
play() | Start playback Begins playing the score from the current cursor position |
pause() | Pause playback Pauses the score playback at the current position |
stop() | Stop playback Stops the score playback and resets the playback position to the beginning of the score |
mute() | Mute playback Mutes all audio output from the score playback |
getMasterVolume() | Get the current master volume Retrieves the current master volume level for score playback |
setMasterVolume() | Set the master volume Sets the master volume level for score playback |
getMetronomeMode() | Get the metronome mode Retrieves the current metronome setting, which controls when the metronome clicks are played during playback |
setMetronomeMode() | Set the metronome mode Controls when metronome clicks are played during score playback |
getPlaybackSpeed() | Get the playback speed Retrieves the current playback speed multiplier |
setPlaybackSpeed() | Set the playback speed Adjusts the playback speed without affecting pitch |
Parts & Instruments
Manage individual parts, instruments, and their audio settings (12 methods)
| Method | Description |
|---|---|
getPartVolume() | Get the volume of a specific part Retrieves the current volume level for a specific instrument part in the score |
setPartVolume() | Set the volume of a specific part Sets the volume level for a specific instrument part in the score |
mutePart() | Mute a specific part Mutes the audio output for a specific instrument part |
unmutePart() | Unmute a specific part Restores the audio output for a previously muted part |
setPartSoloMode() | Enable solo mode for a part Enables solo mode for a specific part, which mutes all other parts while keeping the selected part audible |
unsetPartSoloMode() | Disable solo mode for a part Disables solo mode for a specific part |
getPartSoloMode() | Get the solo mode status of a part Checks whether a specific part is currently in solo mode |
getPartReverb() | Get the reverb level of a part Retrieves the current reverb (reverberation) effect level for a specific instrument part |
setPartReverb() | Set the reverb level of a part Sets the reverb (reverberation) effect level for a specific instrument part |
getParts() | Get information about all parts Retrieves detailed information about all instrument parts in the score, including their names, instruments, and unique identifiers |
getDisplayedParts() | Get the currently displayed parts Retrieves information about which parts are currently visible in the score |
setDisplayedParts() | Set which parts to display Controls which instrument parts are visible in the score |
Audio/Video Tracks
Synchronize external audio or video with the score (3 methods)
| Method | Description |
|---|---|
setTrack() | Configure an audio or video track Sets up a new audio or video track to synchronize with the score playback |
useTrack() | Enable a previously configured track Activates a track that was previously configured with setTrack() |
seekTrackTo() | Seek to a position in the audio track Moves the playback position of the currently active audio/video track to a specific time |
Navigation & Cursor
Navigate through the score and control cursor position (6 methods)
| Method | Description |
|---|---|
focusScore() | Set focus to the score Gives keyboard focus to the score iframe, allowing keyboard shortcuts and navigation to work |
getCursorPosition() | Get the cursor position Retrieves the current position of the cursor in the score, including the part, measure, voice, and note location |
setCursorPosition() | Set the cursor position Moves the cursor to a specific position in the score |
goLeft() | Move cursor left Moves the cursor to the previous item in the score (note, rest, or grace note) |
goRight() | Move cursor right Moves the cursor to the next item in the score (note, rest, or grace note) |
scrollToCursor() | Scroll to cursor position Scrolls the score view to ensure the cursor is visible on screen |
Score Data & Structure
Access and query score structure, measures, notes, and metadata (10 methods)
| Method | Description |
|---|---|
getNbMeasures() | Get the number of measures in the score Retrieves the total count of measures (bars) in the currently loaded score |
getMeasuresUuids() | Get the measure UUIDs of the score Retrieves the unique identifiers for all measures in the score |
getMeasureDetails() | Get detailed measure information Retrieves comprehensive information about the current measure at the cursor position, including time signature, key signature, tempo, and other properties |
getNbParts() | Get the number of parts in the score Retrieves the total count of instrument parts in the currently loaded score |
getPartsUuids() | Get the part UUIDs of the score Retrieves the unique identifiers for all parts in the score |
getMeasureVoicesUuids() | Get voice UUIDs for a specific measure Retrieves the unique identifiers of all voices present in a specific measure of a part |
getMeasureNbNotes() | Get the number of notes in a voice Counts the total number of notes (including rests) in a specific voice within a measure |
getNoteData() | Get information about a specific note Retrieves detailed information about a note at a specific position, including pitch, duration, articulations, and other musical properties |
playbackPositionToNoteIdx() | Convert playback position to note index Finds the note index that corresponds to a specific playback position |
getNoteDetails() | Get note details at cursor position Retrieves detailed information about the note at the current cursor position, including pitch, duration, and musical attributes |
All Methods
| Method | Description |
|---|---|
focusScore() | Set focus to the score Gives keyboard focus to the score iframe, allowing keyboard shortcuts and navigation to work |
fullscreen() | Toggle fullscreen mode Switches the embed in or out of fullscreen mode |
getAutoZoom() | Get the auto-zoom status Checks whether auto-zoom mode is currently enabled |
getCursorPosition() | Get the cursor position Retrieves the current position of the cursor in the score, including the part, measure, voice, and note location |
getDisplayedParts() | Get the currently displayed parts Retrieves information about which parts are currently visible in the score |
getEmbedConfig() | Get the embed configuration Retrieves the complete configuration object for the embed, including display settings, permissions, editor configuration, and enabled features |
getFlatScoreMetadata() | Get the metadata of the score (for scores hosted on Flat) Retrieves metadata for scores that are hosted on Flat, including title, composer, collaborators, creation date, and other information available through Flat's API |
getJSON() | Get the score in Flat JSON format Exports the currently loaded score as Flat's native JSON format |
getMasterVolume() | Get the current master volume Retrieves the current master volume level for score playback |
getMeasureDetails() | Get detailed measure information Retrieves comprehensive information about the current measure at the cursor position, including time signature, key signature, tempo, and other properties |
getMeasureNbNotes() | Get the number of notes in a voice Counts the total number of notes (including rests) in a specific voice within a measure |
getMeasuresUuids() | Get the measure UUIDs of the score Retrieves the unique identifiers for all measures in the score |
getMeasureVoicesUuids() | Get voice UUIDs for a specific measure Retrieves the unique identifiers of all voices present in a specific measure of a part |
getMetronomeMode() | Get the metronome mode Retrieves the current metronome setting, which controls when the metronome clicks are played during playback |
getMIDI() | Convert the displayed score to MIDI Exports the currently loaded score as a MIDI file |
getMusicXML() | Convert the displayed score to MusicXML Exports the currently loaded score as MusicXML, the standard format for sheet music notation exchange |
getNbMeasures() | Get the number of measures in the score Retrieves the total count of measures (bars) in the currently loaded score |
getNbParts() | Get the number of parts in the score Retrieves the total count of instrument parts in the currently loaded score |
getNoteData() | Get information about a specific note Retrieves detailed information about a note at a specific position, including pitch, duration, articulations, and other musical properties |
getNoteDetails() | Get note details at cursor position Retrieves detailed information about the note at the current cursor position, including pitch, duration, and musical attributes |
getPartReverb() | Get the reverb level of a part Retrieves the current reverb (reverberation) effect level for a specific instrument part |
getParts() | Get information about all parts Retrieves detailed information about all instrument parts in the score, including their names, instruments, and unique identifiers |
getPartSoloMode() | Get the solo mode status of a part Checks whether a specific part is currently in solo mode |
getPartsUuids() | Get the part UUIDs of the score Retrieves the unique identifiers for all parts in the score |
getPartVolume() | Get the volume of a specific part Retrieves the current volume level for a specific instrument part in the score |
getPlaybackSpeed() | Get the playback speed Retrieves the current playback speed multiplier |
getPNG() | Convert the displayed score to PNG image Exports the currently loaded score as a PNG image |
getZoom() | Get the current zoom ratio Retrieves the current zoom level of the score display |
goLeft() | Move cursor left Moves the cursor to the previous item in the score (note, rest, or grace note) |
goRight() | Move cursor right Moves the cursor to the next item in the score (note, rest, or grace note) |
loadFlatScore() | Load a score hosted on Flat Loads a Flat score by its unique identifier |
loadJSON() | Load a Flat JSON score Loads a score from Flat's native JSON format |
loadMIDI() | Load a MIDI score Loads a MIDI file and converts it to sheet music notation |
loadMusicXML() | Load a MusicXML score Loads a MusicXML score from a string or binary data |
mute() | Mute playback Mutes all audio output from the score playback |
mutePart() | Mute a specific part Mutes the audio output for a specific instrument part |
off() | Unsubscribe to a specific event |
on() | Subscribe to a specific event |
pause() | Pause playback Pauses the score playback at the current position |
play() | Start playback Begins playing the score from the current cursor position |
playbackPositionToNoteIdx() | Convert playback position to note index Finds the note index that corresponds to a specific playback position |
print() | Print the score Opens the browser's print dialog to print the currently loaded score |
ready() | Wait for the embed to be ready Returns a promise that resolves when the embed iframe has fully loaded and communication with the Flat embed has been established |
scrollToCursor() | Scroll to cursor position Scrolls the score view to ensure the cursor is visible on screen |
seekTrackTo() | Seek to a position in the audio track Moves the playback position of the currently active audio/video track to a specific time |
setAutoZoom() | Enable or disable auto-zoom Controls the auto-zoom feature |
setCursorPosition() | Set the cursor position Moves the cursor to a specific position in the score |
setDisplayedParts() | Set which parts to display Controls which instrument parts are visible in the score |
setEditorConfig() | Set the editor configuration Updates the editor configuration for the embed |
setMasterVolume() | Set the master volume Sets the master volume level for score playback |
setMetronomeMode() | Set the metronome mode Controls when metronome clicks are played during score playback |
setPartReverb() | Set the reverb level of a part Sets the reverb (reverberation) effect level for a specific instrument part |
setPartSoloMode() | Enable solo mode for a part Enables solo mode for a specific part, which mutes all other parts while keeping the selected part audible |
setPartVolume() | Set the volume of a specific part Sets the volume level for a specific instrument part in the score |
setPlaybackSpeed() | Set the playback speed Adjusts the playback speed without affecting pitch |
setTrack() | Configure an audio or video track Sets up a new audio or video track to synchronize with the score playback |
setZoom() | Set the zoom ratio Sets a specific zoom level for the score display |
stop() | Stop playback Stops the score playback and resets the playback position to the beginning of the score |
unmutePart() | Unmute a specific part Restores the audio output for a previously muted part |
unsetPartSoloMode() | Disable solo mode for a part Disables solo mode for a specific part |
useTrack() | Enable a previously configured track Activates a track that was previously configured with setTrack() |