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.

Property	Summary
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.