---
url: https://flat.io/developers/docs/embed/url-parameters.md
description: >-
  Quickly customize our music notation engraving embed with the different URL
  parameters available and add your own sheet music viewer on your website.
---

# Sheet music Embed URL parameters

When [embedding sheet music](index.html) in your website or blog, you can easily customize and control to appearance, the display and the features available for your visitors and users.

The easiest way is by adding different URL parameters of our iframe, you can find the different options available for you below.

Please note that most of the customizations below are ony available in our [Embed Starter and Pro plans](https://flat.io/embed), or may  require the usage of an [API key](https://flat.io/developers/apps). If you need additional options not listed below, feel free to [contact us](mailto:developers@flat.io), we will make sure our embed works for you!

| Query Parameter | Summary | Values |
|:----------------|:--------|:-------|
| `appId` | Your application identifier (aka API key) | [Get yours](https://flat.io/embed) |
| `userId` | End-user opaque identifier for billing & analytics purpose | [Learn more](/embed/usage-billing) |
| `sharingKey` | The score sharing key when the privacy mode is `privateLink` |  |
| `locale` | The language of the user interface | See [available locales](#available-locales) below (default: `en`) |
| `mode` | The mode of the embed | `view`, [`edit`](javascript-editor) [\*](#options-only-available-on-embed-plan) (default = `view`) |

### Available locales

The following locales are supported for the `locale` parameter (default: `en`):

* Danish (`da`)
* Dutch (`nl`)
* English US (`en`)
* English UK (`en-GB`)
* Filipino (`fil`)
* Finnish (`fi`)
* French (`fr`)
* Canadian French (`fr-CA`)
* German (`de`)
* Hindi (`hi`)
* Indonesian (`id`)
* Italian (`it`)
* Japanese (`ja`)
* Japanese Hiragana (`ja-HIRA`)
* Korean (`ko`)
* Malay (`ms`)
* Norwegian Bokmål (`nb`)
* Polish (`pl`)
* Portuguese (`pt`)
* Brazilian Portuguese (`pt-BR`)
* Romanian (`ro`)
* Russian (`ru`)
* Spanish (`es`)
* Swedish (`sv`)
* Turkish (`tr`)
* Simplified Chinese (`zh-Hans`)
* Traditional Chinese Hong Kong (`zh-HK`)
* Traditional Chinese Taiwan (`zh-TW`)

## Layout and Music notation Engraving parameters

These URL query strings control the engraving display of your music scores. You can get more details by clicking on the parameter name.

| Query Parameter | Summary | Values |
|:----------------|:--------|:-------|
| [`layout`](#layout-mode-layout) | Display the score in responsive, page or track mode | `responsive`, `page` or `track` (default = `responsive`) |
| [`zoom`](#zoom-zoom) | Default zoom value | `auto` or `0.1` to `3` (default = `auto`)|
| [`parts`](#parts-to-display-parts) | Specify the parts to display | All the parts |
| [`drawOnlyFirstPage`](#first-page-only-drawonlyfirstpage) [\*](#options-only-available-on-embed-plan) | Only display the first `page` | `true` or `false` (default = `false`) |
| [`noHeader`](#hide-header-noheader) [\*](#options-only-available-on-embed-plan) | Hide the header of the first `page` (title, composer, lyricist) | `true` or `false` (default = `false`) |
| [`hideNonTab`](#tablature-only-hidenontab) [\*](#options-only-available-on-embed-plan) | Only display the tablatures | `true` or `false` (default = `false`) |
| `showTabRests` [\*](#options-only-available-on-embed-plan) | Display rests in TAB staff | `true` or `false` (default = `false`) |
| [`hideTempo`](#hide-tempo-marks-hidetempo) [\*](#options-only-available-on-embed-plan) | Do not display tempo marks | `true` or `false` (default = `false`) |
| [`displayOutOfPitch`](#out-of-range-notes-displayoutofpitch) [\*](#options-only-available-on-embed-plan) | Highlight notes our of tessitura | `true` or `false` (default = `true`) |
| [`displayFirstLinePartsNames`](#hide-part-names-displayfirstlinepartsnames) [\*](#options-only-available-on-embed-plan) | Hide part names | `true` or `false` (default = `true`) |
| [`displayOtherLinesPartsNames`](#hide-subsequent-part-names-displayotherlinespartsnames) [\*](#options-only-available-on-embed-plan) | Hide non first line part names | `true` or `false` (default = `false`) |
| [`respectSystemBreaks`](#system-breaks-respectsystembreaks) [\*](#options-only-available-on-embed-plan) | Respect system breaks on responsive layout | `false` |
| [`layoutId`](#saved-engraving-layout-layoutid) [\*](#options-only-available-on-embed-plan) | Apply a saved layout template from your account | [Read more](#saved-engraving-layout)

## Controls & Theme customization

If you want to customize the controls, including changing their main colors or hide some of them, you can add the following options in your URL.

| Query Parameter | Summary | Values |
|:----------------|:--------|:-------|
| [`theme*`](#embed-theme) [\*](#options-only-available-on-embed-plan)| Change the embed theme | [Read more](#embed-theme) |
| [`branding`](#remove-flat-branding-branding) [\*](#options-only-available-on-embed-plan) | Display or hide Flat logo | `true` or `false` (default = `true`)|
| [`controlsDisplay`](#controls-visibility-controlsdisplay) [\*](#options-only-available-on-embed-plan) | Display or hide main controls | `true` or `false` (default = `true`)|
| [`controlsPosition`](#controls-position-controlsposition) [\*](#options-only-available-on-embed-plan) | Controls position | `bottom` or `top` (default = `bottom`)|
| [`controlsPlay`](#playback-control-controlsplay) [\*](#options-only-available-on-embed-plan) | Display or hide the playback controls | `true` or `false` (default = `true`)|
| [`hideFlatPlayback`](#hide-flat-playback-hideflatplayback) [\*](#options-only-available-on-embed-plan) | Hide Flat playback | `true` or `false` (default = `false`)|
| [`controlsFullscreen`](#fullscreen-control-controlsfullscreen) [\*](#options-only-available-on-embed-plan) | Display or hide the fullscreen button | `true` or `false` (default = `true`)|
| [`controlsPanel`](#extra-controls-button-controlspanel) [\*](#options-only-available-on-embed-plan) | Display or hide the extra controls button | `true` or `false` (default = `true`)|
| [`controlsZoom`](#zoom-controls-controlszoom) [\*](#options-only-available-on-embed-plan) | Display or hide the zoom control | `true` or `false` (default = `true`)|
| [`controlsPrint`](#print-control-controlsprint) [\*](#options-only-available-on-embed-plan) | Display or hide the print button | `true` or `false` (default = `true`)|
| [`controlsParts`](#parts-list-controlsparts) [\*](#options-only-available-on-embed-plan) | Display or hide the parts list | `true` or `false` (default = `false`)|

## Audio & Video sources

On any score on hosted on Flat, you can link one or multiple audio/video sources. These ones can be hosted on YouTube, SoundCloud or Vimeo. You can easily synchronize them using our user interface or [REST API](https://flat.io/developers/api/reference/#operation/addScoreTrack).

| Query Parameter | Summary | Values |
|:----------------|:--------|:-------|
| `audioSource` | Audio source to use when loading the embed | `playback`, `default` (the track marked as default, or playback if none), or the [unique identifier of the track to use](https://flat.io/developers/api/reference/#operation/listScoreTracks) (default value = `playback`) |
| [`videoPosition`](#video-position-videoposition) | Display position of the video in the embed | `top`, `bottom`, `left`, `float`, `hidden` (default = `hidden`) |
| `videoFitWidth` | Should the video width fit the width of the container | `true` or `false` (default = `false`) |
| `videoMaxHeight` | Give a max height for the video | CSS size value (e.g. `400px`) |
| `playbackMetronome`[\*](#options-only-available-on-embed-plan)  | Metronome mode | `count-in`, `inactive`, `active` (default = `inactive`) |
| [`noAudio`](#enable-or-disable-audio-capabilities-noaudio) [\*](#options-only-available-on-embed-plan) | Enable or disable the audio capabilities | `true` or `false` (default = `false`)|
| [`noPlayNote`](#enable-or-diable-the-audio-feedback-when-changing-notes-noplaynote) [\*](#options-only-available-on-embed-plan) | Enable or diable the audio feedback when changing notes ("play-note")  | `true` or `false` (default = `false`)|

## Playback & MIDI options

| Query Parameter | Summary | Values |
|:----------------|:--------|:-------|
| `playbackMetronome` [\*](#options-only-available-on-embed-plan) | Metronome mode | `count-in`, `inactive`, `active` (default = `inactive`) |
| `playbackVolumeMaster` [\*](#options-only-available-on-embed-plan) | Master volume | `0` to `1` (default = `1`) |
| `MIDI` [\*](#options-only-available-on-embed-plan) | Enable MIDI Output Controls | `true` or `false` (default = `false`) |

## Editor mode

| Query Parameter | Summary | Values |
|:----------------|:--------|:-------|
| `editorInterface` [\*](#options-only-available-on-embed-plan) | Editor interface style | `desktop` or `mobile` (default = `desktop`) |
| [`toolsetId`](#editor-toolset) [\*](#options-only-available-on-embed-plan)  | Editor Toolset | [The toolset id to use (see below)](#editor-toolset) |
| `useQuarterTone` [\*](#options-only-available-on-embed-plan) | Always enable quarter tone edition | `false` |

## Parameters details and demos

### Layout mode (`layout`)

Change how the music notation is displayed on the page.

We support three different engraving modes:

* `responsive`

![Layout Responsive mode](/img/embed-layout-responsive.png)

* `page`

![Layout Page mode](/img/embed-layout-page.png)

* `track` (default)

![Layout page mode](/img/embed-layout-track.png)

### Zoom (`zoom`)

Control the scaling of the sheet music display.

You can use different zoom values:

* `auto` (default): If you use a [`page` layout mode](#layout-mode-layout), the page will always fit the width of the embed, and be resize if you resize the embed. In [`track` layout mode](#layout-mode-layout), this is equivalent to `1`.
* `0.1` to `3`: A scaling value, where `1` is the regular size and `3` multiples the size by 3.

Example with `zoom=3` (i.e. Zoom x3):

![Embed zoom](/img/embed-zoom.png)

### Parts to display (`parts`)

Specify which instruments or voices to show in the score.

By default, the embed will display all the parts of your embedded documents. You can choose the parts to display by default, by providing the list of the parts with a `parts` parameter.

This parameter supports multiple formats for the parts references, which must be separated by a comma:

* Parts UUIDs,
* Part indexes (idx), starting at `0` for the first part,
* Part names (e.g. `Piano`),
* Part Abbreviation (e.g. `Pno.`)

Examples of valid inputs:

* `parts=0,3,4`
* `parts=Violin,Viola`

You can also use the [`controlsParts` option](#parts-list-controlsparts) to display a component that will allow your users to choose the part(s) to display.

### First page only (`drawOnlyFirstPage`)

Display only the first page of the score, useful for previews.

If you want to only draw the first page of the score, for example, to create a preview of a score. Please note that the complete file will still be completely loaded in the embed. To protect it, we advise you to use a dedicated preview file with only 1 page or little more available to display.

Here is a demo with this option and the following parameters:

* `drawOnlyFirstPage=true`
* `branding=false`
* `controlsPosition=top`
* `controlsPrint=false`

![Only display the first page](/img/embed-drawOnlyFirstPage.png)

### Hide header (`noHeader`)

Remove the title and composer information from the first page.

You can use the parameter `noHeader` set to `true` to hide the header part of the page when using a page layout (`layout` = `page`).

### Tablature only (`hideNonTab`)

Show only tablature staves and hide standard notation.

If you want to only display the tablatures of the parts, and hide the music notations staves, you can enable the `hideNonTab` option.

![Only TAB](/img/embed-hideNonTab.png)

### Hide tempo marks (`hideTempo`)

Remove tempo markings from the displayed score.

If you want to hide the tempo marks, you can enable the `hideTempo` option.

![No tempo marks](/img/embed-hideTempo.png)

### Out of range notes (`displayOutOfPitch`)

Highlight notes that are outside an instrument's playable range.

If notes go out of the tessitura (out of the available sound range for the instrument), there will be not playback for those notes.
By default we highlight those notes with a red color, and some transparency effect.
If you want to remove this behaviour, you can set the `displayOutOfPitch` to false.

![Notes out of tessitura](/img/embed-displayOutOfPitch.png)

### Hide part names (`displayFirstLinePartsNames`)

Remove instrument names from the score.

If you want to hide the part (instrument) names, you can set the `displayFirstLinePartsNames` option to false.

![Do not display part names](/img/embed-hideAllPartName.png)

### Hide subsequent part names (`displayOtherLinesPartsNames`)

Show instrument names only on the first system.

If you want to only display part (instrument) names on the first system, you can set the `displayOtherLinesPartsNames` option to false.

![Do not display part names](/img/embed-hideOtherPartName.png)

### System breaks (`respectSystemBreaks`)

Maintain manual system breaks in responsive layout mode.

If you want the responsive layout to respect the layout settings for the number of measures per system, and the
forced system breaks, you can set the `respectSystemBreaks` option to true.

### Remove Flat branding (`branding`)

Hide the Flat logo and attribution (requires paid plan).

To remove the Flat logo from the controls, set the parameter `branding` to `false`.

![No Flat branding](/img/embed-branding.png)

### Controls visibility (`controlsDisplay`)

Show or hide the playback control bar.

If you implements your own controls or don't need them, you can disable the ones in the embed by setting the parameter `controlsDisplay` to `false`.

![Embed controls](/img/embed-controls.png)

### Controls position (`controlsPosition`)

Set where the control bar appears on screen.

By default the controls are displayed at the `bottom` of the embed. You can choose the display them at the top by setting the parameter `controlsPosition` to `top`.

![Embed controls at the top](/img/embed-ctrl-top.png)

### Playback control (`controlsPlay`)

Show or hide the play/pause button.

This control is displayed by default, you can hide it by setting this parameter to `false`.

![Playback control](/img/embed-play-ctrl.png)

### Audio capabilities (`noAudio`)

Enable or disable all audio playback features.

When this parameter is set to true, playback will be disabled, and no sound will be heard when adding a note or moving the cursor. Additionally, playback shortcuts will be deactivated.

### Note audio feedback (`noPlayNote`)

Play sound when adding or editing notes.

When this parameter is set to true, no sound will play when adding a note or moving the cursor.

### Hide Flat playback (`hideFlatPlayback`)

Show only alternative audio sources, not Flat's built-in playback.

If you want to display only the alternative audio sources (mp3/video/soundcloud), set this one to true.

![Hide Flat Playback](/img/embed-hideFlatPlayback.png)

### Fullscreen control (`controlsFullscreen`)

Show or hide the fullscreen button.

This control is displayed by default, you can hide it by setting this parameter to `false`.

![Fullscreen control](/img/embed-fullscreen-ctrl.png)

### Extra controls button (`controlsPanel`)

Show or hide the menu for additional controls.

This control is displayed by default, you can hide it by setting this parameter to `false`.

![Side Panel control](/img/embed-panel-ctrl.png)

### Zoom controls (`controlsZoom`)

Show or hide the zoom in/out controls.

This side panel is enabled by default, you can disable it by setting this parameter to `false`.

![Zoom control](/img/embed-fullscreen-ctrl.png)

### Print control (`controlsPrint`)

Show or hide the print button.

This control is displayed by default, you can hide it by setting this parameter to `false`.

![Print control](/img/embed-fullscreen-ctrl.png)

### Parts list (`controlsParts`)

Show or hide the instrument selection dropdown.

This component can be displayed by setting this parameter to `true`, and having a score with at least two parts.

![Print control](/img/embed-parts-ctrl.png)

### Editor Toolset

When using our embeddable editor, you might want to only make specific tools available to your end-users. Toolsets configurations are linked to your Flat developer account and can be managed in the [Embed Generator page](https://flat.io/developers/embed/generator):

* Select the score to embed (or one of your testing scores if you want to use [`loadMusicXML()` from our SDK](/embed/javascript#loadmusicxmlscore-mixed-promisevoid-error))
* Click on "**Editor**" under the "**Embed mode**"
* Under the customizations features, you will be able to select and manage your toolsets:

![Select a toolset](/img/embed-toolset-input.png)

You can then create and update your own configurations. They will be previewed on the generator page, making it easy to test and experiment our embed with your custom toolsets.

![Select a toolset](/img/embed-toolset-panel-edit.png)

Once you selected a toolset, its identifier (`toolsetId`) will be displayed in the generated code or iframe URL at the bottom of the page.

**Notes about toolsets**:

* Using a toolset **will enable or disable the tools across the embed**: toolbars, interfaces on the top of the score, mouse, keyboard shortcuts, and JavaScript API methods.
* Since the configurations are saved in your developer account, when updating the configuration on the generator page, **the updated configuration will also be applied in your existing embeds where you are using the same `toolsetId`**.

## Saved engraving layout (`layoutId`)

In the editor on our webapp, [you can save custom configuration of engraving](https://flat.io/help/en/music-notation-software/layout-templates) layout and re-use them across scores. This can includes custom text fonts, engraving fonts, colors, spacings, sizes, etc.

On our [generator page](https://flat.io/developers/embed/generator), you can select a layout to get its unique identifier and pass it as parameter when loading the embed (`layoutId`).

This will allow to easily update all your embedded scores when you want to change some engraving settings, those will dynamically be applied to all your embedded scores where the identifier is used.

### Embed theme

You can completely change the embed theme by changing the different color options available:

| Parameter | Element | Values |
|-----------|---------|--------|
| `themePrimary` | Theme primary color (e.g. play button) | [color (hex, rgba() or hsla()](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value) |
| `themePrimaryDark` | Theme primary dark color (e.g. used for hover/focus states) | [color (hex, rgba() or hsla()](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value) |
| `themeControlsBackground` | Controls bar background | [color (hex, rgba() or hsla()](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value) |
| `themeSlider` | Playback slider color | [color (hex)](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value) |
| `themeCursorV0` | Cursor 1st Voice color | [color (hex)](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value) |
| `themeCursorV1` | Cursor 2nd Voice color | [color (hex)](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value) |
| `themeSelection` | Selection color | [color (hex)](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value) |
| `themeScoreBackground` | Background of score | `white` or `transparent` |

Please note that these parameters need to be encoded if needed (e.g. `themeControlsBackground=%23B71C1C`).

Demo: Let's say that we want to hide the Flat branding, display the controls different reds (controls background and main voice cursor). We can use the following options as query strings:

* [`branding=false`](#remove-flat-branding-branding)
* `themeControlsBackground=#B71C1C`
* `themePrimary=#E53935`
* `themeCursorV0=#E53935`

![Embed themes demo](/img/embed-colors.png)

The `transparent` background option (`themeScoreBackground`) can be used when your page has a light background that is not white and that you are using the [`page` layout mode](#layout-mode-layout):

![Non-white background](/img/embed-transparent-background.png)

### Video position (`videoPosition`)

When using an [audio or video source](#audio--video-sources), you can customize the position of the player: `top`, `bottom`, `left`, `float`, `hidden`.

### `top`

![Video on the top of the score](/img/embed-video-top.png)

### `left`

![Video on the left of the score](/img/embed-video-left.png)

### `float`

![Video floating of the score](/img/embed-video-float.png)

## Options only available on Embed plan

All the options with a `*` are only available in our [Embed plans](https://flat.io/embed). Other options are also available on [Flat](https://flat.io) and [Flat for Education](https://flat.io/edu).