Navigation & Cursor

Navigate through the score and control cursor position

Methods

focusScore()

Set focus to the score Gives keyboard focus to the score iframe, allowing keyboard shortcuts and navigation to work. This is useful when embedding multiple interactive elements on a page.

focusScore(): Promise<void>

Returns: Promise<void>

Examples:

// Focus score for keyboard interaction
await embed.focusScore();

// Focus score when user clicks a button
document.getElementById('editBtn').addEventListener('click', () => {
  embed.focusScore();
});

---

getCursorPosition()

Get the cursor position Retrieves the current position of the cursor in the score, including the part, measure, voice, and note location.

getCursorPosition(): Promise<NoteCursorPosition>

Returns: Promise<NoteCursorPosition>

View NoteCursorPosition type definition

NoteCursorPosition

Complete cursor position information within a score

Properties:

• partIdx: number - Zero-based index of the part
• partUuid: string - Unique identifier of the part
• staffIdx: number - Zero-based index of the staff within the part
• staffUuid: string - Unique identifier of the staff
• voiceIdxInStaff: number - Zero-based index of the voice within the staff
• voiceUuid: string - Unique identifier of the voice
• measureIdx: number - Zero-based index of the measure
• measureUuid: string - Unique identifier of the measure
• noteIdx: number - Zero-based index of the note within the voice
• line: number - Staff line number (0 = bottom line)
• dpq: number - Divisions per quarter note (timing resolution)
• timePos: number - Absolute time position in seconds from the beginning

Throws:

• Error - If cursor position cannot be retrieved

Example:

const embed = new Embed('container', config);

// Get the current cursor position
const position = await embed.getCursorPosition();
console.log('Current cursor position:', {
  part: position.partIdx,
  staff: position.staffIdx,
  measure: position.measureIdx,
  note: position.noteIdx,
});

// Use cursor position to get note details
if (position.noteIdx >= 0) {
  const parts = await embed.getPartsUuids();
  const measures = await embed.getMeasuresUuids();
  const voices = await embed.getMeasureVoicesUuids({
    partUuid: parts[position.partIdx],
    measureUuid: measures[position.measureIdx],
  });

  if (voices.length > 0) {
    const noteData = await embed.getNoteData({
      partUuid: parts[position.partIdx],
      measureUuid: measures[position.measureIdx],
      voiceUuid: voices[0],
      noteIdx: position.noteIdx,
    });
    console.log('Note at cursor:', noteData);
  }
}

See also:

• setCursorPosition() - Set cursor position
• goLeft() - Move cursor left
• goRight() - Move cursor right

---

setCursorPosition()

Set the cursor position Moves the cursor to a specific position in the score. You can specify any combination of part, measure, voice, staff, and note indices. Unspecified values remain at their current position.

setCursorPosition(position: NoteCursorPositionOptional): Promise<void>

Parameters:

• position - NoteCursorPositionOptional

Returns: Promise<void>

Throws:

• Error - If the position is invalid or cursor cannot be moved

Examples:

// Move to beginning of measure 5
await embed.setCursorPosition({
  measureIdx: 4,  // 0-based index
  noteIdx: 0
});

See also:

• getCursorPosition() - Get current position

---

goLeft()

Move cursor left Moves the cursor to the previous item in the score (note, rest, or grace note). Navigation follows the reading order of the score.

goLeft(mute?: boolean): Promise<void>

Parameters:

• mute (optional) - boolean

Returns: Promise<void>

Throws:

• Error - If cursor cannot move (e.g., at beginning of score)

Examples:

// Move left silently
await embed.goLeft(true);

See also:

• goRight() - Move cursor right
• setCursorPosition() - Set specific position

---

goRight()

Move cursor right Moves the cursor to the next item in the score (note, rest, or grace note). Navigation follows the reading order of the score.

goRight(mute?: boolean): Promise<void>

Parameters:

• mute (optional) - boolean

Returns: Promise<void>

Throws:

• Error - If cursor cannot move (e.g., at end of score)

Examples:

// Move right and play the note
await embed.goRight();

See also:

• goLeft() - Move cursor left
• setCursorPosition() - Set specific position

---

scrollToCursor()

Scroll to cursor position Scrolls the score view to ensure the cursor is visible on screen. This is useful after programmatically moving the cursor or when the cursor moves out of view during navigation.

scrollToCursor(): Promise<void>

Returns: Promise<void>

Throws:

• Error - If scrolling fails

Examples:

// Move cursor and scroll to it
await embed.setCursorPosition({ measureIdx: 20 });
await embed.scrollToCursor();

Note: Scrolling is performed asynchronously and may not complete before the promise resolves

See also:

• setCursorPosition() - Set cursor position

---