chough

chough

use chough for fast, CPU-only transcription of audio or video. it supports plain text, timestamped JSON, and WebVTT subtitles.

install

• Arch Linux: paru -S chough-bin
• macOS: brew install --cask hyperpuncher/tap/chough
• Windows: winget install chough
• source: go install github.com/hyperpuncher/chough/cmd/chough@latest

ffmpeg is required. the first run downloads the roughly 650 MB model into the operating system's user cache under chough/models/<model-name>.

common usage

flags must appear before the input file.

# text to stdout
chough audio.mp3

# audio from stdin
cat audio.mp3 | chough

# timestamped JSON
chough -f json podcast.mp3 > transcript.json

# WebVTT subtitles
chough -f vtt -o subtitles.vtt video.mp4

video input is supported whenever ffmpeg supports the format.

cli flags

flag	purpose	default
-c, --chunk-size INT	chunk size in seconds; maximum 300	20
-f, --format FORMAT	text, json, or vtt	text
-o, --output FILE	write output to a file	stdout
-r, --remote	use the server configured by CHOUGH_URL	off

prefer the default 20-second chunk size.

remote mode

set CHOUGH_URL to an HTTP or HTTPS server and pass --remote:

CHOUGH_URL=http://localhost:8080 chough --remote audio.mp3

when deciding whether to use an available remote server, check ${CHOUGH_URL}/health first. fall back to local transcription if it is unavailable unless the user explicitly requires remote mode.

server mode

start a server that keeps the model loaded between requests:

chough --server --port 8080

chough --server \
	--host 0.0.0.0 \
	--port 8080 \
	--workers 2 \
	--queue-size 10

flag	purpose	default
--host	listen address	0.0.0.0
--port	listen port	8080
--workers	concurrent audio-preparation workers	2
--queue-size	maximum queued requests	10
--max-upload	maximum audio size in MB	1024
--allow-private-urls	allow URL downloads from private networks	off

server mode has no authentication, TLS, CORS policy, or rate limiting. do not expose it directly to the public internet; use a trusted reverse proxy when those controls are required.

URL transcription blocks loopback, private, link-local, multicast, and other special-use destinations, including after redirects. only use --allow-private-urls for trusted LAN or homelab sources.

HTTP API

method	endpoint	purpose
POST	/transcribe	transcribe an upload, public URL, or base64 audio
GET	/health	inspect model and queue status

# upload
curl -X POST http://localhost:8080/transcribe \
	-F "file=@audio.mp3" \
	-F "format=json"

# public URL
curl -X POST http://localhost:8080/transcribe \
	-H "Content-Type: application/json" \
	-d '{"url":"https://example.com/audio.mp3","format":"vtt"}'

# base64
curl -X POST http://localhost:8080/transcribe \
	-H "Content-Type: application/json" \
	-d '{"base64":"...","format":"text"}'

curl http://localhost:8080/health

JSON output

JSON chunks always contain start_time, end_time, and text. when supplied by the recognizer, they also contain aligned arrays:

• tokens: recognizer tokens
• timestamps: token start times in seconds
• durations: token durations in seconds
• log_probs: token log probabilities

optional arrays are omitted when they are unavailable or not aligned with the tokens.

environment

• CHOUGH_MODEL: custom model directory
• CHOUGH_URL: remote server URL for --remote; must start with http:// or https://

troubleshooting

• ffmpeg errors: confirm ffmpeg is installed and supports the input format
• model errors: confirm the user cache directory is writable, or set CHOUGH_MODEL
• memory pressure: try a smaller positive --chunk-size

resources: github