| name | mk-youtube-audio-transcribe |
| description | Transcribe audio to text using local whisper.cpp. Use when user wants to convert audio/video to text, get transcription, or speech-to-text. |
| license | MIT |
| metadata | {"version":"1.1.1","author":"kouko","tags":["youtube","audio","transcribe","whisper","speech-to-text"]} |
| compatibility | {"claude-code":">=1.0.0"} |
YouTube Audio Transcribe
Transcribe audio files to text using local whisper.cpp (no cloud API required).
Quick Start
/mk-youtube-audio-transcribe <audio_file> [model] [language] [--force]
Parameters
| Parameter | Required | Default | Description |
|---|
| audio_file | Yes | - | Path to audio file |
| model | No | auto | Model: auto, tiny, base, small, medium, large-v3, belle-zh, kotoba-ja |
| language | No | auto | Language code: en, ja, zh, auto (auto-detect) |
| --force | No | false | Force re-transcribe even if cached file exists |
Examples
/mk-youtube-audio-transcribe /path/to/audio/video.m4a - Transcribe with auto model selection/mk-youtube-audio-transcribe video.m4a auto zh - Auto-select best model for Chinese → belle-zh/mk-youtube-audio-transcribe video.m4a auto ja - Auto-select best model for Japanese → kotoba-ja/mk-youtube-audio-transcribe audio.mp3 small en - Use small model, force English/mk-youtube-audio-transcribe podcast.wav medium ja - Use medium model (explicit), Japanese
How it Works
- Execute:
{baseDir}/scripts/transcribe.sh "<audio_file>" "<model>" "<language>"
- Auto-download model if not found (with progress)
- Convert audio to 16kHz mono WAV using ffmpeg
- Run whisper-cli for transcription
- Save full JSON to
{baseDir}/data/<filename>.json
- Save plain text to
{baseDir}/data/<filename>.txt
- Return file paths and metadata
┌─────────────────────────────┐
│ transcribe.sh │
│ audio_file, [model], [lang]│
└──────────────┬──────────────┘
│
▼
┌─────────────────────────────┐
│ ffmpeg: convert to WAV │
│ 16kHz, mono, pcm_s16le │
└──────────────┬──────────────┘
│
▼
┌─────────────────────────────┐
│ whisper-cli: transcribe │
│ with Metal acceleration │
└──────────────┬──────────────┘
│
▼
┌─────────────────────────────┐
│ Save to files │
│ .json (full) + .txt │
└──────────────┬──────────────┘
│
▼
┌─────────────────────────────┐
│ Return file paths │
│ {file_path, text_file_path}│
└─────────────────────────────┘
Output Format
Success:
{
"status": "success",
"file_path": "{baseDir}/data/20091025__VIDEO_ID.json",
"text_file_path": "{baseDir}/data/20091025__VIDEO_ID.txt",
"language": "en",
"duration": "3:32",
"model": "medium",
"char_count": 12345,
"line_count": 100,
"text_char_count": 10000,
"text_line_count": 50,
"cached": false,
"video_id": "dQw4w9WgXcQ",
"title": "Video Title",
"channel": "Channel Name",
"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
}
Cache hit (returns existing transcription):
{
"status": "success",
"file_path": "{baseDir}/data/20091025__VIDEO_ID.json",
"cached": true,
...
}
Error (general):
{
"status": "error",
"message": "Error description"
}
Error (unknown model):
{
"status": "error",
"error_code": "UNKNOWN_MODEL",
"message": "Unknown model: invalid-name",
"available_models": ["tiny", "base", "small", "medium", "large-v3", "large-v3-turbo", "belle-zh", "kotoba-ja", "kotoba-ja-q5"]
}
When you receive UNKNOWN_MODEL error: suggest a valid model from the available_models list.
Error (model not found):
{
"status": "error",
"error_code": "MODEL_NOT_FOUND",
"message": "Model 'medium' not found. Please download it first.",
"model": "medium",
"model_size": "1.4GB",
"download_url": "https://huggingface.co/...",
"download_command": "curl -L --progress-bar -o '/path/to/models/ggml-medium.bin' 'https://...' 2>&1"
}
When you receive MODEL_NOT_FOUND error:
- Inform user: "Downloading model '{model}' ({model_size})..."
- Execute
download_command using Bash tool with timeout: 1800000 (30 minutes)
- After download completes: re-run the original transcribe command
Error (model corrupted):
{
"status": "error",
"error_code": "MODEL_CORRUPTED",
"message": "Model 'medium' is corrupted or incomplete. Please re-download.",
"model": "medium",
"model_size": "1.4GB",
"expected_sha256": "6c14d5adee5f86394037b4e4e8b59f1673b6cee10e3cf0b11bbdbee79c156208",
"actual_sha256": "def456...",
"model_path": "/path/to/models/ggml-medium.bin",
"download_command": "rm '/path/to/models/ggml-medium.bin' && curl -L --progress-bar -o '/path/to/models/ggml-medium.bin' 'https://...' 2>&1"
}
When you receive MODEL_CORRUPTED error:
- Inform user: "Model '{model}' is corrupted. Re-downloading ({model_size})..."
- Execute
download_command (removes corrupted file and re-downloads) using Bash tool with timeout: 1800000 (30 minutes)
- After download completes: re-run the original transcribe command
Output Fields
| Field | Description |
|---|
file_path | Absolute path to JSON file (with segments) |
text_file_path | Absolute path to plain text file |
language | Detected language code |
duration | Audio duration |
model | Model used for transcription |
char_count | Character count of JSON file |
line_count | Line count of JSON file |
text_char_count | Character count of plain text file |
text_line_count | Line count of plain text file |
video_id | YouTube video ID (from centralized metadata store) |
title | Video title (from centralized metadata store) |
channel | Channel name (from centralized metadata store) |
url | Full video URL (from centralized metadata store) |
Filename Format
Output files preserve the input audio filename's unified naming format with date prefix: {YYYYMMDD}__{video_id}.{ext}
Example: 20091025__dQw4w9WgXcQ.json
JSON File Format
The JSON file at file_path contains:
{
"text": "Full transcription text...",
"language": "en",
"duration": "3:32",
"model": "medium",
"segments": [
{
"start": "00:00:00.000",
"end": "00:00:05.000",
"text": "First segment..."
}
]
}
Models
Standard Models
| Model | Size | RAM | Speed | Accuracy |
|---|
| auto | - | - | - | Auto-select based on language (default) |
| tiny | 74MB | ~273MB | Fastest | Low |
| base | 141MB | ~388MB | Fast | Medium |
| small | 465MB | ~852MB | Moderate | Good |
| medium | 1.4GB | ~2.1GB | Slow | High |
| large-v3 | 2.9GB | ~3.9GB | Slowest | Best |
| large-v3-turbo | 1.5GB | ~2.1GB | Moderate | High (optimized for speed) |
Language-Specialized Models
| Model | Language | Size | Description |
|---|
| belle-zh | Chinese | 1.5GB | BELLE-2 Chinese-specialized model |
| kotoba-ja | Japanese | 1.4GB | kotoba-tech Japanese-specialized model |
| kotoba-ja-q5 | Japanese | 513MB | Quantized version (faster, smaller) |
Auto-Selection (model=auto)
When model is auto (default), the system automatically selects the best model based on language:
| Language | Auto-Selected Model |
|---|
| zh | belle-zh (Chinese-specialized) |
| ja | kotoba-ja (Japanese-specialized) |
| others | medium (general purpose) |
Example: /mk-youtube-audio-transcribe video.m4a auto zh → uses belle-zh
Notes
- File caching: If transcription already exists for this video, it will be reused (returns
cached: true)
- Force refresh: Use
--force flag to re-transcribe even if cached file exists
- Specify language for best results - enables auto-selection of specialized models (zh→belle-zh, ja→kotoba-ja)
- Use Read tool to get file content from
file_path or text_file_path
- Models must be downloaded before first use - returns
MODEL_NOT_FOUND error with download command
- Uses Metal acceleration on macOS for faster processing
- Supports auto language detection
- Audio is converted to 16kHz WAV for optimal results
- Requires ffmpeg and whisper-cli (pre-built in bin/)
Model Download
Models must be downloaded before transcription. When you receive a MODEL_NOT_FOUND error, execute the download_command with timeout: 1800000.
./scripts/download-model.sh medium
./scripts/download-model.sh belle-zh
./scripts/download-model.sh kotoba-ja
./scripts/download-model.sh --list
Next Step
After transcription completes, invoke /mk-youtube-transcript-summarize with the text_file_path from the output to generate a structured summary:
/mk-youtube-transcript-summarize <text_file_path>
IMPORTANT: Always use the Skill tool to invoke /mk-youtube-transcript-summarize. Do NOT generate summaries directly without loading the skill — it contains critical rules for compression ratio, section structure, data preservation, and language handling.
