---
url: https://flat.io/developers/docs/embed/api/data.md
description: Access and query score structure, measures, notes, and metadata
---

# Score Data & Structure

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

## Methods

### getNbMeasures() {#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()`](#getmeasuresuuids) - Get measure identifiers
* [`getMeasureDetails()`](#getmeasuredetails) - Get detailed measure information

***

### getMeasuresUuids() {#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()`](#getnbmeasures) - Get the total number of measures
* [`getMeasureDetails()`](#getmeasuredetails) - Get details for a specific measure

***

### getMeasureDetails() {#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>`

**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()`](#getnbmeasures) - Get measure count
* [`getMeasuresUuids()`](#getmeasuresuuids) - Get measure identifiers

***

### getNbParts() {#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()`](#getparts) - Get detailed part information
* [`getPartsUuids()`](#getpartsuuids) - Get part identifiers

***

### getPartsUuids() {#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()`](#getnbparts) - Get the total number of parts
* [`getParts()`](#getparts) - Get detailed part information

***

### getMeasureVoicesUuids() {#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()`](#getmeasurenbnotes) - Count notes in a voice

***

### getMeasureNbNotes() {#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()`](#getnotedata) - Get details about specific notes
* [`getMeasureVoicesUuids()`](#getmeasurevoicesuuids) - Get voice UUIDs

***

### getNoteData() {#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>`

**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()`](#getmeasurenbnotes) - Get total notes in voice

***

### playbackPositionToNoteIdx() {#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()`](#getnotedata) - Get note details at index

***

### getNoteDetails() {#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>`

**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()`](#getcursorposition) - Get cursor position
* [`getNoteData()`](#getnotedata) - Get note at specific position

***