Solfa Chorale Text Notation Specification

Version 1.0.0

This document serves as the absolute single source of truth for generating, verifying, and editing ASC Tonic Solfa Text Notation (.txt) files. These files are strictly consumed by the Solfa Chorale mobile player and the Solfa Chorale Windows Workbench.

---

1. File Structure

The file MUST begin with a YAML header exactly bounded by ---, followed by musical sections separated by blank lines.


---
title: Stand Up, Stand Up for Jesus
key: Bb
time: 4/4
tempo: 100
---

[Verse 1]
L: Stand up, stand up for Je - sus, ye sol - diers of the cross;
S: s, | d :- .d :m :d | d :- :l, :d | s, :d :r :d | r :- :-
A: s, | m, :- .m, :s, :s, | l, :- :f, :f, | m, :s, :s, :s, | s, :- :-
T: s,, | d, :- .d, :d, :d, | d, :- :d, :l,, | d, :d, :t,, :d, | t,, :- :-
B: s,, | d,, :- .d,, :d,, :m,, | f,, :- :f,, :f,, | m,, :m,, :r,, :d,, | s,, :- :-

1.1 YAML Header

title: String. The display name of the song.
key: String (e.g., C, Bb, F#). Sets the tonal center.
time: String (e.g., 4/4, 3/4, 6/8). Controls rendering and logical beat groupings.
tempo: Integer (Optional, default ~100). The playback speed in BPM.

1.2 Track Identifiers

Each musical phrase is grouped into blocks containing:

L: - Lyrics line (must represent exactly one complete phrase). To define multiple repeating stanzas, use sequentially numbered tracks instead (e.g., L1:, L2:, L3:).
S: - Soprano part notes.
A: - Alto part notes.
T: - Tenor part notes.
B: - Bass part notes.

*(Note: While SATB is standard, parts are fully flexible. Any voice not listed simply will not render.)*

---

2. Note & Pitch Formatting

2.1 Basic Pitches

Standard diatonic degrees: d, r, m, f, s, l, t. (Always lower case).

2.2 Chromatic Pitches

Accidentals change the vowel sound.

Sharps (Raised): de, ri, fe, se, le.
Flats (Lowered): ra, me, fe (contextual flat/sharp mapping), lo, ta.

2.3 Octave Modifiers

Standard solfa defines octaves visually, but this ASCII format uses suffixes to support standard typography engines automatically:

Middle Octave: No suffix (e.g., d).
Lower Octave: Add commas , (e.g., d, for 1 octave down, s,, for 2 octaves down).
Upper Octave: Add apostrophes ' (e.g., d' for 1 octave up, m'' for 2 octaves up).

2.4 Modulations (Key Changes)

Traditional Tonic Solfa uses letters like G.t. or f.C. to indicate structural key modulations mid-measure. Because an AI cannot reliably calculate absolute pitch transpositions automatically from these markers, you must substitute them with absolute key tags strictly formatted as [Key=X] (where X is the new key).

Place the tag directly before the modulated note: S: m :f :[Key=G]d | r :-
CRITICAL: Because tracks are rendered entirely independently, if a modulation occurs on Beat 3, you MUST inject [Key=X] at Beat 3 in the S:, A:, T:, and B: tracks so their harmonies modulate simultaneously.

2.5 Rests and Holds

- or — (dash or em-dash) extends the duration of the previous valid note.
If a - appears at the start of a beat with no preceding note to tie to, it acts as a Rest.

---

3. Rhythm & Duration Formatting

3.1 Structural Delimiters

| (Pipe): Measure boundary (Bar line). Only used for visual organization.
: (Colon): Beat boundary. Used to separate primary absolute beats.

3.2 Sub-Beats (Dots)

To fit multiple notes inside a single beat, use a . (dot) between them.

Example: d.r divides the beat into two half-beats.
Example: d.-.r divides the beat into thirds, where d holds for 2/3 and r triggers on 1/3.

3.3 Tied Durations

A note's duration expands by crossing beat boundaries using -.

Example: d :- .d

- Beat 1 contains d.

- Beat 2 contains -.d.

- The - extends the preceding d by 0.5 beats. The .d represents a new note played for the remaining 0.5 beats. The first d totals 1.5 beats (a dotted quarter note).

*(Important: The engine calculates logical duration mathematically. Do not place spaces between connected sub-beats like -.d.)*

---

4. Special Musical Articulations

4.1 Melismas (Slurs)

When a single lyric syllable or vowel stretches across multiple different pitches (a melisma), enclose the structural run of notes in underscores _ _.

Example: _d :- :t,_

The d consumes the active lyric syllable exactly as expected.
The t, is flagged internally by the parser as isMelismatic: true, which commands the lyric rendering interface to pause and skip syllable consumption.
Without underscores, t, would blindly consume the next lyric word, permanently knocking the entire song out of synchronization!
Ensure you balance the underscores within the same line, just like you would parentheses!

4.2 Grace Notes

An ornamental appoggiatura or acciaccatura (grace note) relies on brackets ( ).

Place the grace note pitch inside the parenthesis, bonded directly to the principal note.

Example: (d)f or (m,)r'

The engine will insert the grace note pitch mathematically independent of the overall measure duration, playing it fleetingly just before the principal pitch!

4.3 Fermatas (Holds)

Add a carat ^ directly to a note to indicate an open-ended fermata (pause/hold).

Example: d^ or r,^.

---

5. Lyric Formatting

Syllables must perfectly map mathematically to non-hold, non-melismatic notes.

Use hyphens - with spaces to separate syllables of the same word (e.g., Je - sus).
Ensure punctuation attaches directly to the word (e.g., sus, or cross;).
Multi-Stanza Definitions: You can define multiple stanza loop lines by prefixing them numerically (e.g., L1:, L2:). The playback engine will dynamically swap text out each time the sequencer hits the end of a section and repeats. Supplying a bare L: simply implicitly forces a maximum stanza count of 1.
Visual Bar Lines: You may freely use vertical pipes | inside the L:/L[N]: lyrics track to visually align text with the musical measures below it. The parser securely ignores all | delimiters in the lyric line, treating them as structural white space.
Do not use underscores to represent empty space strings for matching; rely on the _ _ slur syntax applied to the voice parts explicitly as it gracefully handles lyric alignment.