Structural Metadata

This page documents the structural metadata scope — the metadata tags that open a new track, staff, or voice.

Use these tags when your song needs more than one of any of them:

Multiple tracks — when several instruments play together in the same song.
Multiple staves — for grand staff piano notation (left hand / right hand) or for splitting voices apart for readability.
Multiple voices — for independent rhythms and pitches inside the same staff, such as vocal parts sung together or a bass line played under a melody on the same instrument.

Start each new track, staff, or voice with the matching tag at the beginning of a bar:

\track
\staff
\voice

The first track, staff, and voice are opened implicitly, so you only need these tags from the second element onward. When a piece has more than one, name the first element explicitly for clarity.

`\track`

Scope: Structural metadata

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:

00:00

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

Properties:

`color`

Scope: Structural metadata

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:

00:00

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

`systemsLayout`

Scope: Structural metadata

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:

00:00

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

`defaultSystemsLayout`

Scope: Structural metadata

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:

00:00

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

`solo`

Scope: Structural metadata

Syntax
solo ()

Description: Set the track to be played solo.

Example:

00:00

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

`mute`

Scope: Structural metadata

Syntax
mute ()

Description: Set the track to be muted.

Example:

00:00

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

`volume`

Scope: Structural metadata

Syntax
volume value

Description: Set the track volume.

Parameters:

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

Example:

00:00

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

`balance`

Scope: Structural metadata

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:

00:00

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

`instrument`

Scope: Structural metadata

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:

00:00

\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`

Scope: Structural metadata

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:

00:00

\track { instrument 25 bank 2 }

`multiBarRest`

Scope: Structural metadata

Syntax
multiBarRest ()

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

Example:

00:00

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

00:00

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

`\staff`

Scope: Structural metadata

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:

00:00

\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`

Scope: Structural metadata

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:

00:00

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

`tabs`

Scope: Structural metadata

Syntax
tabs ()

Description: Enable the display of guitar tablature.

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

Example:

00:00

\track
  \staff {tabs}
  3.3 4.3 5.3 5.5

`slash`

Scope: Structural metadata

Syntax
slash ()

Description: Enable the display of slash notation.

Example:

00:00

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

`numbered`

Scope: Structural metadata

Syntax
numbered ()

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

Example:

00:00

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

`\voice`

Scope: Structural metadata

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:

00:00

\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`