@crafter/trx

Agent-first CLI for audio/video transcription via Whisper.

Downloads, cleans, and transcribes media from URLs or local files with machine-readable output designed for AI agents.

Install

# Run instantly, no install needed (requires Bun)
npx @crafter/trx@latest init

# Or install globally
bun add -g @crafter/trx
trx init

trx init installs dependencies (whisper-cli, yt-dlp, ffmpeg via Homebrew), downloads a Whisper model, and optionally installs the agent skill for your AI coding tool.

Skill Only

If you already have trx set up and just want the agent skill:

npx skills add crafter-station/trx -g

Usage

# Transcribe a local file
trx recording.mp4

# Transcribe from URL (YouTube, Twitter, Instagram, etc.)
trx "https://youtube.com/watch?v=..."

# Agent-friendly JSON output
trx transcribe video.mp4 --output json

# Only get the text (saves tokens)
trx transcribe video.mp4 --fields text --output json

# Dry-run (validate without executing)
trx transcribe video.mp4 --dry-run --output json

# Specify language
trx transcribe video.mp4 --language es

# Keep fillers and false starts instead of a cleaned-up transcript
trx transcribe video.mp4 --words --language es --preset verbatim

# Separate speakers (ElevenLabs Scribe)
trx transcribe interview.m4a -b elevenlabs --speakers 2

# Schema introspection for agents
trx schema transcribe

Speaker diarization

--backend elevenlabs transcribes through ElevenLabs Scribe, the one backend that reports who is speaking. --diarize prefixes every cue with its speaker; --speakers <n> adds the count when you know it and implies --diarize.

1
00:00:01,900 --> 00:00:03,400
[speaker_0] Hola, que tal? Escuchas?

2
00:00:04,520 --> 00:00:05,900
[speaker_1] Si, te escucho bien.

Scribe timestamps every word, so cues are grouped to stay readable: a pause of 0.6s or more starts a new cue, a cue is capped at 84 characters, and a change of speaker always starts a new one so no single cue attributes two people to one line. The .txt reads as a conversation, one paragraph per turn. Both flags are rejected on other backends rather than ignored.

Needs ELEVENLABS_API_KEY. On macOS trx also reads the elevenlabs entry from your login Keychain, so a key stored there does not have to be exported into every shell.

Verbatim transcripts

A transcriber cleans by default: it writes what it believes was meant, so hesitations, stretched vowels and false starts are dropped as noise. That is what you want for captions and the opposite of what you want when the transcript drives an edit, because those spans are exactly the ones worth cutting.

--preset verbatim sends an initial prompt asking for a literal transcript. The prompt has to be written in the language being spoken, so the preset needs --language and covers the languages it has a prompt for (de, en, es, fr, it, pt). Any other language is an error naming what is available rather than a prompt in the wrong language, which steers the model worse than none. Use --prompt "<text>" to write your own.

Timestamps describe the file you handed in. The cleaning stage adjusts level and noise and leaves duration alone, so a cue at 36.68s means 36.68s in the source. Up to 0.8.0 it also removed silence, which moved every cue after the first removed pause: 1.572s of accumulated drift on one 90.5s recording.

Commands

Command	Description
trx <input>	Shorthand for trx transcribe
trx init	Install deps + download Whisper model
trx transcribe <input>	Full transcription pipeline
trx doctor	Check dependency status
trx schema <resource>	JSON schema introspection

Agent-First Design

Built following agent-first CLI principles:

• --output json auto-detects: table for TTY, JSON when piped
• --dry-run validates before executing
• --fields limits response size to protect agent context windows
• trx schema runtime introspection (no docs needed)
• Input validation rejects control characters, path traversals, URL-encoded strings
• Ships with SKILL.md for Claude Code agent post-processing

Agent Skill

The bundled skill (skills/trx/SKILL.md) enables AI agents to:

1. Transcribe media via CLI
2. Post-process output (fix punctuation, accents, technical terms, repeated phrases)
3. Reference whisper-fixes.md for common Whisper mistake patterns

Pipeline

Input (URL or file)
  |
  v
[yt-dlp] Download media (if URL)
  |
  v
[ffmpeg] Clean audio (noise reduction, normalization; duration preserved)
  |
  v
[whisper-cli | OpenAI | Vercel AI Gateway | ElevenLabs Scribe] Transcribe
  |
  v
Output: .wav + .srt + .txt + JSON

Configuration

Stored at ~/.trx/config.json after trx init:

{
  "backend": "local",
  "modelPath": "~/.trx/models/ggml-small.bin",
  "modelSize": "small",
  "language": "auto",
  "threads": 8,
  "elevenlabs": { "model": "scribe_v2", "diarize": false }
}

Backends: local (whisper.cpp) | openai (OPENAI_API_KEY) | vercel (AI_GATEWAY_API_KEY) | elevenlabs (ELEVENLABS_API_KEY, speaker diarization)

Models: tiny (75MB) | base (142MB) | small (466MB) | medium (1.5GB) | large (3GB)

License

MIT