Documentation

Caching

Transcription is the expensive step — in time and in money. subkit treats the whole pipeline as a chain of cached artefacts so that step happens once per file, no matter how many times you change your mind about the output.

The idea

Each stage writes an artefact keyed by its inputs. Re-running the same command with the same input and options reuses those artefacts, and if a final output file has gone missing it is restored from the render cache rather than rebuilt.

bash

subkit subtitle movie.mp4
  ✓ movie.srt  — 31.4s: ffmpeg, Deepgram, cues, render

rm movie.srt
subkit subtitle movie.mp4
  ✓ movie.srt  — 0.08s: restored from the render cache

The useful consequence is that changing a late option is cheap. Switching cue algorithm, adding a format, or re-rendering into a different directory all reuse the transcript, so they cost no provider call at all.

Cache keys

Keys are hashes over the things that would change the result. Each stage keys off the artefact above it, so invalidating something early cascades and something late does not:

audio source media hash + audio options (format, stream, channels, sample rate) + pipeline version + the ffmpeg version string

transcript audio key + provider options (model, language, punctuate, paragraphs, smart-format, diarize, utterances) + pipeline version

cues transcript key + subtitle options (algorithm and every --subtitle-* value) + pipeline version

render cue or transcript key + output kind and format + pipeline version

So: upgrading ffmpeg invalidates cached audio but not the transcript. Changing --model invalidates the transcript and everything after it. Changing --subtitle-algorithm invalidates only cues and renders. Adding --output words:json to a file you have already transcribed invalidates nothing — it is a new render off an existing transcript.

The raw provider response is cached alongside the normalized transcript, so a pipeline-version bump can often rebuild the normalized transcript from the stored response instead of calling Deepgram again.

Audio is temporary by default

Normalized audio grows quickly, so it is not kept by default — extraction writes a run-local artefact used for the provider upload or an explicit copy, and then it goes away. Transcripts, raw provider responses, cues and rendered outputs are all cached persistently.

bash

subkit subtitle movie.mp4 --cache-audio   # keep and reuse audio

This is also why extract-audio insists on --output, --output-dir or --output-template unless --cache-audio is set: without one of them, it would extract audio and then throw it away.

Invalidating

Flag	Effect
--rerun <steps>	Rerun selected steps and everything downstream. Accepts `audio`, `transcribe`, `cues`, `render` or `all`, repeated or comma-separated.
--refresh	Ignore every cache read and rebuild all artefacts. Results are still written back.
--no-cache	Neither read nor write the persistent cache. Nothing is left behind.
--cache-dir <path>	Use a different cache root — handy for a per-project cache you can delete wholesale.

bash

subkit subtitle movie.mp4 --rerun transcribe
subkit subtitle movie.mp4 --rerun audio,transcribe
subkit subtitle movie.mp4 --refresh
subkit subtitle movie.mp4 --no-cache
subkit --cache-dir ./.subkit-cache subtitle movie.mp4

--rerun transcribe means a new provider call. Reach for it when the transcription itself is wrong, not when you want different cues — for that, change a --subtitle-* flag and let the cue stage invalidate on its own.

Inspecting

bash

subkit cache path    # print the cache root
subkit cache list    # size and top-level artefact groups
subkit cache clean   # empty it

Where it lives

The default cache root comes from Go's os.UserCacheDir(), with a subkit folder inside it:

Platform	Default root
Windows	`%LocalAppData%\subkit`
macOS	`~/Library/Caches/subkit`
Linux	`$XDG_CACHE_HOME/subkit`, or `~/.cache/subkit`

Run subkit cache path to see the resolved value on your machine rather than guessing from the table.