alphaTab.CoreSettings

All main settings of alphaTab controlling rather general aspects of its behavior.

 class CoreSettings

Properties

enableLazyLoading

Enables lazy loading of the rendered music sheet chunks. AlphaTab renders the music sheet in smaller sub-chunks to have fast UI feedback. Not all of those sub-chunks are immediately appended to the DOM due to performance reasons. AlphaTab tries to detect which elements are visible on the screen, and only appends those elements to the DOM. This reduces the load of the browser heavily but is not working for all layouts and use cases. This setting set to false, ensures that all rendered items are instantly appended to the DOM. The lazy rendering of partial might not be available on all platforms.

JavaScript

enableLazyLoading: boolean = true;

C#

bool EnableLazyLoading { get; set; } = true

Kotlin

var enableLazyLoading: Boolean = true

engine

The engine which should be used to render the the tablature. AlphaTab can use various render engines to draw the music notation. The available render engines is specific to the platform. Please refer to the table below to find out which engines are available on which platform.

• default- Platform specific default engine
• html5- Uses HTML5 canvas elements to render the music notation (browser only)
• svg- Outputs SVG strings (all platforms, default for web)
• skia - Uses Skia for rendering (all non-browser platforms via alphaSkia, default for non-web)
• gdi - Uses GDI+ for rendering (only on .net)
• android - Uses android.graphics.Canvas for rendering (only on Android)

JavaScript

engine: string = "default";

C#

string Engine { get; set; } = "default"

Kotlin

var engine: String = "default"

file

The full URL to the input file to be loaded. AlphaTab can automatically load and render a file after initialization. This eliminates the need of manually calling one of the load methods which are available. alphaTab will automatically initiate an XMLHttpRequest after initialization to load and display the provided url of this setting. Note that this setting is only interpreted once on initialization.

file: string | null = null;

fontDirectory

The full URL to the alphaTab font directory. AlphaTab will generate some dynamic CSS that is needed for displaying the music symbols correctly. For this it needs to know where the Web Font files of Bravura are. Normally alphaTab expects them to be in a font subfolder beside the script file. If this is not the case, this setting must be used to configure the path. Alternatively also a global variable ALPHATAB_FONT can be set on the page before initializing alphaTab.

Use smuflFontSources for more flexible font configuration.

fontDirectory: string | null = "${AlphaTabScriptFolder}/font/";

includeNoteBounds

Whether in the BoundsLookup also the position and area of each individual note is provided. AlphaTab collects the position of the rendered music notation elements during the rendering process. This way some level of interactivity can be provided like the feature that seeks to the corresponding position when clicking on a beat. By default the position of the individual notes is not collected due to performance reasons. If access to note position information is needed, this setting can enable it.

JavaScript

includeNoteBounds: boolean = false;

C#

bool IncludeNoteBounds { get; set; } = false

Kotlin

var includeNoteBounds: Boolean = false

logLevel

The log level to use within alphaTab AlphaTab internally does quite a bit of logging for debugging and informational purposes. The log level of alphaTab can be controlled via this setting.

JavaScript

logLevel: LogLevel = LogLevel.Info;

C#

LogLevel LogLevel { get; set; } = LogLevel.Info

Kotlin

var logLevel: LogLevel = LogLevel.Info

scriptFile

The full URL to the alphaTab JavaScript file. AlphaTab needs to know the full URL to the script file it is contained in to launch the web workers. AlphaTab will do its best to auto-detect this path but in case it fails, this setting can be used to explicitly define it. Altenatively also a global variable ALPHATAB_ROOT can be defined before initializing. Please be aware that bundling alphaTab together with other scripts might cause errors in case those scripts are not suitable for web workers. e.g. if there is a script bundled together with alphaTab that accesses the DOM, this will cause an error when alphaTab starts this script as worker.

scriptFile: string | null = Absolute url to JavaScript file containing alphaTab. (auto detected);

smuflFontSources

Defines the URLs from which to load the SMuFL compliant font files. These sources will be used to load and register the webfonts on the page so they are available for rendering the music sheet. The sources can be set to any CSS compatible URL which can be passed into url(). See https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/src#url

If you customize the SmuFL font used in alphaTab, you will also need to provide the respective SMuFL Metadata information to alphaTab. Set the metadata via fillFromSmufl on the rendering resources.

smuflFontSources: Map<FontFileFormat, string> | null = Bravura files located at <Signature style="inline" js={[["identifier","fontDirectory","/docs/reference/settings/core/fontdirectory"]]}>fontDirectory</Signature>  .;

tex

Whether the contents of the DOM element should be loaded as alphaTex. This setting allows you to fill alphaTex code into the DOM element and make alphaTab automatically load it when initializing. Note that this setting is only interpreted once on initialization.

tex: boolean = false;

tracks

The tracks to display for the initally loaded file. This setting can be used in combinition with the file or tex option. It controls which of the tracks of the initially loaded file should be displayed.

tracks: number | number[] | 'all' = null;

useWorkers

Whether the rendering should be done in a worker if possible. AlphaTab normally tries to render the music sheet asynchronously in a worker. This reduces the load on the UI side and avoids hanging. However sometimes it might be more desirable to have a synchronous rendering behavior. This setting can be set to false to synchronously render the music sheet on the UI side.

JavaScript

useWorkers: boolean = true;

C#

bool UseWorkers { get; set; } = true

Kotlin

var useWorkers: Boolean = true

Methods

buildDefaultSmuflFontSources

Builds the default SMuFL font sources for the usage with alphaTab in cases where no custom smuflFontSources are provided.

static buildDefaultSmuflFontSources(fontDirectory: string | null): Map<FontFileFormat, string>

Parameter	Summary
fontDirectoryAll	The CoreSettings.fontDirectory configured.