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 partpartUuid
:string
- Unique identifier of the partstaffIdx
:number
- Zero-based index of the staff within the partstaffUuid
:string
- Unique identifier of the staffvoiceIdxInStaff
:number
- Zero-based index of the voice within the staffvoiceUuid
:string
- Unique identifier of the voicemeasureIdx
:number
- Zero-based index of the measuremeasureUuid
:string
- Unique identifier of the measurenoteIdx
:number
- Zero-based index of the note within the voiceline
: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 positiongoLeft()
- Move cursor leftgoRight()
- 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 rightsetCursorPosition()
- 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 leftsetCursorPosition()
- 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