A terminal transcription workbench for local media and YouTube. transcribe
combines an interactive TUI with a scriptable CLI, a resumable job engine, and
a local SQLite library.
It supports OpenAI, Groq, Fireworks AI, and existing YouTube subtitles. API keys are read from the current process environment and are never saved.
- Interactive fuzzy-search TUI and a noninteractive CLI
- Local audio/video, individual YouTube videos, and playlists
- Resumable chunked jobs with retries and configurable concurrency
- OpenAI speaker diarization
- Named alternate runs and AI-assisted transcript comparison
- Searchable viewer, OSC 52 clipboard copy, and
$EDITORhandoff - TXT and structured JSON exports
- Private XDG storage with portable manifests beside every run
The prebuilt release currently supports Linux x86-64, including WSL 2.
ffmpegandffprobefor local media and audio preparationyt-dlpfor YouTube URLs and subtitles- One provider key for hosted transcription, unless using YouTube subtitles
On Ubuntu or Debian:
sudo apt install ffmpeg yt-dlpInstall the latest standalone binary to ~/.local/bin:
curl -fsSL https://raw.githubusercontent.com/DovieW/transcribe-cli/master/install.sh | bashMake sure ~/.local/bin is on PATH, then inspect the runtime dependencies:
transcribe doctorThe installer verifies the release checksum before replacing the binary. Set
TRANSCRIBE_INSTALL_DIR to choose another destination or
TRANSCRIBE_VERSION=v2.0.1 to install a specific release.
Building requires npm; the pinned development dependencies provide Bun and TypeScript locally.
git clone https://github.com/DovieW/transcribe-cli.git
cd transcribe-cli
npm ci
npm test
npm run check
npm run build
install -Dm755 dist/transcribe ~/.local/bin/transcribeAfter compilation, the transcribe executable does not require npm, Node.js,
or Bun.
Export only the key for the provider you want to use:
export GROQ_API_KEY='...'# or OPENAI_API_KEY / FIREWORKS_API_KEYDo not put keys in this repository. Use your shell's existing secret manager or another local, access-controlled mechanism.
The OpenAI picker includes gpt-4o-transcribe,
gpt-4o-mini-transcribe, whisper-1, and
gpt-4o-transcribe-diarize. Groq offers its Whisper Large v3 models, and
Fireworks offers its Whisper v3 models. Availability, limits, and billing are
controlled by each provider.
Run without arguments to open the TUI:
transcribeOr use the CLI directly:
transcribe run recording.mp4 --name interview --provider openai --model gpt-4o-transcribe
transcribe run 'https://www.youtube.com/watch?v=...' --provider youtube-transcript
transcribe resume RUN_ID
transcribe restart RUN_ID
transcribe compare RUN_A RUN_B
transcribe export RUN_ID --format json --output ./transcript.json
transcribe settings
transcribe doctorRun transcribe --help for every job setting.
New installations use:
- Configuration:
${XDG_CONFIG_HOME:-~/.config}/transcribe/config.json - Library:
${XDG_STATE_HOME:-~/.local/state}/transcribe
Override these with TRANSCRIBE_CONFIG_DIR and TRANSCRIBE_STATE_DIR.
Settings, the SQLite database, source metadata, work files, and transcripts are
created with private permissions. Existing users of the earlier dotfiles build
continue using its library automatically and have their settings copied to the
new configuration path.
Local media is normalized on your machine, then audio chunks are uploaded to
the provider you select. YouTube mode also sends the URL to yt-dlp/YouTube.
Transcript comparison and optional subtitle cleanup use OpenAI. Review the
chosen provider's data policies before processing sensitive recordings.
npm ci
npm test
npm run check
npm run buildTests mock network requests; they do not require provider keys or make paid API calls. See CONTRIBUTING.md for the contribution workflow.