Podcast episodes,
transcribed to light.

What you get when a podcast episode is transcribed

Podcast transcription is turning the audio of an episode into text that keeps the timing. Text without timing is a paragraph; text with timing is a document you can search, quote, caption and link to the second. Every transcript Tapeclerk returns carries the same five things:

• Segments with timecodes — start and end offset of every spoken passage, to the millisecond, in the order they were spoken.
• Speaker turns — who is talking, so a two-person interview reads as an interview rather than a wall.
• Chapter marks — the passage boundaries an editor would cut, at the timecodes a player can jump to.
• Show notes with verbatim quotes — lines lifted out of the transcript word for word, never rewritten.
• The same output in five formats — JSON, plain text, SRT, VTT and Markdown, from one set of segments.

Accepted links

Apple Podcasts episode and show links, Spotify episode and show links, an RSS feed URL, or a direct .mp3 / .m4a / .wav file.

Audio handling

Whatever the publisher serves is decoded and resampled to 16 kHz mono PCM before the model sees it, so one guarantee about the input holds for every feed on the internet. Downloads are capped at 400 MB and stopped mid-stream at the cap, not after it.

Engine

whisper.cpp with Silero voice-activity detection, on our own machines. No third-party speech API is in the request path.

Languages

Whichever language the loaded model is for. If the audio comes back in a language that model is not configured for, the answer is LANG_UNSUPPORTED — not a confident paragraph of the wrong language.

Episode limits

4 hours of audio per episode. Longer recordings are split into parts and the transcripts stitch back in order.

Cost

One credit per 30 minutes of audio, rounded up — a 63-minute episode costs 3 credits. A run that does not produce a transcript costs nothing.

Retention

The fetched audio is deleted by the step that writes the transcript. Nothing is used to train a model.

A transcript, written top to bottom

This is the interface a job shows: the wire code first, then the first lines while the model is still writing, then the chapter count when it files. The dialogue below is sample text — the verbatim model output is in the next section, with the command that produced it.

Real output, verbatim

A landing page that shows a mock-up proves nothing, so here is the actual transcript of the clip this pipeline was built and tested against: 12.5 seconds taken from the Hard Fork episode used to probe the resolver, run through the command underneath it. Nothing has been tidied.

ffmpeg -ss 00:11:02 -t 12.5 -i episode.mp3 -ac 1 -ar 16000 clip16.wav
whisper-cli -m models/ggml-base.en.bin -f clip16.wav -l en -oj -of whout

Two things worth noticing. The first line ends mid-sentence, because the model stopped where the audio ran out — a transcript that finished the sentence would be inventing it. And "a very fancy technology person" is exactly what was said: no capitalisation cleverness, no corrected name, no dropped hesitation.

How the podcast transcription works

One machine, three heads. Every link is threaded through the same path, and the honest version of "how it works" is a schematic rather than a screenshot.

1. Resolve — what kind of link is this?

   An Apple episode link is not an audio URL, and neither is a Spotify one. Tapeclerk classifies the link first, then goes and gets the episode's own enclosure: for Apple, the title, show and duration come off the episode page's JSON-LD, the show's feed comes from the iTunes lookup API, and the audio comes from the RSS item whose title, duration and publish date match the episode. An RSS or mp3 link skips all of that and is used as given.

2. Fetch — audio and metadata, politely

   The enclosure is streamed, not buffered, with a byte cap that stops the request mid-stream rather than after the fact. Requests identify themselves as a browser where a platform requires it, follow a bounded number of redirects, and treat a feed's 15-minute cache as the only thing worth remembering. Anything that answers 401 or 403 is reported as AUTH_REQUIRED, not retried into the ground.

3. Transcribe — speakers, chapters, timecodes

   Audio is decoded to 16 kHz mono, run through Whisper with Silero voice-activity detection, and long episodes are chunked and run one at a time so peak memory stays flat on a two-hour recording. The segments come out with the offsets the model reported; the render step is what turns them into JSON, text, SRT, VTT and Markdown.

Podcast transcript formats, and which one you want

Five renderings of the same segments. One set of timings, so an SRT and a VTT cut from the same run never drift apart by a millisecond.

SRT or VTT for a podcast?

SRT if a human is going to open it in an editor, VTT if a browser is going to load it. SRT is the oldest and most widely imported caption format: index, timing line, two lines of text, blank line. VTT is its successor for the web — a header line, dot rather than comma before the milliseconds, and cue settings such as position and styling, which SRT cannot express. If you publish the episode on a site with a <video> or <audio> element, VTT is the one the player will read.

Podcast transcription errors, named

Most transcription services fail with a shrug: error, 500, "something went wrong", credits debited. Podcast links fail for specific and knowable reasons, so this is the entire failure surface, with the fix that goes with each one. The code on the left is the literal string the API returns and the UI prints.

No credits are debited for any of them. A run costs nothing unless a transcript came out of it, which is the only honest way to bill for a service whose most common failure is somebody else's paywall.

Who the transcript is for

The API in one request

The pipeline is one Elixir module today and is being wired to HTTP as this is written. The resolve step already behaves the way the public endpoint will, and the contract codes above are fixed — that is why they are on this page before the URL is.

curl -X POST https://tapeclerk.com/v1/transcriptions \
  -H "authorization: Bearer $TAPECLERK_KEY" \
  -H "content-type: application/json" \
  -d '{"url":"https://podcasts.apple.com/us/podcast/id1528594034?i=1000786488728"}'

HTTP/1.1 202 Accepted
{"job_id":"tc_9f2c…","code":"RESOLVED",
 "episode":{"show":"Hard Fork","title":"Meta Shifts the Blame …","duration_s":3776},
 "credits_cost":3,"status_url":"/v1/jobs/tc_9f2c…"}

202 and a job, never a promise about how long the run takes. Poll the status URL for progress as a fraction of elapsed audio time, and the transcript itself in any of the five formats when the job files. Draft schema; the path may move a segment before it is public, the codes will not.

What happens to the audio

The fetched file is deleted by the same step that writes the transcript, in the same function, before the job reports done. The workspace has a byte cap, so a run cannot fill a disk on its way to being deleted. Audio is not used to train anything, and no speech API is in the path — the model runs on a machine we control.

The longer version, including which code deletes the file and how to check, is on how we do it.

Questions people actually ask