home/ modules/ debugging-and-recovery-in-punctual

Punctual: diagnosing silent failures and recovering live

L5Voice 4h H · Creative coding & live-coded visuals F · Live coding: music 22 atoms

Learning objectives

learner can identify and fix the five most common silent-failure patterns in Punctual — missing output operator, wrong-domain function, combinatorial vs pairwise list confusion, feedback gain at or above 1, and deprecated 0.4 output operators — without seeing an error message
learner can distinguish Punctual's three arrow operators (`<<`, `>>`, `<>`) and use each correctly, including `<> 0` for near-immediate switching and `<> n` for smooth crossfades
learner can reason about Punctual's cycle-quantized evaluation model — changes land at the next boundary by default, `lo/mid/hi` require a running audio statement, `cps` is fixed standalone, and parse errors preserve the previous program
learner can write and evaluate a bounded panic recovery program from memory — a self-analysing drone with non-zero-base colour and a short crossfade — and name the environment (URL or Estuary) where Punctual actually runs

Capstone — one whole task that evidences the objectives

Take a deliberately seeded Punctual file that contains at least nine faults — a statement with no output operator, a wrong-domain function (`lpf` in a visual chain), a square-bracket list where curly braces are needed, a feedback expression with gain >= 1, a deprecated 0.4 output operator (`>> video`), a `lo` read with no audio source running, a pre-0.5 `sin 440` used as a tone oscillator, a `$`/`&` application-order mistake that silently reorders the graph, and a `voronoi`/coherent-noise call for a primitive Punctual lacks — plus a comment claiming the file "won't hot-reload in the jam folder" and a `cps 0.5` line the author thinks matches the set tempo. Without looking up solutions, diagnose each failure by the visual/audio symptom alone (no error is thrown for most), apply the targeted fix or documented workaround (including faking the missing primitive), and correct the two false claims: state where the file must actually run (its own URL or Estuary, not this rig) and why standalone `cps` is fixed at 0.5. When one fix is a parse error you introduce, show that the previous program keeps running until you re-evaluate. Then write from memory the canonical panic recovery program: a bounded two-oscillator drone routed to `audio`, colour derived via lo/mid/hi with non-zero base terms, and a crossfade — demonstrating both `<> 0` for a near-immediate switch and a multi-second `<> n` for a smooth one, and accounting for cycle-quantized landing. Annotate every line of the panic program with the class of failure it avoids.

This module is built around a single performance reality: Punctual is unusually quiet when it goes wrong. Most mistakes never produce a parse error. A function used in the wrong domain silently returns 0; a missing >> operator discards the entire computation; feedback that blooms to white does not throw. The learner who debugs Punctual by waiting for an error message will wait forever. This module trains the habit of reading output — canvas and speakers — as the only diagnostic surface.

The twenty atoms split into two interlocking layers. The first (L1 gotchas) covers the mechanics every Punctual session trips over: the output-routing rule (bare osc 440 is silent without >> audio), the three arrow operators (<< defines, >> routes, <> crossfades — not interchangeable), $ versus & application order, the osc/sin naming split introduced in Punctual 0.5, wrong-domain silence, combinatorial [...] versus pairwise {...} lists, the lo/mid/hi dependency on a running audio statement, feedback gain-at-or-above-1 runaway, cycle-quantized evaluation, the fixed cps of 0.5 in standalone mode, and the fact that Punctual lives at its own URL or inside Estuary — not in this repo’s rig. These are mechanical invariants; the first drills are timed recognition-and-fix pairs, each under two minutes.

The second layer (L5 diagnosis) builds the mental model that lets a performer fix problems mid-set. Punctual errors that do throw (parse or compile failures) preserve the previous working program — the canvas does not go dark — which means a syntax mistake during a live set is recoverable just by fixing and re-evaluating. Silent failures (wrong domain, missing >>, lo/mid/hi with no audio, feedback bloom) require a different procedure: observe the symptom, match it to the known pattern, apply the targeted fix. The punctual-silent-domain-bugs and punctual-arrow-semantics atoms are the diagnostic grammar; punctual-deprecated-output-operators covers the specific class of >> video / >> hsv / >> red / >> left failures inherited from 0.4 code. punctual-missing-primitives sets honest limits: coherent noise, voronoi, and pointer are absent — know the gaps before you plan a set around them.

The capstone exercises all four objectives without scaffolding. The learner receives a seeded bug file, works through symptom-reading alone, and must write the panic recovery program from memory. The annotation requirement — naming the failure class each panic line avoids — forces explicit reasoning rather than cargo-culted copying. The panic program itself is the capstone deliverable: a program a performer can type from scratch in under thirty seconds when Punctual’s canvas blooms or blacks out, guaranteed to land a safe, intentional visual and a bounded audio tone that gives lo/mid/hi values to work from.

The two supporting atoms (punctual-coordinate-system, punctual-rgb-channel-distribution) ground the capstone in the spatial and colour model of Punctual without directly gating bug diagnosis — they enrich the learner’s ability to write visually interesting recovery programs.