Skip to main content

Language Syntax

This page describes the alphaTex source syntax and defines the vocabulary the rest of the reference uses. Every other page links back to the anchors here on first use of a term. Save alphaTex source with the file extension .atex.

Comments​

Use // for a line comment and /* ... */ for a block comment. Place them anywhere in an alphaTex file to annotate your source.

// This is a single-line comment.
/* This is a
   multi-line block comment. */

Strings​

Wrap textual values in double or single quotes.

  • "Double quoted string"
  • 'Single quoted string'

The following escape sequences are supported inside string literals:

  • \n — newline
  • \r — carriage return
  • \t — tab
  • \\ — a literal backslash
  • \' and \" — a literal quote
  • \uXXXX — a Unicode code point given as four hex digits

Numbers​

alphaTex supports integer and decimal numbers. Decimal numbers are accepted only in the places where they cannot collide with fret-note notation or duration values.

Examples:

  • 10
  • -10
  • 0.5
  • -4.5

Argument lists​

An argument list is the group of values you pass into a metadata tag or a property. Wrap multiple values in parentheses. Omit the parentheses when you pass a single value.

Each entry inside the list is called an argument. The reference tables describe the matching parameters — the positional slots that the language accepts for a given construct.

An argument can be:

  • An integer: 3, -10
  • A decimal number: 3.3, -10.5
  • A string: "Hello", 'Hello'
  • A reserved identifier: true, hide, x

Basic examples:

  • (1 2 3) — three numbers
  • ("Test" 3 hide) — mixed types

Real examples:

  • \ts (3 4) — a 3/4 time signature at bar scope
  • 12.2 { b (0 4 0) } — a full bend and release on a note
  • \title ("Song Title" "Title: %TITLE%" left) — a song title shown as Title: Song Title, left aligned

Argument entries are separated by whitespace. Commas are not used.

Properties​

A property is a name arguments pair inside curly braces. Properties attach to beats, notes, and metadata tags to add effects, visibility flags, and other optional aspects.

Property names are case-insensitive. The argument list of a property follows the rules in Argument lists.

\track "Track Name" { color "#FF0000" }
\staff { score }
C4 { b (0 4) v txt "Bend with Vibrato" }

Metadata tags​

A metadata tag is a backslash-prefixed construct of the form \name arguments {properties}. The argument list and the property block are both optional; individual tags decide which arguments and properties they accept.

Metadata tag names are case-insensitive.

\title "Song Title"
\track "Track Name" { color '#FF0000' }
\ts (3 4)

The arguments of a metadata tag follow Argument lists. Its properties follow Properties.

Scopes​

alphaTex constructs are grouped by where they appear in the source. This grouping is called scope. Each reference page in this section documents one scope.

Four scopes apply to metadata tags:

Structural metadata​

Tags that start a new track, staff, or voice: \track, \staff, \voice. Documented in Structural Metadata.

Score metadata​

Song-wide tags that describe the piece — title, artist, tempo defaults, and so on. They belong at the top of the file, above the first bar. Documented in Score Metadata.

Staff metadata​

Tags that configure a single staff — its instrument, tuning, articulation table, and related settings. Documented in Staff Metadata.

Bar metadata​

Tags that apply to a single bar — clef, key signature, time signature, repeats. Documented in Bar Metadata.

Two scopes apply to properties:

Beat property​

A property attached to a beat, controlling effects or annotations that apply to every note in that beat. Documented in Beat Properties.

Note property​

A property attached to a single note, controlling effects specific to that note. Documented in Note Properties.

Signatures and overloads​

Every reference entry lists one or more signatures. A signature is one accepted parameter list for the construct — the parameters it names, their types, and their order. When you write a metadata tag or a property, your argument list must match exactly one of its signatures.

A construct with more than one signature is overloaded. \title, for example, accepts a single string in one signature and a title-plus-template-plus-alignment triple in another. The reference page for each construct shows every signature it accepts.

Case sensitivity​

Metadata tag names, property names, and reserved identifiers such as true, hide, and x are case-insensitive. \Title, \title, and \TITLE all parse the same.

The contents of string literals are case-sensitive. So is the tone letter of a pitched note — C4 and c4 are different notes. Accidentals use the case shown in Pitched notes (#, b, bb, x, ##).

Whitespace​

Whitespace between tokens is not significant. Line breaks, tabs, and runs of spaces all separate tokens equally. Use whitespace freely to lay out your source for readability.

Whitespace is not allowed inside a single value. Fret-note notation must be written as fret.string with no space around the dot, and a pitched-note value must be written as tone-accidental-octave with no space between the parts.

Fret-note notation​

On a stringed instrument, a note is written as fret.string. The number before the dot is the fret. The number after the dot is the string, counted from the highest-pitched string down. String 1 is the top string when you read tab — the thinnest string on a guitar, sounding highest.

5.6      // fret 5 on string 6 (the lowest string on a 6-string guitar)
0.1      // an open note on string 1 (the highest string)
12.3     // fret 12 on string 3

A G-major chord in standard tuning strums six strings at once:

(3.6 2.5 0.4 0.3 0.2 3.1).4

The whole chord is written as a parenthesised beat because six notes ring together. See Argument lists for the parenthesis rules.