audio-scribe/README.md

audio-scribe

Download a video, extract its audio losslessly as FLAC, and transcribe it with Whisper on whatever GPU the machine actually has.

Resumable from any completed stage, with errors that tell you what to do next.

uv sync
uv run audio-scribe doctor                      # check the environment first
uv run audio-scribe run 'https://youtu.be/...'
uv run audio-scribe run -i urls.txt --formats txt,srt

Hardware setup for the Intel path is documented separately in README-intel.md.

What it does

yt-dlp (aria2c)  ->  ffmpeg  ->  Whisper        ->  txt / srt / vtt / json
   video.mkv         audio.flac   OpenVINO GenAI

Each video becomes one job directory under --workdir (default transcripts/):

transcripts/index.json                    <- which jobs each URL expanded to
transcripts/jobs/youtube-<id>/
  state.json          media/video.mkv     out/transcript.{txt,srt,vtt,json}
  events.jsonl        media/audio.flac    logs/{job,aria2}.log

Resume

Artifacts on disk are the source of truth. state.json records only what the filesystem cannot answer — chiefly why a file is absent. There is deliberately no stored "current stage": persisting one is how "marked done but the file is gone" bugs happen. Every run verifies what is actually present (ffprobe duration > 0, non-empty, audio length matching the video) and enters at the first stage whose output does not check out.

Transcript	FLAC	Video	Runs
missing	ok	anything	transcribe, outputs
missing	missing	ok	extract, transcribe, outputs
missing	missing	missing	everything
ok	—	—	nothing

Killing a run mid-download resumes rather than restarting, because yt-dlp keeps its .part and aria2 keeps its control file. How much survives depends on the checkpoint interval, not on the size of the .part: with --file-allocation=falloc the file is full-size from the first second, and only the pieces recorded in the control file are skipped. A .part without that control file is discarded and restarted, because aria2 writes segments out of order, so such a file is sparse with holes rather than a valid prefix -- resuming from its length would produce a video that stops being the source partway through.

A video that exists but fails verification is unlinked before re-downloading. yt-dlp's overwrite default is off, so it would otherwise report the corrupt file as "already downloaded" and skip it forever. Verification checks the recorded byte count as well as the duration: Matroska and WebM write the duration into the header, so a file truncated to a kilobyte still probes as its full length.

Deleting one subtitle file re-renders it from the segments saved in transcript.json instead of re-transcribing the whole recording.

state.json is a convenience, not a dependency. If it is unreadable the record is rebuilt: the job directory is scanned for the video, the FLAC and the written outputs, events.jsonl supplies why an artifact is absent so a deletion you asked for is not mistaken for data loss, and transcript.json supplies how the transcript was produced so a finished job is not transcribed again. Delete it on a completed job and the next run still reports "already complete".

index.json maps each URL to the jobs it expanded to. Re-running a single video is therefore answered from disk with no metadata request at all — it works with no network — and a URL that has been seen before still resumes when the source has become unreadable, saying so. A playlist is always re-read, since that request is the only way to notice videos added to it since the last run.

--dry-run prints the plan for every job without touching anything.

Keeping or discarding media

Video and audio are kept by default.

Flag	Effect
--no-retain-video	delete the video once the job is complete
--no-retain-audio	delete the FLAC once the job is complete
--no-retain	both

These are cleanup flags: deletion is the very last step of a job, after every stage has finished and the outputs are published. A job that fails or is interrupted keeps its media, so resume still works. What you actually give up is re-run flexibility: re-transcribing later with a different --language, --model or --task will need another download.

These flags prompt once per run. On a non-TTY they refuse outright rather than proceeding — a piped or cron invocation should never delete gigabytes with nobody seeing the warning. Pass --yes to confirm non-interactively.

Hardware routing

Detection runs in two phases: a cheap hardware probe that imports nothing, then a toolchain probe that may import. The toolchain probe is only reached once the hardware is confirmed, which is what keeps torch off a machine with no NVIDIA or AMD GPU.

Order is NVIDIA → AMD → Intel GPU → CPU, and --device overrides it.

Fallback happens at runtime, not at detection: constructing the backend and its first generate() are both guarded, because a /dev/dri permission failure and an OpenCL JIT failure surface there rather than at device enumeration. A backend that fails is demoted for the rest of the process, so a long batch does not retry it once per job. An explicit --device never falls back silently — getting the CPU when you asked for the GPU would make any measurement a lie.

NVIDIA and AMD are interface-only in this build. Detection and routing are real and the error says what to implement, but there is no inference code: the cached model is OpenVINO IR, which cannot load on CUDA or ROCm, and neither path could be tested here. CTranslate2 has no ROCm support, so they are genuinely two implementations rather than one.

Download speed

yt-dlp already passes aria2c -x16 -j16 -s16 --min-split-size 1M, and -x16 is aria2's per-server cap, so re-sending connection counts changes nothing. What this adds is the flags that do:

Flag	aria2 default	Why
--retry-wait=3	0	retrying with no delay burns all five tries in under a second
--timeout=30 / --connect-timeout=15	60	a dead connection otherwise holds a slot for a full minute
--lowest-speed-limit=50K	0 (off)	without it a wedged connection hangs forever
--disk-cache=64M	16M	sixteen writers at out-of-order offsets thrash a small cache
--file-allocation=falloc	none	instant on btrfs/ext4/xfs; avoids fragmenting multi-GB files
--auto-save-interval=20	60	the control file is what a resume reads; a kill inside the first minute otherwise preserves zero completed pieces
--log=logs/aria2.log	none	the console level hides everything, leaving no forensics

--continue is deliberately never passed — see the .part note above.

aria2c only handles http/https/ftp/ftps, so HLS and DASH fall through to yt-dlp's native downloader; --concurrent-fragments is the knob there. A missing aria2c downgrades with a warning rather than failing.

Because yt-dlp calls an external downloader exactly once and does not retry it, the retry loop lives here instead.

Options worth knowing

--formats txt,srt,vtt,json · --language en · --task translate · --playlist (a URL carrying &list= stays one video unless you ask) · --audio-profile whisper (16 kHz mono FLAC instead of source quality) · --force / --force-stage · --cookies-from-browser firefox · --js-runtime · -v

Requirements

ffmpeg, ffprobe, and optionally aria2c. Everything else comes from uv sync, including the deno binary YouTube needs for its signature challenges — yt-dlp defaults to deno only, and installing it as a dependency means it works under cron without any PATH setup.

Installing

Either route puts audio-scribe on your PATH; audio-scribe doctor tells you whether the machine can actually run it.

As a tool (needs uv; tracks nothing but what it installed):

uv tool install .          # then: audio-scribe doctor
uv tool install . --reinstall     # pick up later commits
uv tool install . --editable      # or track the checkout instead

As a self-contained directory (needs neither Python nor uv at runtime):

scripts/build-binary.sh    # then: dist/audio-scribe/audio-scribe doctor

~450 MB, most of it OpenVINO and its 47 runtime-loaded plugins. It is onedir rather than onefile on purpose: onefile extracts the whole bundle to /tmp on every launch. Move or copy the whole audio-scribe/ directory, not just the executable inside it. ffmpeg, ffprobe and aria2c are still expected on the system either way — they are not bundled.

Development

uv sync
pre-commit install --hook-type pre-commit --hook-type pre-push --hook-type commit-msg
uv run pytest

Commits run ruff, pyright and the full suite at 100% coverage; pushes run pylint and mypy. No unit test touches the GPU, the network or a real model, which is what keeps the commit gate fast. Live checks sit behind AUDIO_SCRIBE_LIVE=1.

Conventional commits are enforced.