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 simply the normal classes are used and changes are signaled via 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 issue 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 not to 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. This JSON schema can only be used at selected places.When attempting to set JSON values on the derivesalphaTab.Settings object, this can lead to unexpected side effects.The JSON schema can be used when initializing alphaTab or by 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 setup alphaTab should be 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
data-core-engineHTMLdata-engineHTML
Core.Engine.net
The engine which should be used to render the the tablature.
core.includeNoteBoundsJavaScriptincludeNoteBoundsJavaScript
data-core-includenoteboundsHTMLdata-includenoteboundsHTML
Core.IncludeNoteBounds.net
Gets or sets whether in the BoundsLookup also the position and area of each individual note is provided.
core.logLevelJavaScriptlogLevelJavaScript
data-core-loglevelHTMLdata-loglevelHTML
Core.LogLevel.net
The log level to use within alphaTab.
core.useWorkersJavaScriptuseWorkersJavaScript
data-core-useworkersHTMLdata-useworkersHTML
Core.UseWorkers.net
Gets or sets whether the rendering should be done in a worker if possible.
Core - JavaScript Specific
core.enableLazyLoadingJavaScriptenableLazyLoadingJavaScript
data-core-enablelazyloadingHTMLdata-enablelazyloadingHTML
Enables lazy loading of the rendered music sheet chunks.
core.fileJavaScriptfileJavaScript
data-core-fileHTMLdata-fileHTML
The full URL to the input file to be loaded.
core.fontDirectoryJavaScriptfontDirectoryJavaScript
data-core-fontdirectoryHTMLdata-fontdirectoryHTML
The full URL to the alphaTab font directory.
core.scriptFileJavaScriptscriptFileJavaScript
data-core-scriptfileHTMLdata-scriptfileHTML
Core.ScriptFile.net
The full URL to the alphaTab JavaScript file.
core.texJavaScripttexJavaScript
data-core-texHTMLdata-texHTML
Whether the contents of the DOM element should be loaded as alphaTex.
core.tracksJavaScripttracksJavaScript
data-core-tracksHTMLdata-tracksHTML
The tracks to display for the initally loaded file.
Display
display.barCountJavaScriptbarCountJavaScript
data-display-barcountHTMLdata-barcountHTML
Display.BarCount.net
The total number of bars that should be rendered from the song.
display.barCountPerPartialJavaScriptbarCountPerPartialJavaScript
data-display-barcountperpartialHTMLdata-barcountperpartialHTML
Display.BarCountPerPartial.net
The number of bars that should be placed within one partial render.
display.barsPerRowJavaScriptbarsPerRowJavaScript
data-display-barsperrowHTMLdata-barsperrowHTML
Display.BarsPerRow.net
Limit the displayed bars per row.
display.layoutModeJavaScriptlayoutModeJavaScript
data-display-layoutmodeHTMLdata-layoutmodeHTML
Display.LayoutMode.net
The layouting mode used to arrange the the notation.
display.paddingJavaScriptpaddingJavaScript
data-display-paddingHTMLdata-paddingHTML
Display.Padding.net
Adjusts the padding between the music notation and the border
display.resourcesJavaScriptresourcesJavaScript
data-display-resources-*HTMLdata-resources-*HTML
Display.Resources.net
Allows adjusting of the used fonts and colors for rendering.
display.scaleJavaScriptscaleJavaScript
data-display-scaleHTMLdata-scaleHTML
Display.Scale.net
Sets the zoom level of the rendered notation.
display.startBarJavaScriptstartBarJavaScript
data-display-startbarHTMLdata-startbarHTML
Display.StartBar.net
The bar start index to start layouting with.
display.staveProfileJavaScriptstaveProfileJavaScript
data-display-staveprofileHTMLdata-staveprofileHTML
Display.StaveProfile.net
The stave profile defining which staves are shown for the music sheet.
display.stretchForceJavaScriptstretchForceJavaScript
data-display-stretchforceHTMLdata-stretchforceHTML
Display.StretchForce.net
The default stretch force to use for layouting.
Importer
importer.encodingJavaScript
data-importer-encodingHTML
Importer.Encoding.net
The text encoding to use when decoding strings.
importer.mergePartGroupsInMusicXmlJavaScript
data-importer-mergepartgroupsinmusicxmlHTML
Importer.MergePartGroupsInMusicXml.net
If part-groups should be merged into a single track (MusicXML).
Notation
notation.displayTranspositionPitchesJavaScript
data-notation-displaytranspositionpitchesHTML
Notation.DisplayTranspositionPitches.net
The transposition pitch offsets for the individual tracks used for rendering only.
notation.elementsJavaScript
data-notation-elementsHTML
Notation.Elements.net
Render the song information or not.
notation.extendBendArrowsOnTiedNotesJavaScript
data-notation-extendbendarrowsontiednotesHTML
Notation.ExtendBendArrowsOnTiedNotes.net
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
data-notation-extendlineeffectstobeatendHTML
Notation.ExtendLineEffectsToBeatEnd.net
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
data-notation-fingeringmodeHTML
Notation.FingeringMode.net
Gets or sets the fingering mode to use.
notation.notationModeJavaScript
data-notation-notationmodeHTML
Notation.NotationMode.net
Gets or sets the mode to use for display and play music notation elements.
notation.RhythmHeightJavaScript
data-notation-rhythmheightHTML
Notation.RhythmHeight.net
Controls how high the ryhthm notation is rendered below the tab staff
notation.rhythmModeJavaScript
data-notation-rhythmmodeHTML
Notation.RhythmMode.net
Controls how the rhythm notation is rendered for tab staves.
notation.slurHeightJavaScript
data-notation-slurheightHTML
Notation.SlurHeight.net
The height scale factor for slurs
notation.smallGraceTabNotesJavaScript
data-notation-smallgracetabnotesHTML
Notation.SmallGraceTabNotes.net
If set to true the guitar tabs on grace beats are rendered smaller.
notation.transpositionPitchesJavaScript
data-notation-transpositionpitchesHTML
Notation.TranspositionPitches.net
The transposition pitch offsets for the individual tracks used for rendering and playback.
Player
player.enableCursorJavaScript
data-player-enablecursorHTML
Player.EnableCursor.net
Gets or sets whether playback cursors should be displayed.
player.enablePlayerJavaScript
data-player-enableplayerHTML
Player.EnablePlayer.net
Gets or sets whether the player should be enabled.
player.enableUserInteractionJavaScript
data-player-enableuserinteractionHTML
Player.EnableUserInteraction.net
Gets or sets whether the default user interaction behavior should be active or not.
player.playerOffsetXJavaScript
data-player-playeroffsetxHTML
Player.PlayerOffsetX.net
Gets or sets the X-offset to add when scrolling.
player.playTripletFeelJavaScript
data-player-playtripletfeelHTML
Player.PlayTripletFeel.net
Gets or sets whether the triplet feel should be played or only displayed.
player.scrollModeJavaScript
data-player-scrollmodeHTML
Player.ScrollMode.net
Gets or sets the mode how to scroll.
player.scrollOffsetYJavaScript
data-player-scrolloffsetyHTML
Player.ScrollOffsetY.net
Gets or sets the Y-offset to add when scrolling.
player.scrollSpeedJavaScript
data-player-scrollspeedHTML
Player.ScrollSpeed.net
Gets or sets how fast the scrolling to the new position should happen.
player.slideJavaScript
data-player-slideHTML
Player.Slide.net
The Slide settings allow control how the different slide types are generated for audio.
player.songBookBendDurationJavaScript
data-player-songbookbenddurationHTML
Player.SongBookBendDuration.net
The bend duration in milliseconds for songbook bends.
player.songBookDipDurationJavaScript
data-player-songbookdipdurationHTML
Player.SongBookDipDuration.net
The duration of whammy dips in milliseconds for songbook whammys.
player.vibratoJavaScript
data-player-vibratoHTML
Player.Vibrato.net
The Vibrato settings allow control how the different vibrato types are generated for audio.
Player - JavaScript Specific
player.scrollElementJavaScript
data-player-scrollelementHTML
Player.ScrollElement.net
The element to apply the scrolling on.
player.soundFontJavaScript
data-player-soundfontHTML
The sound font file to load for the player.