Skip to main content

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.Artist,
    alphaTab.model.Color.fromJson("#4cb3d4")
  );

  const fretColors = {
      12: alphaTab.model.Color.fromJson("#bb4648"),
      13: alphaTab.model.Color.fromJson("#ab519f"),
      14: alphaTab.model.Color.fromJson("#3953a5"),
      15: alphaTab.model.Color.fromJson("#70ccd6"),
      16: alphaTab.model.Color.fromJson("#6abd45"),
      17: alphaTab.model.Color.fromJson("#e1a90e")
  };

  // 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.

Description

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

Enum Members

NameNumeric ValueDescription
Title0

The title of the song

SubTitle1

The subtitle of the song

Artist2

The artist of the song

Album3

The album of the song

Words4

The word author of the song

Music5

The Music author of the song

WordsAndMusic6

The Words&Music author of the song

7

The copyright holder of the song

ChordDiagramList8

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.

Description

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

Enum Members

NameNumeric ValueDescription
TrackName0

The track names shown before the staves.

BracesAndBrackets1

The braces and brackets grouping the staves. If a bracket spans multiple tracks, the color of the first track counts.

SystemSeparator2

The system separator.

StringTuning3

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.

Description

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

Enum Members

NameNumeric ValueDescription
StandardNotationRepeats0

The repeat signs on the standard notation staff.

GuitarTabsRepeats1

The repeat signs on the guitar tab staff.

SlashRepeats2

The repeat signs on the slash staff.

NumberedRepeats3

The repeat signs on the numbered notation staff.

StandardNotationBarNumber4

The bar numbers on the standard notation staff.

GuitarTabsBarNumber5

The bar numbers on the guitar tab staff.

SlashBarNumber6

The bar numbers on the slash staff.

NumberedBarNumber7

The bar numbers on the numbered notation staff.

StandardNotationBarSeparator8

The bar separator lines on the standard notation staff.

GuitarTabsBarSeparator9

The bar separator lines on the guitar tab staff.

SlashBarSeparator10

The bar separator lines on the slash staff.

NumberedBarSeparator11

The bar separator lines on the numbered notation staff.

StandardNotationClef12

The clefs on the standard notation staff.

GuitarTabsClef13

The clefs on the guitar tab staff.

StandardNotationKeySignature14

The key signatures on the standard notation staff.

NumberedKeySignature15

The key signatures on the numbered notation staff.

StandardNotationTimeSignature16

The time signatures on the standard notation staff.

GuitarTabsTimeSignature17

The time signatures on the guitar tab staff.

SlashTimeSignature18

The time signatures on the slash staff.

NumberedTimeSignature19

The time signature on the numbered notation staff.

StandardNotationStaffLine20

The staff lines on the standard notation staff.

GuitarTabsStaffLine21

The staff lines on the guitar tab staff.

SlashStaffLine22

The staff lines on the slash staff.

NumberedStaffLine23

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.

Description

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

Enum Members

NameNumeric ValueDescription
Glyphs0

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.

Description

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

Enum Members

NameNumeric ValueDescription
Effects0

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.

StandardNotationStem1

The stems drawn for note heads in this beat on the standard notation staff.

StandardNotationFlags2

The flags drawn for note heads in this beat on the standard notation staff.

StandardNotationBeams3

The beams drawn between this and the next beat on the standard notation staff.

StandardNotationTuplet4

The tuplet drawn on the standard notation staff (the first beat affects the whole tuplet if grouped).

StandardNotationEffects5

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.

StandardNotationRests6

The rest symbol on the standard notation staff.

GuitarTabStem7

The stems drawn for note heads in this beat on the guitar tab staff.

GuitarTabFlags8

The flags drawn for note heads in this beat on the guitar tab staff.

GuitarTabBeams9

The beams drawn between this and the next beat on the guitar tab staff.

GuitarTabTuplet10

The tuplet drawn on the guitar tab staff (the first beat affects the whole tuplet if grouped).

GuitarTabEffects11

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.

GuitarTabRests12

The rest symbol on the guitar tab staff.

SlashStem13

The stems drawn for note heads in this beat on the slash staff.

SlashFlags14

The flags drawn for note heads in this beat on the slash staff.

SlashBeams15

The beams drawn between this and the next beat on the slash staff.

SlashTuplet16

The tuplet drawn on the slash staff (the first beat affects the whole tuplet if grouped).

SlashRests17

The rest symbol on the slash staff.

SlashEffects18

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.

NumberedDuration19

The duration lines drawn for this beat on the numbered notation staff.

NumberedEffects20

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.

NumberedRests21

The rest (0) on the numbered notation staff.

NumberedTuplet22

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.

Description

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

Enum Members

NameNumeric ValueDescription
Effects0

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.

StandardNotationNoteHead1

The note head on the standard notation staff.

StandardNotationAccidentals2

The accidentals on the standard notation staff.

StandardNotationEffects3

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.

GuitarTabFretNumber4

The fret number on the guitar tab staff.

GuitarTabEffects5

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.

SlashNoteHead6

The note head on the slash notation staff.

SlashEffects7

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.

NumberedNumber8

The note number on the numbered notation staff.

NumberedAccidentals9

The accidentals on the numbered notation staff.

NumberedEffects10

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.