Sheet music Embed URL parameters

When embedding sheet music 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, or may require the usage of an API key. If you need additional options not listed below, feel free to contact us, we will make sure our embed works for you!

Query Parameter Summary Values
appId Your application identifier (aka API key) Get yours
sharingKey The score sharing key when the privacy mode is privateLink  

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 Display the score in responsive, page or track mode responsive, page or track (default = responsive)
zoom Default zoom value auto or 0.1 to 3 (default = auto)
parts Specify the parts to display all the parts
drawOnlyFirstPage Only display the first page false
hideNonTab Only display the tablatures false
hideTempo Do not display tempo marks false
displayOutOfPitch Highlight notes our of tessitura true
displayFirstLinePartsNames Hide part names true
displayOtherLinesPartsNames Hide non first line part names false

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* Change the embed theme Read more
branding Display or hide Flat logo true or false (default = true)
controlsDisplay Display or hide main controls true or false (default = true)
controlsPosition Controls position bottom or top (default = bottom)
controlsPlay Display or hide the playback controls true or false (default = true)
hideFlatPlayback Hide Flat playback true or false (default = false)
controlsFullscreen Display or hide the fullscreen button true or false (default = true)
controlsPanel Display or hide the extra controls button true or false (default = true)
controlsZoom Display or hide the zoom control true or false (default = true)
controlsPrint Display or hide the print button true or false (default = true)
controlsParts Display or hide the parts list true or false (default = false)
toolsetId Editor Toolset The toolset id to use (see below)

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.

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 (default value = playback)
videoPosition Display position of the video in the embed top, bottom, left, float, hidden (default = hidden)
playbackMetronome Metronome mode count-in, inactive, active (default = inactive)

Playback & MIDI options

Query Parameter Summary Values
playbackMetronome Metronome mode count-in, inactive, active (default = inactive)
playbackVolumeMaster Master volume 0 to 1 (default = 1)
MIDI Enable MIDI Output Controls true or false (default = false)

Parameters details and demos

Change the music engraving layout mode (layout)

We support three different engraving modes:

  • responsive

Layout Responsive mode

  • page

Layout Page mode

  • track (default)

Layout page mode

Change zoom scaling (zoom)

You can use different zoom values:

  • auto (default): If you use a page layout mode, the page will always fit the width of the embed, and be resize if you resize the embed. In track layout mode, 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

Specify the parts to display (parts)

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 to display a component that will allow your users to choose the part(s) to display.

Only display the first page (drawOnlyFirstPage)

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

Only display the tablature of the parts (hideNonTab)

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

Do not display tempo marks (hideTempo)

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

No tempo marks

Highlight notes out of tessitura (displayOutOfPitch)

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

Hide part names (displayFirstLinePartsNames)

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

Do not display part names

Hide non first part names (displayOtherLinesPartsNames)

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

Remove Flat branding (branding)

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

No Flat branding

Display or hide the controls (controlsDisplay)

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

Change controls position (controlsPosition)

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

Display or hide Playback control (controlsPlay)

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

Playback control

Hide Flat playback (hideFlatPlayback)

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

Hide Flat Playback

Display or hide Fullscreen control (controlsFullscreen)

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

Fullscreen control

Display or hide the extra controls button (controlsPanel)

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

Side Panel control

Display or hide the Zoom controls (controlsZoom)

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

Zoom control

Display or hide Print control (controlsPrint)

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

Print control

Display or hide the Parts List (controlsParts)

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

Print control

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:

  • Select the score to embed (or one of your testing scores if you want to use loadMusicXML() from our SDK)
  • Click on “Editor” under the “Embed mode
  • Under the customizations features, you will be able to select and manage your toolsets:

Select a toolset

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

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.

Embed theme

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

Parameter Element Values
themeIconsPrimary Icons primary color (e.g. play button) color (hex, rgba() or hsla()
themeControlsBackground Controls bar background color (hex, rgba() or hsla()
themeControlsIcons Controls icons color (e.g. metronome) color (hex, rgba() or hsla()
themeSlider Playback slider color color (hex)
themeCursorV0 Cursor 1st Voice color color (hex)
themeCursorV1 Cursor 2nd Voice color color (hex)
themeSelection Selection color color (hex)
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
  • themeControlsBackground=#B71C1C
  • themeIconsPrimary=#E53935
  • themeCursorV0=#E53935

Embed themes demo

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:

Non-white background

Video position (videoPosition)

When using an audio or video source, you can customize the position of the player: top, bottom, left, float, hidden.


Video on the top of the score


Video on the left of the score


Video floating of the score