Skip to main content

Breaking changes on settings between 0.9.7 and 0.9.8

With the version 0.9.8 alphaTab moved from the C# codebase to a TypeScript codebase. In preparation of the 1.0.0 release a lot of cleanups happened and many things on the API were reviewed and changed. Goal of this (again) breaking changes is to have a future proof API surface that can survive a few releases without the need of again some reworks.

While this version comes with a lot of new benefits this guide only focuses on the breaking changes and how to upgrade your application.

Web​

For the web version we tried to maintain compatiblity as good as possible while not sacrificing the changes we want to introduce.

Quick Migration​

In most cases developers weren't in the need to use all the exposed classes of alphaTab and rather could stick to the main API surface and just access the properties. Property names did not change on this version. The main changes can be summarized as:

  • The main API class was moved from alphaTab.AlphaTabApi to alphaTab.alphaTabApi
  • Enums have now clean names like alphaTab.LayoutMode
  • Interfaces have been removed
  • The AlphaTexExporter was fully removed.
  • Check for changed event names that were used.
  • Check for new settings on hiding notation elements.
  • Use the new on/off event subscription if you used API object events.

In case you used various classes from the alphaTab module directly, you can find fhe full changes can be found below for migration.

New Event System​

One of the bigger changes on this version is the event system. There are 3 ways to subscribe to events in alphaTab and each event might be affected in a way:

  1. DOM Events:
  2. jQuery Events:

Some events have been renamed and need update.

BeforeAfter
alphaTab.playedBeatChangedalphaTab.playedBeatChanged
alphaTab.beatMouseDownalphaTab.beatMouseDown
alphaTab.beatMouseMovealphaTab.beatMouseMove
alphaTab.beatMouseUpalphaTab.beatMouseUp
alphaTab.loadedalphaTab.scoreLoaded
alphaTab.resizealphaTab.resize
alphaTab.renderalphaTab.renderStarted
alphaTab.renderedalphaTab.renderFinished
alphaTab.postRenderedalphaTab.postRenderFinished
alphaTab.erroralphaTab.error
alphaTab.playerReadyalphaTab.playerReady
alphaTab.finishedalphaTab.playerFinished
alphaTab.soundFontLoadedalphaTab.soundFontLoaded
alphaTab.midiFileLoadedalphaTab.midiFileLoaded
alphaTab.playerStateChangedalphaTab.playerStateChanged
alphaTab.positionChangedalphaTab.playerPositionChanged
alphaTab.soundFontLoadalphaTab.soundFontLoad
  1. Direct API events:

The registration system for the events was completely changed and some events have been renamed. Before events were registered via addEventName(handler) and unregistered via removeEventName(handler). Now events are registered via eventName.on(handler) and unregistered via eventName.off(handler).

BeforeAfter
<add/remove>PlayedBeatChangedplayedBeatChanged.<on/off>
<add/remove>BeatMouseDownbeatMouseDown.<on/off>
<add/remove>BeatMouseMovebeatMouseMove.<on/off>
<add/remove>BeatMouseUpbeatMouseUp.<on/off>
<add/remove>LoadedscoreLoaded.<on/off>
<add/remove>Resizeresize.<on/off>
<add/remove>RenderStartedrenderStarted.<on/off>
<add/remove>RenderFinishedrenderFinished.<on/off>
<add/remove>PostRenderFinishedpostRenderFinished.<on/off>
<add/remove>Errorerror.<on/off>
<add/remove>ReadyForPlaybackplayerReady.<on/off>
<add/remove>PlayerFinishedplayerFinished.<on/off>
<add/remove>SoundFontLoadedsoundFontLoaded.<on/off>
<add/remove>MidiLoadedmidiFileLoade.<on/off>
<add/remove>PlayerStateChangedplayerStateChanged.<on/off>
<add/remove>PlayerPositionChangedplayerPositionChanged.<on/off>
<add/remove>SoundFontLoadsoundFontLoad.<on/off>

Error Handling​

The error event previously included 2 parameters. One for the error type another for the error details. The error type was now moved into the error details itself. Internally the errors are extending the default Error type but due to serialization this information might get lost. The error.type property contains one of the values of alphaTab.AlphaTabErrorType specifying some details about which kind of error was raised.

Before

api.addError(function(type, error) {
    if(type === 'import') {
        alert('The input file has an invalid format: ' + error.message);
    }
})

After

api.error.on(function(error) {
    if(error.type === alphaTab.AlphaTabErrorType.Format) {
        alert('The input file has an invalid format: ' + error.message);
    }
})

New Structure​

One big change is the structure within the main alphaTab module. While the old hierarchy was quite nested, the new structure aims for a rather flat hierarchy.

Legend

All members are prefixed with alphaTab. as module name. In the table this prefix was omitted.

BeforeAfterComment
AlphaTabApiAlphaTabApiSame name but was replaced by platform.javaScript.AlphaTabApi
AlphaTabExceptionAlphaTabError
CoreSettingsCoreSettings
DisplaySettingsDisplaySettings
ImporterSettingsImporterSettings
NotationSettingsNotationSettings
PlayerSettingsPlayerSettings
ProgressEventArgsProgressEventArgs
RenderingResourcesRenderingResources
ResizeEventArgsResizeEventArgs
SettingsSettings
VibratoPlaybackSettingsVibratoPlaybackSettings
_FingeringMode.FingeringMode_Impl_FingeringMode
_LayoutMode.LayoutMode_Impl_LayoutMode
_NotationMode.NotationMode_Impl_NotationMode
_ScrollMode.ScrollMode_Impl_ScrollMode
_StaveProfile.StaveProfile_Impl_StaveProfile
_TabRhythmMode.TabRhythmMode_Impl_TabRhythmMode
audio.BeatTickLookupmidi.BeatTickLookup
audio.MasterBarTickLookupmidi.MasterBarTickLookup
audio.MidiTickLookupmidi.MidiTickLookup
audio.MidiTickLookupFindBeatResultmidi.MidiTickLookupFindBeatResult
audio.generator.AlphaSynthMidiFileHandlermidi.AlphaSynthMidiFileHandler
audio.generator.IMidiFileHandlerremoved
audio.generator.MidiFileGeneratormidi.MidiFileGenerator
audio.synth.AlphaSynthsynth.AlphaSynth
audio.synth.IAlphaSynthremoved
audio.synth.ISynthOutputremoved
audio.synth.PlaybackRangesynth.PlaybackRange
audio.synth.PlayerStateChangedEventArgssynth.PlayerStateChangedEventArgs
audio.synth.PositionChangedEventArgssynth.PositionChangedEventArgs
audio.synth._PlayerState.PlayerState_Impl_synth.PlayerState
audio.synth.ds.CircularSampleBufferremoved
audio.synth.midi.MidiFilemidi.MidiFile
audio.synth.midi.event.MidiEventmidi.MidiEvent
audio.synth.midi.event._ControllerType.ControllerType_Impl_midi.ControllerType
audio.synth.midi.event._MidiEventType.MidiEventType_Impl_midi.MidiEventType
audio.synth.synthesis._OutputMode.OutputMode_Impl_removed
collections._FastDictionary.FastDictionary_Impl_removed
collections._FastList.FastList_Impl_removed
exporter.AlphaTexExporterremovedThe alphaTab exporter feature was fully removed.
importer.FileLoadExceptionFileLoadException
importer.NoCompatibleReaderFoundExceptionimporter.UnsupportedFormatError
importer.PartConfiguration_Partremoved
importer.PartConfiguration_TrackConfigurationremoved
importer.ScoreImporterimporter.ScoreImporter
importer.ScoreLoaderimporter.SCoreLoader
importer.UnsupportedFormatExceptionimporter.UnsupportedFormatError
io.IReadableremoved
io.IWriteableremoved
model.Automationmodel.Automation
model.Barmodel.Bar
model.Beatmodel.Beat
model.BendPointmodel.BendPoint
model.Chordmodel.Chord
model.Fermatamodel.Fermata
model.Lyricsmodel.Lyrics
model.MasterBarmodel.MasterBar
model.Nodemodel.Node
model.PlaybackInformationmodel.PlaybackInformation
model.RenderStylesheetmodel.RenderStylesheet
model.Scoremodel.Score
model.Sectionmodel.Section
model.Staffmodel.Staff
model.Trackmodel.Track
model.Tuningmodel.Tuning
model.TupletGroupmodel.TupletGroup
model.Voicemodel.Voice
model._AccentuationType.AccentuationType_Impl_model.AccentuationType
model._AccidentalType.AccidentalType_Impl_model.AccidentalType
model._AutomationType.AutomationType_Impl_model.AutomationType
model._BendStyle.BendStyle_Impl_model.BendStyle
model._BendType.BendType_Impl_model.BendType
model._BrushType.BrushType_Impl_model.BrushType
model._Clef.Clef_Impl_model.Clef
model._CrescendoType.CrescendoType_Impl_model.CrescendoType
model._Duration.Duration_Impl_model.Duration
model._DynamicValue.DynamicValue_Impl_model.DynamicValue
model._FermataType.FermataType_Impl_model.FermataType
model._Fingers.Fingers_Impl_model.Fingers
model._GraceType.GraceType_Impl_model.GraceType
model._HarmonicType.HarmonicType_Impl_model.HarmonicType
model._KeySignature.KeySignature_Impl_model.KeySignature
model._KeySignatureType.KeySignatureType_Impl_model.KeySignatureType
model._NoteAccidentalMode.NoteAccidentalMode_Impl_model.NoteAccidentalMode
model._Ottavia.Ottavia_Impl_model.Ottavia
model._PickStroke.PickStroke_Impl_model.PickStroke
model._SimileMark.SimileMark_Impl_model.SimileMark
model._SlideInType.SlideInType_Impl_model.SlideInType
model._SlideOutType.SlideOutType_Impl_model.SlideOutType
model._TripletFeel.TripletFeel_Impl_model.TripletFeel
model._VibratoType.VibratoType_Impl_model.VibratoType
model._WhammyType.WhammyType_Impl_model.WhammyType
platform.javaScript.AlphaTabApimoved to alphaTab.AlphaTabApi
platform.model.Colormodel.Color
platform.model.Fontmodel.Font
platform.model._FontStyle.FontStylemodel.FontStyle
platform.model._TextAlign.TextAlignremoved
platform.model._TextBaseline.TextBaselineremoved
rendering.IScoreRendererremoved
rendering.RenderFinishedEventArgsrendering.RenderFinishedEventArgs
rendering.ScoreRendererrendering.ScoreRenderer
rendering.utils.BarBoundsrendering.BarBounds
rendering.utils.BeatBoundsrendering.BeatBounds
rendering.utils.Boundsrendering.Bounds
rendering.utils.BoundsLookuprendering.BoundsLookup
rendering.utils.MasterBarBoundsrendering.MasterBarBounds
rendering.utils.NoteBoundsrendering.NoteBounds
rendering.utils.StaveGroupBoundsrendering.StaveGroupBounds
ui.Cursorsremoved
ui.IContainerremoved
ui.IMouseEventArgsremoved
ui.IUiFacaderemoved
util._LogLevel.LogLevel_Impl_LogLevel
utils.SerializationExceptionFormatError

.net​

For .net the change on the code is way bigger than it is for the Web version. The .net version is now auto generated via the Web Version via a TypeScript to C# compiler. Due to the nature of TypeScript being a superset of JavaScript the available data types are reduced. Due to this alphaTab is now heavily based on double values where earlier float and int values might have been used. This can result in a higher memory consumption and major breaking changes.

New Packages and Namespaces​

The first change is about the new packages and namespaces. The .net version of alphaTab was restructured to come in 2 individual NuGet packages:

  1. AlphaTab is a package targeting .net standard 2.0 containing only the main alphaTab modules without UI specific components
  2. AlphaTab.Windows is a package targeting .net core 3.1 containing the WinForms and WPF specific UI components.

As the .net Framework 4.x is deprecated and .net core 3.x and later .net 5 is the future. If you really need a .net 4.x package feel free to contact us.

New Event System​

Just like the Web version the .net version is affected from the event system rework. The .net version does not use the C# built-in event system anymore. Subscribe to events via the .On(handler) and unsubscribe via the .Off(handler) method on the event object.

BeforeAfter
PlayedBeatChanged += -=PlayedBeatChanged.On/Off()
BeatMouseDown += -=BeatMouseDown.On/Off()
BeatMouseMove += -=BeatMouseMove.On/Off()
BeatMouseUp += -=BeatMouseUp.On/Off()
Loaded += -=ScoreLoaded.On/Off()
Resize += -=Resize.On/Off()
RenderStarted += -=RenderStarted.On/Off()
RenderFinished += -=RenderFinished.On/Off()
PostRenderFinished += -=PostRenderFinished.On/Off()
Error += -=Error.On/Off()
ReadyForPlayback += -=PlayerReady.On/Off()
PlayerFinished += -=PlayerFinished.On/Off()
SoundFontLoaded += -=SoundFontLoaded.On/Off()
MidiLoaded += -=MidiFileLoade.On/Off()
PlayerStateChanged += -=PlayerStateChanged.On/Off()
PlayerPositionChanged += -=PlayerPositionChanged.On/Off()
SoundFontLoad += -=SoundFontLoad.On/Off()

Double based Type System​

At many places where you would likely expect an int value you will now find double values. This does not necessarily mean that decimal values should be filled or are supported but it is rather a side effect that we do not know from the TypeScript codebase whether a property, parameter or variable would be an integer. We plan to improve the situation on the types in future but for now we advise developers to be careful when passing in values to alphaTab and report potential errors that are not handled.

Internally alphaTab will try to cut off decimal parts of values where they are not needed but there might be places where this is missed.

Error Handling​

The new error reporting system is fully based on Exceptions and you should use the corresponding exception types to determine the type of error. For a higher level categorization also the AlphaTabError.Type property can be checked. The previous string value identifying the category has been removed.

New options for hiding elements​

This version also changes some options on hiding/showing individual notation elements.

Previously the NotationSettings had following settings:

  • hideInfo - To hide the general song info
  • hideTuning - To hide the guitar tuning
  • hideTrackNames - To hide the track names in the accolade
  • hideChordDiagrams - To hide the chord diagrams
  • showParenthesisForTiedBends - To show parenthesis for note heads on tied bends
  • showTabNoteOnTiedBends - To show the tab note number on tied bends
  • showZeroOnDiveWhammy - To show the number 0 on dive whammy effects.

All these settings have been unified under the new setting NotationSettings.elements. Please check the docs there on how to show or hide the elements.