ytranscript 0.1.0

Fetch YouTube video transcripts with automatic Whisper fallback

ytranscript

Fetch YouTube video transcripts from the command line. Uses YouTube's caption API when available, falls back to local Whisper transcription for videos without captions.

Installation

pip install ytranscript

System requirement: ffmpeg must be installed for the Whisper fallback.

# macOS
brew install ffmpeg

# Ubuntu/Debian
apt install ffmpeg

Usage

# Basic — auto-detect language
ytranscript 'https://www.youtube.com/watch?v=VIDEO_ID'

# Markdown output with metadata
ytranscript URL -f md

# JSON output (for pipelines)
ytranscript URL -f json

# Include timestamps
ytranscript URL --timestamps

# Force Whisper transcription
ytranscript URL --whisper

# Specify language
ytranscript URL --lang zh

# Choose Whisper model (tiny/base/small/medium/large)
ytranscript URL --model small

Batch processing

# Multiple URLs at once
ytranscript URL1 URL2 URL3 --output-dir ./transcripts/

# From a file (one URL per line)
ytranscript --batch urls.txt --output-dir ./transcripts/

# Entire playlist or channel
ytranscript 'https://www.youtube.com/playlist?list=PLAYLIST_ID' --output-dir ./transcripts/

Options

Flag	Description
-f plain|json|md	Output format (default: plain)
--lang CODE	Language code, e.g. en, zh, ja (default: auto-detect)
--timestamps	Prefix each line with [MM:SS]
--whisper	Force local Whisper transcription
--model SIZE	Whisper model: tiny, base, small, medium, large (default: base)
--no-metadata	Skip title/channel/duration fetch
--no-cache	Bypass disk cache
--batch FILE	Read URLs from a file
--output-dir DIR	Write each transcript to DIR/{video_id}.{ext}

Caching

Transcripts are cached at ~/.cache/ytranscript/ by default. Subsequent calls for the same video are instant. Use --no-cache to force a fresh fetch.

Environment variables

Variable	Description
YT_TRANSCRIPT_MODEL	Default Whisper model size (e.g. small)

How it works

1. Tries youtube-transcript-api — fast, no download needed
2. If no captions exist, downloads audio via yt-dlp and transcribes locally with faster-whisper

This covers ~100% of videos, including those without any captions.

License

MIT