JavaScript/TypeScript SDK - Installation & Setup ​

The Flat Embed SDK provides first-class TypeScript support with complete type definitions, IntelliSense, and compile-time safety. Use it with TypeScript for the best developer experience, or with plain JavaScript - the choice is yours!

Need More Features? ​

While this documentation covers our public API, we have additional internal methods that can be made available for specific use cases. If you need functionality that's not currently exposed in our public API, please contact our developers' support to discuss your requirements. We're happy to work with you to enable the features you need!

Installation ​

You can install our ES/TypeScript Embed Client using npm, pnpm, or yarn:

bash
npm install flat-embed
pnpm add flat-embed
yarn add flat-embed

Or use the latest UMD version hosted on our CDN:

html
<script src="https://prod.flat-cdn.com/embed-js/v2.4.1/embed.min.js"></script>

Getting Started ​

The simplest way to get started is to pass a DOM element to our embed that will be used as container. By default, this one will completely fit its container:

html
<div id="embed-container"></div>
<script src="https://prod.flat-cdn.com/embed-js/v2.4.1/embed.min.js"></script>
<script>
  var container = document.getElementById('embed-container');
  var embed = new Flat.Embed(container, {
    score: '<score-id-you-want-to-load>',
    embedParams: {
      appId: '<your-app-id>',
      controlsPosition: 'bottom',
    },
  });
</script>

Otherwise, if you are using our embed in an ES6 project:

js
import Embed from 'flat-embed';

const container = document.getElementById('embed-container');
const embed = new Embed(container, {
  score: '<score-id-you-want-to-load>',
  embedParams: {
    appId: '<your-app-id>',
    controlsPosition: 'bottom',
  },
});

TypeScript First! 🚀 ​

Our SDK is built with TypeScript and includes complete type definitions out of the box. Enjoy:

✅ Full IntelliSense - Auto-completion for all methods and parameters
✅ Type Safety - Catch errors at compile-time, not runtime
✅ Better Documentation - Inline documentation in your IDE
✅ Zero Configuration - Types included, no @types package needed

typescript
import Embed from 'flat-embed';

const container = document.getElementById('embed-container') as HTMLElement;
const embed = new Embed(container, {
  score: '5ce6a27f052b2a74a91f4a6d',
  embedParams: {
    appId: '<your-app-id>',
    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<PartConfiguration[]>

Constructor Options ​

When instantiating Flat.Embed, you can pass the following options:

javascript
const embed = new Flat.Embed(container, {
  // Score to load (required if not using baseUrl)
  score: '<score-id>',
  
  // Or use a score URL
  baseUrl: 'https://flat.io/embed/<score-id>',
  
  // Embed parameters
  embedParams: {
    // Your app ID (required)
    appId: '<your-app-id>',
    
    // 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%',
});

The embedParams object supports many customization options including:

  • Display options: zoom, page layout, print capabilities
  • Playback options: audio context, instruments, video playback
  • Theme options: colors, fonts, layout customization
  • Editor options: toolbar configuration, notation options

View all available embed parameters →

Basic Usage Examples ​

Loading a Score ​

javascript
const embed = new Flat.Embed(container, {
  score: '5ce6a27f052b2a74a91f4a6d',
  embedParams: {
    appId: '<your-app-id>',
  },
});

// Wait for the embed to be ready
embed.ready().then(() => {
  console.log('Embed is ready!');
});

Related methods:

Controlling Playback ​

javascript
// Start playback
await embed.play();

// Pause playback
await embed.pause();

// Stop playback
await embed.stop();

// Mute/unmute
await embed.mute();

Related methods:

Listening to Events ​

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');

Available events:

Working with Parts ​

javascript
// Get all parts in the score
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
});

Related methods:

Editor Mode ​

You can enable the editor mode by setting the mode to edit when creating the embed:

javascript
const embed = new Flat.Embed(container, {
  score: '<score-id>',
  embedParams: {
    appId: '<your-app-id>',
    mode: 'edit',
  },
});

Learn more about the editor mode →

Error Handling ​

All methods that return promises can be handled with standard error handling:

javascript
try {
  await embed.loadFlatScore('invalid-id');
} catch (error) {
  console.error('Failed to load score:', error);
}

// Or with promise chains
embed.loadFlatScore('invalid-id')
  .then(() => console.log('Score loaded'))
  .catch(error => console.error('Failed to load score:', error));

Browser Support ​

The Flat Embed SDK supports all modern browsers:

  • Chrome (latest)
  • Firefox (latest)
  • Safari (latest)
  • Edge (latest)

Need Help? ​

Copyright © Tutteo Limited

All rights reserved