Skip to main content

alphaTab.PlayerSettings

The player settings control how the audio playback and UI is behaving.

 class PlayerSettings

Properties​

bufferTimeInMilliseconds​

The number of milliseconds the player should buffer. Gets or sets how many milliseconds of audio samples should be buffered in total.

  • Larger buffers cause a delay from when audio settings like volumes will be applied.
  • Smaller buffers can cause audio crackling due to constant buffering that is happening.

This buffer size can be changed whenever needed.

bufferTimeInMilliseconds: number = 500;

enableAnimatedBeatCursor​

Whether the beat cursor should be animated or just ticking. This setting configures whether the beat cursor is animated smoothly or whether it is ticking from beat to beat. The animation of the cursor might not be available on all targets so it might not have any effect.

enableAnimatedBeatCursor: boolean = true;

enableCursor​

Whether playback cursors should be displayed. This setting configures whether the playback cursors are shown or not. In case a developer decides to built an own cursor system the default one can be disabled with this setting. Enabling the cursor also requires the player to be active.

enableCursor: boolean = `true` (if player is not disabled);

enableElementHighlighting​

Whether the notation elements of the currently played beat should be highlighted. This setting configures whether the note elements are highlighted during playback. The highlighting of elements might not be available on all targets and render engine, so it might not have any effect.

enableElementHighlighting: boolean = true;

enablePlayer​

Whether the player should be enabled. This setting configures whether the player feature is enabled or not. Depending on the platform enabling the player needs some additional actions of the developer. For the JavaScript version the player.soundFont property must be set to the URL of the sound font that should be used or it must be loaded manually via API. For .net manually the soundfont must be loaded.

AlphaTab does not ship a default UI for the player. The API must be hooked up to some UI controls to allow the user to interact with the player.

enablePlayer: boolean = false;

enableUserInteraction​

Whether the default user interaction behavior should be active or not. This setting configures whether alphaTab provides the default user interaction features like selection of the playback range and "seek on click". By default users can select the desired playback range with the mouse and also jump to individual beats by click. This behavior can be contolled with this setting.

enableUserInteraction: boolean = true;

nativeBrowserSmoothScroll​

Whether the native browser smooth scroll mechanism should be used over a custom animation. This setting configures whether the native browser feature for smooth scrolling should be used over a custom animation. If this setting is enabled, options like scrollSpeed will not have an effect anymore.

nativeBrowserSmoothScroll: boolean = true;

outputMode​

The mode used for playing audio samples Controls how alphaTab will play the audio samples in the browser.

outputMode: PlayerOutputMode = PlayerOutputMode.WebAudioAudioWorklets;

playerMode​

Whether the player should be enabled and which mode it should use. This setting configures whether the player feature is enabled or not. Depending on the platform enabling the player needs some additional actions of the developer.

Synthesizer

If the synthesizer is used (via EnabledAutomatic or EnabledSynthesizer ) a sound font is needed so that the midi synthesizer can produce the audio samples.

For the JavaScript version the player.soundFont property must be set to the URL of the sound font that should be used or it must be loaded manually via API. For .net manually the soundfont must be loaded.

Backing Track

For a built-in backing track of the input file no additional data needs to be loaded (assuming everything is filled via the input file). Otherwise the score.backingTrack needs to be filled before loading and the related sync points need to be configured.

External Media

For synchronizing alphaTab with an external media no data needs to be loaded into alphaTab. The configured sync points on the MasterBars are used as reference to synchronize the external media with the internal time axis. Then the related APIs on the AlphaTabApi object need to be used to update the playback state and exterrnal audio position during playback.

User Interface

AlphaTab does not ship a default UI for the player. The API must be hooked up to some UI controls to allow the user to interact with the player.

playerMode: PlayerMode = PlayerMode.Disabled;

playTripletFeel​

Whether the triplet feel should be played or only displayed. If this setting is enabled alphaTab will play the triplet feels accordingly, if it is disabled the triplet feel is only displayed but not played.

playTripletFeel: boolean = true;

scrollElement​

The element to apply the scrolling on. When the player is active, it by default automatically scrolls the browser window to the currently played bar. This setting defines which elements should be scrolled to bring the played bar into the view port. By default scrolling happens on the html,body selector.

scrollElement: string | HTMLElement = html,body;

scrollMode​

The mode how to scroll. This setting controls how alphaTab behaves for scrolling.

scrollMode: ScrollMode = ScrollMode.Continuous;

scrollOffsetX​

The X-offset to add when scrolling. When alphaTab does an auto-scrolling to the displayed bar, it will try to align the view port to the displayed bar. If due to some layout specifics or for aesthetics a small padding is needed, this setting allows an additional X-offset that is added to the scroll position.

scrollOffsetX: number = 0;

scrollOffsetY​

The Y-offset to add when scrolling. When alphaTab does an auto-scrolling to the displayed bar, it will try to align the view port to the displayed bar. If due to some layout specifics or for aesthetics a small padding is needed, this setting allows an additional Y-offset that is added to the scroll position.

scrollOffsetY: number = 0;

scrollSpeed​

How fast the scrolling to the new position should happen. If possible from the platform, alphaTab will try to do a smooth scrolling to the played bar. This setting defines the speed of scrolling in milliseconds. Note that nativeBrowserSmoothScroll must be set to false for this to have an effect.

scrollSpeed: number = 300;

slide​

The slide settings allow control how the different slide types are generated for audio. AlphaTab supports various types of slides which can be grouped into 3 types:

  • Shift Slides

  • Legato Slides

  • Slide into from below

  • Slide into from above

  • Slide out to below

  • Slide out to above

  • Pick Slide out to above

  • Pick Slide out to below

For the first 2 groups the audio generation can be adapted. For the pick slide the audio generation cannot be adapted as there is no mechanism yet in alphaTab to play pick slides to make them sound real.

For the first group only the duration or start point of the slide can be configured while for the second group the duration/start-point and the pitch offset can be configured.

readonly slide: SlidePlaybackSettings;

songBookBendDuration​

The bend duration in milliseconds for songbook bends. If the display mode songbook is enabled, this has an effect on the way bends are played. For songbook bends the bend is done very quickly at the end or start of the beat. This setting defines the play duration for those bends in milliseconds. This duration is in milliseconds unlike some other settings which are in midi ticks. The reason is that on songbook bends, the bends should always be played in the same speed, regardless of the song tempo. Midi ticks are tempo dependent.

songBookBendDuration: number = 75;

songBookDipDuration​

The duration of whammy dips in milliseconds for songbook whammys. If the display mode songbook is enabled, this has an effect on the way whammy dips are played. For songbook dips the whammy is pressed very quickly at the start of the beat. This setting defines the play duration for those whammy bars in milliseconds. This duration is in milliseconds unlike some other settings which are in midi ticks. The reason is that on songbook dips, the whammy should always be pressed in the same speed, regardless of the song tempo. Midi ticks are tempo dependent.

songBookDipDuration: number = 150;

soundFont​

The sound font file to load for the player. When the player is enabled the soundfont from this URL will be loaded automatically after the player is ready.

soundFont: string | null = null;

vibrato​

The Vibrato settings allow control how the different vibrato types are generated for audio. AlphaTab supports 4 types of vibratos, for each vibrato the amplitude and the wavelength can be configured. The amplitude controls how many semitones the vibrato changes the pitch up and down while playback. The wavelength controls how many midi ticks it will take to complete one up and down vibrato. The 4 vibrato types are:

  1. Beat Slight - A fast vibrato on the whole beat. This vibrato is usually done with the whammy bar.
  2. Beat Wide - A slow vibrato on the whole beat. This vibrato is usually done with the whammy bar.
  3. Note Slight - A fast vibrato on a single note. This vibrato is usually done with the finger on the fretboard.
  4. Note Wide - A slow vibrato on a single note. This vibrato is usually done with the finger on the fretboard.
readonly vibrato: VibratoPlaybackSettings;