Syntax Reference

Complete syntax specification for the Notations DSL

Basic Elements

Literals (Notes and Syllables)

Literals are text tokens without spaces. Any text can be used as a literal:

S R G M P D N sa ri ga ma pa dha ni do re mi fa so la ti

The notation system doesn't assign meaning to literals - only durations and layout matter.

Octaves

Dots indicate octaves. Place dots before a note for lower octaves, after for higher octaves (no spaces):

Syntax	Octave
`...S`	Three octaves below
`..S`	Two octaves below
`.S`	One octave below
`S`	Middle octave (default)
`S.`	One octave above
`S..`	Two octaves above
`S...`	Three octaves above

..S .S S S. S..

Whitespace

Spaces and line breaks between notes are ignored by the parser. They don't affect timing or layout:

S R G M S R G M

Both lines produce identical output.

Bar Separators

A | or || inside a role line is ignored the same way whitespace is, so you can mark avartanam boundaries in the source if you find them easier to read. The renderer draws its own lines from the cycle either way, one at the end of each bar and a double line at the end of the avartanam, so a bar you type is never what you see:

\cycle("|4|2|2|") Sw: S R G M | P D | N S. ||

Because they are ignored rather than checked, a bar in the wrong place is not an error. The | characters inside \cycle("|4|2|2|") are a different thing entirely, since that argument is a quoted string and the bars in it define the cycle.

Spaces (Karvais)

Spaces represent empty durations where the previous note continues. Use commas:

Symbol	Name	Duration
`,`	Space (Karvai)	1 unit
`;`	Double space	2 units
`_`	Silent space	1 unit (not displayed)

S , R ; G , , M

Silent spaces consume duration without displaying the space symbol, to avoid clutter. Only a standalone _ counts as one, so write _ _ _ for three. A run such as ___ is an ordinary literal, as is an underscore inside a word.

Rests

Use hyphen for an explicit rest (no note continuation):

S - R - - G

Groups

Square brackets group multiple notes into a single beat:

S [R G] M [P D N] S.

Groups can be nested:

S [R [G M] P] D

Note Durations

Prefix a note with a number or fraction to set its duration:

\beatDuration(4) S 2 R G 3 M

Fractional durations are also supported:

\beatDuration(4) S 3/2 R G 1/2 M

Roles

Roles represent different types of content. Use a role selector with a colon (no space before colon):

Sw: S R G M P D N S. Sh: sa ri ga ma pa dha ni sa

Common roles:

Sw - Swaras (notes)
Sh - Sahitya (lyrics)

Create custom roles with the \role command.

Commands

Commands start with a backslash and control notation behavior:

\commandName(param1, param2, key=value)

See the Commands Reference for details.

Embellishments

Embellishments start with a tilde and continue until whitespace:

S ~ R G ~/ M

See the Embellishments Reference for details.

Markers

Markers are annotations that don't participate in timing. They use the \@markerName(params) syntax:

\@label("V1") S R G M P D N S. \@label("V2") S. N D P M G R S

Marker Parameters

Parameter	Type	Default	Description
(first positional)	string	-	The text/label
`position`	"before" \| "after"	"before"	Where to render

Position

Use position="after" to place a marker after a note:

S R G M \@label("End", position="after") P D N S.

Per-Role Markers

Markers are per-role, not per-line. Each role can have its own markers independently:

Sw: \@label("V1") S R G M P D N S. Sh: sa ri ga ma pa dha ni sa

Comments

Use // for line comments. Everything from the // to the end of the line is skipped, whether it starts the line or trails the notation on it:

// This is a comment S R G M P D N S. // and this one trails the notation

Block comments work the same way and can span lines:

/* This is a multi-line comment */ S R G M

Grammar Summary

notation      := elements
elements      := (command | roleSelector | atoms)*
command       := "\\" name "(" params? ")"
roleSelector  := name ":"
atoms         := atom+
atom          := duration? leaf
leaf          := literal | group | space | rest | marker
literal       := (dots? ident dots?) embellishment?
group         := "[" atoms "]"
space         := "," | ";" | "_"
rest          := "-"
marker        := "\@" name "(" params ")"
duration      := number | fraction
fraction      := number "/" number
octave        := "."+ (before or after literal)
embellishment := "~" text