Staff metadata
This page describes all the metadata tags which affect the "staff" level of the data model.
To avoid any unexpected side-effects, these values should be specified on the first bar.
Some of these tags are simply historically metadata tags. They might become staff properties in future.
\tuning
\tuning (strings) { label "Label" hide }
\tuning `piano`
\tuning `none`
\tuning `voice`
Description: Defines the number of strings and their tuning for stringed (and fretted) instruments.
Values:
| Name | Description | Type | Required |
|---|---|---|---|
| strings | The tuning values as pitched notes) | identifier list | yes |
piano | Indicates that this staff is NOT stringed, but a piano with pitched notes. | identifier | yes |
none | Indicates that this staff is NOT stringed and has no tuning and uses pitched notes. | identifier | yes |
voice | Indicates that this staff is NOT stringed, but a vocal voice with pitched notes. | identifier | yes |
Example
\track "Track 1"
\staff {tabs}
\tuning (A1 D2 A2 D3 G3 B3 E4) { hide label "Special Guitar Tuning" }
4.1 3.1 2.1 1.1
\track "Track 2"
\tuning piano
C4 D4 E4 F4
The following properties are supported on this metadata.
hide
hide
Description: Hides the tuning from being displayed above the first staff.
Values: None
Example:
\track
\staff {tabs}
\tuning (E4 B3 G3 D3 A2 D2)
4.1 3.1 2.1 1.1
\track
\staff {tabs}
\tuning (F2 C2 G1 D1) { hide}
4.1 3.1 2.1 1.1
label
label text
Description: Defines the textual label for the tuning.
Values:
| Name | Description | Type | Required |
|---|---|---|---|
| text | The label to set | string | yes |
Example:
\track
\staff {tabs}
\tuning (E4 B3 G3 D3 A2 D2) { label "Dropped D Tuning" }
4.1 3.1 2.1 1.1
\chord
\chord (name strings)
Description: Defines a new chord for a chord diagram display defining how to play it.
To avoid inconsistencies with tunings, chords should be defined after the tuning is set.
To "use" the defined chord the ch chordName beat property has to be applied. The notes for the
chord still have to be specified separately, the definition in this metadata is purely for the chord diagram.
Values:
| Name | Description | Type | Required |
|---|---|---|---|
| name | The name of the chord | string or identifier | yes |
| strings | For every string of the staff tuning, the fret to be played or x for strings not played. | identifier or number list | yes |
Example
\chord ("C" 0 1 0 2 3 x)
\ts 2 4
(0.1 1.2 0.3 2.4 3.5){ch "C"} (0.1 1.2 0.3 2.4 3.5)
The following properties are supported on this metadata.
firstfret
firstfret fret
Description: Shifts the first fret shown in the diagram higher
Values:
| Name | Description | Type | Required |
|---|---|---|---|
| fret | The index of the first fret | number | yes |
Example:
\chord ("D#" 6 8 8 8 6 x) {firstfret 6}
.
(6.1 8.2 8.3 8.4 6.5){ch "D#"}
barre
barre fret
barre (fret1 fret2...)
Description: Defines on which frets a barré should be played (visually joins the dots to a bar).
Values:
| Name | Description | Type | Required |
|---|---|---|---|
| frets | The frets on which a barré should be played | number list | yes |
Example:
\chord ("D#" 6 8 8 8 6 x) {firstfret 6 barre 6}
\chord ("Special" 3 3 3 1 1 1) {showname false barre (1 3)}
.
(6.1 8.2 8.3 8.4 6.5){ch "D#"}
(3.1 3.2 3.3 1.4 1.5 1.6){ch "Special"}
showDiagram
showDiagram visibility
Description: Enables/Disables whether the chord diagram should be shown.
Values:
| Name | Description | Type | Required |
|---|---|---|---|
| visibility | The visibility of the diagram | number (0/1) or boolean (false/true) | No (default: true) |
Example:
\chord ("E" 0 0 1 2 2 0) {showdiagram false}
.
(0.1 0.2 1.3 2.4 2.5 0.6){ch "E"}
showName
showName visibility
Description: Enables/Disables whether the chord name should be shown.
Values:
| Name | Description | Type | Required |
|---|---|---|---|
| visibility | The visibility of the diagram | number (0/1) or boolean (false/true) | No (default: true) |
Example:
// Hide name and multiple barre
\chord ("Special" 3 3 3 1 1 1) {showname false}
.
(3.1 3.2 3.3 1.4 1.5 1.6){ch "Special"}
\capo
\capo fret
Description: Defines the fret on which a capo should be placed.
Values:
| Name | Description | Type | Required |
|---|---|---|---|
| fret | The fret on which a capo is placed | number | yes |
Example:
\track "Guitar"
\staff{tabs}
\capo 5
1.2 3.2 0.1 1.1
There are no properties on this metadata.
\lyrics
\lyrics startBar lyrics
\lyrics lyrics
Description: Define the lyrics shown on the beats of the staff.
The lyrics system of alphaTab is borrowed from Guitar Pro. For every track multiple "lines" of lyrics can be defined which can either start at the beginning or at a later bar.
The syllables of the procided lyrics are spread automatically across the beats of the track. Syllables are separated with spaces.
If multiple words/syllables should stay on the same beat the space can be replaced with a +.
Comments which should not be displayed can be put [into brackets].
Values:
| Name | Description | Type | Required |
|---|---|---|---|
| startBar | The first bar on which the notes should be applied | number | no |
| lyrics | The lyrics text to apply to the beats | string | yes |
Example:
\title "With Lyrics"
\instrument piano
.
\lyrics "Do Re Mi Fa So La Ti"
C4 D4 E4 F4 | G4 A4 B4 r
\title "Combine Syllables (and empty beats)"
\instrument piano
.
\lyrics "Do+Do Mi+Mi"
C4 C4 E4 E4
\title "Start Later"
\instrument piano
.
\lyrics 2 "Do Re Mi Fa So La Ti"
r r r r | r r r r |
C4 D4 E4 F4 | G4 A4 B4 r
\title "Comment"
\subtitle "Useful when loading lyrics from a different source"
\instrument piano
.
\lyrics "[This is a comment]Do Re Mi Fa"
C4 D4 E4 F4
\articulation
since 1.4.0
\articulation defaults
\articulation name value
Description: Defines the articulations available to write percussion and drum tabs.
Currently alphaTex does not defining completely custom articulations (note heads, staff line, technical symbols etc.).
Values:
| Name | Description | Type | Required |
|---|---|---|---|
| defaults | Registers all standard articulation names | identifier | yes (unless name/value syntax is used) |
| name | The string (or identifier) used in the note values | string or identifier | yes |
| value | The numeric value of the built-in articulation | identifier | yes |
Built-in articulations:
| Number | Name Long | Name Short |
|---|---|---|
| 29 | Ride (choke) | Ridechoke |
| 30 | Cymbal (hit) | Cymbalhit |
| 31 | Snare (side stick) | Snaresidestick |
| 33 | Snare (side stick) 2 | Snaresidestick2 |
| 34 | Snare (hit) | Snarehit |
| 35 | Kick (hit) | Kickhit |
| 36 | Kick (hit) 2 | Kickhit2 |
| 37 | Snare (side stick) 3 | Snaresidestick3 |
| 38 | Snare (hit) 2 | Snarehit2 |
| 39 | Hand Clap (hit) | HandClaphit |
| 40 | Snare (hit) 3 | Snarehit3 |
| 41 | Low Floor Tom (hit) | LowFloorTomhit |
| 42 | Hi-Hat (closed) | HiHatclosed |
| 43 | Very Low Tom (hit) | VeryLowTomhit |
| 44 | Pedal Hi-Hat (hit) | PedalHiHathit |
| 45 | Low Tom (hit) | LowTomhit |
| 46 | Hi-Hat (open) | HiHatopen |
| 47 | Mid Tom (hit) | MidTomhit |
| 48 | High Tom (hit) | HighTomhit |
| 49 | Crash high (hit) | Crashhighhit |
| 50 | High Floor Tom (hit) | HighFloorTomhit |
| 51 | Ride (middle) | Ridemiddle |
| 52 | China (hit) | Chinahit |
| 53 | Ride (bell) | Ridebell |
| 54 | Tambourine (hit) | Tambourinehit |
| 55 | Splash (hit) | Splashhit |
| 56 | Cowbell medium (hit) | Cowbellmediumhit |
| 57 | Crash medium (hit) | Crashmediumhit |
| 58 | Vibraslap (hit) | Vibraslaphit |
| 59 | Ride (edge) | Rideedge |
| 60 | Hand (hit) | Handhit |
| 61 | Hand (hit) | Handhit |
| 62 | Conga high (mute) | Congahighmute |
| 63 | Conga high (hit) | Congahighhit |
| 64 | Conga low (hit) | Congalowhit |
| 65 | Timbale high (hit) | Timbalehighhit |
| 66 | Timbale low (hit) | Timbalelowhit |
| 67 | Agogo high (hit) | Agogohighhit |
| 68 | Agogo tow (hit) | Agogotowhit |
| 69 | Cabasa (hit) | Cabasahit |
| 70 | Left Maraca (hit) | LeftMaracahit |
| 71 | Whistle high (hit) | Whistlehighhit |
| 72 | Whistle low (hit) | Whistlelowhit |
| 73 | Guiro (hit) | Guirohit |
| 74 | Guiro (scrap-return) | Guiroscrapreturn |
| 75 | Claves (hit) | Claveshit |
| 76 | Woodblock high (hit) | Woodblockhighhit |
| 77 | Woodblock low (hit) | Woodblocklowhit |
| 78 | Cuica (mute) | Cuicamute |
| 79 | Cuica (open) | Cuicaopen |
| 80 | Triangle (rnute) | Trianglernute |
| 81 | Triangle (hit) | Trianglehit |
| 82 | Shaker (hit) | Shakerhit |
| 83 | Tinkle Bell (hat) | TinkleBellhat |
| 83 | Jingle Bell (hit) | JingleBellhit |
| 84 | Bell Tree (hit) | BellTreehit |
| 85 | Castanets (hit) | Castanetshit |
| 86 | Surdo (hit) | Surdohit |
| 87 | Surdo (mute) | Surdomute |
| 91 | Snare (rim shot) | Snarerimshot |
| 92 | Hi-Hat (half) | HiHathalf |
| 93 | Ride (edge) 2 | Rideedge2 |
| 94 | Ride (choke) 2 | Ridechoke2 |
| 95 | Splash (choke) | Splashchoke |
| 96 | China (choke) | Chinachoke |
| 97 | Crash high (choke) | Crashhighchoke |
| 98 | Crash medium (choke) | Crashmediumchoke |
| 99 | Cowbell low (hit) | Cowbelllowhit |
| 100 | Cowbell low (tip) | Cowbelllowtip |
| 101 | Cowbell medium (tip) | Cowbellmediumtip |
| 102 | Cowbell high (hit) | Cowbellhighhit |
| 103 | Cowbell high (tip) | Cowbellhightip |
| 104 | Hand (mute) | Handmute |
| 105 | Hand (slap) | Handslap |
| 106 | Hand (mute) 2 | Handmute2 |
| 107 | Hand (slap) 2 | Handslap2 |
| 108 | Conga low (slap) | Congalowslap |
| 109 | Conga low (mute) | Congalowmute |
| 110 | Conga high (slap) | Congahighslap |
| 111 | Tambourine (return) | Tambourinereturn |
| 112 | Tambourine (roll) | Tambourineroll |
| 113 | Tambourine (hand) | Tambourinehand |
| 114 | Grancassa (hit) | Grancassahit |
| 115 | Piatti (hat) | Piattihat |
| 116 | Piatti (hand) | Piattihand |
| 117 | Cabasa (return) | Cabasareturn |
| 118 | Left Maraca (return) | LeftMaracareturn |
| 119 | Right Maraca (hit) | RightMaracahit |
| 120 | Right Maraca (return) | RightMaracareturn |
| 122 | Shaker (return) | Shakerreturn |
| 123 | Bell Tee (return) | BellTeereturn |
| 124 | Golpe (thumb) | Golpethumb |
| 125 | Golpe (finger) | Golpefinger |
| 126 | Ride (middle) 2 | Ridemiddle2 |
| 127 | Ride (bell) 2 | Ridebell2 |
Example:
\track "Drums"
\instrument percussion
\tempo 120
\clef neutral
\articulation defaults
(KickHit RideBell).16 r KickHit KickHit (KickHit RideBell).16 r KickHit KickHit (KickHit RideBell).16 r KickHit KickHit (KickHit RideBell).16 r KickHit KickHit |
(KickHit HiHatOpen) KickHit KickHit KickHit (KickHit HiHatOpen) KickHit KickHit KickHit (KickHit SnareHit HiHatOpen) KickHit KickHit.32 KickHit KickHit.16 (KickHit HiHatOpen) KickHit KickHit KickHit |
(KickHit HiHatOpen).8{tu 3} KickHit{tu 3} KickHit{tu 3} (KickHit SnareHit HiHatOpen){tu 3} KickHit.16{tu 3} KickHit{tu 3} KickHit.8{tu 3} (KickHit HiHatOpen).8{tu 3} KickHit{tu 3} KickHit{tu 3} (KickHit SnareHit HiHatOpen).8{tu 3} KickHit{tu 3} KickHit{tu 3}
\track "Drums"
\instrument percussion
\tempo 120
\clef neutral
\ts 2 4
29 30 31 |
33 34 35 36 |
37 38 39 40 |
41 42 43 44 |
45 46 47 48 |
49 50 51 52 |
53 54 55 56 |
57 58 59 60 |
61 62 63 64 |
65 66 67 68 |
69 70 71 72 |
73 74 75 76 |
77 78 79 80 |
81 82 83 83 |
84 85 86 87 |
91 92 93 94 |
95 96 97 98 |
99 100 101 102 |
103 104 105 106 |
107 108 109 110 |
111 112 113 114 |
115 116 117 118 |
119 120 122 123 |
124 125 126 127 |
There are no properties on this metadata.
\displayTranspose
\displayTranspose semitones
Description: Defines the number of semitones by which the standard notation should be transposed.
This only affects the display of the notes, not their audio.
It is typically used in situations like for guitars where the standard notation is displayed 1 octave lower to fit better into the standard staff.
It is a common practice to show a standard clef on guitar notes even though they are transposed by 1 octave to better fit into the standard staff lines.
Values:
| Name | Description | Type | Required |
|---|---|---|---|
| semitones | The number of semitones by which the notes should be transposed | number | yes |
Example:
\track \staff \instrument piano
\displayTranspose -12
C4.4 D4 E4 F4 | r.1
There are no properties on this metadata.
\transpose
\transpose semitones
Description: Defines the number of semitones by which the standard notation should be transposed.
This affects the display and audio.
Values:
| Name | Description | Type | Required |
|---|---|---|---|
| semitones | The number of semitones by which the notes should be transposed | number | yes |
Example:
\track \staff \instrument piano
\transpose -12
C4.4 D4 E4 F4 | r.1
There are no properties on this metadata.