Documentation

Install

subkit ships as a single static binary for amd64 and arm64 on Windows, macOS and Linux. There is nothing to install alongside it except ffmpeg, which does the media work.

Windows

The package is published to winget as AndreSantos.Subkit.

PowerShell

winget install AndreSantos.Subkit

If you would rather not use winget, every release also carries a signed .msi installer for x64 and arm64, plus a plain .zip archive. Grab them from the releases page. The MSI puts subkit on your PATH for you; with the zip, extract it and add the folder yourself.

macOS

Releases include a .dmg for Apple Silicon and Intel:

Release artefacts

subkit_<version>_darwin_arm64.dmg   # Apple Silicon
subkit_<version>_darwin_amd64.dmg   # Intel
subkit_<version>_darwin_arm64.zip   # archive, same binary

The binaries are not notarised, so the first launch needs a one-time approval — open System Settings → Privacy & Security and allow it, or clear the quarantine attribute yourself:

zsh

xattr -d com.apple.quarantine /usr/local/bin/subkit

No Homebrew formula yet. If you want brew install, go install below is the closest equivalent for now.

Linux

Tarballs for amd64 and arm64. Extract, then move the binary onto your PATH:

bash

curl -sSL https://github.com/andrerfcsantos/subkit/releases/latest/download/subkit_linux_amd64.tar.gz | tar xz
sudo install subkit_*/subkit /usr/local/bin/subkit

From source

Any platform with a Go toolchain. The module path is github.com/andrerfcsantos/subkit-codex:

Go 1.26+

go install github.com/andrerfcsantos/subkit-codex/cmd/subkit@latest

Or clone and build, which is all you need for local development — full releases use GoReleaser Pro for the MSI, DMG and winget steps, but a plain build does not:

bash

git clone https://github.com/andrerfcsantos/subkit
cd subkit
go build ./cmd/subkit

ffmpeg

subkit is a standalone CLI that uses ffmpeg, not an ffmpeg plugin. ffmpeg owns media extraction; subkit owns provider calls, artefacts, caching, cue generation and rendering. It must be on your PATH.

Platform	Command
Windows	`winget install Gyan.FFmpeg`
macOS	`brew install ffmpeg`
Debian / Ubuntu	`sudo apt install ffmpeg`
Fedora	`sudo dnf install ffmpeg`
Arch	`sudo pacman -S ffmpeg`

The ffmpeg version string is part of the audio cache key. Upgrading ffmpeg invalidates cached audio artefacts — but not transcripts, cues or rendered outputs, which key off the transcript instead. See caching.

Deepgram API key

Transcription goes through Deepgram, which reads its credential from the DEEPGRAM_API_KEY environment variable.

bash / zsh

export DEEPGRAM_API_KEY="dg_your_key_here"

PowerShell

$env:DEEPGRAM_API_KEY = "dg_your_key_here"          # this session
setx DEEPGRAM_API_KEY "dg_your_key_here"          # persist it

Put the export in your shell profile so it survives a new terminal. Commands that only read cached artefacts — render on an already-transcribed file, or anything under subkit cache — do not need the key at all.

Verify

bash

subkit version --verbose
ffmpeg -version | head -1
subkit cache path

Then run the whole pipeline on something real:

bash

subkit subtitle movie.mp4
  ✓ movie.srt

Run it a second time and it should come back in well under a second — that is the cache working. If it does not, caching explains what goes into the keys.