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:
-
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 callingsettings.fillFromJson( ... )
. -
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).
Property | Summary | ||
---|---|---|---|
Core | |||
core.enableLazyLoadingAll | Enables lazy loading of the rendered music sheet chunks. | ||
core.engineAll | The engine which should be used to render the the tablature. | ||
core.includeNoteBoundsAll | Whether 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.logLevelAll | The log level to use within alphaTab | ||
core.useWorkersAll | Whether the rendering should be done in a worker if possible. | ||
Core - JavaScript Specific | |||
core.fileJavaScript | The full URL to the input file to be loaded. | ||
core.fontDirectoryJavaScript | The full URL to the alphaTab font directory. | ||
core.scriptFileJavaScript | The full URL to the alphaTab JavaScript file. | ||
core.texJavaScript | Whether the contents of the DOM element should be loaded as alphaTex. | ||
core.tracksJavaScript | The tracks to display for the initally loaded file. | ||
Display | |||
display.accoladeBarPaddingRightAll | The padding between the accolade bar and the start of the bar itself. | ||
display.barCountAll | The total number of bars that should be rendered from the song. (-1 for all bars) | ||
display.barCountPerPartialAll | The number of bars that should be placed within one partial render. | ||
display.barsPerRowAll | Limit the displayed bars per system (row). (-1 for automatic mode) | ||
display.effectStaffPaddingBottomAll | The bottom padding applied to effect annotation staffs. | ||
display.effectStaffPaddingTopAll | The top padding applied to effect annotation staffs. | ||
display.firstStaffPaddingLeftAll | The left padding applied between the left line and the first glyph in the first staff in a system. | ||
display.firstSystemPaddingTopAll | The top padding applied to first system. | ||
display.justifyLastSystemAll | Whether to justify also the last system in page layouts. | ||
display.lastSystemPaddingBottomAll | The bottom padding applied to the last system. | ||
display.layoutModeAll | The layouting mode used to arrange the the notation. | ||
display.notationStaffPaddingBottomAll | The bottom padding applied to main notation staves (standard, tabs, numbered, slash). | ||
display.notationStaffPaddingTopAll | The bottom padding applied to main notation staves (standard, tabs, numbered, slash). | ||
display.paddingAll | Adjusts the padding between the music notation and the border. | ||
display.resourcesAll | Allows adjusting of the used fonts and colors for rendering. | ||
display.scaleAll | The zoom level of the rendered notation. | ||
display.staffPaddingLeftAll | The left padding applied between the left line and the first glyph in the following staff in a system. | ||
display.startBarAll | The bar start index to start layouting with. | ||
display.staveProfileAll | The stave profile defining which staves are shown for the music sheet. | ||
display.stretchForceAll | The default stretch force to use for layouting. | ||
display.systemLabelPaddingLeftAll | The padding left to the track name label of the system. | ||
display.systemLabelPaddingRightAll | The padding left to the track name label of the system. | ||
display.systemPaddingBottomAll | The bottom padding applied to systems beside the last one. | ||
display.systemPaddingTopAll | The top padding applied systems beside the first one. | ||
display.systemsLayoutModeAll | The mode used to arrange staves and systems. | ||
Importer | |||
importer.beatTextAsLyricsAll | Enables detecting lyrics from beat texts | ||
importer.encodingAll | The text encoding to use when decoding strings. | ||
importer.mergePartGroupsInMusicXmlAll | If part-groups should be merged into a single track (MusicXML). | ||
Notation | |||
notation.displayTranspositionPitchesAll | The transposition pitch offsets for the individual tracks used for rendering only. | ||
notation.elementsAll | Whether music notation elements are visible or not. | ||
notation.extendBendArrowsOnTiedNotesAll | 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.extendLineEffectsToBeatEndAll | 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.fingeringModeAll | The fingering mode to use. | ||
notation.notationModeAll | The mode to use for display and play music notation elements. | ||
notation.rhythmHeightAll | Controls how high the ryhthm notation is rendered below the tab staff | ||
notation.rhythmModeAll | Controls how the rhythm notation is rendered for tab staves. | ||
notation.slurHeightAll | The height scale factor for slurs | ||
notation.smallGraceTabNotesAll | If set to true the guitar tabs on grace beats are rendered smaller. | ||
notation.transpositionPitchesAll | The transposition pitch offsets for the individual tracks used for rendering and playback. | ||
Player | |||
player.bufferTimeInMillisecondsAll | The number of milliseconds the player should buffer. | ||
player.enableAnimatedBeatCursorAll | Whether the beat cursor should be animated or just ticking. | ||
player.enableCursorAll | Whether playback cursors should be displayed. | ||
player.enableElementHighlightingAll | Whether the notation elements of the currently played beat should be highlighted. | ||
player.enablePlayerAll | Whether the player should be enabled. | ||
player.enableUserInteractionAll | Whether the default user interaction behavior should be active or not. | ||
player.nativeBrowserSmoothScrollJavaScript | Whether the native browser smooth scroll mechanism should be used over a custom animation. | ||
player.playTripletFeelAll | Whether the triplet feel should be played or only displayed. | ||
player.scrollModeAll | The mode how to scroll. | ||
player.scrollOffsetXAll | The X-offset to add when scrolling. | ||
player.scrollOffsetYAll | The Y-offset to add when scrolling. | ||
player.scrollSpeedAll | How fast the scrolling to the new position should happen. | ||
player.slideAll | The slide settings allow control how the different slide types are generated for audio. | ||
player.songBookBendDurationAll | The bend duration in milliseconds for songbook bends. | ||
player.songBookDipDurationAll | The duration of whammy dips in milliseconds for songbook whammys. | ||
player.vibratoAll | The Vibrato settings allow control how the different vibrato types are generated for audio. | ||
Player - JavaScript Specific | |||
player.outputModeJavaScript | The mode used for playing audio samples | ||
player.scrollElementJavaScript | The element to apply the scrolling on. | ||
player.soundFontJavaScript | The sound font file to load for the player. |