youtube-transcriber

# YouTube Transcriber

One-command transcription for any YouTube video — even when subtitles are disabled.

**How it works:**
1. Tries to fetch existing YouTube subtitles first (free, instant)
2. If subtitles are disabled/unavailable → downloads audio → transcribes via OpenAI Whisper API

## Prerequisites

- `yt-dlp` — `brew install yt-dlp` or `pip install yt-dlp`
- `ffmpeg` — `brew install ffmpeg`
- `OPENAI_API_KEY` environment variable set

## Usage

```bash
# Basic — auto-detect best method
{baseDir}/scripts/transcribe.sh "https://www.youtube.com/watch?v=VIDEO_ID"

# Specify language (improves accuracy for non-English)
{baseDir}/scripts/transcribe.sh "https://www.youtube.com/watch?v=VIDEO_ID" --lang zh

# Custom output path
{baseDir}/scripts/transcribe.sh "https://www.youtube.com/watch?v=VIDEO_ID" --out /tmp/transcript.txt

# Force Whisper (skip subtitle check)
{baseDir}/scripts/transcribe.sh "https://www.youtube.com/watch?v=VIDEO_ID" --force-whisper

# Keep downloaded audio file
{baseDir}/scripts/transcribe.sh "https://www.youtube.com/watch?v=VIDEO_ID" --keep-audio
```

## Options

| Option | Description | Default |
|--------|-------------|---------|
| `--lang <code>` | Language hint (ISO 639-1: en, zh, ja, ko, etc.) | auto-detect |
| `--out <path>` | Output transcript file path | `/tmp/yt_transcript_<VIDEO_ID>.txt` |
| `--force-whisper` | Skip subtitle check, always use Whisper API | off |
| `--keep-audio` | Keep the downloaded audio file after transcription | off (deletes audio) |
| `--audio-bitrate <kbps>` | Audio compression bitrate | 64 |

## How It Works

```
YouTube URL
    │
    ├─► Try yt-dlp subtitles (free, instant)
    │       │
    │       ├─ Found → Clean & output transcript ✓
    │       │
    │       └─ Not found / disabled
    │               │
    │               ▼
    └─► Download audio (yt-dlp + ffmpeg)
            │
            ├─ Compress to mono, low bitrate (fit 25MB API limit)
            │
            ▼
        OpenAI Whisper API → tran...

# YouTube Transcriber

One-command YouTube video transcription for [Claude Code](https://claude.com/claude-code). Works even when YouTube subtitles are disabled.

## How It Works

1. **Fast path**: Tries to fetch existing YouTube subtitles (free, instant)
2. **Fallback**: Downloads audio → compresses → transcribes via OpenAI Whisper API

```
YouTube URL → [subtitles available?] → YES → clean transcript ✓
                                     → NO  → download audio → Whisper API → transcript ✓
```

## Install

```bash
npx clawhub install youtube-transcriber
```

Or install directly from GitHub:

```bash
# Clone to your Claude Code skills directory
git clone https://github.com/EdisonChenAI/youtube-transcriber.git ~/.claude/skills/youtube-transcriber
```

## Prerequisites

- **yt-dlp**: `brew install yt-dlp` or `pip install yt-dlp`
- **ffmpeg**: `brew install ffmpeg`
- **OPENAI_API_KEY**: Required only when subtitles are unavailable

## Usage

```bash
# Basic usage
./scripts/transcribe.sh "https://www.youtube.com/watch?v=VIDEO_ID"

# Chinese video
./scripts/transcribe.sh "https://www.youtube.com/watch?v=VIDEO_ID" --lang zh

# Custom output path
./scripts/transcribe.sh "https://www.youtube.com/watch?v=VIDEO_ID" --out ./transcript.txt

# Force Whisper API (skip subtitle check)
./scripts/transcribe.sh "https://www.youtube.com/watch?v=VIDEO_ID" --force-whisper

# Keep the downloaded audio file
./scripts/transcribe.sh "https://www.youtube.com/watch?v=VIDEO_ID" --keep-audio
```

## Options

| Option | Description | Default |
|--------|-------------|---------|
| `--lang <code>` | Language hint (en, zh, ja, ko, etc.) | auto-detect |
| `--out <path>` | Output transcript file path | `/tmp/yt_transcript_<ID>.txt` |
| `--force-whisper` | Always use Whisper API | off |
| `--keep-audio` | Keep downloaded audio | off |
| `--audio-bitrate <kbps>` | Compression bitrate | 64 |

## Cost

| Method | Cost | Speed |
|--------|------|-------|
| Subtitles available | Free | Instant |
| Whisper...