Documentation

CLI reference

Every command takes one or more media files or globs. Flags that shape the pipeline are available on every command that reaches the stage they affect.

Commands

Overview

subkit subtitle      <media-file>...   # whole pipeline → .srt / .vtt
subkit generate      <media-file>...   # whole pipeline → any outputs
subkit extract-audio <media-file>...   # stop after audio
subkit transcribe    <media-file>...   # stop after transcript
subkit cues          <media-file>...   # stop after cues
subkit render        <media-file>...   # render from cached artefacts
subkit cache         path|list|clean
subkit version       [--verbose]

Command	What it does
subtitle	Generate subtitle files. `--format srt` by default; repeat or comma-separate for `srt,vtt`.
generate	Generate one or more outputs of any kind. Driven entirely by `--output` specs; defaults to `subtitle:srt`.
extract-audio	Extract normalized audio artefacts. Needs `--output`, `--output-dir` or `--output-template` unless `--cache-audio` is set, because audio is otherwise run-local.
transcribe	Extract audio if needed, transcribe it, and cache the normalized transcript JSON.
cues	Build and cache subtitle cues from the transcript, without rendering a subtitle file.
render	Render outputs from cached or rebuilt artefacts. Same `--output` grammar as `generate`.
cache	`path` prints the cache root, `list` prints size and top-level artefact groups, `clean` empties it.
version	Print the version; `--verbose` adds commit information.

Output specs

generate and render take --output / -o specs shaped kind:format, repeated or comma-separated:

bash

subkit generate movie.mp4 \
  --output subtitle:srt \
  --output subtitle:vtt \
  --output script:txt \
  --output words:json

Spec	Produces
subtitle:srt	SubRip cues. Speaker labels appear on their own line as `[speaker 0]`, only when the speaker changes.
subtitle:vtt	WebVTT cues. Speakers are inline voice spans: `<v Speaker 0>`.
script:txt	The transcript text as one plain-text file. `script:md` is also accepted.
words:json	The word array from the normalized transcript: index, text, punctuated, start, end, confidence, speaker, channel, language.

Subtitle specs accept two extra attributes. algorithm= overrides the cue algorithm for that output alone, and file= sends it to an exact path:

bash

subkit generate movie.mp4 \
  --output subtitle:srt:algorithm=netflix \
  --output subtitle:vtt:algorithm=deepgram \
  --output script:txt:file=./out/notes.txt

Specs are validated before anything touches the filesystem, so a typo in one --output is reported on its own rather than half-way through a batch.

Output paths

With no path flags, outputs land next to the input: movie.srt, movie.script.txt, movie.words.json.

Flag	Effect
--output, -o	An exact path. Single input only — for `subtitle` it is the subtitle file, for `extract-audio` / `transcribe` / `cues` it is the copied artefact. (The old `--out` spelling still works but is deprecated.)
--output-dir	Write everything into this directory, keeping the derived file names.
--output-template	A path template. Tokens: `{dir}`, `{base}`, `{input_ext}`, `{kind}`, `{format}`.

bash

subkit generate "./season-1/*.mkv" \
  --output subtitle:srt --output words:json \
  --output-template "./out/{base}.{kind}.{format}"

Batch & progress

Every pipeline command accepts multiple files and glob patterns. Inputs run concurrently, and a failure on one file does not stop the rest — errors are collected and printed as a summary at the end.

Flag	Default
--concurrency, -j	`4` — maximum files processed at once.
--progress	`auto` — an interactive Bubble Tea view for multi-file terminal runs, plain logs when output is redirected. Force with `tui`, `plain` or `off`.
--fail-fast	`false` — cancel remaining queued work after the first failure.

Audio flags

Available on extract-audio and every command that runs it.

Flag	Default
--audio-format	`flac` — intermediate audio format.
--audio-stream	`0` — zero-based input audio stream to extract.
--audio-channels	`1` — output channel count.
--audio-sample-rate	`0` — keep the ffmpeg default.

Deepgram flags

Flag	Default
--provider	`deepgram`
--model	`nova-3`
--language	`en-US` — a BCP-47 hint.
--punctuate	`true`
--paragraphs	`true`
--smart-format	`true`
--diarize	`true` — speaker diarization.
--diarize-model	Deepgram diarization model version.
--utterances	`true` — utterance segmentation.
--deepgram-endpoint	The listen endpoint to call.

Subtitle flags

Available on subtitle, generate, cues and render. Every numeric flag defaults to 0, meaning use the selected algorithm's own default — so you only override what you actually care about. Full detail in cue algorithms.

Flag	Meaning
--subtitle-algorithm	`deepgram` (default) or `netflix`.
--subtitle-max-chars	Max characters per line.
--subtitle-max-lines	Max lines per cue.
--subtitle-max-words	Max words per cue — the `deepgram` algorithm's chunk size.
--subtitle-min-duration	Minimum cue duration, in seconds.
--subtitle-max-duration	Maximum cue duration, in seconds.
--subtitle-max-gap	Pause length that forces a cue boundary.
--subtitle-reading-speed	Characters per second — `netflix` only.
--subtitle-prefer-segments	`true` — prefer provider utterance segments when cueing.
--format, -f	`srt` — `subtitle` command only; repeat or comma-separate `srt,vtt`.

Cache flags

These are persistent flags: they work on every command. See caching for what goes into a key.

Flag	Effect
--cache-dir	Use a different cache directory instead of the OS default.
--no-cache	Neither read nor write the persistent cache.
--refresh	Ignore cache reads and rebuild every artefact.
--rerun	Rerun selected steps: `audio`, `transcribe`, `cues`, `render`, or `all`.
--cache-audio	Read and write persistent normalized audio artefacts instead of run-local ones.