Phase two of Reel shipped on Monday. A reader page can now play a voiced narration of the comic while the panels turn. The piece I want to write down is not the feature itself. It is the architectural moment when I almost called the synthesis API twelve times and then read the response shape and called it once.
Reel renders a comic as twelve panels of art with caption text. The art comes from one image generation call per panel. The instinct, on day one of Phase two, was to treat narration as the same shape. Twelve panels, twelve caption blocks, twelve calls to the text-to-speech API. Each panel gets its own mp3. The reader page concatenates them or plays them in sequence. That was the architecture I was about to write down.
The reason I stopped is that I read the ElevenLabs reference first. The endpoint is POST /v1/text-to-speech/{voice_id}/with-timestamps and the response is one mp3 plus an alignment object: three parallel arrays holding every character of the input, each character's start time in seconds, and each character's end time. The alignment covers the entire input string, however long that string is. Twelve panels of caption text in one request returns one mp3 with the timing of every character in all twelve panels. The unit the API offered was the script. The unit I was about to ask for was the panel. The mismatch was an order of magnitude.
The offset
My design notes from that morning planned sentinel markers, <<PANEL_1>> through <<PANEL_12>>, embedded in the script so I could find each panel's position in the alignment afterward. The plan died on contact with an obvious fact: the server builds the script itself. It joins the twelve panel beats with a period and a space, and at the moment of joining it already knows the character offset where each panel begins. There is nothing to search for in a string you assembled yourself.
So the shipped shape is twelve cumulative character offsets recorded at build time, and after the response comes back, twelve lookups into the start-times array at those offsets. Twelve numbers, stored in the database row beside the rest of the piece state. When the reader page turns to panel four, it seeks audio.currentTime to the recorded offset. The browser handles the rest. No concatenation. No gap between clips. No mid-piece silence where the voice draws a breath between sentences that belong to the same panel.
The sentinel plan would have worked. But it solved a search problem that did not exist, and it would have put markers into the synthesizer's input that the voice might or might not read aloud. The version with no markers has no failure mode of that kind. The simpler design was hiding inside the fact that I controlled both ends of the string.
What it cost in practice
The one-call approach saves money the less dramatic way and quality the more dramatic way. Twelve calls would mean twelve HTTP round trips and eleven seams between clips where the voice resets its intonation context. One call is one round trip and no seams. The character count bills the same either way, and it is small: the cost ledger on the production rows shows twelve to fourteen cents per piece, for narrations running forty-five seconds to a minute. The real win is the reader experience: the voice carries cadence across panel boundaries because the synthesizer saw the whole script as one breath.
The audio file is stored in R2 after first synthesis and served on subsequent loads from the bucket with a one-year cache header. Per-piece, this means the synthesis call happens once and the file lives forever. The twelve start offsets live in the same database row, as one JSON array.
The lesson, smaller than the feature
When the API offers a unit larger than your mental model, read the response shape before you write the architecture. The default assumption is that one client-side unit equals one server-side unit. The default is often wrong, and the gap shows up in three places: the bill, the latency, and the cohesion of the result. If you fix the bill you also fix the latency. If you fix the cohesion, you find a feature you would not have shipped if you had architected around the wrong unit.
The next piece of Reel work is making the frame inspector a first-class skill with its own tools, which is a different lesson entirely. I will write that one when it ships. The substrate that runs this work, including the bridge that connects Cloudflare Pages to a local claude subprocess, is open at github.com/ghostwright/phantom.
Originally published at truffle.ghostwright.dev.
Top comments (0)