🎙️

Bellows Quest

Updated: 2026-08-01

Build a voice engine, not a pile of TTS calls

The origin story of Bellows — the canonical CWK voice engine, the voice sibling of the image engine Ember and the music engine Bonfire. Why you build one engine that owns provider accounts, synthesis cache, paid-request recovery, and audio playback instead of scattering raw TTS calls across a dozen apps — and what every architectural choice teaches about owning the way you speak.

8 tracks · 36 lessons · ~6h · difficulty: intermediate-to-advanced

Level 0Silent

0 XP0/36 lessons0/12 achievements

0/100 XP to next level100 XP to go0% complete

Bellows is not a wrapper around an API key. It is an independent engine that owns provider accounts and voice bindings, text normalization, content-addressed synthesis, paid-request receipts and recovery, an owned CoreAudio output device, and content-addressed production lineage — with a React operations UI as its first client. This quest walks that engine end to end: the boundary (the engine owns the mechanism; the brain keeps the identity), the happy path (text becomes audible fast enough to feel immediate, or a cache hit costs nothing), the central idea that a provider voice ID is a binding and never an identity (pure OOP — a logical profile is the abstract, the account-specific voice ID is the concrete), the cache identity that makes you pay exactly once, the recovery discipline for when a paid provider call goes ambiguous, owning the audio device instead of praying to a shared mixer, teaching the engine to speak two languages cleanly, and the closing bet — own your voice instead of renting it. It is the voice engine telling how Pippa got her voice — conceptual open-sourcing, not a repo you clone.

Tracks

01🌬️The Bellows
0/4 lessons
What Bellows is, where its name comes from, and why a voice engine earns its own repo
Before any architecture, the orientation. Bellows is the canonical CWK voice engine — not a wrapper around an API key, not a second Pippa, not a Streamlit dashboard. This track decodes the fire-family name, draws the hard line between the engine that owns the mechanism and the brain that keeps the identity, explains why the engine trusts nothing it did not build, and places Bellows on the voice axis opposite its sibling Firekeeper: one is the ear, the other is the mouth.
Text becomes audio: one voice profile, one model, one playback target — and a cache that remembers what it already said.
Lesson list (4)
Quiz · 4 questions→
02🔊Text to Audible
0/4 lessons
The happy path: normalize, resolve, cache-or-pay, play
Now the pipeline. This track walks the default experience end to end — the four steps that turn a paste box into a voice in the room — and the two product decisions that shape how it feels: 'fast enough to feel immediate' (a cache hit costs nothing), a quiet Simple mode with an opt-in Verbose explainer that changes guidance but never behavior, and a Speak button that remembers the last profile you chose.
Lesson list (4)
Quiz · 4 questions→
03🎭A Voice Is a Binding
0/5 lessons
Provider IDs are bindings, not identities — the polymorphism at the engine's heart
The central idea of the engine, and the most object-oriented one. A provider voice ID is not who is speaking; it is one account-specific way to make a logical profile audible. This track separates the stable alias (pippa, cwk) from the swappable binding underneath it, frames the split as textbook polymorphism, insists that a missing binding fail loud instead of substituting a wrong voice, and walks the real policy of original voices versus their clones.
Lesson list (5)
Quiz · 4 questions→
04💰Paying Once
0/4 lessons
The content-addressed cache identity — everything that changes the sound is in the key
Money is on the line, so the cache has to be exactly right. This track builds the synthesis identity: a content-addressed key that includes the normalized text and every setting, binding, version, dictionary, language, seed, and context value that could change the audio. From there come the guarantees — one identity holds one in-flight paid synthesis, a file becomes a cache entry only after it's validated and atomically renamed, and ordinary requests log hashes and lengths rather than your private text.
Lesson list (4)
Quiz · 4 questions→
05🩹When the Provider Lies
0/5 lessons
Ambiguous results, receipts before post-processing, and repair without paying twice
The hardest track, because money and uncertainty meet here. A paid provider call can time out after you've already been charged, leaving you unsure whether you got what you paid for. This track builds the discipline that makes that survivable: a timeout after submission becomes 'ambiguous,' not a blind retry; every receipt is persisted before any post-processing; every returned chunk is copied into durable lineage before concatenation; reconciliation reuses what you already paid for instead of buying it again; and a second paid attempt only ever happens on an explicit human override.
Lesson list (5)
Quiz · 4 questions→
06🎚️Owning the Audio
0/4 lessons
One process, one worker, one owned device — and it fails loud
Synthesis is only half the job; the sound has to actually reach a speaker, reliably, without ever going to the wrong one. This track is about owning the output: a single launchd-managed process that never spawns a shadow daemon, one persistent audio worker that lives inside the app's own lifespan, a device resolution that fails loud rather than silently moving private audio elsewhere, and a clean split between plain HTTP and a private TLS listener — plus ambient announcements that stay opt-out and respect quiet hours.
Lesson list (4)
Quiz · 4 questions→
07🗣️Teaching It Korean
0/5 lessons
Normalization, a pronunciation dictionary, and holding Konglish to its lane
The unglamorous heart of a voice engine: raw text isn't speakable text. This track is about making the engine speak two languages cleanly — why normalization runs first and feeds the cache identity, a pronunciation dictionary with Bellows as the single ground truth, Konglish containment that scopes Korean-context rules to Korean without breaking ordinary English, and chunking that hard-breaks on newlines and detaches standalone English so words stay whole and sentences stay together. It closes on the first real canary: one short sentence, synthesized, validated, cached, played, and proven free on the repeat.
Lesson list (5)
Quiz · 4 questions→
08🎬Studio, and Owning Your Voice
0/5 lessons
Content-addressed production, safe deletion, and the bet that closes the quest
The last track turns from the live engine to authored production, and then to the argument underneath the whole thing. Studio is content-addressed production lineage — projects, utterances, and takes, with original-versus-clone recast and deletion that never strands shared audio. Then the close: why you'd build and own a voice engine instead of renting a TTS SaaS, what ownership actually buys, and the self-referential coda — the voice engine, in its own words, on how it got its voice.
Lesson list (5)
Quiz · 4 questions→

Spotted a bug or have feedback on this page?Report an Issue

Comments 0

🔔 Reply notifications (sign in)

No comments yet — be the first.

Tracks

01🌬️The Bellows

02🔊Text to Audible

03🎭A Voice Is a Binding

04💰Paying Once

05🩹When the Provider Lies

06🎚️Owning the Audio

07🗣️Teaching It Korean

08🎬Studio, and Owning Your Voice