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
userId End-user opaque identifier for billing & analytics purpose Learn more
sharingKey The score sharing key when the privacy mode is privateLink  
locale The language of the user interface en, en-GB, es, fr, de, it, ja, ja-HIRA, pt-BR, ru (default en for US English)

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 true or false (default = false)
noHeader Hide the header of the first page (title, composer, lyricist) true or false (default = false)
hideNonTab Only display the tablatures true or false (default = false)
showTabRests Display rests in TAB staff true or false (default = false)
hideTempo Do not display tempo marks true or false (default = false)
displayOutOfPitch Highlight notes our of tessitura true or false (default = true)
displayFirstLinePartsNames Hide part names true or false (default = true)
displayOtherLinesPartsNames Hide non first line part names true or false (default = false)
respectSystemBreaks Respect system breaks on responsive layout false
layoutId Apply a saved layout template from your account Read more

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)
noAudio Enable or disable the audio capabilities true or false (default = false)
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)

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

Editor mode

Query Parameter Summary Values
toolsetId Editor Toolset The toolset id to use (see below)
useQuarterTone Always enable quarter tone edition 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

Hide the header of the first page (noHeader)

You can use the parameter noHeader set to true to hide the header part of the page when using a page layout (layout = 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

Respect system breaks in Responsive Layout (respectSystemBreaks)

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)

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

Enable or disable audio capabilities (noAudio)

If this parameter is set to true, there will be no playback, and also no sound when adding a note or when moving around the cursor. Playback shortcuts will also be disabled.

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.

Saved engraving layout (layoutId)

In the editor on our webapp, you can save custom configuration of engraving layout and re-use them across scores. This can includes custom text fonts, engraving fonts, colors, spacings, sizes, etc.

On our generator page, 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()
themePrimaryDark Theme primary dark color (e.g. used for hover/focus states) color (hex, rgba() or hsla()
themeControlsBackground Controls bar background 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
  • themePrimary=#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