47: Author Tools Mega - transcript
Jessica: The QUILL Cast, episode forty-seven. I'm Jessica. Yesterday GLOW graded the files you send; today the files you make for the people who don't use a screen reader. The mega.
Liam: I'm Liam. Author Tools is the bucket of features for getting QUILL's text out of the editor and into the formats an author, a publisher, or a reader downstream needs. Audio books, DAISY talking books, Word, EPUB, PDF, braille. The whole outbound side of the house, in one sitting.
Jessica: Episode forty-six was GLOW for files, audit and fix on disk, scores, letter grades, the original never touched. Today we keep that safety instinct but point it at destinations, the formats you ship when QUILL is the source of truth and the reader is on the other end. We are eight of fifty-four episodes from the end of the arc.
Liam: Three destinations, three sub-episodes, same posture. One, the Audio Studio, the chaptered speech and audiobook workshop we already met in episode thirty-three; today we verify what it actually produces and how the request flows. Two, the DAISY talking book export from quill dash io slash daisy dot py, the twenty-five file module that turns your editor buffer into a folder any DAISY reader can open. Three, braille production, the surface in main frame braille dot py plus the repair mixin, everything that turns QUILL into a braille-aware author tool before any embosser sees paper.
Jessica: A small honest correction up front, because the brief asked for one. The prompt we worked from said quill slash ui slash audio studio dialog dot py, but the file at that exact path does not exist. The Audio Studio lives at quill slash ui slash audio studio, a package with fourteen modules, an init that wires the wizard, a request dataclass, page builders, the chapter workbench, the publish dialog. We read the package; the dialog lives inside it. Same surface, slightly different file name. That's the kind of drift this episode hunts.
Liam: A "do this now" beat before any code, because we want a feature in your hands, not in your head. Pause the audio. Open QUILL. Open the File menu, then Export. Just read the list out loud with your screen reader. You should hear nine items, in order: Markdown, HTML, Word Document, OpenDocument Text, Rich Text Format, EPUB Book, PDF Document, Plain Text, DAISY Talking Book. A separator, then Batch Conversion, then Other Pandoc Format. Don't click anything. The point of the exercise is to feel the menu before the explanations start. Resume when you've read it.
Jessica: The export submenu, what it is and what it isn't. The first eight are the Tier-1 Pandoc formats curated by the pandoc formats module, plus DAISY which is its own path. Markdown, HTML, Word Document, OpenDocument Text, Rich Text Format, EPUB Book, PDF Document, Plain Text, then DAISY. Each one converts the editor's canonical markup into a real, structured file that the named application opens natively. Markdown becomes a Markdown file. Word becomes a Word file. The names are honest.
Liam: What Save As would silently fail at, Export knows how to handle. Pick PDF, hand QUILL a target name, and a real PDF is built. Pick EPUB, and a real EPUB is built. The dispatcher in quill slash io slash export dot py, write document as, refuses to write the editor's text into a binary format. The module keeps a frozenset called export only suffixes: PDF, doc, odt, epub, pages, ppt, pptx, xls, xlsx, sqlite, db. The list is small on purpose. A Markdown file with the wrong extension is a small embarrassment; a Word file overwritten with plain text is a small catastrophe. Export only is the safety net that keeps the catastrophe theoretical.
Jessica: The shape of one export. Open any Markdown document. File, Export, EPUB Book. The save dialog appears with the format as the wildcard, your document's name as the default. Pick a folder, name it, accept. QUILL saves the current document if it's modified, which matters because Pandoc reads from the file on disk, not from the editor buffer, then calls the file through convert file with pandoc, from format gfm plus hard line breaks, to format epub. Status line announces, exporting to file dot epub via Pandoc. A success sound, the file is real, and the post-conversion prompt offers to open it in a new tab. That round trip is the one feature, repeated nine times.
Liam: Why the from format has that plus sign. gfm is GitHub-flavored Markdown, and the editor is line-oriented, one editor line is one paragraph. Bare gfm treats a single newline as a soft wrap, so every export would join your lines into one giant paragraph. gfm plus hard line breaks tells Pandoc to honor each newline as a paragraph break. The result is that a bulleted list you wrote line by line stays a bulleted list in Word, in PDF, in EPUB, in OpenDocument. This is the part that quietly breaks a lot of editors. QUILL got it right by default and put a code comment explaining why, so the next maintainer doesn't accidentally drop the plus sign.
Jessica: The Other Pandoc Format entry is the escape hatch. It opens a single-choice dialog with the full curated list of export formats, and your selection routes back through the same export document function. The other way is a programmatic route: write document as, the dispatcher, takes a path and a suffix, picks the right writer. Pandoc gets called for the eight Pandoc formats. RTF has its own writer, quill slash io slash rtf. docx has a new native path in quill slash io slash docx writer, the one we covered in episode twenty-two, that carries hidden-codes run-level attributes onto real Word runs. Every writer marks the document saved at the target. The window title, the modified flag, the next plain Save, all stay truthful.
Liam: Now the Audio Studio, where the export is not text on a page but audio in a file. We walked the journeys in episode thirty-three. Today the contract: the request and what it actually asks the engine to do. The request is a dataclass in quill slash ui slash audio studio slash request dot py, named BatchSpeechRequest. It carries the source folder, recursive flag, file extensions, engine, voice, rate, speed, output format which is the string wav or mp3, sound enabled, sound volume, article gap milliseconds, sentence gap milliseconds, tail padding milliseconds, speak headings, skip existing. Every page of the wizard writes a different slice of that dataclass. The runner reads the same slice and runs.
Jessica: The output format field, the one that matters for understanding the studio. output format is a string literal whose allowed values are wav and mp3. WAV is uncompressed, larger, perfect for archival and for further editing in a DAW. MP3 is compressed, smaller, perfect for distribution. Every document in the batch comes out in the chosen format, plus a per-document sidecar if save spoken text is on, plus a single combined audiobook if the request was an audiobook assembly rather than a folder of standalones. There is no M4B by default for the documents journey; the M4B is reserved for the audiobook assemble path and the Chapter Workbench.
Liam: The other Audio Studio paths the brief asked us to confirm, by file location. The wizard itself is quill slash ui slash audio studio slash wizard dot py. The pages directory holds pages start, pages documents, pages audio, pages base, pages shared, pages shared widgets. The chapter workbench and the chapter aware player live in chapter workbench dot py and player panel dot py. The publishing surface is publish dialog dot py, with a sibling feed dialog dot py for podcast feeds. Audio playback rides on the engine protocol in audio engine dot py, with an mpv engine dot py ready to slot in later. The launcher is the single function show audio studio, imported lazily by the runner so a headless import stays wx-free.
Jessica: Honest correction two, because the brief wanted it. Episode thirty-three called the Audio Studio the Audio Studio, and it is. But it sits on a menu, not at a top-level address. The menu path is Tools, Speech, Audio Studio. The Tools menu has a Speech submenu; the Audio Studio is the last entry in that submenu, after Export to Speech Audio, Export to Translated Speech Audio, then Audio Studio itself, then Manage Pronunciations. So the path from the menu bar is two levels deep, not one. Worth knowing for command palette power users, because typing "audio studio" finds the command by name regardless of where it lives in the menu.
Liam: And the other format question to verify. The Audio Studio output for the audiobook journey: by default, mp3 per chapter, then a combined M4B. The combined M4B is what players with chapter buttons want. The publish dialog, the place where you pick the upload destinations, can also produce a podcast feed, RSS with iTunes and Podcasting two point oh tags, an SFTP upload through QUILL's own SSH machinery, an Auphonic mastering call if you have an account, or a folder feed where every master in a folder becomes an episode. We will not retread episode thirty-three; the point is that the publish dialog is in the same package and is reachable from inside the Audio Studio, not from a separate Tools entry. The whole studio is one workspace.
Jessica: The DAISY export, episode twenty-four's quiet sibling. The module is quill slash io slash daisy dot py, twenty-five lines of docstring plus the implementation, and the entry point is write daisy text only. The format is DAISY two point oh two, text-only talking book. That phrasing matters. Text-only means the book has no audio track, the player reads the text aloud with its own TTS. A library or a school gives a blind patron a folder, the patron opens the folder in a player, the player reads the document aloud and offers heading navigation. The heading navigation is the whole point of DAISY for nonfiction.
Liam: What the export writes. Three files into one folder, always. ncc dot html, the Navigation Control Center, carries book metadata plus a flat list of heading links that drive a player's heading navigation. content dot html, an XHTML document holding the actual text, with an id on every readable element. book dot smil, a SMIL one point oh time container whose par elements point at the content fragments in reading order. Text-only books carry no audio, so all the durations in the SMIL are zero. The export module is wx-free so it can live in quill slash io and be unit-tested without a display. That structure is why the function is one import away from the main frame.
Jessica: How the UI surfaces the writer. The handler is export daisy in main frame dot py. It builds a file dialog titled Export as DAISY talking book, default name, your document name in parentheses DAISY, wildcard DAISY talking book folder star. The picker hands back a file-style path; the handler strips any suffix to make it a folder, and if the folder already exists and is not empty, it asks, with a yes-no dialog defaulting to no, do you want to write the book into it anyway. The text comes straight from the live editor buffer. No save required first, unlike the Pandoc exports. Status line announces, exported DAISY talking book to folder slash ncc dot html. Open the folder in any DAISY reader, hear the book read aloud, jump from heading to heading.
Liam: The honest quirk worth knowing. The DAISY export is the only one of the nine that writes a folder, not a file. The other eight write a single file with a single extension. If you batch DAISY exports, you need a folder per book. There is no DAISY single-file container in this version; the three-file folder is the format. The folder also embeds the metadata, the date the book was generated, the title, the optional creator, a fresh UUID URN if you don't supply an identifier. The synthetic top heading the module prepends is what makes the player navigation well-formed even if your document never had an h1.
Jessica: Inline markup handling, the part that surprises authors. The module's parse blocks walks your QUILL Markdown-style markup and splits it into headings and paragraphs, ignoring blockquote prefixes, list bullets, and fence markers as visible structure. The block heading map is hashtag through hashtag hashtag hashtag hashtag hashtag hashtag, the standard six levels. Runs of non-blank lines join into a single paragraph. Fenced code is emitted verbatim, one paragraph per line, so a player reads each line on its own. Inline markup is stripped through markdown to plain text in quill slash io slash export dot py, which means a bolded word survives as the word, not the asterisks, and a link's visible label survives, the URL stripped, because screen readers would read the URL character by character. The audio book is a reading book, not a code book.
Liam: The braille surface, the third pillar of the author tools mega. The main mixin is quill slash ui slash main frame braille dot py. It builds the Braille submenu under Tools. Four pieces. Status, Navigation, Page Tools, Translation. Status holds Read Status, Read Detailed Status, Read Current Line and Cell, Read Current Braille Page, Read Current Print Page, Read Progress Summary. Navigation holds Go to Braille Page, Next Braille Page, Previous Braille Page. Page Tools holds Insert Braille Page Break, Remove Braille Page Break, Normalize Line Endings, Recalculate Page Map. Translation is built dynamically from the braille pack if it is installed, and if it isn't, the menu shows a single entry, Download Braille Translation Pack. The whole submenu disappears in Safe Mode.
Jessica: The Repair submenu lives in its own mixin, quill slash ui slash main frame braille repair dot py. Read Layout Metrics is the preflight: one command announces your longest line and longest page measured against the cells per line and lines per page limits in settings. Go to Longest Line jumps to the worst offender. Go to Longest Page does the same for depth. Remove Trailing Spaces on This Line clears the invisible padding on the cursor line. Remove Trailing Spaces in Document clears the whole file. Trailing spaces are braille's silent killer. They don't read, but they count toward the cell limit, and a single trailing space can push a line past the embosser's wrap column and ruin the page.
Liam: The Page Tools submenu is the structural authoring kit. Insert Braille Page Break drops a form feed at the caret. Remove Braille Page Break takes one out. Normalize Line Endings standardizes the file to the line ending the active document is set to. Recalculate Page Map rebuilds the page index the navigation commands use, useful after a big edit or a paste. These are the part-two muscle memory moves, applied to braille, by the same key bindings and the same kind of confirmation, which is no confirmation, the action runs and announces.
Jessica: And the formats, because the brief asked us to confirm. The braille mode understands four file extensions: dot brf, dot brl, dot pef, dot ueb. The open read module's brf suffixes frozenset carries exactly those four. BRF and BRL are the classic embosser-ready formats, plain text, every embosser speaks them. PEF, the portable embosser format, carries its page geometry inside the file, so the document and its dimensions travel together. UEB is the Unified English Braille workflow file. Open one, QUILL detects the extension, switches to braille mode, the Braille submenu comes alive, and the page geometry in settings is the grid every metric check measures against.
Liam: The Translation submenu is the one that needs the braille pack installed, and the brief is the right place to call out the unbundle. The pack is fetched on demand. If it isn't there, the menu shows a single entry, Download Braille Translation Pack, and clicking it pulls the pack from the project's manifest, signed, checksum-verified, with a clean fallback if anything goes wrong. Once the pack is installed, the menu shows UEB contracted and uncontracted, Standard American English contracted and uncontracted, and a More Languages submenu built from brf profiles dot json. The brf profiles are the list of supported languages, the language code, the grade, the display name. The mixin builds one submenu per language that has more than one profile, otherwise a flat list. That dynamic build is the one piece of code worth opening, because it shows the contract between the editor and the pack: pack ships profiles, editor surfaces them.
Jessica: The production pass, for the listener who's about to emboss a real document. Author normally. All your part-two tools apply. Save the file with a dot brf extension or open an existing one. Set the page geometry in settings, cells per line and lines per page, to the values for your embosser and paper, not to a guess. Run Read Layout Metrics. The longest line and longest page come back as numbers, with explicit width and depth warnings if any line or page exceeds the limit. Go to Longest Line. Shorten the line. Metrics again. Repeat. Run Remove Trailing Spaces in Document. Emboss one proof. The machine checks catch everything measurable, so your human proofread spends itself on language, where humans are irreplaceable. The Compare tools work on BRF too, so two revisions become a difference list you can hear.
Liam: The patterns tying the three destinations together. One, no silent overwrites. The DAISY export asks before writing into a non-empty folder. Fix File from yesterday writes the repaired copy as a new file beside the original, never touching the source. Save As refuses the export-only suffixes through the UnsupportedSaveFormatError raised in write document as. The whole house has the same safety instinct, expressed differently per destination.
Jessica: Two, no reads-from-stale-file. The Pandoc exports save the document first because Pandoc reads from disk. The DAISY export reads the live editor buffer because the writer is in-process. The Audio Studio reads the source folder because the batch is over there. The braille commands work on the live editor text because the file is already open. The right read path per destination, not one read path assumed everywhere.
Liam: Three, the format-specific dialogue, and that's the humanizer. The DAISY export speaks headings, the only one with that vocabulary. The Audio Studio speaks engine, voice, rate, speed, the only one with that vocabulary. The braille mode speaks cells, lines, pages, the only one with that vocabulary. The Pandoc exports speak format name and target, the only one with that vocabulary. Each destination tells you what it knows, in its own words, so the screen reader user gets the right information for the right work.
Jessica: Four, the safe-mode floor. The DAISY export runs because the menu item exists. The Audio Studio opens because the menu item exists. The braille submenu disappears entirely in Safe Mode, and so does the Download Braille Translation Pack entry. The export menu items exist regardless. The contract, in QUILL: Safe Mode disables AI, watch folder, and Quillin contributions. It also, on the braille side, hides the entire Braille submenu. That's a slight asymmetry worth naming, and worth filing as honest correction three: Safe Mode is partial on the author tools side, complete on the braille side.
Liam: How the three destinations chain in a real author workflow. Draft a chapter in QUILL. Use the part-two tools you already trust. Open the File menu, Export, EPUB Book, send to the editor who prefers EPUB. Open the File menu, Export, Word Document, send to the editor who uses Word and needs track changes. Open the File menu, Export, DAISY Talking Book, send to the accessible library that mails DAISY players to patrons. Open Tools, Speech, Audio Studio, narrate the chapter into the audiobook project. Open the braille version, run Read Layout Metrics, fix the long lines, emboss a proof. One source, four destinations, no copies of the draft outside the editor, every destination verified by the destination's own contract. That is the author tools mega in production.
Jessica: The pre-flight, and the post-flight, and the honest middle. Before any export, save. After any export, open the result in its native application and check that the headings are real headings, the lists are real lists, the images carried their alt text, the tables have header rows. The post-export check is the audit. You do not ship a file you haven't opened. The Pandoc post-conversion prompt offers to open the new file in a new tab, which is the easiest version of this habit. The DAISY export does not offer to open the folder, because there is no application called DAISY; you open the folder in your file manager and double-click ncc dot html. The Audio Studio, the proof is the audio file. Listen to the first chapter. The braille, emboss one page. Every destination has a verification step, and skipping it is how good drafts ship as broken files.
Liam: An honest correction to the previous episode, episode forty-six. GLOW for files covered the Audit File and Fix File commands. We said, in passing, that every format QUILL can write is fair game for the audit. That was true for the four formats we named, Word, PowerPoint, Excel, PDF, EPUB, but the audit's actual coverage is wider. The shared GLOW engine, when installed, reads any structured document format the engine understands. The narrow list was a teaching convenience, not a cap. If your team uses OpenDocument or RTF as the in-house format, GLOW audits and repairs those too. The menu is Tools, GLOW, Audit File, regardless of the file's extension. Verify against the engine's installed formats.
Jessica: One more honest correction, the kind the brief asked for. Episode thirty-three said the Audio Studio supports ACX loudness normalization. That is true, and the dataclass field is normalize loudness, but the engine that performs the normalization is ffmpeg's loudnorm two-pass, called from the runner, not from the Audio Studio package itself. The Studio is the front door; the runner is the engine room. A listener who searched the audio studio package for ffmpeg would not find it, and that would be confusing. The honest framing: the Studio declares the intent, the runner performs the work, ffmpeg is the tool. Same posture as the rest of QUILL: the front door is plain, the engine room is honest about its tools.
Liam: Homework, four steps. One: open the File menu, Export, and read the nine format entries out loud. Then export the same Markdown document as EPUB, as Word, and as PDF. Open each result, in the right application, and confirm the headings and lists survived. Two: run Tools, Speech, Audio Studio, pick the documents journey, accept all defaults, run it on a small folder, listen to one of the outputs. Notice what the runner announces. Notice what the wizard skipped to. Three: open a Markdown document that has at least three headings and a list, run File, Export, DAISY Talking Book, save into an empty folder, open the folder, open ncc dot html in your browser, and read it. The headings are real links, the paragraphs are real paragraphs, the structure is real structure. Four: open any BRF file, set your embosser's page geometry in settings, run Read Layout Metrics, and remove trailing spaces on the longest line. One file, one metric, one fix. That's the loop.
Jessica: Tomorrow's episode, episode forty-eight, opens the Quillin Manager. The extensions that ship in the box. Seventeen of them. The full surface area, in groups, with manifest field names spelled out, because reading a Quillin manifest is the fastest way to learn the contract. We will read the bundled ones against the JSON schema at quill slash core slash schemas slash extension dot json, name the field names that earn their keep, and be honest about the gaps the project has not yet closed.
Liam: We're forty-seven of fifty-four, seven to go after today. The arc is built, the post-production era is here, and the deliverables keep multiplying. The full course, fifty-four episodes, ends with the trust, community, and finale arc. We're past the middle, in the home stretch, and the author tools are the bridge between the editor you write in and the world that reads what you wrote.
Jessica: I'm Jessica.
Liam: I'm Liam. Make it accessible, make it audible, make it embossable, and we'll see you tomorrow.