Bar Metadata

The following metadata tags are affecting things on bar (and masterbar) level. Time signatures, clefs, repeats, such kind of things.

\ts

Syntax

// [1]: Specifies a common (4/4) time signature using the special C symbol
\ts common
// [2]: 
\ts (numerator denominator)

Description: Defines the time signature for this and subsequent bars.

AlphaTab does not yet support polytempo notation where instruments might use different time signatures. Therefore be sure to only specify the timesignatures once as part of the first track/staff or ensure they are consistent across the whole document.

Parameters:

Overload	Name	Description	Type	Required
[1]	common	Specifies a common (4/4) time signature using the special C symbol	common	yes
[2]	numerator	The time signature numerator	Number	yes
[2]	denominator	The time signature denominator	Number	yes

Parameter Values:

Following parameters have value limitations

Overload	Name	Values
[1]	common	Value Description common Specifies a common (4/4) time signature using the special C symbol

Example:

\ts 3 4 | \ts 4 4 | \ts 6 8 | \ts common

\ts 3 4 | \ts 4 4 | \ts 6 8 | \ts common

\ro

Syntax

\ro ()

Description: Start a repeat

Example:

\ro 1.3 2.3 3.3 4.3 | 5.3 6.3 7.3 8.3 | \rc 2 1.3 2.3 3.3 4.3 | \ro \rc 3 1.3 2.3 3.3 4.3

\ro 1.3 2.3 3.3 4.3 | 5.3 6.3 7.3 8.3 | \rc 2 1.3 2.3 3.3 4.3 |
\ro \rc 3 1.3 2.3 3.3 4.3

\rc

Syntax

\rc repeats

Description: Marks the end of a repeat.

Parameters:

Name	Description	Type	Required
repeats	The number of repeats which should be played	Number	yes

Example:

\ro 1.3 2.3 3.3 4.3 | 5.3 6.3 7.3 8.3 | \rc 2 1.3 2.3 3.3 4.3 | \ro \rc 3 1.3 2.3 3.3 4.3

\ro 1.3 2.3 3.3 4.3 | 5.3 6.3 7.3 8.3 | \rc 2 1.3 2.3 3.3 4.3 |
\ro \rc 3 1.3 2.3 3.3 4.3

\ae

Syntax

\ae (ending)

Description: Specifies on which repeats a bar should be played (to build alternate endings).

Parameters:

Name	Description	Type	Required
ending	The repeats on which the bar should be played	Number[]	yes

Example:

\ro 1.3 2.3 3.3 4.3 | \ae (1 2 3) 5.3 6.3 7.3 8.3 | \ae 4 c 4 5.3 8.3 7.3 6.3

\ro 1.3 2.3 3.3 4.3 | \ae (1 2 3) 5.3 6.3 7.3 8.3 | \ae 4 
c 4 5.3 8.3 7.3 6.3

\ks

Syntax

\ks key

Description: Specifies the key signature for this and subsequent bars.

Parameters:

Name	Description	Type	Required
key	The key signature	Ident	yes

Parameter Values:

Following parameters have value limitations

Name	Values
key	Value Description cb gb db ab eb bb f c g d a e b f# c# cbmajor abminor gbmajor ebminor dbmajor bbminor abmajor fminor ebmajor cminor bbmajor gminor fmajor dminor cmajor aminor gmajor eminor dmajor bminor amajor f#minor emajor c#minor bmajor g#minor f#major d#minor f# c#major a#minor c#

Example:

\ks Cb | \ks C | \ks C# | \ks Aminor | \ks Dmajor | \ks Bminor

\ks Cb | \ks C | \ks C# |
\ks Aminor | \ks Dmajor | \ks Bminor

\clef

Syntax

\clef clef

Description: Changes the clef for this and subsequent bars.

Parameters:

Name	Description	Type	Required
clef	The clef	Ident|Number	yes

Parameter Values:

Following parameters have value limitations

Name	Values
clef	Value Description neutral c3 c4 f4 g2 n alto tenor bass treble

Example:

\clef G2 | \clef F4 | \clef C3 | \clef C4 | \clef N | \clef Treble | \clef Bass | \clef Tenor | \clef Alto | \clef Neutral |

\clef G2 | \clef F4 | \clef C3 | \clef C4 | \clef N |
\clef Treble | \clef Bass | \clef Tenor | \clef Alto | \clef Neutral |

\ottava

Syntax

\ottava ottava

Description: Changes the clef ottave for this and subsequent bars.

Parameters:

Name	Description	Type	Required
ottava	The clef ottava	Ident	yes

Parameter Values:

Following parameters have value limitations

Name	Values
ottava	Value Description 15ma Quindicesima (+2 octaves) 8va Ottava (+1 octave) regular Regular 8vb Ottava Bassa (-1 octave) 15mb Quindicesima bassa (-2 octaves) 15ma Quindicesima (+2 octaves) 8va Ottava (+1 octave) 8vb Ottava Bassa (-1 octave) 15mb Quindicesima bassa (-2 octaves)

Example:

\clef F4 \ottava 15ma | | \ottava regular | | \clef C3 \ottava 8vb | |

\clef F4 \ottava 15ma | | \ottava regular | | \clef C3 \ottava 8vb | |

\tempo

Syntax

// [1]: 
\tempo (tempo label)
// [2]: 
\tempo (tempo label position hide)

Description: Adds a tempo change to the bar.

A bar can have multiple tempo changes. They can either be relatively positioned using this metadata tag or applied via the tempo property as beat effect.

Tempo changes affect the whole song and not only an individual track. To avoid unexpected side effects, we recomment to specify the tempo changes only once on the first track/staff.

Parameters:

Overload	Name	Description	Type	Required
[1]	tempo	The new tempo in BPM	Number	yes
[1]	label	A textual label for the tempo	String	no ""
[2]	tempo	The new tempo in BPM	Number	yes
[2]	label	A textual label for the tempo	String	yes ""
[2]	position	A relative (ratio) position where within the bar the tempo change should happen	Number	no 0
[2]	hide	If specified the tempo change is not visually shown	hide	no

Parameter Values:

Following parameters have value limitations

Overload	Name	Values
[2]	hide	Value Description hide If specified the tempo change is not visually shown

Example:

\tempo 30 C4 D4 E4 F4 | \tempo (120 "Moderate") \tempo (60 "" 0.5 hide) C4 D4 E4 F4 |

\tempo 30
C4 D4 E4 F4 |
\tempo (120 "Moderate")
\tempo (60 "" 0.5 hide)
C4 D4 E4 F4 |

\tf

Syntax

\tf tripletFeel

Description: Changes the triplet feel (aka. swing) play style.

Parameters:

Name	Description	Type	Required
tripletFeel	The triplet feel style	Ident|Number	yes

Parameter Values:

Following parameters have value limitations

Name

Values

tripletFeel

Value Description none No triplet feel triplet16th Triplet 16th triplet8th Triplet 8th dotted16th Dotted 16th dotted8th Dotted 8th scottish16th Scottish 16th scottish8th Scottish 8th none No triplet feel no No triplet feel noTripletFeel No triplet feel t16 Triplet 16th triplet-16th Triplet 16th t8 Triplet 8th triplet-8th Triplet 8th d16 Dotted 16th dotted-16th Dotted 16th d8 Dotted 8th dotted-8th Dotted 8th s16 Scottish 16th scottish-16th Scottish 16th s8 Scottish 8th scottish-8th Scottish 8th

Example:

\tf none 3.3*4 | \tf triplet16th 3.3*4 | \tf triplet8th 3.3*4 | \tf dotted16th 3.3*4 | \tf dotted8th 3.3*4 | \tf scottish16th 3.3*4 | \tf scottish8th 3.3*4 |

\tf none 3.3*4 |
\tf triplet16th 3.3*4 | \tf triplet8th 3.3*4 |
\tf dotted16th 3.3*4 | \tf dotted8th 3.3*4 |
\tf scottish16th 3.3*4 | \tf scottish8th 3.3*4 |

\ac

Syntax

\ac ()

Description: Marks the bar as an anacrusis (pick-up) bar.

By default bars follow a strict timing defined by the time signature and tempo. Anacrusis (aka. pickup bars) do not follow this rule. The length of those bars is defined by the actual beats/notes in the bar.

Example:

\ks D \ts 24 16 \ac r.16 6.3 7.3 9.3 7.3 6.3 | r.16 5.4 7.4 9.4 7.4 5.4 6.3.4{d} 9.6.16 10.6 12.6 10.6 9.6 14.6.4{d} r.16

\ks D \ts 24 16 \ac r.16 6.3 7.3 9.3 7.3 6.3 | r.16 5.4 7.4 9.4 7.4 5.4 6.3.4{d} 9.6.16 10.6 12.6 10.6 9.6 14.6.4{d} r.16

\section

Syntax

// [1]: 
\section text
// [2]: 
\section (marker text)

Description: Starts a new section

Parameters:

Overload	Name	Description	Type	Required
[1]	text	The text/description of the new section	String	yes
[2]	marker	The marker for the section, typically a single letter	String	yes
[2]	text	The text/description of the new section	String	yes

Example:

\section "Intro" // simple section 1.1 1.1 1.1 1.1 | 1.1 1.1 1.1 1.1 | \section "S" "Solo" // with marker and section name differently 1.1 1.1 1.1 1.1

\section "Intro" // simple section
1.1 1.1 1.1 1.1 | 1.1 1.1 1.1 1.1 |
\section "S" "Solo" // with marker and section name differently
1.1 1.1 1.1 1.1

\jump

Syntax

\jump direction

Description: Adds a direction/jump instruction to the bar.

Parameters:

Name	Description	Type	Required
direction	The direction to add	Ident	yes

Parameter Values:

Following parameters have value limitations

Name

Values

direction

Value Description fine Fine (Target) segno Segno (Target) segnoSegno SegnoSegno (Target) coda Coda (Target) doubleCoda DoubleCoda (Target) daCapo DaCapo (Jump) daCapoAlCoda DaCapoAlCoda (Jump) daCapoAlDoubleCoda DaCapoAlDoubleCoda (Jump) daCapoAlFine DaCapoAlFine (Jump) dalSegno DalSegno (Jump) dalSegnoAlCoda DalSegnoAlCoda (Jump) dalSegnoAlDoubleCoda DalSegnoAlDoubleCoda (Jump) dalSegnoAlFine DalSegnoAlFine (Jump) dalSegnoSegno DalSegnoSegno (Jump) dalSegnoSegnoAlCoda DalSegnoSegnoAlCoda (Jump) dalSegnoSegnoAlDoubleCoda DalSegnoSegnoAlDoubleCoda (Jump) dalSegnoSegnoAlFine DalSegnoSegnoAlFine (Jump) daCoda DaCoda (Jump) daDoubleCoda DaDoubleCoda (Jump)

Example:

\ro \rc 2 3.3*4 | 3.3*4 | \jump Segno 3.3*4 | \ro c 2 3.3*4 | \jump DaCoda 3.3*4 | 3.3*4 | 3.3*4 \jump DalSegnoAlCoda 3.3*4 | 3.3*4 | \jump Coda 3.3*4 | 3.3*4 | 3.3*4

\ro \rc 2 3.3*4 | 
  3.3*4 | 
  \jump Segno 3.3*4 |
  \ro 
c 2 3.3*4 | 
  \jump DaCoda 3.3*4 |
  3.3*4 | 3.3*4
  \jump DalSegnoAlCoda 3.3*4 |
  3.3*4 |
  \jump Coda 3.3*4 |
  3.3*4 |
  3.3*4

\ft

Syntax

\ft ()

Description: Marks the bar as a free-time bar where players are free to vary the timing.

Example:

:2 C4*2 | \ft C4*2 | \ft C4*2 | C4*2 |

:2 
C4*2 |
\ft C4*2 |
\ft C4*2 |
C4*2 |

\simile

Syntax

\simile mark

Description: Adds a simile mark to the bar indicating that the content of the last, or previous two bars should be repeated.

Parameters:

Name	Description	Type	Required
mark	The mark to add	none|simple|firstOfDouble|secondOfDouble	yes

Parameter Values:

Following parameters have value limitations

Name	Values
mark	Value Description none No simile mark is applied simple A simple simile mark. The previous bar is repeated. firstOfDouble A double simile mark. This value is assigned to the first bar of the 2 repeat bars. secondOfDouble A double simile mark. This value is assigned to the second bar of the 2 repeat bars.

Example:

3.3*4 | \simile simple | 3.3*4 | 4.3*4 | \simile firstofdouble | \simile secondofdouble

3.3*4 | \simile simple | 3.3*4 | 4.3*4 | \simile firstofdouble | \simile secondofdouble

\barlineLeft

Syntax

\barlineLeft style

Description: Adjusts the lines which will be shown left on the bar.

For some special notation needs, the default bar line can be adjusted on every bar. The bar line styles are aligned with the ones from MusicXML.

alphaTab attempts to reuse lines on overlapping styles across bars.

Parameters:

Name	Description	Type	Required
style	The line style to use	Ident	yes

Parameter Values:

Following parameters have value limitations

Name	Values
style	Value Description automatic Auto detect line to show dashed dotted heavy heavyHeavy heavyLight lightHeavy lightLight none regular short tick

Example:

\instrument piano \track "Overlapping" \staff \barlineleft dashed \barlineright dotted | \barlineleft heavyheavy \barlineright heavyheavy \staff \barlineleft lightlight \barlineright lightheavy | \barlineleft heavylight \barlineright dashed \track "All Styles" \staff \barlineright dashed | \barlineright dotted | \barlineright heavy | \barlineright heavyHeavy | \barlineright heavyLight | \barlineright lightHeavy | \barlineright lightlight | \barlineright none | \barlineright regular | \barlineright short | \barlineright tick |

\instrument piano
\track "Overlapping"
\staff 
    \barlineleft dashed 
    \barlineright dotted 
    | 
    \barlineleft heavyheavy
    \barlineright heavyheavy
    
\staff 
    \barlineleft lightlight 
    \barlineright lightheavy 
    | 
    \barlineleft heavylight
    \barlineright dashed
\track "All Styles"
\staff 
    \barlineright dashed |
    \barlineright dotted |
    \barlineright heavy |
    \barlineright heavyHeavy |
    \barlineright heavyLight |
    \barlineright lightHeavy |
    \barlineright lightlight |
    \barlineright none |
    \barlineright regular |
    \barlineright short |
    \barlineright tick |

\barlineRight

Syntax

\barlineRight style

Description: Adjusts the lines which will be shown right on the bar.

For some special notation needs, the default bar line can be adjusted on every bar. The bar line styles are aligned with the ones from MusicXML.

alphaTab attempts to reuse lines on overlapping styles across bars.

Parameters:

Name	Description	Type	Required
style	The line style to use	Ident	yes

Parameter Values:

Following parameters have value limitations

Name	Values
style	Value Description automatic Auto detect line to show dashed dotted heavy heavyHeavy heavyLight lightHeavy lightLight none regular short tick

Example:

\instrument piano \track "Overlapping" \staff \barlineleft dashed \barlineright dotted | \barlineleft heavyheavy \barlineright heavyheavy \staff \barlineleft lightlight \barlineright lightheavy | \barlineleft heavylight \barlineright dashed \track "All Styles" \staff \barlineright dashed | \barlineright dotted | \barlineright heavy | \barlineright heavyHeavy | \barlineright heavyLight | \barlineright lightHeavy | \barlineright lightlight | \barlineright none | \barlineright regular | \barlineright short | \barlineright tick |

\instrument piano
\track "Overlapping"
\staff 
    \barlineleft dashed 
    \barlineright dotted 
    | 
    \barlineleft heavyheavy
    \barlineright heavyheavy
    
\staff 
    \barlineleft lightlight 
    \barlineright lightheavy 
    | 
    \barlineleft heavylight
    \barlineright dashed
\track "All Styles"
\staff 
    \barlineright dashed |
    \barlineright dotted |
    \barlineright heavy |
    \barlineright heavyHeavy |
    \barlineright heavyLight |
    \barlineright lightHeavy |
    \barlineright lightlight |
    \barlineright none |
    \barlineright regular |
    \barlineright short |
    \barlineright tick |

\scale

Syntax

\scale scale

Description: Adjusts the relative scale of the bar when using systemsLayoutMode: 'UseModelLayout' with the page layout.

Parameters:

Name	Description	Type	Required
scale	The scale of the bar within the system	Number	yes

Example:

\track { defaultSystemsLayout 3 } \scale 0.25 :1 c4 | \scale 0.5 c4 | \scale 0.25 c4 | \scale 0.5 c4 | \scale 2 c4 | \scale 0.5 c4 | c4 | c4

\track { defaultSystemsLayout 3 }
\scale 0.25 :1 c4 | \scale 0.5 c4 | \scale 0.25 c4 | 
\scale 0.5 c4 | \scale 2 c4 | \scale 0.5 c4 |
c4 | c4

\width

Syntax

\width width

Description: Adjusts the absolute of the bar when using systemsLayoutMode: 'UseModelLayout' with the horizontal layout.

Parameters:

Name	Description	Type	Required
width	The absolute width of the bar	Number	yes

Example:

\track \width 100 :1 c4 | \width 300 c4 | \width 350 c4

\track
  \width 100 :1 c4 | \width 300 c4 | \width 350 c4

\sync

Syntax

\sync (barIndex occurence millisecondOffset ratioPosition)

Description: Adds a new sync point for synchronizing the music sheet with an external media source like a backing track or video player.

alphaTex support specifying sync points for the synchronization with external media.

It is recommended to add the sync points at the very end of the song but it is also possible to define them inbetween.

The barIndex, occurence, ratioPosition parameters define the absolute position within the music sheet. The millisecondOffset defines the absolute position within the external media.

With this information known, alphaTab can synchronize the external media with the music sheet.

Parameters:

Name	Description	Type	Required
barIndex	The index of the bar being synced	Number	yes
occurence	The occurence of the bar for which this sync point applies (on repeats)	Number	yes
millisecondOffset	The absolute millisecond offset within the external media	Number	yes
ratioPosition	The relative position within the bar where the synchronization happens	Number	no 0

Example:

\title "Prelude in D Minor"
\artist "J.S. Bach (1685-1750)"
\copyright "Public Domain"
\tempo 80
.
\ts 3 4
0.4.16 (3.2 -.4) (1.1 -.4) (5.1 -.4) 1.1 3.2 1.1 3.2 2.3.8 (3.2 3.4) |
(3.2 0.4).16 (3.2 -.4) (1.1 -.4) (5.1 -.4) 1.1 3.2 1.1 3.2 2.3.8 (3.2 3.4) | 
(3.2 0.4).16 (3.2 -.4) (3.1 -.4) (6.1 -.4) 3.1 3.2 3.1 3.2 3.3.8 (3.2 0.3) | 
(3.2 0.4).16 (3.2 -.4) (3.1 -.4) (6.1 -.4) 3.1 3.2 3.1 3.2 3.3.8 (3.2 0.3) |
.
\sync 0 0 0
\sync 0 0 1500 0.666
\sync 1 0 4075 0.666
\sync 2 0 6475 0.333
\sync 3 0 10223 1

\accidentals

Syntax

\accidentals mode

Description: Changes the mode how alphaTab should treat accidentals when writing pitched notes.

alphaTab can use the accidentals as specified in alphaTex, or apply accidentals automatically based on the note pitch.

Parameters:

Name	Description	Type	Required
mode	The mode which should be active	auto|explicit	yes

Parameter Values:

Following parameters have value limitations

Name	Values
mode	Value Description auto Automatic (Based on Pitch) explicit Explicit (as Written)

Example:

\accidentals explicit C#4 C4 Eb4 Ax4 | \accidentals auto C#4 C4 Eb4 Ax4 |

\accidentals explicit
C#4 C4 Eb4 Ax4 |
\accidentals auto
C#4 C4 Eb4 Ax4 |

\spd

Syntax

\spd position

Description: Specifies how the sustain petal should be pressed down (spd), held (sph) or lifted up (spu).

This tag allows specifying the sustain pedal relative to the bar. The sustain pedal can also be applied via beat properties.

Parameters:

Name	Description	Type	Required
position	The relative position within the bar for the marker (0-1)	Number	yes

Example:

\spd 0 \spu 0.25 \spd 0.5 \sph 0.75 \spu 1 :8 C4 * 8

\spd 0
\spu 0.25
\spd 0.5
\sph 0.75
\spu 1
:8 C4 * 8

\sph

Syntax

\sph position

Description: Specifies how the sustain petal should be pressed down (spd), held (sph) or lifted up (spu).

This tag allows specifying the sustain pedal relative to the bar. The sustain pedal can also be applied via beat properties.

Parameters:

Name	Description	Type	Required
position	The relative position within the bar for the marker (0-1)	Number	yes

Example:

\spd 0 \spu 0.25 \spd 0.5 \sph 0.75 \spu 1 :8 C4 * 8

\spd 0
\spu 0.25
\spd 0.5
\sph 0.75
\spu 1
:8 C4 * 8

\spu

Syntax

\spu position

Description: Specifies how the sustain petal should be pressed down (spd), held (sph) or lifted up (spu).

This tag allows specifying the sustain pedal relative to the bar. The sustain pedal can also be applied via beat properties.

Parameters:

Name	Description	Type	Required
position	The relative position within the bar for the marker (0-1)	Number	yes

Example:

\spd 0 \spu 0.25 \spd 0.5 \sph 0.75 \spu 1 :8 C4 * 8

\spd 0
\spu 0.25
\spd 0.5
\sph 0.75
\spu 1
:8 C4 * 8