Language Basics

This guide covers the core building blocks of Gen: notes, rhythms, octaves, accidentals, and rests.

Document Structure

A Gen file has two parts: optional YAML metadata, followed by music where each line is a measure.

---
title: My Song
composer: Me
time-signature: 4/4
key-signature: G
tempo: 120
---

G A B ^C
^D ^E ^F# ^G

See Metadata Reference for all available fields.

Note Anatomy

^Ab/
│││└─ Rhythm: / = eighth note
││└── Accidental: b = flat
│└─── Note name: A
└──── Octave: ^ = one octave up

Format: [octave][note][accidental][rhythm]

Only the note name is required. Everything else is optional.

Notes

The seven note names:

Note	Name
C	C
D	D
E	E
F	F
G	G
A	A
B	B

Rests

Use $ for rests:

C D $ F      # Quarter rest on beat 3
C $/ $/ D    # Two eighth rests
$o           # Whole rest

Rests accept rhythm modifiers but not pitch modifiers.

Rhythm Modifiers

Placed at the end of a note:

Modifier	Duration	Divisions
(none)	Quarter note	1 beat
p	Half note	2 beats
o	Whole note	4 beats
/	Eighth note	½ beat
//	Sixteenth note	¼ beat
///	32nd note	⅛ beat

Dotted Notes

Add * after the rhythm modifier to dot the note (adds 50% duration):

Example	Duration
C*	Dotted quarter (1.5 beats)
Cp*	Dotted half (3 beats)
C/*	Dotted eighth (0.75 beats)
Co*	Dotted whole (6 beats)

Accidentals

Placed after the note name:

Modifier	Result
#	Sharp
b	Flat
%	Natural (force)

F#     # F sharp
Bb     # B flat
F%     # F natural (overrides key signature)

Key Signatures and Accidentals

When you set a key signature, notes automatically follow it:

---
key-signature: G    # One sharp (F#)
---

F G A B    # The F is automatically F#
Fb G A B   # Explicit Fb to get F natural

Use % to force a natural when the key signature would otherwise apply an accidental:

---
key-signature: F    # One flat (Bb)
---

B C D E    # The B is automatically Bb
B% C D E   # Force B natural with %

Octaves

The Octave System

Gen uses an absolute octave system centered on middle C:

Modifier	Octave	Range
__	2	Two octaves below middle
_	3	One octave below middle
(none)	4	Middle octave (contains middle C)
^	5	One octave above middle
^^	6	Two octaves above middle

Octave Boundaries

The octave always resets at C, regardless of key signature:

• Base octave: C D E F G A B
• Next octave up: ^C ^D ^E ^F ^G ^A ^B

This means going from B to the next C up requires changing octave:

G A B ^C ^D    # Ascending through the break
^D ^C B A G    # Descending through the break

Common Patterns

# Scale going up
C D E F G A B ^C

# Scale going down
^C B A G F E D C

# Arpeggio spanning octaves
C E G ^C ^E ^G ^^C

# Low melody
_G _A _B C D E F G

Octave Examples

Example	Note	Octave
C	Middle C	4
^C	C above middle	5
_C	C below middle	3
^^G	G two octaves up	6
__D	D two octaves down	2

Putting It Together

Here’s how all the elements combine:

---
title: Example
time-signature: 4/4
key-signature: G
---

G A B ^C              # Quarter notes, ascending
^D/ ^E/ ^F#/ ^G/      # Eighth notes
^G ^F# ^E ^D          # Quarter notes, descending
^C* B/ Gp             # Dotted quarter, eighth, half

Key Signature Reference

Major Keys

Key	Sharps/Flats
C	None
G	1 sharp (F#)
D	2 sharps (F#, C#)
A	3 sharps (F#, C#, G#)
E	4 sharps
B	5 sharps
F#	6 sharps
F	1 flat (Bb)
Bb	2 flats (Bb, Eb)
Eb	3 flats
Ab	4 flats
Db	5 flats
Gb	6 flats

Minor Keys

Add m suffix for minor keys:

Key	Sharps/Flats	Relative Major
Am	None	C
Em	1 sharp	G
Bm	2 sharps	D
F#m	3 sharps	A
Dm	1 flat	F
Gm	2 flats	Bb
Cm	3 flats	Eb

By Sharp/Flat Count

Notation	Meaning
#	1 sharp
##	2 sharps
###	3 sharps
bb	2 flats
bbb	3 flats

Key Changes

Change key mid-piece with @key::

---
key-signature: C
---

C D E F              # C major
@key:G G A B ^C      # Now G major (F#)
@key:F F G A Bb      # Now F major (Bb)

Next Steps

• Chords — Simultaneous notes and chord symbols
• Groups — Bracket groups, tuplets, ties, and slurs
• Multi-Part — Writing for multiple instruments