### Clone Embed Examples Repository Source: https://flat.io/developers/docs/embed/demos Clone the Flat Embed examples repository to explore and run demos locally. Each demo includes its own README with setup instructions. ```bash git clone https://github.com/FlatIO/embed-examples.git cd embed-examples ``` -------------------------------- ### Make a GET Request to /me Endpoint Source: https://flat.io/developers/docs/api/flat-for-education Example using cURL to authenticate and retrieve information about the current user. Replace with your actual token. ```bash curl -H 'Authorization: Bearer ' https://api.flat.io/v2/me ``` -------------------------------- ### Install Flat Embed SDK Source: https://flat.io/developers/docs/embed/javascript Use a package manager to add the SDK to your project. ```bash npm install flat-embed pnpm add flat-embed yarn add flat-embed ``` -------------------------------- ### Get Part Volume Usage Example Source: https://flat.io/developers/docs/embed/api/parts Retrieves the volume for a specific part UUID. ```typescript const embed = new Embed('container', config); const partVolume = await embed.getPartVolume({ partUuid: '00000000-0000-0000-0000-000000000001' }); console.log(partVolume); ``` -------------------------------- ### Initialize Embed with TypeScript Source: https://flat.io/developers/docs/embed/javascript Example demonstrating type safety and event handling with TypeScript. ```typescript import Embed from 'flat-embed'; const container = document.getElementById('embed-container') as HTMLElement; const embed = new Embed(container, { score: '5ce6a27f052b2a74a91f4a6d', embedParams: { appId: '', mode: 'edit', // TypeScript knows: 'view' | 'edit' controlsPosition: 'bottom', // TypeScript knows: 'top' | 'bottom' | 'float' | 'hidden' }, }); // Full type checking and autocompletion embed.on('play', () => { // TypeScript knows all available events console.log('Playback started'); }); // Type-safe method calls const parts = await embed.getParts(); // TypeScript knows: Promise ``` -------------------------------- ### Initialize Embed in HTML Source: https://flat.io/developers/docs/embed/javascript Basic setup using a DOM container and the global Flat object. ```html
``` -------------------------------- ### play Event Source: https://flat.io/developers/docs/embed/api/events This event is triggered when playback starts. It does not include any data. ```APIDOC ## play Event ### Description This event is triggered when playback starts. This event doesn't include any data. ### Method `embed.on('play', () => { ... });` ### Response Example ```javascript embed.on('play', () => { console.log('Playback started'); }); ``` ``` -------------------------------- ### Authenticate with cURL Source: https://flat.io/developers/docs/api/authentication Example request using a personal access token to retrieve user information. ```bash curl -H 'Authorization: Bearer ' https://api.flat.io/v2/me ``` -------------------------------- ### Handle Playback Start Event Source: https://flat.io/developers/docs/embed/api/events Listen for the 'play' event to know when audio playback has begun. This event does not carry any specific data. ```typescript embed.on('play', () => { console.log('Playback started'); }); ``` -------------------------------- ### HTML Import Link Source: https://flat.io/developers/docs/import/usage An example of an anchor tag used to initiate an import with a specific file URL and title. ```html Edit with Flat ``` -------------------------------- ### Get All Parts in TypeScript Source: https://flat.io/developers/docs/embed/api/parts Retrieve a list of all instrument parts available in the loaded score. ```typescript getParts(): Promise ``` ```typescript // Get all parts const parts = await embed.getParts(); parts.forEach(part => { console.log(`${part.name}: ${part.uuid}`); }); ``` -------------------------------- ### Set Part Solo Mode Usage Example Source: https://flat.io/developers/docs/embed/api/parts Enables solo mode for the violin part. ```typescript // Solo the violin part const parts = await embed.getParts(); const violinPart = parts.find(p => p.instrument === 'violin'); await embed.setPartSoloMode({ partUuid: violinPart.uuid }); ``` -------------------------------- ### Implicit Grant Callback URI Source: https://flat.io/developers/docs/api/authentication Example of the URI hash structure received at the redirect_uri after successful authorization. ```text https://my-website.example.com/callback#scope=account.public_profile&expires_in=86400&access_token= ``` -------------------------------- ### GET /score/import-url Source: https://flat.io/developers/docs/import/usage Imports a MusicXML or MIDI file from a public URL into the Flat editor. ```APIDOC ## GET https://flat.io/score/import-url ### Description Allows users to import a publicly accessible MusicXML or MIDI file into Flat by providing the file URL. ### Method GET ### Endpoint https://flat.io/score/import-url ### Parameters #### Query Parameters - **url** (string) - Required - The full URL of the MusicXML or MIDI file to import. The file must be publicly accessible and served with CORS. - **title** (string) - Optional - The title of the file you are importing. Default: "New music score". - **app** (string) - Optional - Your app ID to display your app name and logo on the landing page. ### Request Example https://flat.io/score/import-url?url=https%3A%2F%2Fflat.io%2Fexamples%2Fhello-world.xml&title=Hello%20World ### Response #### Success Response (200) - The user is redirected to the Flat editor with the imported score. ``` -------------------------------- ### Sign-in Link Response Source: https://flat.io/developers/docs/api/flat-for-education Example JSON response when creating a sign-in link. It provides the unique URL and its expiration date. The URL is intended for a single use. ```json { "url": "https://flat.io/auth/signin-link/xxxxxxxxxxxxxxxxxxx?next=%2F", "expirationDate": "2021-11-30T13:12:09.783Z" } ``` -------------------------------- ### Set Part Volume Usage Example Source: https://flat.io/developers/docs/embed/api/parts Sets a specific part's volume to 75%. ```typescript // Set violin part to 75% volume const parts = await embed.getParts(); await embed.setPartVolume({ partUuid: parts[0].uuid, volume: 75 }); ``` -------------------------------- ### Access Token Response Source: https://flat.io/developers/docs/api/flat-for-education Example JSON response when creating an access token. It includes the token ID, name, the token itself, and its issue and expiration dates. ```json { "id": "61a4bc9750724f0013fdc7fd", "name": "Access token created by organization admin", "token": "An access token for your student account", "issuedDate": "2021-11-29T11:42:15.475Z", "expirationDate": "2021-11-30T11:42:15.475Z", "scopes": [ "scores", "collections" ] } ``` -------------------------------- ### Import API Endpoint Source: https://flat.io/developers/docs/import/usage The base URL for the GET request used to trigger the import process. ```text GET https://flat.io/score/import-url ``` -------------------------------- ### User Account Information Response Source: https://flat.io/developers/docs/api/flat-for-education Example JSON response when searching for a user account. It includes the user's ID, type, and roles within the organization and class. ```json [ { "id": "STUDENT_USER_ID", "type": "user", "organizationRole": "user", "classRole": "student", "username": "tony", ... } ] ``` -------------------------------- ### GET /v2/scores/{score}/revisions/{revision}/{format} Source: https://flat.io/developers/docs/api/changelog Fetches a specific format of a score revision, with an option to get the CDN URL of the exported file. ```APIDOC ## GET /v2/scores/{score}/revisions/{revision}/{format} ### Description Fetches a specific format of a score revision. Supports retrieving the CDN URL of the exported file. ### Method GET ### Endpoint `/v2/scores/{score}/revisions/{revision}/{format}` ### Query Parameters - **url** (boolean) - Optional - If true, returns the CDN URL of the exported file in the JSON body. ``` -------------------------------- ### Get metronome mode Source: https://flat.io/developers/docs/embed/api/playback Retrieves the current metronome setting. ```typescript getMetronomeMode(): Promise ``` ```typescript const embed = new Embed('container', config); const metronomeMode = await embed.getMetronomeMode(); console.log(metronomeMode); ``` -------------------------------- ### Core Methods Source: https://flat.io/developers/docs/embed/api Essential methods for initializing and configuring the Flat embed instance. ```APIDOC ## Core Methods ### ready() - **Description**: Returns a promise that resolves when the embed iframe has fully loaded and communication is established. ### getEmbedConfig() - **Description**: Retrieves the complete configuration object for the embed, including display settings, permissions, and enabled features. ### setEditorConfig(config) - **Description**: Updates the editor configuration for the embed. ``` -------------------------------- ### Get Part UUIDs Source: https://flat.io/developers/docs/embed/api/data Retrieves the unique identifiers for all parts in the score. ```APIDOC ## getPartsUuids() ### Description Get the part UUIDs of the score. ### Method GET (conceptual, as this is a method call) ### Endpoint N/A (Method call on an object) ### Parameters None ### Request Example ```typescript const partsUuids = await embed.getPartsUuids(); console.log(partsUuids); ``` ### Response #### Success Response (200) - **uuids** (string[]) - An array of unique part identifiers. #### Response Example ```json ["partUuid1", "partUuid2", "partUuid3"] ``` ### Throws - `Error` - If no score is loaded ``` -------------------------------- ### Include Flat Embed via CDN Source: https://flat.io/developers/docs/embed/javascript Load the SDK directly in an HTML file using the hosted script tag. ```html ``` -------------------------------- ### Get Measure UUIDs Source: https://flat.io/developers/docs/embed/api/data Retrieves the unique identifiers for all measures in the score. ```APIDOC ## getMeasuresUuids() ### Description Get the measure UUIDs of the score. ### Method GET (conceptual, as this is a method call) ### Endpoint N/A (Method call on an object) ### Parameters None ### Request Example ```typescript const measuresUuids = await embed.getMeasuresUuids(); console.log(measuresUuids); ``` ### Response #### Success Response (200) - **uuids** (string[]) - An array of unique measure identifiers. #### Response Example ```json ["uuid1", "uuid2", "uuid3"] ``` ### Throws - `Error` - If no score is loaded ``` -------------------------------- ### GET getPlaybackSpeed() Source: https://flat.io/developers/docs/embed/api/playback Retrieves the current playback speed multiplier from the embed. ```APIDOC ## GET getPlaybackSpeed() ### Description Retrieves the current playback speed multiplier. Normal speed is 1.0. ### Method GET ### Endpoint getPlaybackSpeed() ### Response - **Promise** - The current playback speed multiplier. ### Response Example 1.0 ``` -------------------------------- ### Embed Initialization and Readiness Source: https://flat.io/developers/docs/embed/api/core Methods related to initializing the embed and ensuring it is ready for interaction. ```APIDOC ## POST /developers/docs/embed/api/core.md ### Description Essential methods for embed initialization and configuration. ### Method N/A (This is a documentation overview, not a specific endpoint) ### Endpoint N/A ## ready() ### Description Wait for the embed to be ready. Returns a promise that resolves when the embed iframe has fully loaded and communication with the Flat embed has been established. This method is automatically called by all other embed methods, so you typically don't need to call it directly. However, it can be useful when you want to know exactly when the embed is ready without performing any other action. ### Method `ready()` ### Endpoint N/A ### Returns `Promise` - A promise that resolves when the embed is ready. ### Examples ```typescript // Explicitly wait for embed to be ready const embed = new Embed('container', { score: '56ae21579a127715a02901a6' }); await embed.ready(); console.log('Embed is now ready!'); ``` ### Notes All embed methods automatically call ready() internally, so explicit calls are optional. ``` -------------------------------- ### Get master volume Source: https://flat.io/developers/docs/embed/api/playback Retrieves the current master volume level. ```typescript getMasterVolume(): Promise ``` ```typescript const embed = new Embed('container', config); const masterVolume = await embed.getMasterVolume(); console.log(masterVolume); ``` -------------------------------- ### Core API Source: https://flat.io/developers/docs/embed/api Core API functions for initialization and configuration. ```APIDOC ## POST ready ### Description Returns a promise that resolves when the embed iframe has fully loaded and communication with the Flat embed has been established. ### Method POST ### Endpoint /api/core/ready ### Parameters None ### Request Example None ### Response #### Success Response (200) - **ready** (boolean) - True if the embed is ready, false otherwise. #### Response Example { "ready": true } ``` ```APIDOC ## POST setEditorConfig ### Description Updates the editor configuration for the embed. ### Method POST ### Endpoint /api/core/setEditorConfig ### Parameters #### Request Body - **config** (object) - Required - An object containing the editor configuration options. ### Request Example { "config": { "appearance": { "theme": "dark" } } } ### Response #### Success Response (200) - **success** (boolean) - Indicates if the configuration was updated successfully. #### Response Example { "success": true } ``` -------------------------------- ### List Scores Response Source: https://flat.io/developers/docs/api/flat-for-education Example JSON response when listing scores from a student's library. Includes score details like ID, title, and privacy settings. ```json [ { "id": "615adeb58e4ed600136ab31d", "title": "My first assignment - Tony Morris", "privacy": "private", .... }, .... ] ``` -------------------------------- ### GET /collections Source: https://flat.io/developers/docs/api/changelog Lists collections. Includes parent collections when listing scores. ```APIDOC ## GET /collections ### Description Lists collections. When listing scores, parent collections are now included. ### Method GET ### Endpoint /collections ### Response #### Success Response (200) - **collections** (array) - A list of collection objects. #### Response Example ```json { "collections": [ { "id": "collection_uuid", "name": "My Collection" } ] } ``` ``` -------------------------------- ### Configure Audio/Video Track Source: https://flat.io/developers/docs/embed/api/tracks Sets up a new audio or video track for synchronization with score playback. Ensure the `url` is provided for 'soundcloud' and 'audio' types, or `mediaId` for 'youtube' and 'vimeo'. The 'external' type requires `totalTime`. ```typescript const embed = new Embed('container', config); await embed.setTrack({ id: 'backing-track', type: 'audio', url: 'https://example.com/track.mp3', synchronizationPoints: [ { type: 'measure', measure: 0, time: 0 } ] }); ``` -------------------------------- ### GET /v2/classes Source: https://flat.io/developers/docs/api/changelog Retrieves a list of classes. Includes Microsoft Graph information. ```APIDOC ## GET /v2/classes ### Description Retrieves a list of classes. Includes Microsoft Graph information for each class. ### Method GET ### Endpoint /v2/classes ### Response #### Success Response (200) - **classes** (array) - A list of class objects, each potentially containing Microsoft Graph info. #### Response Example ```json { "classes": [ { "id": "class_uuid", "name": "Math 101", "microsoftGraphInfo": { "id": "mg_class_id" } } ] } ``` ``` -------------------------------- ### Playback & MIDI Options Source: https://flat.io/developers/docs/embed/url-parameters Adjust playback volume and enable MIDI controls. ```APIDOC ## GET /embed ### Description Configure playback and MIDI options for the embeddable Flat.io player. ### Method GET ### Endpoint /embed ### Query Parameters - **playbackMetronome** (string) - Optional - Metronome mode. Values: `count-in`, `inactive`, `active` (default = `inactive`). Available on embed plan. - **playbackVolumeMaster** (number) - Optional - Master volume. Values: `0` to `1` (default = `1`). Available on embed plan. - **MIDI** (boolean) - Optional - Enable MIDI Output Controls. Values: `true` or `false` (default = `false`). Available on embed plan. ``` -------------------------------- ### GET /v2/organizations/users Source: https://flat.io/developers/docs/api/flat-for-education Searches for organization user accounts to retrieve their unique identifiers. ```APIDOC ## GET /v2/organizations/users ### Description Retrieves a list of users in the organization, often used to find a user ID via email or username query. ### Method GET ### Endpoint /v2/organizations/users ### Parameters #### Query Parameters - **q** (string) - Optional - Search query (e.g., email address). ### Response #### Success Response (200) - **id** (string) - User unique identifier - **type** (string) - Entity type - **organizationRole** (string) - Role in organization - **classRole** (string) - Role in class - **username** (string) - Username #### Response Example [ { "id": "STUDENT_USER_ID", "type": "user", "organizationRole": "user", "classRole": "student", "username": "tony" } ] ``` -------------------------------- ### Listening to Events Source: https://flat.io/developers/docs/embed/javascript Explains how to listen for and respond to various events emitted by the embed, such as playback status and cursor position. ```APIDOC ## Event Handling API ### Description Listen to events emitted by the embed instance to react to score and playback changes. ### Methods - **`embed.on(eventName, callback)`**: Registers a callback function for a specific event. - **`embed.off(eventName, [callback])`**: Removes an event listener. If no callback is provided, all listeners for the event are removed. ### Available Events - **`scoreLoaded`**: Fired when the score has finished loading. - **`play`**: Fired when playback starts. - **`pause`**: Fired when playback is paused. - **`stop`**: Fired when playback is stopped. - **`cursorPosition`**: Fired when the playback cursor changes position. The callback receives the `position` object. - **`noteDetails`**: Fired when note information updates (e.g., during playback). ### Request Example ```javascript // Listen to playback events embed.on('play', () => { console.log('Playback started'); }); embed.on('pause', () => { console.log('Playback paused'); }); // Listen to cursor position changes embed.on('cursorPosition', (position) => { console.log('Cursor moved to:', position); }); // Remove event listener embed.off('play'); ``` ``` -------------------------------- ### Get Playback Speed Source: https://flat.io/developers/docs/embed/api/playback Retrieves the current playback speed multiplier as a promise. ```typescript getPlaybackSpeed(): Promise ``` ```typescript const embed = new Embed('container', config); const playbackSpeed = await embed.getPlaybackSpeed(); console.log(playbackSpeed); ``` -------------------------------- ### Get Auto-Zoom Status Source: https://flat.io/developers/docs/embed/api/display Checks whether auto-zoom mode is currently enabled. ```typescript getAutoZoom(): Promise ``` ```typescript const embed = new Embed('container', config); const autoZoom = await embed.getAutoZoom(); console.log(autoZoom); ``` -------------------------------- ### Get Zoom Ratio Source: https://flat.io/developers/docs/embed/api/display Retrieves the current zoom level of the score display. ```typescript getZoom(): Promise ``` ```typescript const embed = new Embed('container', config); const zoom = await embed.getZoom(); console.log(zoom); ``` -------------------------------- ### Create Access Token for End-User Source: https://flat.io/developers/docs/api/flat-for-education Use this endpoint to create an access token for a student user, granting specific scopes like 'scores' and 'collections'. Requires an admin API endpoint and a valid organization token. ```bash curl -X POST 'https://api.flat.io/v2/organizations/users/STUDENT_USER_ID/accessToken' \ -H "Authorization: Bearer $TOKEN" \ -H 'Content-Type: application/json' \ -d '{"scopes": ["scores", "collections"]}' ``` -------------------------------- ### Mute Part Usage Example Source: https://flat.io/developers/docs/embed/api/parts Mutes the audio output for a specific part. ```typescript const embed = new Embed('container', config); await embed.mutePart({ partUuid: '00000000-0000-0000-0000-000000000001' }); ``` -------------------------------- ### Load a MusicXML score with Flat Embed Source: https://flat.io/developers/docs/embed/javascript Initializes the embed and loads a MusicXML file from a URL. ```javascript const embed = new Flat.Embed(container, { embedParams: { appId: '', }, }); fetch('https://prod.flat-cdn.com/examples/hello-world.xml') .then(response => response.text()) .then(xml => embed.loadMusicXML(xml)) .then(() => { console.log('Embed is ready!'); }); ``` -------------------------------- ### Respect System Breaks (`respectSystemBreaks`) Source: https://flat.io/developers/docs/embed/url-parameters Maintains manual system breaks in responsive layout mode. Set to `true` to enable. ```APIDOC ## System breaks (`respectSystemBreaks`) ### Description Maintain manual system breaks in responsive layout mode. ### Method GET (Implicitly via embed URL parameters) ### Endpoint / ### Query Parameters - **respectSystemBreaks** (boolean) - Optional - If `true`, the responsive layout respects manual system breaks. ### Request Example ``` ?respectSystemBreaks=true ``` ### Response (No specific response body defined for this parameter, affects embed rendering) ### Response Example (N/A) ``` -------------------------------- ### Create Sign-in Link Source: https://flat.io/developers/docs/api/flat-for-education Generate a sign-in link for a specific end-user. This link can be used once to redirect the user to Flat.io and log them in. Requires the user's ID and an admin token. ```bash curl -X POST 'https://api.flat.io/v2/organizations/users/STUDENT_USER_ID/signinLink' \ -H "Authorization: Bearer $TOKEN" \ -H 'Content-Type: application/json' \ -d '{}' ``` -------------------------------- ### GET /collections/{collection} Source: https://flat.io/developers/docs/api/changelog Retrieves details of a specific collection. Includes creation date. ```APIDOC ## GET /collections/{collection} ### Description Retrieves details of a specific collection. Includes the `creationDate` property in the collection details. ### Method GET ### Endpoint /collections/{collection} ### Parameters #### Path Parameters - **collection** (string) - Required - The ID of the collection. ### Response #### Success Response (200) - **collectionDetails** (object) - Details of the collection, including creation date. #### Response Example ```json { "collectionDetails": { "id": "collection_uuid", "name": "My Collection", "creationDate": "2023-10-27T10:00:00Z" } } ``` ``` -------------------------------- ### GET /v2/organizations/users/count Source: https://flat.io/developers/docs/api/changelog Counts the number of users matching specified filters within an organization. ```APIDOC ## GET /v2/organizations/users/count ### Description Counts the number of users matching specified filters within an organization. ### Method GET ### Endpoint /v2/organizations/users/count ### Parameters #### Query Parameters - **filter** (string) - Optional - Filters to apply for counting users. ### Response #### Success Response (200) - **count** (integer) - The number of users matching the filters. #### Response Example ```json { "count": 150 } ``` ``` -------------------------------- ### Build Authorization Link Source: https://flat.io/developers/docs/api/authentication Construct the URL to redirect users to the Flat.io authorization page. ```text https://flat.io/auth/oauth?client_id=&response_type=(code|token)&state=&scope=account.public_profile+scores&redirect_uri= ``` -------------------------------- ### GET /v2/organizations/users Source: https://flat.io/developers/docs/api/changelog Retrieves a list of users within an organization. Supports sorting and filtering. ```APIDOC ## GET /v2/organizations/users ### Description Retrieves a list of users within an organization. Supports sorting options and filters. ### Method GET ### Endpoint /v2/organizations/users ### Parameters #### Query Parameters - **sort** (string) - Optional - Sorting options for the user list. - **filter** (string) - Optional - Filters to apply to the user list. ### Response #### Success Response (200) - **users** (array) - A list of user objects. #### Response Example ```json { "users": [ { "id": "user_uuid_1", "firstname": "John", "lastname": "Doe" }, { "id": "user_uuid_2", "firstname": "Jane", "lastname": "Smith" } ] } ``` ``` -------------------------------- ### Configure Embed Options Source: https://flat.io/developers/docs/embed/javascript Detailed constructor options for customizing the embed behavior and appearance. ```javascript const embed = new Flat.Embed(container, { // Score to load, you can also use `loadMusicXML()`, see example below score: '', // Or use a score URL baseUrl: 'https://flat.io/embed/', // Embed parameters embedParams: { // Your app ID (required) appId: '', // Display mode: 'view' (default) or 'edit' mode: 'view', // Controls position: 'top', 'bottom' (default), 'float', or 'hidden' controlsPosition: 'bottom', // Many more customization options available... }, // Container dimensions (optional) width: '100%', height: '100%', }); ``` -------------------------------- ### GET /v2/me Source: https://flat.io/developers/docs/api/changelog Fetches the current user's information, with an option to retrieve only their ID. ```APIDOC ## GET /v2/me ### Description Fetches the current user's information. Includes an option to quickly fetch only the user ID. ### Method GET ### Endpoint `/v2/me` ### Query Parameters - **onlyId** (boolean) - Optional - If true, fetches only the current user's ID. ``` -------------------------------- ### GET /auth/oauth Source: https://flat.io/developers/docs/api/authentication Redirects the user to the Flat.io authorization page to grant access to their account. ```APIDOC ## GET /auth/oauth ### Description Redirects the user to the Flat.io authorization page to grant your application access to their account. Supports both Authorization Code and Implicit grants. ### Method GET ### Endpoint https://flat.io/auth/oauth ### Parameters #### Query Parameters - **client_id** (string) - Required - The client id (key) provided by Flat. - **response_type** (string) - Required - Must be 'code' for Authorization Code grant or 'token' for Implicit grant. - **scope** (string) - Required - A space-separated list of scopes granted for your app. - **redirect_uri** (string) - Required - The URI where the response is sent; must match your App Credentials settings. - **state** (string) - Optional - An opaque string returned in the response for security. - **access_type** (string) - Optional - Available for Authorization Code grant; values: 'online' or 'offline' (returns refresh token). ``` -------------------------------- ### Authentication Overview Source: https://flat.io/developers/docs/api/authentication Details on how to authenticate requests using Personal Access Tokens or OAuth 2.0. ```APIDOC ## Authentication ### Description The Flat API uses OAuth 2.0 for authorization. For personal scripts, Personal Access Tokens can be generated in the Flat account settings and used in the Authorization header. ### Authorization Header - **Authorization** (string) - Required - Use the format `Bearer ` ### Request Example ```bash curl -H 'Authorization: Bearer ' https://api.flat.io/v2/me ``` ### OAuth2 Endpoints - **Authorization URL**: `https://flat.io/auth/oauth` - **Token URL**: `https://api.flat.io/oauth/access_token` - **Invalidation URL**: `https://api.flat.io/oauth/invalidate_token` ``` -------------------------------- ### loadMIDI() Source: https://flat.io/developers/docs/embed/api/score-management 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. ```APIDOC ## loadMIDI() ### Description 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. ### Method `loadMIDI` ### Parameters #### Path Parameters - **score** (Uint8Array) - Required - The MIDI score data as a Uint8Array. ### Request Example ```typescript // Load MIDI file from URL const response = await fetch('song.mid'); const buffer = await response.arrayBuffer(); await embed.loadMIDI(new Uint8Array(buffer)); // Load MIDI file from file input const file = document.getElementById('fileInput').files[0]; const buffer = await file.arrayBuffer(); await embed.loadMIDI(new Uint8Array(buffer)); ``` ### Response #### Success Response (200) - **void** - Indicates the score was loaded successfully. #### Error Handling - `TypeError` - If the score format is invalid - `Error` - If the MIDI file cannot be parsed or loaded ``` -------------------------------- ### Get Measure Details Source: https://flat.io/developers/docs/embed/api/data Retrieves comprehensive information about the current measure at the cursor position. ```APIDOC ## getMeasureDetails() ### Description Get detailed measure information. ### Method GET (conceptual, as this is a method call) ### Endpoint N/A (Method call on an object) ### Parameters None ### Request Example ```typescript const measureDetails = await embed.getMeasureDetails(); console.log(measureDetails); ``` ### Response #### Success Response (200) - **clef** (Clef) - Current clef in this measure. - **'displayed-time'** (DisplayedTime) - Time signature as displayed. - **key** (Key) - Current key signature. - **tempo** (Tempo) - Tempo marking. - **time** (Time) - Actual time signature. - **transpose** (Transpose) - Transposition settings for this measure. #### Response Example ```json { "clef": "treble", "displayed-time": "4/4", "key": "C major", "tempo": 120, "time": "4/4", "transpose": 0 } ``` ### Throws - `Error` - If no score is loaded or details cannot be retrieved ``` -------------------------------- ### Get Measure Details Source: https://flat.io/developers/docs/embed/api/data Retrieves comprehensive information about the measure at the current cursor position. ```typescript getMeasureDetails(): Promise ``` ```typescript const embed = new Embed('container', config); const measureDetails = await embed.getMeasureDetails(); console.log(measureDetails); ``` -------------------------------- ### Support for MIDI Output Source: https://flat.io/developers/docs/embed/changelog The SDK now supports MIDI output, enabling integration with MIDI devices and software. This feature was added in v1.1.0. ```javascript // Example usage for MIDI output would go here, if available. ``` -------------------------------- ### Get Number of Measures Source: https://flat.io/developers/docs/embed/api/data Retrieves the total count of measures in the currently loaded score. ```typescript getNbMeasures(): Promise ``` ```typescript const embed = new Embed('container', config); const nbMeasures = await embed.getNbMeasures(); console.log(nbMeasures); ``` -------------------------------- ### Migrate from jQuery to Vanilla JS Constructor Source: https://flat.io/developers/docs/embed/changelog This code demonstrates the migration required for the Flat Embed SDK constructor when moving from jQuery to vanilla JavaScript. Ensure the container element is correctly selected. ```javascript var container = $("#embed-container"); var embed = new Flat.Embed(container[0], { // your options }); ``` -------------------------------- ### Initialize Embed in ES6 Source: https://flat.io/developers/docs/embed/javascript Standard module import for modern JavaScript projects. ```javascript import Embed from 'flat-embed'; const container = document.getElementById('embed-container'); const embed = new Embed(container, { score: '', embedParams: { appId: '', controlsPosition: 'bottom', }, }); ``` -------------------------------- ### Unmute Part Usage Example Source: https://flat.io/developers/docs/embed/api/parts Restores the audio output for a previously muted part. ```typescript const embed = new Embed('container', config); await embed.unmutePart({ partUuid: '00000000-0000-0000-0000-000000000001' }); ``` -------------------------------- ### List Student Library Scores Source: https://flat.io/developers/docs/api/flat-for-education Use a delegated access token to interact with the end-user's account, such as listing scores in their library. Ensure the STUDENT_TOKEN environment variable is set. ```bash export STUDENT_TOKEN=student-access-token curl 'https://api.flat.io/v2/collections/root/scores' \ -H "Authorization: Bearer $STUDENT_TOKEN" ``` -------------------------------- ### Get Displayed Parts in TypeScript Source: https://flat.io/developers/docs/embed/api/parts Retrieve information about parts currently visible in the score interface. ```typescript getDisplayedParts(): Promise ``` ```typescript const embed = new Embed('container', config); const displayedParts = await embed.getDisplayedParts(); console.log(displayedParts); ``` -------------------------------- ### Working with Parts Source: https://flat.io/developers/docs/embed/javascript Details how to retrieve, control volume, and mute individual parts within a score. ```APIDOC ## Parts Management API ### Description Manage individual parts within a musical score, including retrieving information, adjusting volume, and muting. ### Methods - **`getParts()`**: Returns a promise that resolves to an array of part objects. - **`setPartVolume(options: { partUuid: string, volume: number })`**: Sets the volume for a specific part. `volume` should be between 0 and 100. - **`mutePart(options: { partUuid: string })`**: Mutes a specific part. - **`unmutePart(options: { partUuid: string })`**: Unmutes a specific part. - **`setPartSoloMode(options: { partUuid: string, solo: boolean })`**: Enables or disables solo mode for a part. - **`setDisplayedParts(options: { partUuids: string[], visible: boolean })`**: Shows or hides specified parts. ### Request Example ```javascript // Get all parts const parts = await embed.getParts(); console.log('Available parts:', parts); // Set volume for a specific part await embed.setPartVolume({ partUuid: parts[0].uuid, volume: 75 }); // Mute a part await embed.mutePart({ partUuid: parts[0].uuid }); // Set solo mode for a part await embed.setPartSoloMode({ partUuid: parts[1].uuid, solo: true }); ``` ``` -------------------------------- ### Get Part Reverb in TypeScript Source: https://flat.io/developers/docs/embed/api/parts Retrieve the current reverb level for a specific instrument part. ```typescript getPartReverb(parameters: { partUuid: string; }): Promise ``` ```typescript const embed = new Embed('container', config); const partReverb = await embed.getPartReverb({ partUuid: '00000000-0000-0000-0000-000000000001' }); console.log(partReverb); ``` -------------------------------- ### Audio & Video Sources Customization Source: https://flat.io/developers/docs/embed/url-parameters Configure audio and video sources for the embeddable player. ```APIDOC ## GET /embed ### Description Allows configuration of audio and video sources for the embeddable Flat.io player. ### Method GET ### Endpoint /embed ### Query Parameters - **audioSource** (string) - Optional - Audio source to use when loading the embed. Values: `playback`, `default`, or the unique identifier of the track. (default = `playback`). - **videoPosition** (string) - Optional - Display position of the video in the embed. Values: `top`, `bottom`, `left`, `float`, `hidden` (default = `hidden`). Available on embed plan. - **videoFitWidth** (boolean) - Optional - Should the video width fit the width of the container. Values: `true` or `false` (default = `false`). - **videoMaxHeight** (string) - Optional - Give a max height for the video. Example: `400px`. - **playbackMetronome** (string) - Optional - Metronome mode. Values: `count-in`, `inactive`, `active` (default = `inactive`). Available on embed plan. - **noAudio** (boolean) - Optional - Enable or disable the audio capabilities. Values: `true` or `false` (default = `false`). Available on embed plan. - **noPlayNote** (boolean) - Optional - Enable or disable the audio feedback when changing notes. Values: `true` or `false` (default = `false`). Available on embed plan. ``` -------------------------------- ### GET /collections/{collection}/rights Source: https://flat.io/developers/docs/api/changelog Retrieves rights information for a collection. Includes an `isCollaborator` boolean. ```APIDOC ## GET /collections/{collection}/rights ### Description Retrieves rights information for a collection. Returns an `isCollaborator` boolean property. ### Method GET ### Endpoint /collections/{collection}/rights ### Parameters #### Path Parameters - **collection** (string) - Required - The ID of the collection. ### Response #### Success Response (200) - **rights** (object) - Rights information for the collection. #### Response Example ```json { "rights": { "canEdit": true, "isCollaborator": true } } ``` ``` -------------------------------- ### GET /scores/{score}/rights Source: https://flat.io/developers/docs/api/changelog Retrieves rights information for a score. Includes an `isCollaborator` boolean. ```APIDOC ## GET /scores/{score}/rights ### Description Retrieves rights information for a score. Returns an `isCollaborator` boolean property. ### Method GET ### Endpoint /scores/{score}/rights ### Parameters #### Path Parameters - **score** (string) - Required - The ID of the score. ### Response #### Success Response (200) - **rights** (object) - Rights information for the score. #### Response Example ```json { "rights": { "canEdit": true, "isCollaborator": false } } ``` ``` -------------------------------- ### GET /v2/classes/{class} Source: https://flat.io/developers/docs/api/changelog Retrieves details of a specific class. Includes Microsoft Graph information. ```APIDOC ## GET /v2/classes/{class} ### Description Retrieves details of a specific class. Includes Microsoft Graph information for the class. ### Method GET ### Endpoint /v2/classes/{class} ### Parameters #### Path Parameters - **class** (string) - Required - The ID of the class. ### Response #### Success Response (200) - **classDetails** (object) - Details of the class, potentially including Microsoft Graph info. #### Response Example ```json { "classDetails": { "id": "class_uuid", "name": "Math 101", "microsoftGraphInfo": { "id": "mg_class_id" } } } ``` ``` -------------------------------- ### Parts API Source: https://flat.io/developers/docs/embed/api Methods for retrieving information about parts, including visibility, solo mode, volume, and reverb. ```APIDOC ## GET /api/parts/displayed ### Description Get the currently displayed parts. Retrieves information about which parts are currently visible in the score. ### Method GET ### Endpoint /api/parts/displayed ### Response #### Success Response (200) - **parts** (array) - A list of displayed part IDs. #### Response Example ```json { "parts": ["part-1", "part-3"] } ``` ## GET /api/parts/{partId}/soloMode ### Description Get the solo mode status of a part. Checks whether a specific part is currently in solo mode. ### Method GET ### Endpoint /api/parts/{partId}/soloMode ### Parameters #### Path Parameters - **partId** (string) - Required - The ID of the part. ### Response #### Success Response (200) - **isSolo** (boolean) - Whether the part is in solo mode. #### Response Example ```json { "isSolo": false } ``` ## GET /api/parts/{partId}/volume ### Description Get the volume of a specific part. Retrieves the current volume level for a specific instrument part in the score. ### Method GET ### Endpoint /api/parts/{partId}/volume ### Parameters #### Path Parameters - **partId** (string) - Required - The ID of the part. ### Response #### Success Response (200) - **volume** (number) - The volume level of the part (0.0 to 1.0). #### Response Example ```json { "volume": 0.7 } ``` ## GET /api/parts/{partId}/reverb ### Description Get the reverb level of a part. Retrieves the current reverb (reverberation) effect level for a specific instrument part. ### Method GET ### Endpoint /api/parts/{partId}/reverb ### Parameters #### Path Parameters - **partId** (string) - Required - The ID of the part. ### Response #### Success Response (200) - **reverb** (number) - The reverb level of the part (0.0 to 1.0). #### Response Example ```json { "reverb": 0.3 } ``` ## GET /api/parts ### Description Get information about all parts. Retrieves detailed information about all instrument parts in the score, including their names, instruments, and unique identifiers. ### Method GET ### Endpoint /api/parts ### Response #### Success Response (200) - **parts** (array) - A list of part objects. - **id** (string) - The unique ID of the part. - **name** (string) - The name of the part. - **instrument** (string) - The instrument of the part. #### Response Example ```json { "parts": [ { "id": "part-1", "name": "Piano", "instrument": "Grand Piano" }, { "id": "part-2", "name": "Violin", "instrument": "Violin" } ] } ``` ## GET /api/parts/uuids ### Description Get the part UUIDs of the score. Retrieves the unique identifiers for all parts in the score. ### Method GET ### Endpoint /api/parts/uuids ### Response #### Success Response (200) - **uuids** (array) - A list of part UUIDs. #### Response Example ```json { "uuids": ["uuid-part-1", "uuid-part-2"] } ``` ``` -------------------------------- ### GET /v2/groups/{group}/users Source: https://flat.io/developers/docs/api/changelog Retrieves users within a group, filterable by sync source. ```APIDOC ## GET /v2/groups/{group}/users ### Description Retrieves users within a group. Users can be filtered by their sync source: `googleClassroom`, `microsoftGraph`, or `clever`. ### Method GET ### Endpoint /v2/groups/{group}/users ### Parameters #### Path Parameters - **group** (string) - Required - The ID of the group. #### Query Parameters - **syncSource** (string) - Optional - The sync source to filter users by (e.g., `googleClassroom`, `microsoftGraph`, `clever`). ### Response #### Success Response (200) - **users** (array) - A list of user objects. #### Response Example ```json { "users": [ { "id": "user_uuid", "name": "Alice" } ] } ``` ``` -------------------------------- ### Make Authenticated API Request Source: https://flat.io/developers/docs/api/authentication Use the obtained access token in the Authorization header to call the Flat.io API. ```bash curl -H 'Authorization: Bearer ' https://api.flat.io/v2/me ``` -------------------------------- ### Get Number of Parts Source: https://flat.io/developers/docs/embed/api/data Retrieves the total count of instrument parts in the currently loaded score. ```APIDOC ## getNbParts() ### Description Get the number of parts in the score. ### Method GET (conceptual, as this is a method call) ### Endpoint N/A (Method call on an object) ### Parameters None ### Request Example ```typescript const nbParts = await embed.getNbParts(); console.log(nbParts); ``` ### Response #### Success Response (200) - **count** (number) - The total number of parts in the score. #### Response Example ```json 4 ``` ### Throws - `Error` - If no score is loaded ``` -------------------------------- ### Wait for Embed Readiness Source: https://flat.io/developers/docs/embed/javascript Use the ready promise to ensure the embed is fully loaded before interacting with it. ```javascript const embed = new Flat.Embed(container, { score: '56ae21579a127715a02901a6', embedParams: { appId: '', }, }); // Wait for the embed to be ready embed.ready().then(() => { console.log('Embed is ready!'); }); ``` -------------------------------- ### Get Number of Measures Source: https://flat.io/developers/docs/embed/api/data Retrieves the total count of measures (bars) in the currently loaded score. ```APIDOC ## getNbMeasures() ### Description Get the number of measures in the score. ### Method GET (conceptual, as this is a method call) ### Endpoint N/A (Method call on an object) ### Parameters None ### Request Example ```typescript const nbMeasures = await embed.getNbMeasures(); console.log(nbMeasures); ``` ### Response #### Success Response (200) - **count** (number) - The total number of measures in the score. #### Response Example ```json 128 ``` ### Throws - `Error` - If no score is loaded ``` -------------------------------- ### Get Number of Parts Source: https://flat.io/developers/docs/embed/api/data Retrieves the total count of instrument parts in the currently loaded score. ```typescript getNbParts(): Promise ``` ```typescript const embed = new Embed('container', config); const nbParts = await embed.getNbParts(); console.log(nbParts); ```