Run any Skill in Manus with one click

mk-youtube-audio-transcribe

Transcribe audio to text using local whisper.cpp. Use when user wants to convert audio/video to text, get transcription, or speech-to-text.

Run Skill in Manus

Overview

Transcribe audio to text using local whisper.cpp. Use when user wants to convert audio/video to text, get transcription, or speech-to-text.

Install command

npx skills add https://github.com/kouko/monkey-knowledge-youtube-skills --skill mk-youtube-audio-transcribe

Copy and paste this command into Claude Code to install the skill

Source

kouko/monkey-knowledge-youtube-skills

Stars0

Forks0

UpdatedMarch 19, 2026 at 02:23

File Explorer

22 files

SKILL.md

readonly

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.

# In terminal (to see progress bar)
./scripts/download-model.sh medium      # 1.4GB
./scripts/download-model.sh belle-zh    # 1.5GB (Chinese)
./scripts/download-model.sh kotoba-ja   # 1.4GB (Japanese)
./scripts/download-model.sh --list      # Show all available models

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.

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"}

mk-youtube-audio-transcribe

More from this repository

More from this repository

YouTube Audio Transcribe

Quick Start

Parameters

Examples

How it Works

Output Format

Output Fields

Filename Format

JSON File Format

Models

Standard Models

Language-Specialized Models

Auto-Selection (model=auto)

Notes

Model Download

Next Step

YouTube Audio Transcribe

Quick Start

Parameters

Examples

How it Works

Output Format

Output Fields

Filename Format

JSON File Format

Models

Standard Models

Language-Specialized Models

Auto-Selection (model=auto)

Notes

Model Download

Next Step