Score Management ​

Methods for loading and exporting scores in various formats

Methods ​

loadFlatScore() ​

Load a score hosted on Flat Loads a Flat score by its unique identifier. For private scores, you must provide the sharing key obtained from a private link.

typescript
loadFlatScore(score: string | { score: string; sharingKey?: string; }): Promise<void>

Parameters:

  • score.score - string
  • score.sharingKey? - string

Returns: Promise<void>

Throws:

  • TypeError - If the score parameter is invalid
  • Error - If the score cannot be loaded (e.g., not found, access denied)

Examples:

typescript
// Load a public score
await embed.loadFlatScore('56ae21579a127715a02901a6');
typescript
// Load a private score with sharing key
await embed.loadFlatScore({
  score: '56ae21579a127715a02901a6',
  sharingKey: 'f79c3c0dd1fc76ed8b30d6f2c845c8c30f11fe88d9fc39ab96e8e407629d4885'
});

loadMusicXML() ​

Load a MusicXML score Loads a MusicXML score from a string or binary data. The score will be converted to Flat's internal format and displayed in the embed.

typescript
loadMusicXML(score: string | Uint8Array): Promise<void>

Parameters:

  • score - string | Uint8Array

Returns: Promise<void>

Throws:

  • TypeError - If the score format is invalid
  • Error - If the MusicXML cannot be parsed or loaded

Examples:

typescript
// Load from XML string
const xmlString = '<?xml version="1.0"?>...';
await embed.loadMusicXML(xmlString);
typescript
// Load from compressed MXL file
const response = await fetch('score.mxl');
const buffer = await response.arrayBuffer();
await embed.loadMusicXML(new Uint8Array(buffer));

loadMIDI() ​

Load a MIDI score Loads a MIDI file and converts it to sheet music notation. Note that MIDI files contain performance data rather than notation, so the conversion may not perfectly represent the original musical intent.

typescript
loadMIDI(score: Uint8Array): Promise<void>

Parameters:

  • score - Uint8Array

Returns: Promise<void>

Throws:

  • TypeError - If the score format is invalid
  • Error - If the MIDI file cannot be parsed or loaded

Examples:

typescript
// Load MIDI file from URL
const response = await fetch('song.mid');
const buffer = await response.arrayBuffer();
await embed.loadMIDI(new Uint8Array(buffer));
typescript
// Load MIDI file from file input
const file = document.getElementById('fileInput').files[0];
const buffer = await file.arrayBuffer();
await embed.loadMIDI(new Uint8Array(buffer));

loadJSON() ​

Load a Flat JSON score Loads a score from Flat's native JSON format. This format preserves all score data and is the most reliable way to transfer scores between Flat applications.

typescript
loadJSON(score: string | Record<string, unknown>): Promise<void>

Parameters:

  • score - string | Record<string, unknown>

Returns: Promise<void>

Throws:

  • TypeError - If the JSON is invalid or cannot be parsed
  • Error - If the score data is malformed or cannot be loaded

Examples:

typescript
// Load from JSON object
const scoreData = await fetch('score.json').then(r => r.json());
await embed.loadJSON(scoreData);
typescript
// Load from JSON string
const jsonString = '{"score-partwise": {...}}';
await embed.loadJSON(jsonString);

getJSON() ​

Get the score in Flat JSON format Exports the currently loaded score as Flat's native JSON format. This format preserves all score data including notation, layout, and metadata.

typescript
getJSON(): Promise<Record<string, unknown>>

Returns: Promise<Record<string, unknown>>

Throws:

  • Error - If no score is currently loaded

Examples:

typescript
// Export and save score data
const scoreData = await embed.getJSON();
const jsonString = JSON.stringify(scoreData);

// Save to file
const blob = new Blob([jsonString], { type: 'application/json' });
const url = URL.createObjectURL(blob);
const a = document.createElement('a');
a.href = url;
a.download = 'score.json';
a.click();

getMusicXML() ​

Convert the displayed score to MusicXML Exports the currently loaded score as MusicXML, the standard format for sheet music notation exchange. Supports both uncompressed XML and compressed MXL formats.

typescript
getMusicXML(options?: { compressed?: boolean; }): Promise<string | Uint8Array>

Parameters:

  • options.compressed (optional) - boolean

Returns: Promise<string | Uint8Array>

Throws:

  • TypeError - If options parameter is invalid
  • Error - If no score is loaded or conversion fails

Examples:

typescript
// Get uncompressed MusicXML
const xml = await embed.getMusicXML();
console.log(xml); // <?xml version="1.0"...
typescript
// Get compressed MusicXML (.mxl)
const mxl = await embed.getMusicXML({ compressed: true });
const blob = new Blob([mxl], { type: 'application/vnd.recordare.musicxml' });
const url = URL.createObjectURL(blob);

getPNG() ​

Convert the displayed score to PNG image Exports the currently loaded score as a PNG image. Supports various export options including resolution, layout mode, and output format.

typescript
getPNG(options?: { result?: 'Uint8Array' | 'dataURL'; dpi?: number; layout?: 'track' | 'page'; }): Promise<Uint8Array | string>

Parameters:

  • options.result (optional) - 'Uint8Array' | 'dataURL': Export result (either a PNG returned as Uint8Array or in dataURL)
  • options.dpi (optional) - number: DPI of exported image (min: 50, max: 300, default: 150)
  • options.layout (optional) - 'track' | 'page': Layout of exported image

Returns: Promise<Uint8Array | string>

Throws:

  • TypeError - If options parameter is invalid
  • Error - If no score is loaded or conversion fails

Examples:

typescript
// Get PNG as Uint8Array
const pngData = await embed.getPNG();
const blob = new Blob([pngData], { type: 'image/png' });
typescript
// Get PNG as data URL for direct display
const dataUrl = await embed.getPNG({ result: 'dataURL' });
document.getElementById('preview').src = dataUrl;
typescript
// High resolution export with page layout
const hqPng = await embed.getPNG({ dpi: 300, layout: 'page' });

getMIDI() ​

Convert the displayed score to MIDI Exports the currently loaded score as a MIDI file. The MIDI file will contain performance data including notes, tempo, dynamics, and instrument information. Note that some notation elements may not be represented in MIDI format.

typescript
getMIDI(): Promise<Uint8Array>

Returns: Promise<Uint8Array>

Throws:

  • Error - If no score is loaded or conversion fails

Examples:

typescript
// Export score as MIDI
const midiData = await embed.getMIDI();

// Save as file
const blob = new Blob([midiData], { type: 'audio/midi' });
const url = URL.createObjectURL(blob);
const a = document.createElement('a');
a.href = url;
a.download = 'score.mid';
a.click();
typescript
// Play MIDI in browser (requires Web MIDI API)
const midiData = await embed.getMIDI();
// ... use with Web MIDI API or MIDI player library

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. This method only works for scores loaded via loadFlatScore().

typescript
getFlatScoreMetadata(): Promise<ScoreDetails>

Returns: Promise<ScoreDetails>

View ScoreDetails type definition

ScoreDetails

Complete score details including metadata and statistics

Properties:

  • id: string - The unique identifier of the score
  • sharingKey (optional): string - The private sharing key of the score (available when the privacy mode is set to privateLink)
  • title: string - The title of the score
  • privacy: ScorePrivacy - Privacy setting of the score
  • user: UserPublic - User who created the score
  • htmlUrl: string - The url where the score can be viewed in a web browser
  • editHtmlUrl: string - The url where the score can be edited in a web browser
  • subtitle (optional): string - Subtitle of the score
  • lyricist (optional): string - Lyricist of the score
  • arranger (optional): string - Arranger of the score
  • composer (optional): string - Composer of the score
  • description (optional): string - Description of the creation
  • tags (optional): string[] - Tags describing the score
  • creationType (optional): ScoreCreationType - Type of creation
  • license (optional): ScoreLicense - License of the score
  • licenseText (optional): string - Additional license text written on the exported/printed score
  • durationTime (optional): number - In seconds, an approximative duration of the score
  • numberMeasures (optional): number - The number of measures in the score
  • mainTempoQpm (optional): number - The main tempo of the score (in QPM)
  • mainKeySignature (optional): number - The main key signature of the score (expressed between -7 and 7).
  • rights (optional): ResourceRights - Access rights for the score
  • collaborators: ResourceCollaborator[] - The list of the collaborators of the score
  • creationDate: string - The date when the score was created
  • modificationDate (optional): string - The date of the last revision of the score
  • publicationDate (optional): string - The date when the score was published on Flat
  • scheduledDeletionDate (optional): string - The date when the score will be definitively deleted. This date can be in the past if the score will be deleted at the next deletion batch.
  • highlightedDate (optional): string - The date when the score was highlighted (featured) on our community
  • organization (optional): string - If the score has been created in an organization, the identifier of this organization
  • parentScore (optional): string - If the score has been forked, the unique identifier of the parent score
  • instruments: string[] - An array of the instrument identifiers used in the last version of the score. The format of the strings is {instrument-group}.{instrument-id}.
  • instrumentsNames: string[] - An array of the instrument names that match the indexes from the instruments list
  • samples: string[] - An array of the audio samples identifiers used in the different score parts. The format of the strings is {instrument-group}.{sample-id}.
  • googleDriveFileId (optional): string - If the score exists on Google Drive, this field will contain the unique identifier
  • likes (optional): ScoreLikesCounts - Like statistics
  • comments (optional): ScoreCommentsCounts - Comment statistics
  • views (optional): ScoreViewsCounts - View statistics
  • plays (optional): ScorePlaysCounts - Play statistics
  • collections (optional): string[] - The list of parent collections which includes all the collections this score is included in

Throws:

  • Error - If no Flat score is loaded or metadata is unavailable

Example:

typescript
const embed = new Embed('container', config);
const flatScoreMetadata = await embed.getFlatScoreMetadata();
console.log(flatScoreMetadata);

See also:

Copyright © Tutteo Limited

All rights reserved