@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 whisper-cli, yt-dlp, and ffmpeg, downloads a Whisper model, and optionally installs the agent skill for your AI coding tool. It uses Homebrew on macOS, apt on Debian or Ubuntu, and a trx-managed binary directory on Windows.

Windows

Run these commands in PowerShell as the Windows user who will run trx:

powershell -c "irm bun.sh/install.ps1 | iex"
bun add --global @crafter/trx
trx init --yes --backend local --model small --language es
trx doctor --output json

The local backend keeps the media and transcript on the laptop. Windows stores Whisper, ffmpeg, ffprobe, and yt-dlp in %USERPROFILE%\.trx\bin. Setup prefers winget and falls back to checksum-verified portable downloads when App Installer is unavailable. --yes makes setup non-interactive for IT and CI. Company policy can still block Bun, GitHub, Hugging Face, or unsigned third-party software, so IT approval remains the final gate.

Large local videos are not uploaded. trx extracts a 16 kHz mono WAV and transcribes that locally. Keep enough free disk space for the source, the temporary WAV, the model, and the transcript outputs.

trx transcribe "C:\Users\me\Videos\meeting.mp4" --language es --output-dir "C:\Users\me\Documents\trx-output" --output json

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