transcribe

Audio & video transcription CLI using Parakeet V3 on Apple Silicon.

Features

• Fast local transcription - ~1 min for 1 hour of audio on M4
• Audio, video, or URL - local files, whole folders, or any yt-dlp supported site
• Multilingual - Parakeet V3 supports 25 languages with auto-detection
• Auto-paragraphing - Groups text by natural speech pauses (>1.5s gaps)
• Optional timestamps - [MM:SS] markers with -t flag
• Smart filenames - Uses video title, or kebab-case with -k
• Markdown output - Includes title, source, duration, date

Installation

Dependencies:

# ffmpeg (audio extraction) and yt-dlp (URL downloads)
brew install ffmpeg yt-dlp

# parakeet-mlx
pipx install parakeet-mlx

Nix:

nix run github:flowerornament/transcribe/release -- --help
nix profile add github:flowerornament/transcribe/release

The flake advertises the public flowerornament.cachix.org cache. Released packages are published before the release branch moves, so consumers either receive the cached package or remain on the previous release.

For live development, ./ship.sh symlinks transcribe.py into the local Nix configuration.

Usage

transcribe "https://youtube.com/watch?v=..."   # URL
transcribe screencast.mp4                      # video file
transcribe recording.opus                      # audio file
transcribe ./voice-notes/ -r                   # every media file in a tree
transcribe a.mp4 b.opus -o ./out/ -f           # batch into a directory

Supported inputs

• Audio: .aac .flac .m4a .mp3 .ogg .opus .wav .wma
• Video: .3gp .avi .flv .m4v .mkv .mov .mp4 .mpeg .mpg .ts .webm .wmv (audio track extracted via ffmpeg)
• URLs: anything yt-dlp supports. Chrome cookies are used when available for age/login-gated videos, and skipped automatically when they aren't.

Flags

Flag	Description
-t, --timestamps	Add [MM:SS] timestamp at start of each segment
-k, --kebab	Use kebab-case filename (video-title-transcript.md)
-o, --output PATH	Output file (single input) or directory (multiple inputs)
-f, --force	Overwrite existing files and skip batch confirmation
-r, --recursive	Recursively scan directories for media files

Exits non-zero if any input fails to transcribe.

Output

Default filename: Video Title Transcript.md for URLs, <file stem>.md for local files.

# Transcript: Video Title

**Source:** https://youtube.com/watch?v=...
**Duration:** 5:32
**Transcribed:** 2026-01-14

---

## Transcript

First paragraph of transcribed speech, automatically
grouped by natural pauses in the audio.

Second paragraph begins after a pause of 1.5+ seconds.

With -t timestamps:

[00:00] First segment with timestamp.

[00:15] Another segment with timestamp.

Requirements

• macOS with Apple Silicon (M1/M2/M3/M4)
• Python 3, ffmpeg/ffprobe, parakeet-mlx (and yt-dlp for URLs)
• ~2.3GB disk space for Parakeet model (downloads on first run)

---

Built with Claude Code