SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsmedia-transcriber

media-transcriber

Office & productivity

View repository

Updated 10-15 09:39

About this skill

media-transcriber — audio/video verbatim transcription

Author: Produced by 43 COLLEGE 凯寓 (KAIYU) Version: v1.0

Use OpenAI Whisper to transcribe video/audio files into timestamped verbatim transcripts. Supports speaker diarization and Claude punctuation restoration.

On first run, it automatically creates a virtual environment, installs dependencies, and downloads the Whisper model (turbo is about 1.5GB). The whole process is automatic and requires no manual configuration.

Important: You must inform the user in advance before the first transcription— model download + dependency installation may take 5-15 minutes (depending on network speed). During this period, the terminal may show no new output for a long time; this is not a freeze. Be sure to explain this to the user before executing the transcription command, to avoid the user force-interrupting midway and corrupting the environment.

If an error occurs due to missing ffmpeg, or if speaker diarization needs to be configured, read SETUP.md to complete the initial configuration.

Cross-platform compatibility

Item macOS / Linux Windows
Python python3 python
Path separator / \
Script path ${CLAUDE_SKILL_DIR}/scripts/transcribe.py ${CLAUDE_SKILL_DIR}\scripts\transcribe.py

About ${CLAUDE_SKILL_DIR}: This is a documentation placeholder representing this skill's installation directory (usually ~/.claude/skills/media-transcriber/). Claude automatically replaces it with the actual path when executing commands in bash.Users should not copy this string directly into the terminal— directly copying and pasting will fail because the variable is undefined. Either hand the command to the AI to execute, or replace it yourself with the specific directory.

How to invoke

Quality mode (default recommendation)

With speaker diarization + Claude punctuation restoration, suitable for formal content archival. Speed is about 1/2 of real time (turbo model, CPU).

# 预检环境和权限（推荐首次运行）
python3 ${CLAUDE_SKILL_DIR}/scripts/transcribe.py --check

# 质量模式：说话人识别 + 标点恢复
python3 ${CLAUDE_SKILL_DIR}/scripts/transcribe.py "video.mp4" --language zh --diarize --punctuate

# 指定说话人数量（不指定则自动检测）
python3 ${CLAUDE_SKILL_DIR}/scripts/transcribe.py "video.mp4" --language zh --diarize --punctuate --speakers 2

# 整个文件夹批量转录（质量模式）
python3 ${CLAUDE_SKILL_DIR}/scripts/transcribe.py "/path/to/folder" --language zh --diarize --punctuate

# 强制覆盖已有逐字稿
python3 ${CLAUDE_SKILL_DIR}/scripts/transcribe.py "video.mp4" --language zh --diarize --punctuate --overwrite

Python inline invocation:

import sys; sys.path.insert(0, f"{CLAUDE_SKILL_DIR}/scripts")
from transcribe import transcribe_file

transcribe_file("video.mp4", language="zh", diarize=True, punctuate=True)

Fast mode

No speaker diarization, no punctuation restoration, 3-5 times faster, suitable for quick content preview.

# 快速模式：仅转录，无说话人，无标点
python3 ${CLAUDE_SKILL_DIR}/scripts/transcribe.py "video.mp4" --language zh

# Windows 快速模式
python ${CLAUDE_SKILL_DIR}\scripts\transcribe.py "C:\path\to\video.mp4" --language zh

Environment information

  • Virtual environment: Automatically created on first run in the skill directory's venv/
  • Model storage: models/(localized, does not depend on system cache)
  • Auto-install: openai-whisper, numpy<2.4, numba, anthropic
  • Install on demand: pyannote-audio (only when --diarize is used)
  • GPU: Automatically falls back to CPU when there is no CUDA

Model selection

Model Size CPU speed Chinese quality Scenario
turbo 1.5GB ~2x real time Excellent Default recommendation
medium 1.4GB ~3x real time Good turbo alternative
small 461MB ~1x real time Average Pursuing speed
base 139MB ~0.3x real time Poor Quick preview

"Nx real time" = 1 minute of audio requires N minutes of processing (CPU)

Output format

Each file generates <原文件名>_逐字稿.txt：

No speaker diarization(default):

# 文件名

[00:00 - 00:05] 文本内容
[00:05 - 00:12] 文本内容

---

# 完整文本

完整的文本内容。

With speaker diarization（--diarize）：

# 文件名

**[说话人A]**
[00:00 - 00:05] 文本内容

**[说话人B]**
[00:05 - 00:12] 文本内容

---

# 完整文本

[说话人A] 第一段话内容。
[说话人B] 第二段话内容。

Supported formats:.mp4 .mkv .avi .mov .wmv .flv .webm .mp3 .wav .flac .aac .ogg .m4a .wma

Key design

  • Automatic bootstrap: On first run, automatically creates a venv and installs dependencies; afterward, directly use python3 Just call it, no activate needed
  • Anti-hallucination: condition_on_previous_text=False Prevent error propagation + ffprobe duration filtering of overlong segments
  • Punctuation guidance: Specify --language zh automatically injects initial_prompt guides punctuation output
  • Claude punctuation restoration: --punctuate Call Claude Haiku to perform overall punctuation restoration on the full text
  • Speaker matching: Match Whisper segments to pyannote speaker segments by time overlap amount
  • On-demand installation: pyannote-audio is large, only when using --diarize is it automatically installed
  • Model localization: Whisper models are stored in the models/ directory, loaded via download_root loading

Known limitations

  1. NumPy version: numba requires numpy<2.4, the version is pinned during automatic installation
  2. Long video memory: videos over 2 hours with the turbo model require about 4-6GB RAM
  3. Background music: pure music segments at the end may retain a small amount of misrecognition
  4. Speaker recognition accuracy: accuracy decreases when multiple people speak simultaneously
  5. Punctuation restoration speed: Claude API calls have about 3-10 seconds of latency