Score Data & Structure | Flat Developer

Access and query score structure, measures, notes, and metadata

Methods

getNbMeasures()

Get the number of measures in the score

Retrieves the total count of measures (bars) in the currently loaded score.

typescript

getNbMeasures(): Promise<number>

Returns: Promise<number>

Throws:

Error - If no score is loaded

Example:

typescript

const embed = new Embed('container', config);
const nbMeasures = await embed.getNbMeasures();
console.log(nbMeasures);

See also:

getMeasuresUuids() - Get measure identifiers
getMeasureDetails() - Get detailed measure information

getMeasuresUuids()

Get the measure UUIDs of the score

Retrieves the unique identifiers for all measures in the score. These UUIDs can be used to reference specific measures in other API calls.

typescript

getMeasuresUuids(): Promise<string[]>

Returns: Promise<string[]>

Throws:

Error - If no score is loaded

Example:

typescript

const embed = new Embed('container', config);
const measuresUuids = await embed.getMeasuresUuids();
console.log(measuresUuids);

See also:

getNbMeasures() - Get the total number of measures
getMeasureDetails() - Get details for a specific measure

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.

typescript

getMeasureDetails(): Promise<MeasureDetails>

Returns: Promise<MeasureDetails>

View MeasureDetails type definition

MeasureDetails

Comprehensive details about a measure

Properties:

clef: Clef - Current clef in this measure
'displayed-time': DisplayedTime - Time signature as displayed (can differ for pickup measures, etc.)
key: Key - Current key signature
tempo: Tempo - Tempo marking (always included, populated from current tempo)
time: Time - Actual time signature
transpose: Transpose - Transposition settings for this measure

Throws:

Error - If no score is loaded or details cannot be retrieved

Example:

typescript

const embed = new Embed('container', config);
const measureDetails = await embed.getMeasureDetails();
console.log(measureDetails);

See also:

getNbMeasures() - Get measure count
getMeasuresUuids() - Get measure identifiers

getNbParts()

Get the number of parts in the score

Retrieves the total count of instrument parts in the currently loaded score.

typescript

getNbParts(): Promise<number>

Returns: Promise<number>

Throws:

Error - If no score is loaded

Example:

typescript

const embed = new Embed('container', config);
const nbParts = await embed.getNbParts();
console.log(nbParts);

See also:

getParts() - Get detailed part information
getPartsUuids() - Get part identifiers

getPartsUuids()

Get the part UUIDs of the score

Retrieves the unique identifiers for all parts in the score. These UUIDs are used to reference specific parts in volume, mute, and other part-specific operations.

typescript

getPartsUuids(): Promise<string[]>

Returns: Promise<string[]>

Throws:

Error - If no score is loaded

Example:

typescript

const embed = new Embed('container', config);
const partsUuids = await embed.getPartsUuids();
console.log(partsUuids);

See also:

getNbParts() - Get the total number of parts
getParts() - Get detailed part information

getMeasureVoicesUuids()

Get voice UUIDs for a specific measure

Retrieves the unique identifiers of all voices present in a specific measure of a part. Voices represent independent melodic lines within a part.

typescript

getMeasureVoicesUuids(parameters: { partUuid: string; measureUuid: string; }): Promise<string[]>

Parameters:

parameters.partUuid - string
parameters.measureUuid - string

Returns: Promise<string[]>

Throws:

Error - If the part or measure UUID is invalid

Example:

typescript

const embed = new Embed('container', config);
const measureVoicesUuids = await embed.getMeasureVoicesUuids({
  partUuid: '00000000-0000-0000-0000-000000000001',
  measureUuid: '00000000-0000-0000-0000-000000000002'
});
console.log(measureVoicesUuids);

See also:

getMeasureNbNotes() - Count notes in a voice

getMeasureNbNotes()

Get the number of notes in a voice

Counts the total number of notes (including rests) in a specific voice within a measure. This is useful for iterating through notes or determining voice complexity.

typescript

getMeasureNbNotes(parameters: { partUuid: string; measureUuid: string; voiceUuid: string; }): Promise<number>

Parameters:

parameters.partUuid - string
parameters.measureUuid - string
parameters.voiceUuid - string

Returns: Promise<number>

Throws:

Error - If any UUID is invalid

Example:

typescript

const embed = new Embed('container', config);
const measureNbNotes = await embed.getMeasureNbNotes({
  partUuid: '00000000-0000-0000-0000-000000000001',
  measureUuid: '00000000-0000-0000-0000-000000000002',
  voiceUuid: '00000000-0000-0000-0000-000000000003'
});
console.log(measureNbNotes);

See also:

getNoteData() - Get details about specific notes
getMeasureVoicesUuids() - Get voice UUIDs

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.

typescript

getNoteData(parameters: { partUuid: string; measureUuid: string; voiceUuid: string; noteIdx: number; }): Promise<NoteDetails>

Parameters:

parameters.partUuid - string
parameters.measureUuid - string
parameters.voiceUuid - string
parameters.noteIdx - number

Returns: Promise<NoteDetails>

View NoteDetails type definition

NoteDetails

Detailed information about a note or rest Note: The actual structure of complex fields (articulations, harmony, etc.) depends on the score content and Flat's internal representation

Properties:

articulations: string[] - List of articulation markings (e.g., 'accent', 'staccato', 'tenuto')
classicHarmony: null | RomanNumeralData - Classical harmony notation (Roman numerals, etc.)
durationType: string - Duration type in MusicXML format (e.g., 'quarter', 'eighth', 'half', 'whole')
dynamicStyle: null | string - Dynamic marking style (e.g., 'p', 'f', 'mf', 'crescendo')
ghostNotes: boolean[] - Ghost note status for each pitch in chord (for guitar/drums)
hammerOnPullOffs: boolean[] - Hammer-on/pull-off status for each pitch (for guitar)
harmony: null | JazzChordData - Jazz/pop chord symbol
hasArpeggio: boolean - Whether this note/chord has an arpeggio marking
hasGlissando: boolean - Whether this note starts a glissando
isChord: boolean - Whether this is a chord (multiple pitches)
isInSlur: boolean - Whether this note is part of a slur
isRest: boolean - Whether this is a rest (no pitches)
isTied: boolean - Whether this note is tied to the next
lines: number[] - Staff line positions for each pitch
lyrics: LyricLine[] - Lyrics attached to this note
nbDots: number - Number of augmentation dots
nbGraces: number - Number of grace notes attached
ornaments: OrnamentObject - Ornaments on the note
pitches: Pitch[] - Array of pitches (empty for rests)
technical: string[] - Technical markings (for strings/guitar, e.g., 'up-bow', 'down-bow', 'harmonic')
tupletType: null | TupletType - Tuplet information if part of irregular grouping
wedgeType: WedgeType - Wedge (hairpin) type if present

Throws:

Error - If the position is invalid or note not found

Example:

typescript

const embed = new Embed('container', config);
const noteData = await embed.getNoteData({
  partUuid: '00000000-0000-0000-0000-000000000001',
  measureUuid: '00000000-0000-0000-0000-000000000002',
  voiceUuid: '00000000-0000-0000-0000-000000000003',
  noteIdx: 0
});
console.log(noteData);

See also:

getMeasureNbNotes() - Get total notes in voice

playbackPositionToNoteIdx()

Convert playback position to note index

Finds the note index that corresponds to a specific playback position. This is useful for synchronizing visual elements with audio playback.

typescript

playbackPositionToNoteIdx(parameters: { partUuid: string; voiceUuid: string; playbackPosition: PlaybackPosition; }): Promise<number>

Parameters:

parameters.partUuid - string
parameters.voiceUuid - string
parameters.playbackPosition - PlaybackPosition

Returns: Promise<number>

Throws:

Error - If the position cannot be mapped to a note

Example:

typescript

const embed = new Embed('container', config);
await embed.playbackPositionToNoteIdx({
  partUuid: '00000000-0000-0000-0000-000000000001',
  voiceUuid: '00000000-0000-0000-0000-000000000003',
  playbackPosition: 
});

See also:

getNoteData() - Get note details at index

getNoteDetails()

Get note details at cursor position

Retrieves detailed information about the note at the current cursor position, including pitch, duration, and musical attributes.

typescript

getNoteDetails(): Promise<NoteDetails>

Returns: Promise<NoteDetails>

View NoteDetails type definition

NoteDetails

Detailed information about a note or rest Note: The actual structure of complex fields (articulations, harmony, etc.) depends on the score content and Flat's internal representation

Properties:

articulations: string[] - List of articulation markings (e.g., 'accent', 'staccato', 'tenuto')
classicHarmony: null | RomanNumeralData - Classical harmony notation (Roman numerals, etc.)
durationType: string - Duration type in MusicXML format (e.g., 'quarter', 'eighth', 'half', 'whole')
dynamicStyle: null | string - Dynamic marking style (e.g., 'p', 'f', 'mf', 'crescendo')
ghostNotes: boolean[] - Ghost note status for each pitch in chord (for guitar/drums)
hammerOnPullOffs: boolean[] - Hammer-on/pull-off status for each pitch (for guitar)
harmony: null | JazzChordData - Jazz/pop chord symbol
hasArpeggio: boolean - Whether this note/chord has an arpeggio marking
hasGlissando: boolean - Whether this note starts a glissando
isChord: boolean - Whether this is a chord (multiple pitches)
isInSlur: boolean - Whether this note is part of a slur
isRest: boolean - Whether this is a rest (no pitches)
isTied: boolean - Whether this note is tied to the next
lines: number[] - Staff line positions for each pitch
lyrics: LyricLine[] - Lyrics attached to this note
nbDots: number - Number of augmentation dots
nbGraces: number - Number of grace notes attached
ornaments: OrnamentObject - Ornaments on the note
pitches: Pitch[] - Array of pitches (empty for rests)
technical: string[] - Technical markings (for strings/guitar, e.g., 'up-bow', 'down-bow', 'harmonic')
tupletType: null | TupletType - Tuplet information if part of irregular grouping
wedgeType: WedgeType - Wedge (hairpin) type if present

Throws:

Error - If no note is at the cursor position

Example:

typescript

const embed = new Embed('container', config);
const noteDetails = await embed.getNoteDetails();
console.log(noteDetails);

See also:

getCursorPosition() - Get cursor position
getNoteData() - Get note at specific position

Methods ​

getNbMeasures() ​

getMeasuresUuids() ​

getMeasureDetails() ​

getNbParts() ​

getPartsUuids() ​

getMeasureVoicesUuids() ​

getMeasureNbNotes() ​

getNoteData() ​

playbackPositionToNoteIdx() ​

getNoteDetails() ​

Methods

getNbMeasures()

getMeasuresUuids()

getMeasureDetails()

getNbParts()

getPartsUuids()

getMeasureVoicesUuids()

getMeasureNbNotes()

getNoteData()

playbackPositionToNoteIdx()

getNoteDetails()