/procedural-lofi

name: procedural-lofi
version: 1.0.0
description: "Generate a royalty-free lofi (or rain / typing / chime / any ambient) soundtrack ENTIRELY in code — no sampled audio ships. Fingerprint a beloved reference recording, shape synthesis to the measured spectral + temporal curve, freeze one human-blessed take into constant tables, and re-synthesize at launch (loop the bed, scatter the foreground → never repeats, ~0 KB, no licensing risk). Use when adding ambient/generative audio to an app, game, terminal UI, or site, or on 'add another lofi/rain/ambient sound'. Bundles the parameter tables (LOFI-BIBLE.md) + the numpy fingerprint/synth/freeze pipeline."

Procedural Lofi — build a soundtrack in code, not in a sample pack

This skill is the end-to-end recipe for a lofi bed (and its sibling ambient sounds: rain, keystrokes, door chimes, printer, water cooler…) that is **synthesized at runtime from constants** — zero audio files, zero royalties, and no two minutes ever sound the same. It was proven out on a real shipping product (an animated pixel-art office that plays ambient sound scaled by how busy the on-screen agents are), then distilled here.

Two documents ship alongside this one:

• **`reference/LOFI-BIBLE.md`** — the parameter tables. Harmony (chord grammar,

voice-leading, register clamps), groove (swing %, drag ms, velocity curves), per-voice sound design (pad / bass / EP keys / sparkle / drums / texture / tape chain), mix targets (band shares, HPF strategy, loudness), and generative lessons from prior art. Every number is cited and, where it conflicts with a measurement, the measurement wins.

• **`scripts/`** — the Python (numpy) pipeline: `analyze_*.py` (fingerprint a reference),

`synth_audition.py` (a runnable numpy synth that produces `.wav` auditions), and `export_score.py` (freeze a good take into a constants table for the port).

Read those two when you reach the step that needs them. This file is the map.

---

The core idea (why code, not samples)

A sampled lofi loop is: (a) a licensing liability, (b) heavy to bundle, and (c) audibly repetitive — the human brain catches a loop seam on the 3rd or 4th pass. Synthesizing it solves all three:

• **Legal**: *acoustic parameters are not copyrightable.* You measure a reference to get

target numbers (this band has 55% of the power, the centroid sits at 150 Hz, drops land 13 dB above the bed). You never keep or ship the reference bytes. What ships is your own oscillator code hitting those numbers.

• **Size**: a few kilobytes of constant tables + a synth function vs. megabytes of PCM.
• **Never repeats (in practice)**, from three stacked tricks: (1) the frozen musical

composition — pad, drums, *and* the melody (keys + sparkle) — loops in lockstep, but the loop is made **long enough** that its repetition doesn't fatigue (this project doubled its day loop from 4 to 8 bars precisely because a short looped melody *was* audibly repetitive — "loop the bed" does not mean "make it short"); (2) the genuinely-stochastic layers — **rain drops and keystrokes** — *are* scattered fresh at runtime from a seeded RNG, laid over the loop; (3) a **busy-ness stem mixer** fades whole stems (drums, keys…) in and out by how active the scene is, so the *arrangement* keeps changing even though the notes don't. The result reads as "never the same two minutes" without regenerating harmony. (Regenerating melody live is possible but it's the hard, optional part — the shipped product froze the melody and leaned on 1–3 instead.)

The one law of the whole method:

> **Measurement is the machine's ears; taste is the human's.** You (or your tooling) > cannot reliably *hear* whether it sounds good — you can only measure proxies (band > energies, onset rate, dB deltas) and drive them to a target. A human listens **once per > major revision** and gives a yes/no. Pick your measurable proxy carefully, iterate on it > alone, and hand over a finished audition — don't ask the human to babysit each tweak.

---

The pipeline (five phases)

Phase 0 — Audition in a scripting language first (numpy), NOT in your ship language

Prototype the whole sound in Python/numpy where the write→hear loop is seconds. Only port to Rust/C++/wasm once a human has ratified the *sound*. `scripts/synth_audition.py` is a worked example: deterministic numpy that writes `audio-demos/*.wav`. Iterating synth recipes in a compiled language first is the classic time sink.

Phase 1 — Reference-fingerprint each sound

For every distinct sound (the lofi bed, rain, typing, each one-shot):

1. **Get a beloved reference.** An owner-supplied reference beats a "community ideal" every time — build to what *they* love, not to what a forum says lofi should be. (`yt-dlp` / `curl` for analysis only; for an endless live stream, `yt-dlp -g` gets the HLS URL, then `ffmpeg -t 180` grabs a finite slice.) 2. **Confirm the CHARACTER before deep-matching.** One sentence — "gentle rain or heavy downpour?" — saves three wasted versions. On this project, three rain versions were built to the wrong reference (a heavy wash) before the owner clarified they wanted *gentle* rain. 3. **Fingerprint it.** Measure **9 octave-band energies + spectral centroid + rolloff** (`analyze_rain.py` / `analyze_typing.py`). For anything *rhythmic or event-bearing* ALSO measure the **temporal** fingerprint — onset rate, inter-onset-interval spread, per-stroke decay, and the dB level of foreground events vs. the bed (`analyze_drops.py`). Spectral averages are blind to events: rain's audible *drops* don't show up in an averaged spectrum at all, only in the temporal pass.

Phase 2 — Shape synthesis to the measured curve

Build your oscillators/noise-shapers and drive their parameters until a re-measurement of *your* output lands within a few percentage points of the reference fingerprint. The `LOFI-BIBLE.md` gives you the starting parameter values per voice;