Coloring Music Sheet

since 1.5.0

alphaTab supports individual styling of music notation elements via a special style container which is available on most levels of the Data Model. This means you can customize the colors of individual notes being rendered base on custom logic.

The best place to apply custom coloring is the api.scoreLoaded event which is triggered whenever a new score is detected. But you can modify the styles later at any time by accessing the score and then initiating a re-render via render.

important

alphaTab does not detect dynamically any changes made to the data model. Rendering happens in a background worker, and calling render will ensure all updated information is passed to this renderer and the display is updated. Calling render will initiate a full re-layout and drawing of the music sheet to apply any style changes accordingly, hence it is a quite performance intense operation.

The example codes in this Guide are in JavaScript but can be adapted to the other platforms accordingly.

Quick Start

This code example here should give you a good first idea how you apply custom colors to elements. Depending on the elements you want to color, you have to traverse the tree of elements. Then on the style container you can fill the colors with the particular elements

const api = new alphaTab.AlphaTabApi(...);
api.scoreLoaded.on(score => applyColors(score));
function applyColors(score) {
  // create custom style on score level
  score.style = new alphaTab.model.ScoreStyle();
  score.style.colors.set(
    alphaTab.model.ScoreSubElement.Title,
    alphaTab.model.Color.fromJson("#426d9d")
  );
  score.style.colors.set(
    alphaTab.model.ScoreSubElement.SubTitle,
    alphaTab.model.Color.fromJson("#4cb3d4")
  );

  const fretColors = {
      3: alphaTab.model.Color.fromJson("#d13a3a"),
      4: alphaTab.model.Color.fromJson("#e17722"),
      5: alphaTab.model.Color.fromJson("#e1a90e"),
      7: alphaTab.model.Color.fromJson("#6abd45"),
      8: alphaTab.model.Color.fromJson("#70ccd6"),
      10: alphaTab.model.Color.fromJson("#3953a5"),
      12: alphaTab.model.Color.fromJson("#ab519f"),
      13: alphaTab.model.Color.fromJson("#d047a3")
  };

  // traverse hierarchy and apply colors as desired
  for (const track of score.tracks) {
    for (const staff of track.staves) {
      for (const bar of staff.bars) {
        for (const voice of bar.voices) {
          for (const beat of voice.beats) {
            // on tuplets colors beam and tuplet bracket
            if (beat.hasTuplet) {
              beat.style = new alphaTab.model.BeatStyle();
              const color = alphaTab.model.Color.fromJson("#00DD00");
              beat.style.colors.set(
                alphaTab.model.BeatSubElement.StandardNotationTuplet,
                color
              );
              beat.style.colors.set(
                alphaTab.model.BeatSubElement.StandardNotationBeams,
                color
              );
            }

            for (const note of beat.notes) {
              // color notes based on the fret
              note.style = new alphaTab.model.NoteStyle();
              note.style.colors.set(alphaTab.model.NoteSubElement.StandardNotationNoteHead,
                  fretColors[note.fret]
              );
              note.style.colors.set(alphaTab.model.NoteSubElement.GuitarTabFretNumber,
                  fretColors[note.fret]
              );
            }
          }
        }
      }
    }
  }
}

Styleable elements

alphaTab tries to give fine grained access to coloring music notation elements. Only when it comes to individual effects and annotations things get more coarse.

Score level

On Score level initialize the score.style = new alphaTab.model.ScoreStyle() and then select the element to color via alphaTab.model.ScoreSubElement.

Lists all graphical sub elements within a Score which can be styled via style

Enum Members

Name	Numeric Value	Description
Title	0	The title of the song
SubTitle	1	The subtitle of the song
Artist	2	The artist of the song
Album	3	The album of the song
Words	4	The word author of the song
Music	5	The Music author of the song
WordsAndMusic	6	The Words&Music author of the song
Transcriber	7	The transcriber of the music sheet
Copyright	8	The copyright holder of the song
CopyrightSecondLine	9	The second copyright line (typically something like 'All Rights Reserved')
ChordDiagramList	10	The chord diagram list shown on top of the score.

Track level

On Track level initialize the track.style = new alphaTab.model.TrackStyle() and then select the element to color via alphaTab.model.TrackSubElement.

Lists all graphical sub elements within a Track which can be styled via style

Enum Members

Name	Numeric Value	Description
TrackName	0	The track names shown before the staves.
BracesAndBrackets	1	The braces and brackets grouping the staves. If a bracket spans multiple tracks, the color of the first track counts.
SystemSeparator	2	The system separator.
StringTuning	3	The tuning of the strings.

Bar level

On Bar level initialize the bar.style = new alphaTab.model.BarStyle() and then select the element to color via alphaTab.model.BarSubElement.

Lists all graphical sub elements within a Bar which can be styled via style

Enum Members

Name	Numeric Value	Description
StandardNotationRepeats	0	The repeat signs on the standard notation staff.
GuitarTabsRepeats	1	The repeat signs on the guitar tab staff.
SlashRepeats	2	The repeat signs on the slash staff.
NumberedRepeats	3	The repeat signs on the numbered notation staff.
StandardNotationBarNumber	4	The bar numbers on the standard notation staff.
GuitarTabsBarNumber	5	The bar numbers on the guitar tab staff.
SlashBarNumber	6	The bar numbers on the slash staff.
NumberedBarNumber	7	The bar numbers on the numbered notation staff.
StandardNotationBarLines	8	The bar lines on the standard notation staff.
GuitarTabsBarLines	9	The bar lines on the guitar tab staff.
SlashBarLines	10	The bar lines on the slash staff.
NumberedBarLines	11	The bar lines on the numbered notation staff.
StandardNotationClef	12	The clefs on the standard notation staff.
GuitarTabsClef	13	The clefs on the guitar tab staff.
StandardNotationKeySignature	14	The key signatures on the standard notation staff.
NumberedKeySignature	15	The key signatures on the numbered notation staff.
StandardNotationTimeSignature	16	The time signatures on the standard notation staff.
GuitarTabsTimeSignature	17	The time signatures on the guitar tab staff.
SlashTimeSignature	18	The time signatures on the slash staff.
NumberedTimeSignature	19	The time signature on the numbered notation staff.
StandardNotationStaffLine	20	The staff lines on the standard notation staff.
GuitarTabsStaffLine	21	The staff lines on the guitar tab staff.
SlashStaffLine	22	The staff lines on the slash staff.
NumberedStaffLine	23	The staff lines on the numbered notation staff.

Voice level

On Bar level initialize the voice.style = new alphaTab.model.VoiceStyle() and then select the element to color via alphaTab.model.VoiceSubElement.

Lists all graphical sub elements within a Voice which can be styled via style

Enum Members

Name	Numeric Value	Description
Glyphs	0	All general glyphs (like notes heads and rests).

Beat level

On Beat level initialize the beat.style = new alphaTab.model.BeatStyle() and then select the element to color via alphaTab.model.BeatSubElement.

Lists all graphical sub elements within a Beat which can be styled via style

Enum Members

Name	Numeric Value	Description
Effects	0	The effects and annotations shown in dedicated effect bands above the staves (e.g. fermata). Only applies to items which are on beat level but not any individual note level effects.
StandardNotationStem	1	The stems drawn for note heads in this beat on the standard notation staff.
StandardNotationFlags	2	The flags drawn for note heads in this beat on the standard notation staff.
StandardNotationBeams	3	The beams drawn between this and the next beat on the standard notation staff.
StandardNotationTuplet	4	The tuplet drawn on the standard notation staff (the first beat affects the whole tuplet if grouped).
StandardNotationEffects	5	The effects and annotations applied to this beat on the standard notation staff (e.g. brushes). Only applies to items which are on beat level but not any individual note level effects.
StandardNotationRests	6	The rest symbol on the standard notation staff.
GuitarTabStem	7	The stems drawn for note heads in this beat on the guitar tab staff.
GuitarTabFlags	8	The flags drawn for note heads in this beat on the guitar tab staff.
GuitarTabBeams	9	The beams drawn between this and the next beat on the guitar tab staff.
GuitarTabTuplet	10	The tuplet drawn on the guitar tab staff (the first beat affects the whole tuplet if grouped).
GuitarTabEffects	11	The effects and annotations applied to this beat on the guitar tab staff (e.g. brushes). Only applies to items which are on beat level but not any individual note level effects.
GuitarTabRests	12	The rest symbol on the guitar tab staff.
SlashStem	13	The stems drawn for note heads in this beat on the slash staff.
SlashFlags	14	The flags drawn for note heads in this beat on the slash staff.
SlashBeams	15	The beams drawn between this and the next beat on the slash staff.
SlashTuplet	16	The tuplet drawn on the slash staff (the first beat affects the whole tuplet if grouped).
SlashRests	17	The rest symbol on the slash staff.
SlashEffects	18	The effects and annotations applied to this beat on the slash staff (e.g. brushes). Only applies to items which are on beat level but not any individual note level effects.
NumberedDuration	19	The duration lines drawn for this beat on the numbered notation staff.
NumberedEffects	20	The effects and annotations applied to this beat on the numbered notation staff (e.g. brushes). Only applies to items which are on beat level but not any individual note level effects.
NumberedRests	21	The rest (0) on the numbered notation staff.
NumberedTuplet	22	The tuplet drawn on the numbered notation staff (the first beat affects the whole tuplet if grouped).

Note level

On Note level initialize the note.style = new alphaTab.model.NoteStyle() and then select the element to color via alphaTab.model.NoteSubElement.

Lists all graphical sub elements within a Note which can be styled via style

Enum Members

Name	Numeric Value	Description
Effects	0	The effects and annotations shown in dedicated effect bands above the staves (e.g. vibrato). The style of the first note with the effect wins.
StandardNotationNoteHead	1	The note head on the standard notation staff.
StandardNotationAccidentals	2	The accidentals on the standard notation staff.
StandardNotationEffects	3	The effects and annotations applied to this note on the standard notation staff (e.g. bends). If effects on beats result in individual note elements shown, this color will apply.
GuitarTabFretNumber	4	The fret number on the guitar tab staff.
GuitarTabEffects	5	The effects and annotations applied to this note on the guitar tab staff (e.g. bends). If effects on beats result in individual note elements shown, this color will apply.
SlashNoteHead	6	The note head on the slash notation staff.
SlashEffects	7	The effects and annotations applied to this note on the slash notation staff (e.g. dots). If effects on beats result in individual note elements shown, this color will apply.
NumberedNumber	8	The note number on the numbered notation staff.
NumberedAccidentals	9	The accidentals on the numbered notation staff.
NumberedEffects	10	The effects and annotations applied to this note on the number notation staff (e.g. dots). If effects on beats result in individual note elements shown, this color will apply.