earmuff

Bars and the step grid

Mon, 01 Jan 0001 00:00:00 +0000

Bars and the step grid#

A bar lays events on a grid. The grid’s step is the bar’s duration, and the cursor advances exactly one step per token.

bar quarter { C E G _ } // four quarter-note slots
bar 8 { C C C C C C C C } // an eighth-note grid: eight slots

A duration can be a word (whole, half, quarter) or a number (1, 2, 4, 8, 16, 32, 64, 128), with the suffix . for dotted (×1.5) and t for triplet (×2/3).

Introduction

Mon, 01 Jan 0001 00:00:00 +0000

Introduction#

earmuff is a small language for describing music in plain text. You write a project made of tracks and bars; earmuff parses and analyzes the source, then turns it into a Standard MIDI File, live playback through a synth, or engraved sheet music.

Why text#

Music in earmuff is just source code, so the tools you already use apply to it directly:

Diffable — a change to a phrase is a line in a diff, not an opaque binary.
Reviewable — pull requests, comments, and blame work on a song.
Scriptable — generate progressions, transpose, or template arrangements with ordinary code, then compile the result.

Everything in earmuff is resolved at compile time, so a given source always produces the same output — the music is deterministic.

Install

Mon, 01 Jan 0001 00:00:00 +0000

Install#

earmuff is written in Go and requires Go 1.18+.

Binaries#

There are two binaries. Install the compiler/player:

go install github.com/poolpOrg/earmuff/cmd/earmuff@latest

And, for editor support, the language server:

go install github.com/poolpOrg/earmuff/cmd/earmuff-lsp@latest

Both land in $(go env GOPATH)/bin; make sure that directory is on your PATH.

Optional dependencies#

These are only needed for the corresponding features:

Playback — a MIDI synth. earmuff auto-detects one (timidity on Linux, fluidsynth with a SoundFont, etc.). See Command line → Playback for the resolution order and the macOS note.
Sheet music — LilyPond on your PATH, used by the -pdf/-svg/-ly flags. See Sheet music.

Verify it works#

Compile and play one of the bundled examples:

Notes and chords

Mon, 01 Jan 0001 00:00:00 +0000

Notes and chords#

Notes and chords are written by name, directly in musical position — the note/chord keywords are optional.

Notes#

A note is a letter A–G, an optional accidental (# or b), and an optional octave number:

C C# Eb F#3 Cb

Without an octave, a default register is used; an explicit number (C5, F#3, E2) pins the octave.

Chords#

Chords are written by name:

Am7 Gmaj7 C7 Dm7b5 C7/E

Slash chords (C7/E) specify the bass note.

Patterns and control flow

Mon, 01 Jan 0001 00:00:00 +0000

Patterns and control flow#

Patterns and control flow are evaluated at compile time. There is no runtime branching: for, if, let, and pattern calls all run during elaboration over compile-time-known values, so the event stream is fully determined before any MIDI is emitted. Loops are bounded and bindings are immutable, which guarantees termination and keeps the music deterministic and diffable.

Patterns#

A pattern is a named, reusable block. It can take parameters and is invoked with a call:

MIDI and dynamics

Mon, 01 Jan 0001 00:00:00 +0000

MIDI and dynamics#

earmuff exposes the full MIDI set as first-class statements, alongside notes and chords.

Raw events#

program "violin"; // program change (by name or number)
cc 74 = 64; // control change
bend +2; // pitch bend, in semitones
pressure 90; // channel aftertouch
sysex F0 7E 7F 09 01 F7; // raw system-exclusive bytes

These can sit in a step slot or be placed with on beat.

Bend#

bend is expressed in semitones. bend +2 bends two semitones up; the elaborator emits the RPN pitch-bend-range message once per track so the result is correct regardless of the synth’s default range, then the 14-bit value for the requested offset. Escape hatches:

Command line

Mon, 01 Jan 0001 00:00:00 +0000

Command line#

earmuff [flags] source.ear

Flag	Description
`-out file.mid`	write a Standard MIDI File
`-pdf file.pdf`	engrave sheet music as PDF (needs lilypond)
`-svg file.svg`	engrave sheet music as SVG (needs lilypond)
`-ly file.ly`	write the intermediate LilyPond source
`-player <cmd>`	player command template, `{}` = the MIDI file
`-lilypond <path>`	path to the lilypond binary (for `-pdf`/`-svg`)
`-quiet`	suppress the summary and skip playback
`-verbose`	dump the elaborated event stream

With no -out/-pdf/-svg and without -quiet, earmuff plays the piece.

Sheet music

Mon, 01 Jan 0001 00:00:00 +0000

Sheet music#

earmuff can engrave a score from the same source it plays. It emits LilyPond and lets LilyPond do the engraving.

earmuff -pdf song.pdf song.ear # engrave a PDF
earmuff -svg song.svg song.ear # engrave an SVG
earmuff -ly song.ly song.ear # write the intermediate LilyPond source

LilyPond requirement#

-pdf and -svg require LilyPond on your PATH:

brew install lilypond # macOS; use your package manager elsewhere

If LilyPond is installed somewhere unusual, point -lilypond at the binary. -ly writes only the LilyPond source and needs no LilyPond installed, which is useful for inspecting or hand-tweaking the output.

Editor support

Mon, 01 Jan 0001 00:00:00 +0000

Editor support#

Language server#

earmuff-lsp is a language server that works in any LSP-capable editor. It provides:

live diagnostics (from earmuff’s own parser and analyzer, so they match the compiler exactly);
completion;
hover;
go-to-definition;
a document-symbol outline.

Install it with:

go install github.com/poolpOrg/earmuff/cmd/earmuff-lsp@latest

VS Code extension#

The VS Code extension bundles the language server and adds:

syntax highlighting for .ear files (keywords, note/chord literals, durations, dynamics, strings, comments, operators);
a live sheet-music preview that re-renders automatically (debounced) as you type, engraving the unsaved buffer with LilyPond;
commands (from the Command Palette or the editor’s title-bar buttons):
- earmuff: Compile to MIDI — writes <file>.mid next to the source;
- earmuff: Play — streams the piece to a MIDI port;
- earmuff: Show Sheet Preview — opens the live sheet-music preview beside the editor.

The language server is bundled for macOS (arm64/x64), Linux (x64/arm64), and Windows (x64), so editor features need no extra install on those platforms. The compile/play commands invoke the earmuff CLI, which you install separately. The sheet preview needs LilyPond.

Examples

Mon, 01 Jan 0001 00:00:00 +0000

Examples#

The examples/ directory holds complete, compilable pieces. Each one exercises a different corner of the language:

File	Shows
`12bars-blues.ear`	patterns, loops, drums
`minor-swing.ear`	nested loops, comping
`nuages.ear`	syncopation on a fine grid
`lofi.ear`	lists, dynamics, off-beats
`small-jazz.ear`	a small swing arrangement
`bach-prelude.ear`	a classical fragment
`mozart-nachtmusik.ear`	a classical fragment

Compile or play any of them as described in Command line:

earmuff examples/minor-swing.ear
earmuff -pdf nuages.pdf examples/nuages.ear

A taste — the lofi keys part comps off-beat stabs over a list of changes, accenting the second hit of each pair:

Language reference

Mon, 01 Jan 0001 00:00:00 +0000

earmuff language reference#

This is the complete reference for the earmuff language: its surface syntax, the execution model behind it, and the step-grid timing rules. Everything described here is implemented.

Goals (from design discussion)#

Express the entire MIDI set (notes, CC, pitch bend, aftertouch, program change, sysex, per-event channel/port).
Stay developer-friendly and less verbose than v1.
Add functions, patterns, loops.
Be able to interpret and emit MIDI live as the source is processed, not only compile to an SMF file.

Design decisions#

Step-grid is the default note-entry surface. A block sets a default step duration; events auto-advance one step. on beat remains as an explicit escape hatch for absolute placement.
Patterns and functions are pure. Source elaborates deterministically into a flat, time-ordered event stream. User code never touches the clock or the MIDI port — only the scheduler does. Live playback and SMF export consume the same elaborated stream.
Full MIDI now. Raw primitives (cc, bend, pressure, program, sysex, per-event @channel) are first-class, with named sugar over raw numbers.
Structured control flow, evaluated at elaboration time and pure. Real if/else, for x in <range|list|sequence> (or unbound for each …), boolean operators, and immutable let bindings. They run during elaboration over compile-time-known values — they are not live/runtime branches — so the event stream is fully determined before any MIDI is emitted. Loops are bounded (range or list, no while), bindings are immutable: this guarantees termination and keeps music diffable and deterministic.
Domain language, not general-purpose. Values are musical: number, boolean, note, chord, duration, interval, list, and pattern. No mutable state, no strings-as-data arithmetic, no I/O from user code, no recursion/while — no Turing-completeness creep.

1. Execution model#

Two phases, one stream:

Playground

Mon, 01 Jan 0001 00:00:00 +0000