Document Structure

An alphaTex file is a list of bars. Each bar carries optional metadata tags followed by its beat content. Place song-wide metadata at the top of the file and any external media sync points at the bottom.

/* Song Metadata */
/* Song Contents */
/* Sync Points */

note

Before alphaTex 1.7 the three sections had to be separated by a .. Since 1.7 the separator dots are optional and you should omit them.

/* Song Metadata */
.
/* Song Contents */
.
/* Sync Points */

Bars

A bar (also called a measure) begins with an optional list of bar metadata tags and continues with the beats it contains. See Bar Metadata for the tags you can apply here.

A bar ends at a pipe | or at the next metadata tag.

// bar 1 metadata tags
\clef G2 \ks 
  // bar 1 contents
  Cb C4 
|  
// bar 2 metadata tags
\ks A
  // bar 2 contents
  C4 
// bar 3 metadata tags (notice the missing pipe, bar 3 start is indicated by the time signature tag)
\ts (3 4)
  C4

Metadata tags need to be at the start of bar followed by the content as a new metadata tag is also a marker for a new bar. This can be confusing for tags which control display of elements at the end of the bar. e.g. a repeat end or a barLineRight are still declared in the start of a bar.

\barLineLeft lightlight
C4 
|
\barLineRight dashed
C4
\barLineRight dotted
C4
\barLineRight heavyHeavy
C4
|
C4

Specifically \barLineRight dotted is important in this example, it starts bar 3 and specifies the right barline of it. This behavior exists for backwards compatibility. In future alphaTex versions we will make the | mandatory setting clear boundaries of what belongs to a bar.

Beats

A beat groups notes that sound at the same time. The general shape of a beat is:

• duration-change content duration effects multiplier

:4
  C4
  (C4 D4).8
  (C4 D4) { f }
  C4.16 * 2
  C4.4

Duration change (optional)

Change the duration for every following beat with :Duration, where Duration is one of:

• :-4 a Quadruple Whole Note
• :-2 a Double Note
• :1 a Whole Note
• :2 a Half Note
• :4 a Quarter Note
• :8 an 8th Note
• :16 a 16th Note
• :32 a 32nd Note
• :64 a 64th Note
• :128 a 128th Note
• :256 a 256th Note

You can attach a property block after the duration to declare tuplets.

:4 {tu 3 2}

See Tuplet Effect for details.

:16 // 16th notes from here
  3.3
  4.3 
  5.3
  6.3
:4 { tu 3 } // quarter notes triplets
  3.3
  4.3
  5.3
:8 
  3.3 * 3

Beat Content (required)

The content of a beat is one of:

• A rest
• Multiple notes played together (grouped by parentheses)
• A single note

Write a rest as r.

:4 r r r r

Group multiple Notes with parentheses (). As with argument lists, you can omit the parentheses when there is a single note.

:4 
  C4 // single note on beat
  (C4 E4) // multiple notes with parenthesis

Beat Duration (optional)

You can also set the beat duration after the beat content as . duration. The new duration is remembered for the next beat, but tuplet effects are not.

C4 .4
C4 .8
C4 // .8 remembered
C4 .2

Beat Effects (optional)

Attach beat properties after the beat content. See Beat Properties for the full list.

:4
  (C4 D4) { tp 8 } 
  C4 { f }
  r.2 {txt "Pause here"}

Beat Multiplier (optional)

Repeat the same beat with * times, where times is the number of copies.

:4
  // 4 times the same A-chord 
  (0.1 2.2 2.3 2.4 0.5) * 4

Notes

Depending on the instrument, a bar contains one of three note kinds. Do not mix them within a staff — pick one and stay with it:

• Fretted and stringed instruments (guitars and similar) use fret.string.
• Percussion and drums use articulation names.
• Other pitched instruments use note names.

After each note you can attach note properties as note-value {note-properties}.

info

alphaTab detects the staff kind from the first note it reads.

Fretted Notes

When the current staff is a stringed instrument (\tuning or \instrument set accordingly), you write notes as fret and string. alphaTab computes the resulting pitch.

:1
  (12.1 {sib} 14.2 {sib b (0 4)})
  12.1 { v }

Percussion / Drum Notes

On percussion instruments, write the articulation to play as the note value. Use a quoted string or an unquoted identifier.

See the \\articulation metadata tag for details.

\track { instrument percussion }
\articulation defaults
:4
  (KickHit RideBell) 
  r 
  KickHit 
  KickHit

Pitched notes

A pitched note combines:

• The tone (C, D, E, F, G, A, B, C)
• The accidental (#, b, bb, x, ##, …; see Accidentals for details)
• The octave (a number)

C4
C#4
Ebb4
Dx5

Note Effects

See Note Properties for the full list of note-level effects.

:2
  3.3 { b (0 4) } // note bend
  (
      3.3 { v } // Vibrato
      3.2 { sib } // slide into from below
  )

When a beat holds a single note, you can combine note and beat properties in one block.

:2
  // combined effects
  3.3 {
      b (0 4)     // note effect
      txt "Bend"  // beat effect
  }
  // separated effects 
  3.3 
      { b (0 4) }     // note effect
      { txt "Bend" }  // beat effect

Tracks, Staves and Voices

A song can hold multiple tracks and staves. Dedicated structural metadata tags mark the start of each. See Structural Metadata for the full reference.

\track "Track 1"
  \staff {score} // first staff
      \voice // first voice 
          C4 D4 E4 F4 | C4 D4 E4 F4
      \voice // second voice
          C5 D5 E5 F5 | C5 D5 E5 F5
  \staff {tabs} // second staff
      3.5 5.5 7.5 8.5 | 3.5 5.5 7.5 8.5
\track "Track 2"
   1.2 3.2 5.2 6.2

You only need to write these structural tags to start a new element. The initial track, staff, and voice are opened implicitly.

// first track
  // first staff
      // first voice 
          C4 D4 E4 F4 | C4 D4 E4 F4
      \voice // second voice
          C5 D5 E5 F5 | C5 D5 E5 F5
  \staff {tabs} // second staff
      3.5 5.5 7.5 8.5 | 3.5 5.5 7.5 8.5
\track "Track 2"
   1.2 3.2 5.2 6.2