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. For take of simplicity the table lists the properties with the JavaScript naming convention, but if properties are listed with all they are available on all platforms (e.g. in C# with PascalCase).

PropertySummary
Core
core.enableLazyLoadingAllEnables lazy loading of the rendered music sheet chunks.
core.engineAllThe engine which should be used to render the the tablature.
core.includeNoteBoundsAllWhether in the <code style={{"color":"#393A34","backgroundColor":"#f6f8fa"}}><span style={{"color":"#36acaa"}}>{"BoundsLookup"}</span></code> also the position and area of each individual note is provided.
core.logLevelAllThe log level to use within alphaTab
core.useWorkersAllWhether the rendering should be done in a worker if possible.
Core - JavaScript Specific
core.fileJavaScriptThe full URL to the input file to be loaded.
core.fontDirectoryJavaScriptThe full URL to the alphaTab font directory.
core.scriptFileJavaScriptThe full URL to the alphaTab JavaScript file.
core.texJavaScriptWhether the contents of the DOM element should be loaded as alphaTex.
core.tracksJavaScriptThe tracks to display for the initally loaded file.
Display
display.accoladeBarPaddingRightAllThe padding between the accolade bar and the start of the bar itself.
display.barCountAllThe total number of bars that should be rendered from the song. (-1 for all bars)
display.barCountPerPartialAllThe number of bars that should be placed within one partial render.
display.barsPerRowAllLimit the displayed bars per system (row). (-1 for automatic mode)
display.effectStaffPaddingBottomAllThe bottom padding applied to effect annotation staffs.
display.effectStaffPaddingTopAllThe top padding applied to effect annotation staffs.
display.firstStaffPaddingLeftAllThe left padding applied between the left line and the first glyph in the first staff in a system.
display.firstSystemPaddingTopAllThe top padding applied to first system.
display.justifyLastSystemAllWhether to justify also the last system in page layouts.
display.lastSystemPaddingBottomAllThe bottom padding applied to the last system.
display.layoutModeAllThe layouting mode used to arrange the the notation.
display.notationStaffPaddingBottomAllThe bottom padding applied to main notation staves (standard, tabs, numbered, slash).
display.notationStaffPaddingTopAllThe bottom padding applied to main notation staves (standard, tabs, numbered, slash).
display.paddingAllAdjusts the padding between the music notation and the border.
display.resourcesAllAllows adjusting of the used fonts and colors for rendering.
display.scaleAllThe zoom level of the rendered notation.
display.staffPaddingLeftAllThe left padding applied between the left line and the first glyph in the following staff in a system.
display.startBarAllThe bar start index to start layouting with.
display.staveProfileAllThe stave profile defining which staves are shown for the music sheet.
display.stretchForceAllThe default stretch force to use for layouting.
display.systemLabelPaddingLeftAllThe padding left to the track name label of the system.
display.systemLabelPaddingRightAllThe padding left to the track name label of the system.
display.systemPaddingBottomAllThe bottom padding applied to systems beside the last one.
display.systemPaddingTopAllThe top padding applied systems beside the first one.
display.systemsLayoutModeAllThe mode used to arrange staves and systems.
Importer
importer.beatTextAsLyricsAllEnables detecting lyrics from beat texts
importer.encodingAllThe text encoding to use when decoding strings.
importer.mergePartGroupsInMusicXmlAllIf part-groups should be merged into a single track (MusicXML).
Notation
notation.displayTranspositionPitchesAllThe transposition pitch offsets for the individual tracks used for rendering only.
notation.elementsAllWhether music notation elements are visible or not.
notation.extendBendArrowsOnTiedNotesAllIf 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.extendLineEffectsToBeatEndAllIf set to true, line effects like w/bar and let-ring are drawn until the end of the beat instead of the start
notation.fingeringModeAllThe fingering mode to use.
notation.notationModeAllThe mode to use for display and play music notation elements.
notation.rhythmHeightAllControls how high the ryhthm notation is rendered below the tab staff
notation.rhythmModeAllControls how the rhythm notation is rendered for tab staves.
notation.slurHeightAllThe height scale factor for slurs
notation.smallGraceTabNotesAllIf set to true the guitar tabs on grace beats are rendered smaller.
notation.transpositionPitchesAllThe transposition pitch offsets for the individual tracks used for rendering and playback.
Player
player.bufferTimeInMillisecondsAllThe number of milliseconds the player should buffer.
player.enableAnimatedBeatCursorAllWhether the beat cursor should be animated or just ticking.
player.enableCursorAllWhether playback cursors should be displayed.
player.enableElementHighlightingAllWhether the notation elements of the currently played beat should be highlighted.
player.enablePlayerAllWhether the player should be enabled.
player.enableUserInteractionAllWhether the default user interaction behavior should be active or not.
player.nativeBrowserSmoothScrollJavaScriptWhether the native browser smooth scroll mechanism should be used over a custom animation.
player.playTripletFeelAllWhether the triplet feel should be played or only displayed.
player.scrollModeAllThe mode how to scroll.
player.scrollOffsetXAllThe X-offset to add when scrolling.
player.scrollOffsetYAllThe Y-offset to add when scrolling.
player.scrollSpeedAllHow fast the scrolling to the new position should happen.
player.slideAllThe slide settings allow control how the different slide types are generated for audio.
player.songBookBendDurationAllThe bend duration in milliseconds for songbook bends.
player.songBookDipDurationAllThe duration of whammy dips in milliseconds for songbook whammys.
player.vibratoAllThe Vibrato settings allow control how the different vibrato types are generated for audio.
Player - JavaScript Specific
player.outputModeJavaScriptThe mode used for playing audio samples
player.scrollElementJavaScriptThe element to apply the scrolling on.
player.soundFontJavaScriptThe sound font file to load for the player.