Skip to main content

Settings

This section contains a list of all properties that allow configuration of the alphaTab behavior.

There are multiple ways how settings in alphaTab can be specified. For .net, the normal classes are used and changes are signaled via an UpdateSettings call. For JavaScript, the interaction with the settings is a bit more sensitive due to the lack of type safety and the support of JSON based settings.

Not all settings contain reasonable examples as they often just activate something within alphaTab or change the display of some notation. If you have questions on certain settings, feel free to open a Discussion on GitHub.

The first and most important rule is: when interacting with the settings object directly, the correct structure and data types must be followed to not break alphaTab or make the changes useless. In order to simplify things when configuring alphaTab via JavaScript there are 2 additional features:

  1. AlphaTab can be configured via a simple plain JSON object. This JSON format supports some aliases and also some value conversions like for enums, fonts and colors. The JSON schema can only be used at selected places. Attempting to set JSON values on the derived alphaTab.Settings object can lead to unexpected side effects. The JSON schema can be used when initializing alphaTab or when calling settings.fillFromJson( ... ).

  2. AlphaTab can be configured via HTML data attributes. All settings can also be added as data attributes on the element for which alphaTab is initialized. This is especially useful when multiple different instances of alphaTab are running on the same site but the main code to set up alphaTab is shared. Individual settings can be specified on HTML elements.

The following table contains all the properties as they can be set on the general settings object.

PropertySummary
Core
core.engineJavaScriptengineJavaScript
core.engineJSONengineJSON
data-core-engineHTMLdata-engineHTML
Core.Engine.net
core.engineAndroid
The engine which should be used to render the the tablature.
core.includeNoteBoundsJavaScriptincludeNoteBoundsJavaScript
core.includeNoteBoundsJSONincludeNoteBoundsJSON
data-core-includenoteboundsHTMLdata-includenoteboundsHTML
Core.IncludeNoteBounds.net
core.includeNoteBoundsAndroid
Gets or sets whether in the BoundsLookup also the position and area of each individual note is provided.
core.logLevelJavaScriptlogLevelJavaScript
core.logLevelJSONlogLevelJSON
data-core-loglevelHTMLdata-loglevelHTML
Core.LogLevel.net
core.logLevelAndroid
The log level to use within alphaTab.
core.useWorkersJavaScriptuseWorkersJavaScript
core.useWorkersJSONuseWorkersJSON
data-core-useworkersHTMLdata-useworkersHTML
Core.UseWorkers.net
core.useWorkersAndroid
Whether the rendering should be done in a worker if possible.
Core - JavaScript Specific
core.enableLazyLoadingJavaScriptenableLazyLoadingJavaScript
core.enableLazyLoadingJSONenableLazyLoadingJSON
data-core-enablelazyloadingHTMLdata-enablelazyloadingHTML
Enables lazy loading of the rendered music sheet chunks.
core.fileJavaScriptfileJavaScript
core.fileJSONfileJSON
data-core-fileHTMLdata-fileHTML
The full URL to the input file to be loaded.
core.fontDirectoryJavaScriptfontDirectoryJavaScript
core.fontDirectoryJSONfontDirectoryJSON
data-core-fontdirectoryHTMLdata-fontdirectoryHTML
The full URL to the alphaTab font directory.
core.scriptFileJavaScriptscriptFileJavaScript
core.scriptFileJSONscriptFileJSON
data-core-scriptfileHTMLdata-scriptfileHTML
The full URL to the alphaTab JavaScript file.
core.texJavaScripttexJavaScript
core.texJSONtexJSON
data-core-texHTMLdata-texHTML
Whether the contents of the DOM element should be loaded as alphaTex.
core.tracksJavaScripttracksJavaScript
core.tracksJSONtracksJSON
data-core-tracksHTMLdata-tracksHTML
The tracks to display for the initally loaded file.
Display
display.barCountJavaScriptbarCountJavaScript
display.barCountJSONbarCountJSON
data-display-barcountHTMLdata-barcountHTML
Display.BarCount.net
display.barCountAndroid
The total number of bars that should be rendered from the song.
display.barCountPerPartialJavaScriptbarCountPerPartialJavaScript
display.barCountPerPartialJSONbarCountPerPartialJSON
data-display-barcountperpartialHTMLdata-barcountperpartialHTML
Display.BarCountPerPartial.net
display.barCountPerPartialAndroid
The number of bars that should be placed within one partial render.
display.barsPerRowJavaScriptbarsPerRowJavaScript
display.barsPerRowJSONbarsPerRowJSON
data-display-barsperrowHTMLdata-barsperrowHTML
Display.BarsPerRow.net
display.barsPerRowAndroid
Limit the displayed bars per row.
display.justifyLastSystemJavaScriptjustifyLastSystemJavaScript
display.justifyLastSystemJSONjustifyLastSystemJSON
data-display-justifylastsystemHTMLdata-justifylastsystemHTML
Display.JustifyLastSystem.net
display.justifyLastSystemAndroid
Whether to justify also the last system in page layouts.
display.layoutModeJavaScriptlayoutModeJavaScript
display.layoutModeJSONlayoutModeJSON
data-display-layoutmodeHTMLdata-layoutmodeHTML
Display.LayoutMode.net
display.layoutModeAndroid
The layouting mode used to arrange the the notation.
display.paddingJavaScriptpaddingJavaScript
display.paddingJSONpaddingJSON
data-display-paddingHTMLdata-paddingHTML
Display.Padding.net
display.paddingAndroid
Adjusts the padding between the music notation and the border
display.resourcesJavaScriptresourcesJavaScript
display.resourcesJSONresourcesJSON
data-display-resources-*HTMLdata-resources-*HTML
Display.Resources.net
display.resourcesAndroid
Allows adjusting of the used fonts and colors for rendering.
display.scaleJavaScriptscaleJavaScript
display.scaleJSONscaleJSON
data-display-scaleHTMLdata-scaleHTML
Display.Scale.net
display.scaleAndroid
The zoom level of the rendered notation.
display.startBarJavaScriptstartBarJavaScript
display.startBarJSONstartBarJSON
data-display-startbarHTMLdata-startbarHTML
Display.StartBar.net
display.startBarAndroid
The bar start index to start layouting with.
display.staveProfileJavaScriptstaveProfileJavaScript
display.staveProfileJSONstaveProfileJSON
data-display-staveprofileHTMLdata-staveprofileHTML
Display.StaveProfile.net
display.staveProfileAndroid
The stave profile defining which staves are shown for the music sheet.
display.stretchForceJavaScriptstretchForceJavaScript
display.stretchForceJSONstretchForceJSON
data-display-stretchforceHTMLdata-stretchforceHTML
Display.StretchForce.net
display.stretchForceAndroid
The default stretch force to use for layouting.
display.systemsLayoutModeJavaScriptsystemsLayoutModeJavaScript
display.systemsLayoutModeJSONsystemsLayoutModeJSON
data-display-systemslayoutmodeHTMLdata-systemslayoutmodeHTML
Display.SystemsLayoutMode.net
display.systemsLayoutModeAndroid
The mode used to arrange staves and systems.
Importer
importer.beatTextAsLyricsJavaScript
importer.beatTextAsLyricsJSON
data-importer-beattextaslyricsHTML
Importer.BeatTextAsLyrics.net
importer.beatTextAsLyricsAndroid
Enables detecting lyrics from beat texts
importer.encodingJavaScript
importer.encodingJSON
data-importer-encodingHTML
Importer.Encoding.net
importer.encodingAndroid
The text encoding to use when decoding strings.
importer.mergePartGroupsInMusicXmlJavaScript
importer.mergePartGroupsInMusicXmlJSON
data-importer-mergepartgroupsinmusicxmlHTML
Importer.MergePartGroupsInMusicXml.net
importer.mergePartGroupsInMusicXmlAndroid
If part-groups should be merged into a single track (MusicXML).
Notation
notation.displayTranspositionPitchesJavaScript
notation.displayTranspositionPitchesJSON
data-notation-displaytranspositionpitchesHTML
Notation.DisplayTranspositionPitches.net
notation.displayTranspositionPitchesAndroid
The transposition pitch offsets for the individual tracks used for rendering only.
notation.elementsJavaScript
notation.elementsJSON
data-notation-elementsHTML
Notation.Elements.net
notation.elementsAndroid
Render the song information or not.
notation.extendBendArrowsOnTiedNotesJavaScript
notation.extendBendArrowsOnTiedNotesJSON
data-notation-extendbendarrowsontiednotesHTML
Notation.ExtendBendArrowsOnTiedNotes.net
notation.extendBendArrowsOnTiedNotesAndroid
If set to true bend arrows expand to the end of the last tied note of the string. Otherwise they end on the next beat.
notation.extendLineEffectsToBeatEndJavaScript
notation.extendLineEffectsToBeatEndJSON
data-notation-extendlineeffectstobeatendHTML
Notation.ExtendLineEffectsToBeatEnd.net
notation.extendLineEffectsToBeatEndAndroid
If set to true, line effects like w/bar and let-ring are drawn until the end of the beat instead of the start
notation.fingeringModeJavaScript
notation.fingeringModeJSON
data-notation-fingeringmodeHTML
Notation.FingeringMode.net
notation.fingeringModeAndroid
The fingering mode to use.
notation.notationModeJavaScript
notation.notationModeJSON
data-notation-notationmodeHTML
Notation.NotationMode.net
notation.notationModeAndroid
The mode to use for display and play music notation elements.
notation.rhythmHeightJavaScript
notation.rhythmHeightJSON
data-notation-rhythmheightHTML
Notation.RhythmHeight.net
notation.rhythmHeightAndroid
Controls how high the ryhthm notation is rendered below the tab staff
notation.rhythmModeJavaScript
notation.rhythmModeJSON
data-notation-rhythmmodeHTML
Notation.RhythmMode.net
notation.rhythmModeAndroid
Controls how the rhythm notation is rendered for tab staves.
notation.slurHeightJavaScript
notation.slurHeightJSON
data-notation-slurheightHTML
Notation.SlurHeight.net
notation.slurHeightAndroid
The height scale factor for slurs
notation.smallGraceTabNotesJavaScript
notation.smallGraceTabNotesJSON
data-notation-smallgracetabnotesHTML
Notation.SmallGraceTabNotes.net
notation.smallGraceTabNotesAndroid
If set to true the guitar tabs on grace beats are rendered smaller.
notation.transpositionPitchesJavaScript
notation.transpositionPitchesJSON
data-notation-transpositionpitchesHTML
Notation.TranspositionPitches.net
notation.transpositionPitchesAndroid
The transposition pitch offsets for the individual tracks used for rendering and playback.
Player
player.bufferTimeInMillisecondsJavaScript
player.bufferTimeInMillisecondsJSON
data-player-buffertimeinmillisecondsHTML
Player.BufferTimeInMilliseconds.net
player.bufferTimeInMillisecondsAndroid
The number of milliseconds the player should buffer.
player.enableAnimatedBeatCursorJavaScript
player.enableAnimatedBeatCursorJSON
data-player-enableanimatedbeatcursorHTML
Player.EnableAnimatedBeatCursor.net
player.enableAnimatedBeatCursorAndroid
Whether the beat cursor should be animated or just ticking.
player.enableCursorJavaScript
player.enableCursorJSON
data-player-enablecursorHTML
Player.EnableCursor.net
player.enableCursorAndroid
Whether playback cursors should be displayed.
player.enableElementHighlightingJavaScript
player.enableElementHighlightingJSON
data-player-enableelementhighlightingHTML
Player.EnableElementHighlighting.net
player.enableElementHighlightingAndroid
Whether the notation elements of the currently played beat should be highlighted.
player.enablePlayerJavaScript
player.enablePlayerJSON
data-player-enableplayerHTML
Player.EnablePlayer.net
player.enablePlayerAndroid
Whether the player should be enabled.
player.enableUserInteractionJavaScript
player.enableUserInteractionJSON
data-player-enableuserinteractionHTML
Player.EnableUserInteraction.net
player.enableUserInteractionAndroid
Whether the default user interaction behavior should be active or not.
player.nativeBrowserSmoothScrollJavaScript
player.nativeBrowserSmoothScrollJSON
data-player-nativebrowsersmoothscrollHTML
Whether the native browser smooth scroll mechanism should be used over a custom animation.
player.playTripletFeelJavaScript
player.playTripletFeelJSON
data-player-playtripletfeelHTML
Player.PlayTripletFeel.net
player.playTripletFeelAndroid
Whether the triplet feel should be played or only displayed.
player.playerOffsetXJavaScript
player.playerOffsetXJSON
data-player-playeroffsetxHTML
Player.PlayerOffsetX.net
player.playerOffsetXAndroid
The X-offset to add when scrolling.
player.scrollModeJavaScript
player.scrollModeJSON
data-player-scrollmodeHTML
Player.ScrollMode.net
player.scrollModeAndroid
The mode how to scroll.
player.scrollOffsetYJavaScript
player.scrollOffsetYJSON
data-player-scrolloffsetyHTML
Player.ScrollOffsetY.net
player.scrollOffsetYAndroid
The Y-offset to add when scrolling.
player.scrollSpeedJavaScript
player.scrollSpeedJSON
data-player-scrollspeedHTML
Player.ScrollSpeed.net
player.scrollSpeedAndroid
How fast the scrolling to the new position should happen.
player.slideJavaScript
player.slideJSON
data-player-slideHTML
Player.Slide.net
player.slideAndroid
The slide settings allow control how the different slide types are generated for audio.
player.songBookBendDurationJavaScript
player.songBookBendDurationJSON
data-player-songbookbenddurationHTML
Player.SongBookBendDuration.net
player.songBookBendDurationAndroid
The bend duration in milliseconds for songbook bends.
player.songBookDipDurationJavaScript
player.songBookDipDurationJSON
data-player-songbookdipdurationHTML
Player.SongBookDipDuration.net
player.songBookDipDurationAndroid
The duration of whammy dips in milliseconds for songbook whammys.
player.vibratoJavaScript
player.vibratoJSON
data-player-vibratoHTML
Player.Vibrato.net
player.vibratoAndroid
The Vibrato settings allow control how the different vibrato types are generated for audio.
Player - JavaScript Specific
player.outputModeJavaScript
player.outputModeJSON
data-player-outputmodeHTML
The mode used for playing audio samples
player.scrollElementJavaScript
player.scrollElementJSON
data-player-scrollelementHTML
The element to apply the scrolling on.
player.soundFontJavaScript
player.soundFontJSON
data-player-soundfontHTML
The sound font file to load for the player.