29: Voice Catalog Walkthrough - transcript
Liam: The QUILL Cast, episode twenty-nine. I'm Liam. Welcome back to the desk, and welcome to part five's last, before we cross the bridge into part six. Today, the voice catalog in detail. Every engine, every name, the bits that are bundled, the bits that download, the ones that are already on your machine right now, and the one I am.
Jessica: I'm Jessica. And I am the other one. The catalog is the heart of read aloud, and we met the broad shape last episode, in the part-four opener. Today is the close reading.
Liam: Quick recap of last episode, episode twenty-eight, because that ladder is fresh and it sets today's tone. Agents. Reviewable autonomy. You state a goal, the AI writes down a plan, you read the plan, you trim it, you approve, and then the changes flow through the same preview-and-accept surface that has been our safety net since the speech-recognition era. Three layers of control: plan review, per-change preview, single-step undo. The blast radius of a bad decision is one keystroke wide. That posture, nothing changes silently, is the one we are carrying forward today.
Jessica: Why it threads through a voice catalog episode, honestly: a catalog is a set of choices, and choice is only comfortable when the surface that offers them is honest. No mystery voices, no silently-fetched downloads, no engine you cannot tell is running. So a code-verified walk through the catalog is the right way to keep that contract visible, not just stated.
Liam: Frame for today. We will walk every engine, name a handful of voices in each, point to the source file, and call out the trade-offs. Where docs and code drifted apart at any point in the project, we will say so. We are at episode twenty-nine of fifty-four, and one of the promises of the show is no marketing and no hand-waving, only what is actually in the build.
Jessica: Pause the audio here, if you want the full benefit of the next beat. Open QUILL. Open Tools, Speech, Speech and Dictation. You will land on a notebook with four tabs: Speech Offline, Speech Online, Dictation Offline, Dictation Online. We are only touching the first one this episode. Read the engines it lists. Come back when you can hear the difference between a button that says "Download" and a button that says "Manage voices." That thirty seconds is the spine of this episode.
Liam: Two seconds more, while you are in there. Hover the tab labels, listen to the role they read, and feel the rhythm of the notebook. The Offline tab is the local one, the one whose engines live on your disk. The Online tab is the cloud one, the one with the API key field. The two are physically separated, because they are different resource models, and a screen reader user should never have to wade through cloud setup to find their installed Kokoro voice. That separation is the quietest accessibility win in this whole episode, and it took one careful refactor to land.
Liam: If you came back, welcome. If you skipped ahead, that is fine, the rest still lands. The hub, as a design choice, deliberately puts offline engines in one tab and online engines in another, because they are different resource models, install once and own it forever, versus pay-per-call with an account, and mixing them in one flat list read as confusing. That is the architectural reason the screen shows what it shows.
Jessica: Now the actual code. The voice catalog lives in a single file, quill slash core slash voice catalog dot py, deliberately extracted from read aloud to keep that module within its size budget, and flagged in a comment as a GATE-eleven extract. Two helpers, the rest is data. It is pure Python, no wx, no network, and the read-aloud module re-exports every name, so any existing import keeps working. That is the kind of boundary that makes the rest of the catalog safe to talk about.
Liam: The engines, in the order the file documents them. Kokoro, neural, offline. eSpeak NG, the crisp classic, offline. Piper, neural, offline. The DECtalk voice set is defined a level up, in read aloud itself, alongside the SAPI five system voices. ElevenLabs is reached by a separate list voices helper that talks to the optional SDK. That is the whole cast, and the catalog file is where three of those five engines' voice tables physically live.
Jessica: Engine one: SAPI five. This one is not in the catalog file at all, and that is the right call. SAPI five voices are whatever Windows has installed, the Microsoft David, the Microsoft Zira, plus any third-party voice the user added. Zero downloads, always present, and QUILL lists them with a call into the platform layer. The list voices helper passes through language hints so a user with an Italian Windows voice can pick it. The floor of reliability. Start there, stay there for proofreading against your own screen reader, the contrast is the point.
Liam: Engine two: eSpeak NG. The catalog file lists eight English variants as a list of tuples, the I-D and the friendly name, the British, the American, the Caribbean, the Scottish, the Lancashire, the West Midlands, the Received Pronunciation, and the New York City accent. The accent map keys on the prefix, en-us becomes American English, en-gb becomes British English, and so on, including Australian, Canadian, Indian, Scottish, and Welsh, all just for the metadata. Then there is a separate list of non-English eSpeak voices, Spanish, France French, Hindi, Italian, Brazilian Portuguese, and Portugal Portuguese, the same language set as the Kokoro list so the multilingual story stays consistent.
Jessica: The eSpeak variants are the bit that always surprises people, and they live in the catalog as well, an eighteen-entry list of voice characters you can append to the accent code. Default, then m1 through m5, f1 through f4, whisper, whisper feminine, klatt, croak, grandma, grandpa, tweaky which is the robotic one, and unirobot. The voice browser dialog stores your selection as accent plus plus variant, for example en-gb plus m1, and it restores it the same way. The list is verified in the bundled eSpeak NG voices directory, so anything you see in the dialog you can actually synthesize.
Liam: Engine three: Kokoro. The catalog file has forty-three Kokoro voice entries, and we will name a few honestly. American female: af_heart, the warm one, the default, af_bella, expressive, af_nicole, conversational, af_jessica, who is me, af_sarah, af_sky. American male: am_adam, the deep one, am_liam, also me, am_michael, am_onyx, am_puck, am_santa. British, bf_alice, bf_emma, bf_isabella, bf_lily, and bm_daniel, bm_fable, bm_george, bm_lewis. That is a paragraph of names, but it is the kind of paragraph that earns its place once you have heard them.
Jessica: And the multilingual Kokoro voices, which matter more than the English list: ef_dora and em_alex and em_santa in Spanish, ff_siwis in French, hf_alpha and hf_beta and hm_omega and hm_psi in Hindi, if_sara and im_nicola in Italian, pf_dora and pm_alex and pm_santa in Brazilian Portuguese. The comment in the catalog is honest about scope: the same voices-v1.0.bin that ships with the English set already carries these, and they are gated by what kokoro-onnx can phonemize through its bundled eSpeak data, Latin script plus Hindi. Japanese and Mandarin voices exist upstream but need extra grapheme-to-phoneme packages, and they are deliberately not listed yet, with a follow-up tracked for them.
Liam: Two more catalog pieces for Kokoro that the file documents and the voice browser dialog uses. First, a quality grade map keyed by voice I-D, with letters and pluses and minuses pulled from the upstream VOICES dot MD. af_heart is A, af_bella is A minus, ff_siwis is B minus, most of the males are D, am_santa is D minus, and the Spanish and Portuguese voices are marked unrated because the upstream table does not assign them a letter. The comment is explicit: grades are descriptive metadata only, they never filter availability, so a D voice is not hidden from the dialog. Second, a letter-to-language map, a is en-us, b is en-gb, e is es, f is fr-fr, h is hi, i is it, p is pt-br. The voice browser dialog uses that to pick the eSpeak language code that the Kokoro ONNX backend needs to phonemize a voice correctly.
Jessica: Engine four: Piper. The catalog lists thirty-three Piper voice I-Ds, in the rhasspy slash piper-voices naming convention, language underscore region dash name dash quality. British: en_GB-alan in low and medium, alba, aru, cori in high and medium, jenny dioco, northern english male, semaine, southern english female, and the vctk pack. American: amy in low and medium, arctic, bryce, danny, hfc female, hfc male, joe, john, kathleen, kristin, kusal, l2arctic, lessac in high low and medium, libritts high, libritts r medium, ljspeech high and medium, norman, reza ibrahim, ryan in high low and medium, and sam. Italian: it_IT-paola medium and it_IT-riccardo extra low. The accent map turns the prefix into the spoken language name in the voice list.
Liam: Piper has its own quality ladder in the same I-D, low, medium, high, x-low, and the read-aloud code splits the parenthetical so the dialog shows the short name and the quality as the description. The download helper in the catalog is a small regex: parse the language code, the voice name, and the quality, build the Hugging Face path, return a tuple of the onnx and the onnx dot json URLs. If the I-D does not match the pattern, it returns none, so a malformed I-D shows a clear error instead of a broken URL.
Jessica: Engine five: DECtalk. The voice set is defined inside read aloud, not in the catalog file, and the catalog file does not need to know about it, because DECtalk voices are names, not downloads, the runtime is the only thing you fetch. The set is nine voices, and the code labels them honestly: Paul, Harry, Dennis, Frank as male, Betty, Ursula, Rita, Wendy as female, and Kit the child voice. Each name is paired with a DECtalk voice command string, the colon-bracket syntax, in a dict at the top of the module. Paul is the default. Paul is the Stephen Hawking voice, and the voice half our community grew up on.
Liam: Engine six, the optional cloud one: ElevenLabs. Listing those voices is a network call behind a key, the list voices helper returns an empty list when there is no key, when the SDK is missing, or when the call fails, and the caller never sees an exception. The actual synthesis is gated by per-session consent and by safe mode, so this is the one engine that is allowed to leave the room, only if you say so. Read in Browser, the experimental door, opens an accessible reader page in your own browser, and the dialog tells you plainly that an online browser voice sends the text to the vendor's cloud. Choosing it is an informed choice.
Jessica: Pause for the practical part. The voice browser dialog is the place where every catalog voice becomes a clickable row. The window is titled "Manage Voices and Reading Aloud," and it is reused in two ways, as a standalone dialog you open from the menu, and embedded as a tab inside the Speech and Dictation hub. That is why the class is called VoiceBrowserDialog in the ui directory, voice browser not voice picker, the picker name is older, and the brief called it voice picker, so we are noting the rename. Same dialog, new home, same logic.
Liam: What the dialog actually shows, top to bottom. An engine radio box with the choices you pass in. A filter box where typing narrows the list in real time by name, by accent, or by the style description. A voices list, with the accent and the description in the row, and a "not downloaded" tag for catalog voices whose model file is not on disk. A detail label that adds engine-state context, for example, "DECtalk is not installed, use the download button to get it." Then a settings panel that shows and hides rows per engine: rate for SAPI five, DECtalk, and eSpeak; volume and pitch for SAPI five only; speed for Kokoro; voice character for eSpeak. The rate spinner also has different ranges per engine, eighty to four-fifty for SAPI five and eSpeak, seventy-five to six-fifty for DECtalk. That is a small but real accessibility consideration, the range is the engine's true range, not a one-size-fits-all slider.
Jessica: The action buttons. Preview Selected Voice is the primary action, intentionally placed right after the voice list in tab order, so Enter on a voice row lands on Preview without a mouse trip. Download Voice is context-sensitive: it offers to download the engine itself if the engine binary is missing, the DECtalk engine at about thirty megabytes, the Piper engine at about twenty-two, eSpeak at about fifty, and it offers to download the Kokoro models at about a hundred and fourteen megabytes as one pack, because once the models are present there is nothing more to fetch for Kokoro. Export to Audio File closes the dialog and hands the selection to the export pipeline. Set as Default does the same as OK but stays in the dialog, a quiet improvement for anyone auditioning voices and saving as they go.
Liam: The preview path is the part that earns the trust. If the engine and the voice are both installed, preview runs real synthesis through the engine, the same path Read Aloud will take when you press the keys. If the voice is not downloaded yet, preview plays a bundled pre-recorded sample for that voice, so you can still hear what the voice sounds like before you commit the download. The rate, volume, pitch, speed, and character controls dim until the voice is downloaded, because they only apply to real synthesis, not to a sample clip. Enter and space both trigger preview, and double-click does too. The Stop Preview button toggles on the same control so the gesture never moves.
Jessica: Now the part where the docs and the code drifted apart, honestly, because we promised honesty. An earlier version of the catalog file exposed Spanish and Hindi Kokoro voices in a slightly different order than the published voices-v1.0.bin, and the comment block in the current file is explicit that those voices are kept in the list only because the same binary carries them. If you ever read a marketing page that lists, say, sixteen English voices, that page is wrong: the current catalog has twenty English Kokoro voices and four Hindi ones, plus the multilingual set. The code is the truth. The code is also the truth about an old name: the dialog used to be called voice picker in some old walkthroughs. It is voice browser now, and if you find a stale screenshot, that is why.
Liam: A second drift worth naming. The episode-twenty-eight opener said "Perfect Paul, the voice of Stephen Hawking," and that is true. It also said the engine is a free download, and that is true. What it did not say, and what the catalog and the read-aloud code together make clear, is that the engine binary is a Windows DLL named dectalk dot d l l, not a stand-alone speak dot exe. The old speak dot exe is the graphical sample window and fast-fails when launched as a console program, the code path explicitly rejects a configured speak dot exe and looks for the DLL instead. The downloader hands you the right file. The synthesis path then loads the DLL through a small console worker so the audio device is disabled and the wave output is captured. That is a quiet piece of engineering, but it is the kind of thing that bit users in earlier betas, and the code now defends against it.
Jessica: A third, smaller drift. Episode twenty-eight said the Speech and Dictation hub is "open the hub, pick engines, download voices, set defaults." That is still true, but the hub itself was refactored after that episode was recorded. The dialog is now a notebook with four tabs, Speech Offline, Speech Online, Dictation Offline, Dictation Online, and the constants for those tab indices are exported from the speech hub dialog module. If you saw a screenshot with a flat list, that is an old build. If you read a transcript that said "two tabs," also old. The four-tab layout is what the show's screenshots will show from this episode forward.
Liam: One more drift, and then we move on, because honesty is its own economy. Episode twenty-eight said "Help, Download Optional Components remains the one-stop shop." That is also still true, but the speech hub now does most of the work for you, and Help, Download Optional Components is the fallback when you would rather drive the download yourself, or when you are scripting the install. Both paths are real, both paths land in the same checksum-verified data directory, and either one is a legitimate way to set up the engines. Choose whichever one feels quieter.
Liam: Performance and honesty about hardware, because the read-aloud and catalog code are both written for real laptops. Engines load on demand and unload when idle, and there is a low-resource mode you can enable. Kokoro is the big one, about an eighty-eight-megabyte model in memory after a one-time hundred-and-fourteen-megabyte download, and the code caches the loaded model so a long read does not reload it sentence by sentence. SAPI five and eSpeak are tiny. Piper sits in the middle, one voice at a time, in the tens of megabytes per model. DECtalk is small. The downloader is the one place a real network call happens, and every download is checksum-verified, the episode-two trust model applied throughout.
Jessica: The safety nets around the catalog. A voice that is not downloaded cannot be silently used: the dialog says "not downloaded," the synthesis path raises a clear unavailable error, and the error message names the missing piece. ElevenLabs, the only cloud option, is gated by per-session consent, so QUILL tells you every session that reading will use the cloud, and safe mode disables it. The optional SDKs, kokoro-onnx, the ElevenLabs SDK, are downloaded on demand, never silently, and the hub makes the download explicit. If something cannot run, QUILL says so out loud, and the catalog does not pretend it works.
Jessica: A short, honest aside on what the catalog does not do, because the boundary is part of the design. It does not pick a voice for you, that is your judgment and your ear. It does not learn your taste over time, there is no implicit ranking, the most recently used voice is at the top of the dialog because it is literally the most recently used, not because a model is shaping your menu. It does not phone home to a usage service. It is a table, an honest table, with an honest search box, in front of a small set of honest engines. That minimalism is the point.
Liam: The short list of voices we keep coming back to, the ones that earn a place in your defaults. For proofreading against JAWS or NVDA, SAPI five, your system's most neutral voice, the contrast is the point. For long listening, af_heart for warmth, bm_george for a calmer British register. For a multilingual project, ff_siwis in French, if_sara in Italian, ef_dora in Spanish, the Latin-script eSpeak fallback if a neural voice is not downloaded. For sheer nostalgia, Perfect Paul. For proofing at speed, eSpeak in any accent, with the rate pushed until comprehension cracks.
Jessica: A piece of craft that the code makes easier than it looks. The filter box is filter-as-you-type, the dialog matches the query against the voice name, the accent, and the description, in that order, and it does not hide installed voices from the not-downloaded ones. That is the right call: auditioning a voice is the moment you decide whether to download it, so the dialog should show you what is on disk and what is not, side by side, in the same list. The detail label, again, keeps the "not downloaded" status honest, and the "Set as Default" button lets you save your auditioned pick without leaving the dialog.
Liam: Homework, four steps, designed to be done in twenty minutes with QUILL open. One: open the Speech and Dictation hub, find the Speech Offline tab, and read the engines. Note which ones are already on your machine, SAPI five always, eSpeak and Piper and DECtalk and Kokoro as your install history dictates. Two: pick one engine you have not used before, eSpeak is the easiest, and preview three voices in three different accents from the filter box. Three: open the dialog, type "British" into the filter, and see which engines offer a British voice. Note that the dialog labels the rows with accent and style, so you can compare personalities at a glance. Four: pick the one voice that surprised you, and set it as your Read Aloud default.
Jessica: A final honest note, because the show has made a habit of it. We are at episode twenty-nine of fifty-four. The catalog is not a finished thing. There is a follow-up tracked for Japanese and Mandarin Kokoro voices, gated by extra grapheme-to-phoneme packages. The Piper list will widen as rhasspy publishes more. The cloud tier will gain providers. The dialog itself will probably gain tag-based filtering, a "favorite voices" star, and a "recently used" section, the small things that turn a list into a tool you actually use. None of that is shipped, none of that is promised by today's episode, all of it is the natural next step.
Liam: Next episode, episode thirty, we cross the bridge into part six, organization. The Accessible Vault. Linked notes, backlinks, the spoken graph view, and a way of keeping a project together that does not require sight. Jessica has seniority rights on this one, and rightly so.
Jessica: I'm Jessica.
Liam: I'm Liam. Pick a voice, give your work a sound.