Subtitle Extractor Skill

Extracts subtitles from video platforms in their native format. Supports Bilibili, YouTube, Xiaohongshu, Douyin, and local video files.

Scope of this skill: subtitle extraction only. Summarization, analysis, Q&A — all handled by the agent based on the user's actual request.

What It Does

1. 1. Detect platform from URL
2. Extract native subtitles via yt-dlp (or Whisper transcription when no native subtitles exist)
3. Output: raw subtitle file path + video title/author
4. Agent saves subtitle to outputs/ and processes per user request

Dependencies

Agent must verify dependencies before calling the script. If any are missing, inform the user with the relevant install command.

yt-dlp — Required (always)

CODEBLOCK0

ffmpeg — Required only for Whisper transcription

Only needed for Xiaohongshu, Douyin, local files, or Path B (Whisper transcription).

CODEBLOCK1

Windows users: restart the terminal after installation for PATH to take effect.
If winget is unavailable, download from ffmpeg.org and add the bin/ directory to system PATH.

faster-whisper — Required only for transcription platforms

Only needed for Xiaohongshu, Douyin, local files, or Path B (Whisper transcription).

CODEBLOCK2

Note: Model files are downloaded automatically on first transcription run (~150MB for base). This may take a minute depending on network speed.

China network note: If auto-download fails (HuggingFace blocked), see Whisper model download failed in Troubleshooting.

Transcription time estimate (CPU, faster-whisper):

GPU accelerates transcription 5–15×. First run downloads the model (~150MB for base).

Cookie Configuration

Bilibili — Cookie Required

Bilibili requires a cookie file for all requests. The script auto-discovers cookie files in the skill directory only (same folder as subtitle-extractor.py and SKILL.md):

Any .txt file whose name contains bilibili will be picked up automatically — including the browser extension's default export format www.bilibili.com_netscape_<timestamp>.txt.

Place your cookie file in the skill directory. The agent does not need to locate or pass it manually (see Step 1b).

Xiaohongshu / Douyin — Manual

CODEBLOCK3

How to export cookies:

1. 1. Install browser extension: "Cookie Editor（https://cookieeditor.org/）"
2. Log in to the platform
3. Export cookies to a .txt file（Netscape format）

Agent Workflow

EXECUTION ORDER — NON-NEGOTIABLE

Steps 1–4 in this skill MUST be completed in full before addressing any user request. The subtitle file MUST be saved to disk (Step 4) before the agent proceeds to summarization, translation, analysis, or any other task the user has asked for.

Treat Steps 1–4 as mandatory prerequisites, not optional helpers. Do not skip any step even if the user's final output format (e.g. a markdown file) appears to make it unnecessary.

Step 1 — Check Dependencies

CODEBLOCK4

If the user requests Whisper transcription (keywords: "whisper转录" / "用whisper" / "transcribe" / "转录" / "语音转文字"), or the platform is Xiaohongshu, Douyin, or a local file, also check:

CODEBLOCK5

If anything is missing, stop and tell the user which dependency to install (see Dependencies section).

Step 1b — Bilibili Cookie

The script auto-discovers any .txt file containing "bilibili" in the skill directory. Do not search for or pass the cookie file yourself.

Only act if the script exits with:

• - 未找到 Bilibili Cookie 文件 → tell the user to place a cookie file in the skill directory
• INLINECODE11 → tell the user to re-export

To export: install "Cookie Editor (https://cookieeditor.org/)", log in to Bilibili, export Netscape format → place in skill directory → retry.

Step 2 — Extract Subtitles

Determine which path applies, then execute it completely before moving to Step 3.

Use when: Bilibili or YouTube URL, and the user has not mentioned any transcription keyword.

Tell the user: "正在提取字幕..."

CODEBLOCK6

Parse the JSON from stdout. You now have all four fields needed for Step 3:

If the script exits non-zero: read stderr, report the error to the user, stop.

Use when: user mentions any transcription keyword, OR platform is Xiaohongshu or Douyin.

Transcription keyword takes priority over phrasing like "提取字幕" or "字幕原文" — those describe the desired output, not the method.

Call 1 — Download audio (skip for local files, go to Call 2 directly)

Tell the user: "正在下载音频，请稍候..."

CODEBLOCK7

Parse the JSON from stdout and record these values:

If the script exits non-zero: read stderr, report the error to the user, stop.

Tell the user: "音频下载完成，开始 Whisper 转录（模型: base），请稍候..."

Call 2 — Transcribe

For URL input, use the audio_file recorded from Call 1:
CODEBLOCK8

For local file input (set title = filename, author = "local"):
CODEBLOCK9

Parse the JSON from stdout and record:

Tell the user: "转录完成！"

If the script exits non-zero:

• - Read stderr, report the error to the user, stop
• If stderr contains Whisper 模型下载失败: show the full error message verbatim — it contains the exact download directory and manual steps

Step 3 — Confirm Data

Verify you have collected all four values from the script outputs in Step 2:

Note: non-ASCII characters in JSON output appear as \uXXXX escapes — standard JSON parsing produces the correct decoded strings.

Step 4 — Save Subtitle to Outputs (REQUIRED — DO NOT SKIP)

Before answering the user, save the subtitle file to the session outputs directory.

Naming rule: {title前8字}_{author}.{原格式扩展名}

Steps:

1. 1. Take title, keep the first 8 characters (Chinese and English each count as 1)
2. Replace unsafe filesystem characters / \ : * ? " < > | and spaces with INLINECODE32
3. Apply the same sanitization to INLINECODE33
4. Use the extension from subtitle_file path (.srt or .vtt)
5. Save to INLINECODE37

Step 5 — Process and Respond

Read the subtitle file content and respond to the user's original request — summarize, analyze, translate, answer questions, etc. The subtitle content is in SRT or VTT format with timestamps; LLMs handle both directly.

Platform Notes

Supported URL Formats

YouTube: youtube.com/watch?v=... · INLINECODE39

Bilibili: bilibili.com/video/BV... · bilibili.com/video/av... · b23.tv/... (short link)

Xiaohongshu: xiaohongshu.com/explore/... · xhslink.com/... (short link)

Douyin: douyin.com/video/... · v.douyin.com/... (short link)

Script Reference

CODEBLOCK10

Troubleshooting

"yt-dlp: command not found"

"No subtitles found"

• - The video may not have CC subtitles — use Path B (--step download-audio then --step transcribe) to force Whisper
• For Xiaohongshu/Douyin, transcription is always required (no native subtitles)
• Try --lang to specify a different language code

Bilibili 412 Precondition Failed

1. 1. Log in to Bilibili in browser
2. Use "Cookie Editor（https://cookieeditor.org/）" extension
3. Export（Netscape format）→ place in skill directory → retry

Bilibili: no zh-CN subtitle found

"Whisper not installed"

Whisper model download failed

The script tries hf-mirror.com then huggingface.co. If both fail (common in China), the script will print exact steps. Show the error message to the user verbatim — it contains the exact directory path and download URL.

Manual download (browser accessible in China):

1. 1. Open: INLINECODE54
2. Download these 5 files: config.json model.bin tokenizer.json vocabulary.json INLINECODE59
3. Create the directory shown in the error message and place all 5 files there
4. Re-run the script — it auto-detects the local model, no download needed

For other model sizes (tiny/small/medium/large), change faster-whisper-base to faster-whisper-{size} in the ModelScope URL.

"ffmpeg not found" (during transcription)

Video too long for Whisper

export VIDEO_SUMMARY_WHISPER_MODEL=tiny