Whisper’s Shout

The book’s content comes from three generators: illustrations from ChatGPT’s image model, recordings from Suno, and code from AI coding agents working to my architecture. The media would arrive named after song titles and be replaced many times. Numbered filenames survive a retitle and keep spaces and apostrophes out of URLs. The plate frame is exactly 2:3, so a 1024×1536 illustration drops in with nothing cropped. Every slot has a drawn placeholder or a greyed-out play seal, so the book could go live complete with no art or audio in it at all.

A small installer bridges each generator’s exports to that contract. It matches files to songs by the titles in the same data file the pages are built from, ignoring case and stray apostrophes. It skips an ambiguous match rather than guess, reads each file’s first bytes to flag a mislabelled format, and only ever reads the source folder, never writes to it.

The page plan is six fixed pages plus two per song, so a sixth song would keep the spreads paired. Every URL hash has two destinations: in landscape it names a spread, in portrait a single page. A phone deep-linked to the index or the dedication lands on the content, not on the endpaper facing it (Fig. 6).

The lyrics are fourteeners, long lines that the page sets on two. Each sung line is split at its own caesura. A comma near the middle wins; otherwise the break goes at the nearest word gap that doesn’t strand a function word or a verb’s particle; and a hand-placed bar overrides both. Every type size and space on the page is a fraction of the live page width, so line length holds at every screen size with no type breakpoints at all, and a longer regenerated verse shrinks its own type instead of being clipped.

The website engine for small congregations that grew from this book kept the viewport cap, the back-turn repair, the deterministic page-jump routing, the page-width type scale and the deploy-time cache stamper.

1. A misspelt class. The library’s shipped stylesheet targets a class name with a typo, which collapses the book. The correction lives in the project’s own stylesheet, so a future upgrade can’t silently drop it.
2. A backward turn that fakes a touch. It simulates a press at a hard-coded x coordinate. In portrait that point lands mid-book, and the turn is dropped with no error. The fix wraps the instance’s own methods rather than the buttons, which is what lets the repair reach the library’s swipe handler too.
3. No way to fit a short window. The book’s height is derived from its width. A viewport cap, computed from the window alone, rewrites three inline styles the library owns.
4. A “flip” event that doesn’t mean a flip. It means “page index published”: it also fires at start-up, on rotation and whenever the book asks it to re-measure after a change in window height, and an index link runs the arrival code twice, once from the library’s event and once from the page’s own hash handler. The play button’s spark was made idempotent per page. The music stop on the same event was not, so a change in window height still stops a playing song (see the honest notes).
5. An animation that restarted mid-turn. The library hides offscreen pages with display:none, and a stylesheet animation restarts whenever its element is shown again. The play button’s spark now runs through the Web Animations API, which keeps its own timeline.

Anyone who had opened the link would have been held on the first build for a month. The site’s core workflow, drop in an illustration or a recording and it appears, would have failed for them, with nothing on my side looking wrong. A corrected header only helps browsers that haven’t visited yet, because a cached copy’s own expiry is what governs it.

An .htaccess now makes every request revalidate, so a revisit costs a 304. The deploy copies the site to a staging directory and stamps the current commit hash onto each script, stylesheet and icon URL there (seven links in the HTML, plus an @import inside the stylesheet), so a returning browser asks for URLs it has never seen. The illustrations and recordings keep plain URLs, and the revalidation covers them. The working tree keeps plain links, so there is no version number to remember to bump.

The stamper asserts every link it expects to find and refuses to deploy otherwise. That assert caught a real mismatch the first time an icon was removed from the page but not from its list. The same script refuses on unexpected files in the publish folder, dotfiles included, and on a dirty tree, and it checks five live URLs for a 200 before it reports success.

The play button and every page turn share one fade, and since each spread holds a single song, moving between songs always goes through a faded turn. A first attempt, never committed, stepped the element’s volume on every animation frame. It crackled even though its curve and length were right: each write is a step change in loudness applied at a buffer boundary, about thirty audible discontinuities per fade (zipper noise). The shipped version routes each track through a Web Audio gain node and schedules an exponential ramp on the audio clock, so the engine smooths it sample by sample.

The engineering is in the edge cases:

• The audio context is created on the first press, because a context starts suspended until a user gesture.
• A media element can be wired into the audio graph only once, so if that fails the song falls back to a clean stop instead of becoming a song that can never play again.
• Interrupting a fade freezes the volume where it is, instead of snapping it back to full.
• Pressing play on a song that is still fading out brings it back from wherever it had got to.