audiogram_production v1.0.0

name: audiogram_production description: Turn an audio-only podcast episode into a shareable audiogram: pick the clip worth promoting with a scored selection check, render a clean animated waveform over a still or flat background, burn captions that match the audio word for word, and export legible per-platform sizes. Use when promoting a podcast episode on TikTok, Reels, Shorts, or a feed, when asked to make an audiogram, waveform video, or podcast clip, or when a clip needs captions checked before it posts.

Audiogram Production

Purpose

An audiogram is a short video made from audio: a waveform moving over a still, captions burned in, sized for a phone feed. It is how an audio-only show gets seen in places that only carry video. This skill covers the whole job in order: choose the clip, prove the captions, render once, export for each platform, and check the result on a frame before anything posts.

The bundled tools do the mechanical work. scripts/score_clips.py ranks candidate clips from a transcript. scripts/caption_check.py flags captions a viewer cannot read in time. scripts/audiogram.py renders the exports with FFmpeg.

Workflow

1. Pick the clip worth promoting

• Start from the episode transcript in SRT form. Run the scorer and read the top candidates in full, not just the first line:

bash
python3 scripts/score_clips.py episode.srt --top 5

• Score what the scorer scores, then listen. It rewards a duration of 30 to 60 seconds, a start that is not a filler word, an end on a complete sentence, a question or a number inside the window, and hook words that signal a concrete claim. It penalises mid-sentence endings and heavy filler. The score is a shortlist tool. The final pick is made by listening to the top two or three candidates end to end.

• Apply the stand-alone test to the winner: a viewer who has never heard the show should be able to say what the point was after one watch, with the sound off and with the sound on. If the clip needs the episode around it to make sense, pick a different window.

• Fill in templates/clip-brief.md for the chosen clip. One clip per brief, one point per clip. If an episode has two strong moments, make two audiograms instead of one long one.

• Export the winning window as clip-relative captions. The renderer expects timestamps that start at zero:

bash
python3 scripts/score_clips.py episode.srt --export-srt clip.srt

The export prints the exact cut point and duration to pass to the renderer.

2. Prove the captions

• Build the caption file from the clip audio itself. Transcribe the clip, then correct the transcript against the audio. Names, numbers, and negations are where auto-transcription fails most, so check every instance of each.

• Hold the word-for-word rule: captions carry the same words in the same order as the audio. No paraphrase, no silent cleanup. Full method in references/caption-accuracy.md.

• Run the checker and fix every failure before rendering:

bash
python3 scripts/caption_check.py clip.srt

It enforces at most 42 characters per line, at most 2 lines per cue, a reading speed of at most 20 characters per second, cue durations between 0.83 and 7 seconds, and no overlaps. A failed check means the captions get re-cut, not that the limits get waived.

3. Prepare the background

• Use a still that reads at phone size: the episode art, a guest photo the show has the right to use, or a flat colour. Test it shrunk, not full screen. If the image has busy detail behind where the waveform and captions will sit, darken it or switch to the flat colour.

• Keep one visual identity across clips from the same show: same background treatment, same waveform colour, same title placement. A feed viewer should recognise the show before reading a word.

• Keep titles to five words or fewer and pull them from the clip itself. A title that promises something the clip does not say is a broken promise at the exact moment a new viewer decides whether to trust the show.

4. Render the exports

• Render all three sizes from the same cut in one call:

bash
python3 scripts/audiogram.py --audio episode.mp3 --start 612 --duration 38 \
  --image art.png --captions clip.srt --title "Write the ending first" \
  --outdir audiogram-out

Omit --start and --duration when the audio is already a cut clip. Omit --image for a flat background and set --bg-color instead. Use --dry-run to print the FFmpeg commands without rendering.

• Know what the render does, so a bad output can be diagnosed: the background is scaled and cropped to fill the frame, the waveform is an animated showwaves render in centred line mode at 30 frames per second, captions are burned with the subtitles filter above the waveform, and the audio is normalised inside the same render with loudnorm to -16 LUFS integrated and a -1 dB true peak ceiling. Video is H.264 in yuv420p with faststart, audio is AAC at 192 kbps and 48 kHz.

• The three exports are vertical 1080x1920 for TikTok, Reels, and Shorts, square 1080x1080 for feed posts, and landscape 1920x1080 for YouTube. Which of those numbers are platform rules and which are production choices is spelled out in references/platform-specs.md. Do not quote a recommended export size as a platform requirement.

5. Check before posting

• Probe every export and confirm the size and duration match the plan:

bash
ffprobe -v error -show_entries stream=codec_type,width,height \
  -show_entries format=duration -of default=noprint_wrappers=1 audiogram-out/audiogram-vertical.mp4

• Extract a frame in the middle of a caption and read it:

bash
ffmpeg -y -ss 12 -i audiogram-out/audiogram-vertical.mp4 -frames:v 1 frame-check.png

Read the caption on the frame and confirm it matches the words being spoken at that second, the text stays clear of the bottom and right edges where feed buttons sit, and the waveform is moving and legible. Check the vertical export first, it is the strictest frame.

• Listen to the first two seconds and the last two seconds. The clip should start on speech, not silence or a half word, and end after the final word lands, not clipped mid-syllable. If either end is wrong, adjust the cut by a fraction of a second and re-render. Do not pad a bad cut with a fade and call it fixed.

• Post the native file to each platform. Do not post a file that carries another platform watermark, and do not stretch a vertical render into a square slot. Each platform gets its own export from step 4.

Output Contract

A finished job delivers:

• A filled clip brief naming the episode, the cut points, the one point the clip makes, and where it posted.
• The clip-relative caption file that passed caption_check.py with a PASS result.
• One MP4 per requested platform, probed for the correct width, height, and duration.
• A frame check on at least the vertical export, with the caption read against the audio at that timestamp.
• Audio at -16 LUFS integrated with a -1 dB true peak ceiling in every export, from the same normalised render.

Operating Rules

• Captions match the audio word for word. Never paraphrase, summarise, or clean up a quote inside a caption.
• Never ship a clip whose captions fail the checker. Re-cut the cues and check again.
• Never pick a clip from the transcript alone. Listen to the final candidate end to end before rendering.
• Never invent a platform specification. If a size or limit is a recommendation, say it is a recommendation. The sourced breakdown is in references/platform-specs.md.
• Loudness stays at -16 LUFS and -1 dB true peak for podcast audiograms, the Apple Podcasts published recommendation. Do not master promo clips louder to stand out, platforms normalise playback and the extra loudness only costs clarity.
• Use only images and audio the show has the right to publish. A guest photo from a recording session is not automatically cleared for promotion.
• One point per clip. A window that scores well but makes two points gets split or passed over.
• No em dashes in titles, captions added by hand, or post copy written around the audiogram. Use plain punctuation instead.