Skip to main content

Bird Notation

Bird is a musical notation designed for composition of modern electronic music. Think of it as Markdown for music.

File Structure

A .bird file has these sections, in order:
  1. Signature — set BPM, key, and scale
  2. Global track definitions — declare tracks with their instruments, effects, and channel strips
  3. Motif definitions (optional) — reusable MIDI pattern fragments
  4. Arrangement — define the section order and bar counts
  5. Section definitions — write the musical content for each section
# 1. Signature
sig
  bpm 128
  scale A aeolian

# 2. Global track definitions
tracks
  1 kick
    plugin kick
    strip console1

  2 bass
    plugin mini
    fx delay

  3 lead
    plugin jup8

# 3. Arrangement
arr
  intro 4
  verse 8
  chorus 8

# 4. Section definitions
sec intro
  trk 1 kick
    p x _ x _ x _ x _
    v 100 - 80 - 90 - 85 -
    n C1

sec verse
  trk 2 bass
    p q q q q
    v 90 70 80 60
    n C2 - Eb2 G2
[!NOTE] The older ch and channels keywords are still accepted by the parser for backward compatibility, but new files should use trk and tracks.

Motif Definitions

Motifs are reusable MIDI pattern fragments defined at the top level of a bird file. They appear between track definitions and the arrangement. A motif is a named PatternGroup — it supports the full pattern vocabulary (p/v/n/t/sw/MPE/voice layers).
motif bass_lick 2
  p q q q q
  v 100 80 90 70
  n Eb2 Gb2 Ab2 Bb2

motif fill 1
  p xx xx xx xx
  v 80 60 70 50
  n C3 D3 Eb3 F3

motif chord_stab 1
  p x _ x _x _ x _
  v 80 . 70 60 . 90 .
  n C4
  .
  v 60
  n +3
  .
  v 40
  n +7
The header is motif <name> <length_beats>. The body uses the same 2-space indent as sections and tracks. All pattern features work inside motifs: bracket subdivisions, euclidean rhythms, dotted/triplet durations, voice layers, MPE, swing, groove.

Motif Operations

When referencing a motif with @name(ops), operations are applied left to right, comma-separated:
OperationSyntaxDescription
transposetranspose 7Shift all pitches by N semitones
octaveoctave -1Transpose by whole octaves
invertinvert 60Mirror pitches around pivot (default 60)
rev / reverserevReverse note order in time
stretchstretch 0.5Scale durations by factor
rotaterotate 2Cyclic pitch rotation
constrainconstrain 0 2 4 5 7 9 11Snap to scale pitch classes
harmonizeharmonize 3 7Add parallel voices at intervals
shift_velshift_vel -20Shift all velocities
scale_velscale_vel 0.8Multiply all velocities
quantizequantize 0.25Snap note starts to grid
humanizehumanize 0.05Add timing/velocity jitter
swingswing 0.6 0.5Apply swing (amount, grid)
legatolegatoExtend notes to next note start
staccatostaccato 0.5Shorten notes by factor
phasephase 0.5Time-rotate within length
degradedegrade 0.3Randomly remove 30% of notes
thinthin 2Keep every Nth note
truncatetruncate 2Cut to first N beats
repeatrepeat 2Repeat the pattern N times
offsetoffset 0.5Shift all notes forward
# Chained transforms
p @bass_lick(rev, transpose 7, stretch 0.5)

# Motif with multiple operations
p @fill(degrade 0.3, humanize 0.02)

Tokens Reference

Structure

TokenPurposeSyntaxExample
sigStart signature blocksig then indented entriessee above
tracksStart tracks blocktracks then indented entriessee above
trkDefine a track (in sections)trk <number> <name>trk 1 kick
pluginAssign instrument pluginplugin <keyword>plugin mini
fxAssign insert effectfx <keyword>fx delay
stripAssign channel stripstrip <keyword>strip console1
typeSet track typetype midi or type audiotype audio
arrStart arrangement blockarr then indented entriessee below
secStart section definitionsec <name>sec verse
bSet global bar countb <bars>b 4
keySet key signaturekey <root> [mode]key Eb min
contContinue pattern phase across section boundarycontcont

Arrangement

The arr block lists sections with their bar lengths, indented:
arr
  intro 4
  verse 8
  chorus 8
  verse 8
  chorus 8
  outro 4

Key Signature

Sets the musical key for the project. Supports all 12 roots with sharps/flats, major and minor:
key C            # C major
key Eb min       # Eb minor
key F# minor     # F# minor
key Bb           # Bb major

Pattern (p)

Defines the rhythmic grid. Each token is one note slot. Positive = note-on, _ = rest.

Duration Tokens

TokenDurationTicks
wwDouble whole note768
wWhole note (1 bar in 4/4)384
qqHalf note192
qQuarter note (1 beat)96
xxEighth note48
xSixteenth note24
sThirty-second note12
ssSixty-fourth note6
Dotted (1.5× duration) — append . or d:
TokenAliasDurationTicks
w.wdDotted whole576
q.qdDotted quarter144
xx.xxdDotted eighth72
x.xdDotted sixteenth36
s.sdDotted thirty-second18
Double dotted: q.. = 1.75 beats (qdd). Triplet (⅔× duration) — append , or t:
TokenAliasDurationTicks
w,wtWhole triplet256
q,qtQuarter triplet64
xx,xxtEighth triplet32
x,xtSixteenth triplet16
s,stThirty-second triplet8

Rests

  • . or _ — rest of the same length as the previous duration
  • _w, _q, _x, _xx, _s, _ss etc. — explicit rest durations (same naming as above, prefixed with _)
Note: . as a standalone token (space-separated) means rest. . immediately after a duration letter (no space) means dotted: q. = dotted quarter (1.5 beats), q . = quarter then rest.

Duration Multiplier

Append a number to any duration token to multiply its length. Works for both note-ons and rests:
TokenMeaningTicks
w4Whole note × 4 = 4 bars1536
q2Quarter note × 2 = half note192
_w88 bars of rest3072
_q44 beats of rest384
qd2Dotted quarter × 2288
This is useful for held notes that span multiple bars, or for compactly expressing long rests:
p w4 _w8              # 4-bar held note, then 8 bars of silence
p q2 _q q _q q _q     # half note, then alternating quarter rests and quarter notes

Timing Rule

All p lines in a section must sum to the same total bar length. A 4/4 bar = 384 ticks = 4 quarters = 8 eighths = 16 sixteenths. Mismatched lengths cause desync.

Examples

p q q q q          # 4 quarter notes = 1 bar
p x x x x x x x x x x x x x x x x   # 16 sixteenths = 1 bar
p qq . qq .        # half note, rest, half note, rest = 1 bar
p q . q q          # quarter, rest, quarter, quarter
p q. xx q q        # dotted quarter + eighth + two quarters = 1 bar
p q, q, q,         # three quarter-note triplets = 2 beats

Ties

Combine durations with ~ (tilde) to express held notes that span standard note values — just like ties in sheet music:
p w~q          # whole tied to quarter = 5 beats
p w~qq         # whole tied to half = 6 beats
p qq~q         # half tied to quarter = 3 beats
p w~w          # 2 bars tied
p w~q~xx       # whole + quarter + eighth = 5.5 beats
p _w~q         # 5-beat rest
Ties are more musical than multipliers for note-on durations. Both can coexist — ties for composition, multipliers for mechanical rests.

Tuplets (Bracket Subdivision)

Divide any duration into N equal parts using bracket notation. Inside brackets, - (or x) marks a hit, . (or _) marks a rest:
# 5 notes in a quarter note (quintuplet)
p q[- - . - -] q q q
  v [80 70 . 60 50] 100 80 80
  n C2 [D2 E2 . G2 A2] C2 C2

# 7 notes evenly spaced within 1 quarter note
p q q[- - - - - - -] q q
  v 100 [80 90 100 90 80 70 60] 100 80

# 5 notes in a half note (quintuplet)
p qq[- - - - -] qq
  v [100 90 80 70 60] 80

# Nested: quarter split into 3, middle part split into 4
p q[- [- - - -] -] q q q
  v [60 [50 40 30 20] 80] 100 80 80

# Rests inside brackets
p q[- - . - -] q q q     # hit, hit, rest, hit, hit
p q[- . - . -] q q q     # alternating hit/rest
Brackets on v, n, and t lines are visual grouping only — the parser strips them. They keep tuplet values visually aligned with the p line.

Euclidean Rhythms

Distribute K hits evenly across N slots using the Bjorklund algorithm. Syntax: duration(k,n) or duration(k,n,r) where r is an optional rotation offset:
p q(3,8)               # quarter note: 3 hits in 8 slots (Bjorklund)
p w(5,16)              # whole bar: 5 hits in 16 slots
p w(3,8,1)             # with rotation: shift pattern 1 position right
p q q(3,8) q q         # mix euclidean with regular durations
The duration token sets the total time span. Each slot gets duration / n beats. Hits and rests are distributed as evenly as possible by the Bjorklund algorithm.

Motif References

Reference a named motif as a pattern token. The motif occupies its length_beats on the timeline and brings its own notes, velocities, and timing:
# Simple stamp
p @verse_bass @verse_bass(transpose 5)

# Mixed with regular pattern
p q q @fill(rev) q
  v 100 80 90 70         # values cycle through non-motif slots only
  n Eb2 Gb2 Ab2 Bb2

# After rests
p w . @bass_lick w

# Chained transforms
p @bass(rev, transpose 7, stretch 0.5)
Optional ... on v/n lines for visual alignment (no-op, purely cosmetic):
p q @bass_lick q q
  v 80 ... 90 70
  n Eb2 ... Ab2 Bb2

Velocity (v)

Sets the MIDI velocity (0–127) for each note slot. Cycles through values when the pattern repeats.
SyntaxMeaningExample
80Absolute velocityv 80
.Default velocity (80)v . 100 . 100
-Repeat previous velocityv 100 - 60 - → 100, 100, 60, 60
+N / -NRelative offset from previousv 80 +10 -20
Values are clamped to 0–127. The velocity list cycles independently of the pattern length. Omitting the v line entirely also yields velocity 80 — the same value . produces.
v 100 60 80 40      # cycling 4 velocities
v 90 -               # alternating: 90, 90, 90, ...
v 80 +10 +10 -30    # 80, 90, 100, 70, 80, 90, ...

Notes (n)

Specifies pitches for each pattern slot. Supports multiple formats that can be mixed.

Formats

FormatExampleDescription
MIDI numbern 60Middle C
Note namen C4Middle C (with octave)
Chord namen @Cm7C minor 7th chord (all notes play simultaneously)
Repeatn 60 -Repeat previous pitch
Relative offsetn 60 +7 +5Add/subtract semitones from previous
Simultaneous notesn 60 64 67All on one line = chord (C major triad)

Note Names

Standard note names with optional accidentals and octave:
C4  D4  E4  F4  G4  A4  B4     # naturals
C#4 D#4 F#4 G#4 A#4            # sharps
Db4 Eb4 Gb4 Ab4 Bb4            # flats
Octave 4 starts at MIDI 60 (Middle C). Omitting octave defaults to 4.

Chord Names

Prefix with @. Optionally prefix octave before root letter.
ChordSyntaxNotes
Major@C, @Cmaj, @CMC E G
Minor@Cm, @Cmin, @C-C Eb G
Dominant 7th@C7, @Cdom7C E G Bb
Major 7th@Cmaj7, @CM7C E G B
Minor 7th@Cm7, @Cmin7, @C-7C Eb G Bb
Diminished@Cdim, @CoC Eb Gb
Diminished 7th@Cdim7, @Co7C Eb Gb A
Half-diminished@Cm7b5, @CøC Eb Gb Bb
Augmented@Caug, @C+C E G#
Augmented 7th@Caug7, @C+7C E G# Bb
Suspended 2nd@Csus2C D G
Suspended 4th@Csus4, @CsusC F G
Dominant 9th@C9C E G Bb D
Minor 9th@Cm9, @Cmin9C Eb G Bb D
Major 9th@Cmaj9, @CM9C E G B D
Power chord@C5, @CpowerC G
Octave prefix: @3Cm7 = C minor 7th starting at octave 3.

Simultaneous Notes (Chords)

Multiple plain notes on one n line play simultaneously as a chord:
n 41 48 53 56       # MIDI numbers = chord
n E2 C3 F3 Ab3      # note names = chord

Bracket Chords (Explicit Voicings)

Use [note note note] on an n line for per-step chord voicings. Each bracketed group counts as one note step that cycles with the pattern:
p q q q q
  n [C4 Eb4 G4] [F4 Ab4 C5] C4 [G4 B4 D5]
  # step 1: C minor triad
  # step 2: F minor (1st inv)
  # step 3: single C4
  # step 4: G major

# Mix bracket chords with named chords
p w w
  n @Cm7 [F4 Ab4 C5 Eb5]

Sequential Notes

When using -, +N, or @chords, each token is a separate step that cycles with the pattern:
n C4 - Eb4 G4       # step 1: C4, step 2: C4, step 3: Eb4, step 4: G4
n 60 +7 +5 -12      # step 1: 60, step 2: 67, step 3: 72, step 4: 60
n @Cm7 @Fm7 @G7     # step 1: Cm7 chord, step 2: Fm7, step 3: G7

Layering

Multiple velocity + note groups can share one pattern (multi-layer voicings):
p w _ w _
  v 70 90 100
    n @Cm7 @Fm7 @G7
  v 60
    n +7 +7 +8        # second layer at different velocity
  v 30
    n +12              # third layer (higher octave, soft)

Swing (sw)

Adds groove by shifting every other note later. Applied per channel per section.
sw <percent> [~<humanize>]
ValueFeel
50Perfectly straight (default)
55Light swing
60Medium swing
67Triplet swing (classic MPC feel)
75Heavy swing
The optional ~N adds random ±N ticks of jitter to all notes for extra humanization.
sw 60           # medium swing
sw 67 ~5        # triplet swing + ±5 tick humanize
sw 50 ~3        # straight timing + slight random jitter

Per-Note Timing (t)

Fine-grained timing offsets per pattern slot. Values are in ticks (1 tick ≈ 1/96 of a beat). Cycles like velocity.
t <start[/end]> <start[/end]> ...
  • Start offset — shifts the note-on position:
    • Positive = late (behind the beat / laid back)
    • Negative = early (ahead of the beat / pushing)
    • 0 = on grid
  • End offset (optional, after /) — adjusts the note-off (release) by N ticks:
    • Positive = longer held note
    • Negative = shorter (more staccato)
    • Defaults to 0 if omitted
# Start offsets only (backward compatible)
t 0  +5 -3  0       # C4 on grid, Eb4 late, G4 early, Bb4 on grid

# Start and end offsets
t 0/0  +5/-3  -3/+10  0/0   # Eb4 starts late and releases early, G4 starts early and holds 10 ticks longer
One tick = 1/24 of a sixteenth note = 1/96 of a quarter note.

CC Curves (cc)

Define MIDI continuous controller curves. Supports both multi-line (preferred) and single-line (legacy) formats.

Multi-line format (preferred)

Uses the same position/value/shape sub-lines as auto blocks:
cc <number>
  .  <bar:tick> <bar:tick> ...     # positions
  _  <value> <value> ...           # CC values (0–127)
  ~  <shape> <shape> ...           # curve shapes
# Filter cutoff (CC 74): sweep up then step back down
cc 74
  .  0:0 2:0 4:0 6:0
  _  0 64 127 0
  ~  lin exp stp lin

Single-line format (legacy, still supported)

cc <number> <value> [shape duration] <value> ...
cc 1 0 ramp q2 127 hold q ramp q 0
cc 74 20 ramp w4 127

Pitch Bend (pb)

Same multi-line format as cc but without a controller number. Values range from -8191 to +8191.
pb
  .  0:0 2:0
  _  0 8192
  ~  lin
Legacy single-line: pb 0 ramp q2 8191 ramp q2 0

Aftertouch (at)

Channel aftertouch (key pressure). Same format as pb. Values 0–127.
at
  .  0:0 2:0 4:0
  _  0 90 0
  ~  lin lin
Legacy single-line: at 0 ramp q2 90 hold q ramp q 0

Automation (auto)

Define automation curves using breakpoints with positions, values, and interpolation shapes. Each block has a header line and up to three sub-lines:
auto <param_name>
  .  <bar:tick> <bar:tick> ...     # positions (beat grid)
  _  <value> <value> ...           # values (normalized 0.0–1.0)
  ~  <shape> <shape> ...           # curve shape per segment

Sub-Lines

PrefixPurposeExample
.Positions — beat locations in bar:tick format (96 ticks per beat). 0:0 4:0 8:0
_Values — parameter values at each position (0.0–1.0 normalized)_ 0.2 0.8 1.0
~Shapes — interpolation curve from this point to the next~ lin exp smt

Shape Keywords

ShapeInterpolation
linLinear (straight line between points)
expExponential (fast start, slow end)
logLogarithmic (slow start, fast end)
stpStep/hold (constant until next point)
smtSmooth (cubic Hermite interpolation)

Examples

# Filter cutoff: sweep up over 4 bars with exponential curve
auto cutoff
  .  0:0 4:0 8:0 12:0
  _  0.2 0.8 0.3 1.0
  ~  lin exp stp smt

# Multiple automation blocks on one track
auto cutoff
  .  0:0 4:0
  _  0.2 0.8
  ~  lin exp
auto resonance
  .  0:0 8:0
  _  0.5 1.0
  ~  stp smt
Sub-lines are optional — you can provide just positions and values without shapes (defaults to linear), or just a header with no sub-lines.

Automation Macro Names

Semantic macro names are mapped to real plugin parameter names automatically:
MacroControls
brightness / cutoffFilter cutoff frequency
resonanceFilter resonance
attackAmp/filter attack time
decayAmp/filter decay time
releaseAmp/filter release time
pitchOscillator/sound pitch
driveDistortion/harmonics amount
mixWet/dry mix
widthStereo width

Plugin Keywords

Instruments

KeywordPluginType
synthsPigmentsGeneral synth
miniMini V3Analog mono synth
cs80CS-80 V4Poly synth
prophetProphet-5 VPoly synth
jup8Jup-8 V4Poly synth
dx7DX7 VFM synth
buchlaBuchla Easel VWest coast
surgeSurge XTOpen source synth
kickKick 3Kick drum synth
drumsHeartbeatDrum machine
bassMini V3Bass (uses Mini V)
sublabSubLabXLSub bass
monomentMonoment BassBass synth

Effects

KeywordPlugin
delayTube Delay
valhallaValhallaRoom
widenerSoftube Widener
soothesoothe2
tubeDist TUBE-CULTURE

Channel Strips

KeywordPlugin
console1Console 1

Automation Macro Names

Semantic macro names are mapped to real plugin parameter names automatically. Use these in step or ramp automation.

Synth Macros

MacroControls
brightness / cutoffFilter cutoff frequency
resonanceFilter resonance
attackAmp/filter attack time
decayAmp/filter decay time
releaseAmp/filter release time

Drum/Bass Macros

MacroControls
pitchOscillator/sound pitch
decaySound decay time
volumeOutput level
driveDistortion/harmonics amount

Effect Macros

MacroControls
mixWet/dry mix
decayReverb decay / delay feedback
widthStereo width

Channel Strip Macros (Console 1)

MacroControls
input_gainInput gain
comp_threshCompressor threshold
comp_ratioCompressor ratio
eq_mid_gainEQ mid band gain
low_cutHigh-pass filter

cont — Pattern Continuity

Use cont in a section to continue a channel’s pattern phase from the previous section (rather than restarting from beat 1):
sec verse
  trk 1 arp
    cont
    p x x x x x x x x
    v 80 60 70 50
    n C4 E4 G4 C5
Without cont, each section resets the pattern/note/velocity counters to 0. With cont, the counters pick up where the previous section left off, creating seamless transitions.

Track Types

TypeDescription
midiMIDI track (default) — plays notes through instrument plugin
audioAudio track — plays audio samples or Lyria-generated audio
trk 4 pad
  type audio

Complete Example

sig
  bpm 120
  key Eb min

tracks
  1 kick
    plugin kick
    strip console1

  2 hihat
    plugin drums

  3 bass
    plugin mini
    fx delay

  4 chords
    plugin jup8
    strip console1

arr
  intro 4
  verse 8
  chorus 8

sec intro
  trk 1 kick
    p q _ q _
    v 100 - 80 -
    n C1

  trk 2 hihat
    sw 60
    p x x x x x x x x x x x x x x x x
    v 60 40 80 40 60 40 80 40 60 40 80 40 60 40 80 40
    n F#2

sec verse
  trk 1 kick
    p q _ q q
    v 110 - 90 100
    n C1

  trk 2 hihat
    sw 60 ~3
    p x x x x x x x x x x x x x x x x
    v 70 40 90 40 70 40 90 50 70 40 90 40 70 40 90 50
    n F#2
    t 0 +3 -2 0 +1 +4 -1 0 0 +2 -3 0 +1 +3 -2 0

  trk 3 bass
    p xx xx _ xx xx xx _ xx
    v 100 80 - 90 85 100 - 70
    n Eb2 - - Gb2 Ab2 Bb2 - Eb2
    brightness ramp 0.3 0.8

  trk 4 chords
    p w _ w _
    v 70
    n @Ebm7 - @Abm7 @Bb7

sec chorus
  trk 1 kick
    p q q q q
    v 120
    n C1

  trk 3 bass
    cont
    p xx xx xx xx xx xx _ xx
    v 110 90 100 80 110 90 - 70
    n Eb2 Gb2 Ab2 Bb2 Eb3 Bb2 - Gb2

  trk 4 chords
    p qq qq qq qq
    v 85 75 90 80
    n @Ebm7 @Abm7 @Bb7 @Gbmaj7

Tick Reference

All timing in Bird is based on a 384-tick bar (96 ticks per beat in 4/4):
UnitTicks
Whole note (bar)384
Half note192
Quarter note (beat)96
Eighth note48
Sixteenth note24
One t tick1
The sw and t timing features operate in this tick space.