Structural Metadata

For some songs you might want to define that the song has multiple tracks, staves or voices.

Multiple tracks are used when multiple instruments are playing together in one song.
Multiple staves are typically used to write grand staff piano notation (left hand/right hand) or splitup voices for readability.
Multiple voices are typically used to write notation where multiple independent timings and pitches are played. This can be if multiple vocals are singing together (hence the name voices), or special playing techniques (playing a base rhythm and melody on the same instrument).

In alphaTex new tracks, staves and voices are started with their respective metadata tags specified at the start of a bar:

\track
\staff
\voice

alphaTab refers to these kind of metadata tags as "structural" tags as they define the general structure of the song.

The initial track, staff or voice is implicitly started. Only on the "second" item you need to specify the tags. For clarity it is encouraged to also specify the initial item if there are multiple tracks, staves or voices.

`\track`

Syntax
\track (name shortName)

Description: Start a new track

Parameters:

Name	Description	Type	Required
`name`	The full name of the track	`String`	no
`shortName`	The short name of the track	`String`	no `/computed from name/`

Example:

\track "First Track" "frst" C4 D4 E4 F4 \track C5 D5 E5 F5

\track "First Track" "frst" 
  C4 D4 E4 F4
\track
  C5 D5 E5 F5

Properties:

`color`

Syntax
color colorCode

Description: The data model holds information about the color of the track which might be used by user interfaces to visually differenciate them. This data mainly originates from the Guitar Pro file format where colors are used to differenciate the tracks in the track picker and some other visualizations. It does not have an impact on the color of the music notation but can be used in a custom UI.

Parameters:

Name	Description	Type	Required
`colorCode`	The colorCode in any supported color format	`String`	yes

Example:

\track { color "#FF0000" } 1.1 2.1 3.1 4.1

\track { color "#FF0000" }
1.1 2.1 3.1 4.1

`systemsLayout`

Syntax
systemsLayout (numberOfBars)

Description: Defines the number of bars to display per system.

The systemsLayout and defaultSystemsLayout allow configuring the system layout. The system layout, defines how many bars should be displayed per system (line) if enabled via systemsLayoutMode.

Parameters:

Name	Description	Type	Required
`numberOfBars`	Defines for every system (line) the number of bars it should contain	`Number[]`	no

Example:

\title "Single Track" \track { systemsLayout (2 3 2) } :1 c4 | c4 | c4 | c4 | c4 | c4 | c4

\title "Single Track"
\track { systemsLayout (2 3 2) }
:1 c4 | c4 | c4 | c4 | c4 | c4 | c4

`defaultSystemsLayout`

Syntax
defaultSystemsLayout numberOfBars

Description: Defines the default number of bars to display per system.

The systemsLayout and defaultSystemsLayout allow configuring the system layout. The system layout, defines how many bars should be displayed per system (line) if enabled via systemsLayoutMode.

Parameters:

Name	Description	Type	Required
`numberOfBars`	Defines for every system (line) the number of bars it should contain	`Number`	yes

Example:

\title "Single Track" \track { defaultSystemsLayout 2 } :1 c4 | c4 | c4 | c4 | c4 | c4 | c4

\title "Single Track"
\track { defaultSystemsLayout 2 }
  :1 c4 | c4 | c4 | c4 | c4 | c4 | c4

`solo`

Syntax
solo ()

Description: Set the track to be played solo.

Example:

\track { solo } 1.1 2.1 3.1 4.1 \track 10.1 11.1 12.1 13.1

\track { solo }
1.1 2.1 3.1 4.1
\track 
10.1 11.1 12.1 13.1

`mute`

Syntax
mute ()

Description: Set the track to be muted.

Example:

\track 1.1 2.1 3.1 4.1 \track { mute } 10.1 11.1 12.1 13.1

\track 
1.1 2.1 3.1 4.1
\track { mute }
10.1 11.1 12.1 13.1

`volume`

Syntax
volume value

Description: Set the track volume.

Parameters:

Name	Description	Type	Required
`value`	The volume to set (0-16)	`Number`	yes

Example:

\track { volume 0 } 1.1 2.1 3.1 4.1 \track { volume 16 } 10.1 11.1 12.1 13.1

\track { volume 0 } 
1.1 2.1 3.1 4.1
\track { volume 16 }
10.1 11.1 12.1 13.1

`balance`

Syntax
balance value

Description: Set the track balance.

Parameters:

Name	Description	Type	Required
`value`	The balance to set (0-16; 8 is centered)	`Number`	yes

Example:

\track { volume 0 } 1.1 2.1 3.1 4.1 \track { volume 16 } 10.1 11.1 12.1 13.1

\track { volume 0 } 
1.1 2.1 3.1 4.1
\track { volume 16 }
10.1 11.1 12.1 13.1

`instrument`

Syntax
// [1]: Set the midi instrument as midi program number
instrument program
// [2]: Set the midi instrument as midi program name
instrument programName
// [3]: Set the instrument to percussion
instrument percussion

Description: Set the midi instrument for this track.

Parameters:

Overload	Name	Description	Type	Required
`[1]`	`program`	MIDI program number (0-127)	`Number`	yes
`[2]`	`programName`	MIDI program name	`String`	yes
`[3]`	`percussion`	Percussion	`percussion`	yes

Parameter Values:

Following parameters have value limitations

Overload Name Values

[2]

programName

Value	Description
`"Acoustic Grand Piano"`
`"Bright Grand Piano"`
`"Electric Grand Piano"`
`"Honky tonk Piano"`
`"Electric Piano 1"`
`"Electric Piano 2"`
`"Harpsichord"`
`"Clavinet"`
`"Celesta"`
`"Glockenspiel"`
`"Musicbox"`
`"Vibraphone"`
`"Marimba"`
`"Xylophone"`
`"Tubularbells"`
`"Dulcimer"`
`"Drawbar Organ"`
`"Percussive Organ"`
`"Rock Organ"`
`"Church Organ"`
`"Reed Organ"`
`"Accordion"`
`"Harmonica"`
`"Tango Accordion"`
`"Acoustic Guitar Nylon"`
`"Acoustic Guitar Steel"`
`"Electric Guitar Jazz"`
`"Electric Guitar Clean"`
`"Electric Guitar Muted"`
`"Overdriven Guitar"`
`"Distortion Guitar"`
`"Guitar Harmonics"`
`"Acoustic Bass"`
`"Electric Bass Finger"`
`"Electric Bass Pick"`
`"Fretless Bass"`
`"Slap Bass 1"`
`"Slap Bass 2"`
`"Synth Bass 1"`
`"Synth Bass 2"`
`"Violin"`
`"Viola"`
`"Cello"`
`"Contrabass"`
`"Tremolo Strings"`
`"Pizzicato Strings"`
`"Orchestral Harp"`
`"Timpani"`
`"String Ensemble 1"`
`"String Ensemble 2"`
`"Synth Strings 1"`
`"Synth Strings 2"`
`"Choir Aahs"`
`"Voice Oohs"`
`"Synth Voice"`
`"Orchestra Hit"`
`"Trumpet"`
`"Trombone"`
`"Tuba"`
`"Muted Trumpet"`
`"French Horn"`
`"Brass Section"`
`"Synth Brass 1"`
`"Synth Brass 2"`
`"Soprano Sax"`
`"Alto Sax"`
`"Tenor Sax"`
`"Baritone Sax"`
`"Oboe"`
`"English Horn"`
`"Bassoon"`
`"Clarinet"`
`"Piccolo"`
`"Flute"`
`"Recorder"`
`"Pan Flute"`
`"Blown bottle"`
`"Shakuhachi"`
`"Whistle"`
`"Ocarina"`
`"Lead 1 Square"`
`"Lead 2 Sawtooth"`
`"Lead 3 Calliope"`
`"Lead 4 Chiff"`
`"Lead 5 Charang"`
`"Lead 6 Voice"`
`"Lead 7 Fifths"`
`"Lead 8 Bass and Lead"`
`"Pad 1 newage"`
`"Pad 2 warm"`
`"Pad 3 polysynth"`
`"Pad 4 choir"`
`"Pad 5 bowed"`
`"Pad 6 metallic"`
`"Pad 7 halo"`
`"Pad 8 sweep"`
`"Fx 1 rain"`
`"Fx 2 soundtrack"`
`"Fx 3 crystal"`
`"Fx 4 atmosphere"`
`"Fx 5 brightness"`
`"Fx 6 goblins"`
`"Fx 7 echoes"`
`"Fx 8 scifi"`
`"Sitar"`
`"Banjo"`
`"Shamisen"`
`"Koto"`
`"Kalimba"`
`"Bag pipe"`
`"Fiddle"`
`"Shanai"`
`"Tinkle Bell"`
`"Agogo"`
`"Steel Drums"`
`"Woodblock"`
`"Taiko Drum"`
`"Melodic Tom"`
`"Synth Drum"`
`"Reverse Cymbal"`
`"Guitar Fret Noise"`
`"Breath Noise"`
`"Seashore"`
`"Bird Tweet"`
`"Telephone Ring"`
`"Helicopter"`
`"Applause"`
`"Gunshot"`

[3]

percussion

Value	Description
`percussion`

Example:

\track { instrument 0 } C4 C5 r r \track { instrument "Acoustic Steel Guitar" } \tuning (E4 B3 G3 D3 A2 E2) r r 12.1 13.1

\track { instrument 0 } 
C4 C5 r r
\track { instrument "Acoustic Steel Guitar" }
\tuning (E4 B3 G3 D3 A2 E2)
r r 12.1 13.1

`bank`

Syntax
bank value

Description: Set the MIDI bank to select when playing this track.

The loaded soundfont needs to have this bank defined, otherwise there might be no audio.

Parameters:

Name	Description	Type	Required
`value`	The midi bank to set	`Number`	yes

Example:

\track { instrument 25 bank 2 }

\track { instrument 25 bank 2 }

`multiBarRest`

Syntax
multiBarRest ()

Description: Enables the display of multibar rests if this track is shown as standalone.

Example:

\track { multiBarRest } C4*4 | r.1 | r.1 | r.1 | C4 * 4

\track { multiBarRest } 
C4*4 | r.1 | r.1 | r.1 | C4 * 4

\track C4*4 | r.1 | r.1 | r.1 | C4 * 4

\track
C4*4 | r.1 | r.1 | r.1 | C4 * 4

`\staff`

Syntax
\staff ()

Description: Marks the start of a new staff.

The staff with the largest number of bars defines how long the overall song is. There is no need to manually ensure that all staves have the correct number of bars. AlphaTab will create missing empty bars automatically.

If no properties describing the visible notation are provided, the default is score tabs.

Example:

\track "Piano with Grand Staff" "pno." \staff{score} \tuning piano \instrument acousticgrandpiano c4 d4 e4 f4 | \staff{score} \tuning piano \clef F4 c2 c2 c2 c2 | \track "Guitar" \staff{tabs slash} \capo 5 1.2 3.2 0.1 1.1

\track "Piano with Grand Staff" "pno."
\staff{score} \tuning piano \instrument acousticgrandpiano
c4 d4 e4 f4 |
\staff{score} \tuning piano \clef F4
c2 c2 c2 c2 |
\track "Guitar"
\staff{tabs slash} \capo 5
1.2 3.2 0.1 1.1

Properties:

`score`

Syntax
score lineCount

Description: Enable the display of standard notation.

Parameters:

Name	Description	Type	Required
`lineCount`	The number of staff lines	`Number`	no `5`

Example:

\track \staff {score 3} D4 D4 D4 D4 \staff {score} C4 C4 C4 C4

\track
  \staff {score 3}
  D4 D4 D4 D4
  \staff {score}
  C4 C4 C4 C4

`tabs`

Syntax
tabs ()

Description: Enable the display of guitar tablature.

Guitar tabs are only shown if the contained notes are stringed/fretted notes.

Example:

\track \staff {tabs} 3.3 4.3 5.3 5.5

\track
  \staff {tabs}
  3.3 4.3 5.3 5.5

`slash`

Syntax
slash ()

Description: Enable the display of slash notation.

Example:

\track \staff {tabs slash} 3.3 4.3 5.3 5.5

\track
  \staff {tabs slash}
  3.3 4.3 5.3 5.5

`numbered`

Syntax
numbered ()

Description: Enable the display of numbered notation (Jianpu).

Example:

\track \staff {score numbered} C4 D4 E4 F4

\track
  \staff {score numbered}
  C4 D4 E4 F4

`\voice`

Syntax
\voice ()

Description: Marks the start of a new voice.

Unlike the structure in the data model, alphaTex expects you to define all bars of a voice, then all the bars of the next voice.

It structure is: \voice /* Voice 1 Bar 1*/ | /* Voice 1 Bar 2*/ oice /* Voice 2 Bar 1*/ | /* Voice21 Bar 2*/ Once a new voice starts, you again can define the notes starting from the first bar. alphaTab will try to consolidate inconsistencies in the number of bars across voices.

Example:

\track "Piano" \staff{score} \tuning piano \instrument acousticgrandpiano \voice c4 d4 e4 f4 | c4 d4 e4 f4 \voice c3 d3 e3 f3 | c3 d3 e3 f3 \track "Piano2" \staff{score} \tuning piano \instrument acousticgrandpiano \voice c4 d4 e4 f4 | c4 d4 e4 f4 \voice c3 d3 e3 f3

\track "Piano"
\staff{score} \tuning piano \instrument acousticgrandpiano
    \voice 
        c4 d4 e4 f4 | c4 d4 e4 f4
    \voice 
        c3 d3 e3 f3 | c3 d3 e3 f3

\track "Piano2"
\staff{score} \tuning piano \instrument acousticgrandpiano
    \voice 
        c4 d4 e4 f4 | c4 d4 e4 f4
    \voice 
        c3 d3 e3 f3

\track​

color​

systemsLayout​

defaultSystemsLayout​

solo​

mute​

volume​

balance​

instrument​

bank​

multiBarRest​

\staff​

score​

tabs​

slash​

numbered​

\voice​

`\track`

`color`

`systemsLayout`

`defaultSystemsLayout`

`solo`

`mute`

`volume`

`balance`

`instrument`

`bank`

`multiBarRest`

`\staff`

`score`

`tabs`

`slash`

`numbered`

`\voice`