Sermon Pipeline

Orientation

The week, in two lanes

The same picture that opens How It Works. Everything below is this diagram with the hosts, credentials, and failure paths filled in.

Data flow

Services and the data between them

Read left to right, then down into the Shorts band. The week runs in four phases split by approval gates (/approve, /publish, then one per clip) where a reviewer signs off before anything irreversible happens. Inside each phase the Runner on the church Mac is the hub, calling out to the boxed services beside it; every numbered arrow is one flow of data, keyed to the legend below. The Runner lives on a residential IP because YouTube blocks video downloads from datacenter addresses. Follow the numbers 1 to 20 in order.

Reference

Where each piece runs

Phase 4, in detail

Shorts: propose, produce, publish

A published sermon can fan out into short vertical clips. The subsystem is three jobs behind two of its own human gates, and it never touches the sermon record's own lifecycle. Propose reads the published sermon's transcript and asks Claude for roughly 30-second candidates, each with a hook and the verbatim quote it is built around; a theological quality gate then drops candidates that are weak or that only hold together with the surrounding context, so what survives stands alone and represents the message fairly. Produce renders the picked candidates to 1080×1920 and uploads them UNLISTED. Publish is a second, separate human step that flips a reviewed clip public. Nothing in this path goes public on its own.

Selection happens from the phone: the candidates arrive as Telegram inline buttons (the same owner-only dispatcher used for /approve), or as typed commands for anyone who prefers them. Candidates are cached in a per-sermon sidecar, so a re-propose never re-pays the model calls.

Adaptive reframing

Grace's service is filmed on a locked-off camera that cuts between the preacher and the projected slides, so a single fixed crop is wrong for half of any given clip. Instead, scene-cut detection splits each clip into segments and one keyframe per segment is classified speaker vs slide by a vision model. Speaker segments are zoomed and cropped to fill the vertical frame; slide segments are fit whole, so a slide is never cropped. Both happen inside one clip, in a single encode pass. Behind a fitted slide the backdrop is a blurred still of the preacher, taken from the nearest speaker segment, so the clip still reads as him speaking. The fit leaves a small margin because the Shorts player crops slightly on some phones. Video is rendered at a constant 30 fps so the overlay animation stays smooth, and the end card carries a subscribe call-to-action. Any vision or detection failure falls back to fitting the whole frame, the one behavior that can never crop a slide.

Captions are burned in from the verified quote, never from raw machine transcription. If the words cannot be aligned to the audio with confidence, the captions are held back entirely rather than rendered at the wrong moment.

Media

Fetch, trim, and the audio chain

The multi-GB service video never crosses a job boundary, so every stage fetches only the bytes it needs. Processing pulls the sermon span alone with yt-dlp --download-sections and --force-keyframes-at-cuts, never the full stream and never a second pass for audio. The trim is a stream copy (-c:v copy -c:a copy -avoid_negative_ts make_zero), not a re-encode: it replaced an libx264 pass that took an hour per sermon, it runs in seconds, and the picture is bit-for-bit what was broadcast. YouTube re-encodes on ingest anyway, so the extra generation bought nothing but loss.

A short fetch that exits zero is the dangerous case, because it looks like success. Every clip is probed against the requested span and rejected under DOWNLOAD_MIN_FRACTION, and the retry deletes the partial file first, since yt-dlp skips a destination that already exists and would otherwise re-probe the same broken download three times.

Sunday captures are quiet and uneven: measured raw integrated loudness across real sermons runs from about −42 to −28 LUFS. A fixed pre-gain plus a single loudnorm pass cannot close that range; it landed around −16.5 LUFS and drew complaints that the audio was too quiet. The chain is ordered instead as adaptive leveler → speech EQ → compressor → EBU R128 normalization, so the final stage only makes a small, accurate correction regardless of how quiet the capture was.

Constrained AI

The Shorts council

A clip lifted out of a sermon loses the context that held it steady, so a true sentence can land as something the preacher never meant. The gate that decides this is deliberately not one broad prompt: a model asked "is this good enough to publish?" tends to agree with whoever asked. The judgement is decomposed into narrow questions with thresholds instead, and every verdict is written to the sermon's record, so a rejection can be read back months later with its reason.

Stage one is the proposer's own marks (hook, weight, stands-alone) which decide what is worth considering. Stage two is the council: one batched call scoring every surviving candidate on three lenses, each shown the clip plus 40 seconds of padding on either side so out-of-context risk is judged against what actually surrounded it.

Artifacts

Drive publishing and link integrity

Processing writes the mp3 and the mp4 into the church Google Drive. That write alone does not produce a shareable link: a separate resolve step makes each file publicly shareable, then records the real share URL back onto the sermon record. A receipt that still holds a local mount path is a 404 waiting to happen, so the resolve job runs on a daily schedule rather than by hand, and a link can no longer sit broken between one manual run and the next.

Downstream of that, two hard gates make a broken link unshippable rather than merely reported. The public sermons page refuses to render a download link until the receipt holds a real id with a working share URL, so a visitor sees no link instead of a dead one. The VietChristian mp3 email will not send at all without a working public mp3 link. A repair path can rebuild a published sermon's Drive files without regressing its status, without re-uploading to YouTube, and without sending any email, so fixing an old sermon's artifacts is safe at any time.

Live

System status

A heartbeat for each moving part, read from status.json. Grey means the check has not run recently.

State

Status machine

There is no database. Each sermon is one JSON record in the repo, and git history is the audit log. A job checks the record's status at the top and refuses work not in its expected predecessor state, so re-running tomorrow is always safe.

The one deliberate exception is repair: re-running the process step on a sermon that is already scheduled or published rebuilds its artifacts and does not regress its lifecycle stage. Fixing a Drive file or a bad render never un-publishes a sermon, re-uploads it to YouTube, or re-sends an email.

Rationale

Design decisions