Agent Skills › Illyism/transcribe-cli › transcribe

transcribe

GitHub

使用@illyism/transcribe将视频、音频及各类媒体链接转换为SRT字幕。支持本地文件、文件夹、YouTube、Instagram等输入源，提供AI自动修正、说话人分离及自定义模型选项。

skills/transcribe/SKILL.md Illyism/transcribe-cli

Trigger Scenarios

用户要求转录媒体内容需要生成字幕或提取文本请求从音视频中提取SRT

Install

npx skills add Illyism/transcribe-cli --skill transcribe -g -y

More Options

Use without installing

npx skills use Illyism/transcribe-cli@transcribe

指定 Agent (Claude Code)

npx skills add Illyism/transcribe-cli --skill transcribe -a claude-code -g -y

安装 repo 全部 skill

npx skills add Illyism/transcribe-cli --all -g -y

预览 repo 内 skill

npx skills add Illyism/transcribe-cli --list

SKILL.md

Frontmatter

{
    "name": "transcribe",
    "description": "Transcribe any video, audio file, folder, YouTube video, Instagram Reel, Screen Studio recording, or remote URL into SRT subtitles using @illyism\/transcribe. Use whenever the user asks to transcribe, generate subtitles, extract captions, or get text from media."
}

Transcribing Media with `@illyism/transcribe`

Use npx @illyism/transcribe <input> to convert any media source into ready-to-use .srt subtitles.

Input Routing Decision Tree

Walk this decision procedure to determine the exact command for any request:

What is the input?
├── Local video or audio file (.mp4, .mov, .mkv, .mp3, .wav, etc.)
│   └── Run: npx @illyism/transcribe /path/to/media.mp4
├── Folder of media files
│   └── Run: npx @illyism/transcribe /path/to/folder/
│       (Presents an interactive picker; outputs .srt next to each selected file)
├── YouTube URL (watch, shorts, or youtu.be)
│   └── Run: npx @illyism/transcribe "https://www.youtube.com/watch?v=VIDEO_ID"
├── Instagram Reel / Post / IGTV (instagram.com/reel/, /p/)
│   ├── Default: npx @illyism/transcribe "https://www.instagram.com/reel/SHORTCODE/"
│   └── If auth fails or browser specified:
│       └── npx @illyism/transcribe "https://www.instagram.com/reel/SHORTCODE/" --cookies-from-browser chrome
├── Screen Studio recording (.screenstudio bundle or zip)
│   └── Run: npx @illyism/transcribe /path/to/recording.screenstudio
└── Any other remote URL (X/Twitter, TikTok, Vimeo, etc.)
    └── Run: npx @illyism/transcribe "https://x.com/user/status/123"

Options & Flags

Apply flags based on specific requirements:

2-Pass AI Autofix & Diarization: --autofix or --autofix <model> (e.g. google/gemini-3.7-flash). Automatically fixes phonetic mishearings, domain terms, brands, and labels distinct speakers at turns ([Speaker 1]: ...).
Disable Diarization in Autofix: --no-diarize
Custom model: -m <model> or --model <model> (e.g. whisper-1, whisper-large-v3, google/gemini-2.5-flash, nova-3)
Custom base URL: --base-url <url> (e.g. https://openrouter.ai/api/v1, https://api.groq.com/openai/v1)
Custom output location: -o /path/to/output.srt (for single files) or -o /path/to/dir/ (for folders)
Force original audio: --raw
Timecode offset: --offset 01:00:00.000 or --offset 3600 Note: Shifts subtitle start timestamps to align with NLE video editor timelines (e.g. Premiere, Final Cut, Resolve).
Install macOS Finder Quick Action: --install-mac-action Note: Adds a right-click "Transcribe Subtitles" menu option directly into Finder on macOS.

Troubleshooting Decision Tree

When an error occurs during execution, walk this recovery tree:

What is the error message?
├── "API key not found" / "OPENAI_API_KEY not found"
│   └── Set env var: export OPENAI_API_KEY=sk-... (or export OPENROUTER_API_KEY=sk-or-...) or create ~/.transcribe/config.json
├── "FFmpeg is not installed"
│   └── Install FFmpeg: brew install ffmpeg (macOS), sudo apt install ffmpeg (Linux)
├── "yt-dlp is not installed"
│   └── Install yt-dlp: brew install yt-dlp (macOS), sudo apt install yt-dlp (Linux)
└── "Instagram requires login cookies" / empty media response
    └── Instagram blocks unauthenticated scrapers. Ensure you are logged into Instagram in a desktop browser, then run:
        npx @illyism/transcribe "<url>" --cookies-from-browser <browser_name>