home/ modules/ glicol-debugging-and-performance-craft

Glicol: diagnosing errors and keeping audio alive under pressure

L1Foundations 4h F · Live coding: music 27 atoms

Learning objectives

learner can predict and avoid the five most common Glicol parse errors — unbalanced chevrons, undefined bus references, missing out: line, multiple chains per line, and unknown node names — before they occur
learner can interpret every Glicol TUI error message and restore the last-known-good graph to audio within 30 seconds
learner can route audio chains and reference buses correctly, including the tilde-bus silent-until-referenced rule and the all-non-tilde-lines-go-to-DAC summing model
learner can identify Glicol's limits (no embedded samples, no mini-notation, no music-theory primitives, BPM locked at launch) and work around each without leaving the tool
learner can write and deploy a panic patch that survives offline, gang clipping, and sample-folder absence

Capstone — one whole task that evidences the objectives

Build a three-voice Glicol session from a cold start at a chosen BPM (set with the launch flag, since it cannot change in-file): a percussive hit that fires from an `imp`/`seq` trigger, a pitched melodic line, and a slow pad driven by a `~lfo` bus. Because Glicol has no note names, scales, or chord primitives, hand-code the melodic pitches — either as `seq` integers routed through a `mul` so the pitch ratio becomes real frequency (not the ~1 Hz rumble a raw `seq → sin` produces), or as bare frequencies with explicit decimal points — and lay out the `seq` so top-level spaces divide the bar while adjacent digits subdivide a step. Load one drum sample, demonstrating that it must live in a local `samples/` folder separate from Strudel's dirt-samples, and keep summed gains attenuated so nothing clips (Glicol has no limiter). Confirm every non-`~` line reaches the DAC while the `~lfo` bus stays silent until referenced. Then deliberately introduce each of the five most common parse errors one at a time — unbalanced chevrons, undefined bus reference, missing `out:`/`out` line, two chains on one line, and an unknown node name (including one node that glicol.org documents but the 0.13.5 CLI cannot parse) — observing that the last good graph keeps playing, reading what the TUI reports, and fixing each within 30 seconds. Finish by corrupting the session to silence via an unresolved bus reference, swapping in your panic patch, and narrating what each line does and why it survives sample-folder absence, feedback/gain runaway, and every known parse trap. In a short write-up, name three things Glicol deliberately cannot do (mini-notation/Euclid, music-theory vocabulary, in-file BPM change) and the workaround you used for each.

Glicol’s text-to-graph model is lean and fast to type, but its parser is unforgiving: a single misplaced >>, a missing out: line, or a bus referenced before it is defined will silence the session or leave the old graph frozen. This module teaches you to fail safely — to read what the TUI is telling you, recover in under 30 seconds, and avoid the traps entirely once you know them.

The arc has three phases. Phase one is structural fluency: you learn the five most common parse errors (unbalanced chevrons, undefined bus references, missing out:, multiple chains per line, unknown node names) by introducing them deliberately in a safe scratch file and reading each error report. Phase two is signal-routing: the tilde-bus silent-until-referenced rule and the all-non-tilde-lines-go-to-DAC summing model are not errors but surprises — a ~bus you forget to reference simply does nothing, and two named out: lines sum to double gain. You practice spotting both in code review before running. Phase three is limit navigation: Glicol’s intentional constraints (no embedded sample bank, no mini-notation, no MIDI note names, BPM fixed at launch) are not bugs; knowing them lets you design around them rather than fighting a wall you cannot move.

The seq pitch-ratio misconception is the single most expensive beginner error: seq 60 _ outputs 1.0, not 60 Hz, so connecting it to sin produces an inaudible ~1 Hz rumble. The fix is a mul 261.63 stage or a synth node (sawsynth, bd) that expects a ratio. glicol-seq-spacing-defines-subdivision pairs with this: top-level spaces divide the bar, adjacent digits subdivide a step — misunderstanding the space rule produces the wrong rhythm before any pitch mistake matters.

The capstone requires a panic patch — glicol-panic-patch earns its place as a part-task drill because writing it once is not enough; it needs to be muscle memory. The canonical panic patch is one ~lfo bus and one out: oscillator chain using lpf, no sp nodes, gain kept gentle. It survives sample-folder absence (G1), satisfies the one-out:-per-file rule (G4), uses balanced >> (G2), and defines the bus before referencing it (G3). The simplest possible single-liner is out: sin 110 >> mul 0.2.

The supporting atoms enrich rather than gate: glicol-graph-oriented-paradigm gives the mental model of why these rules exist (named nodes in a directed graph), glicol-lcs-whole-graph-update explains why a valid edit lands smoothly rather than causing a glitch, and glicol-sequencer-pattern-syntax provides the broader pattern vocabulary that seq-pitch-ratio and seq-spacing-defines-subdivision refine.