Communitygithub.com

shushuitie2017/claude-video

影片轉寫與翻譯:將外語影片轉換為帶有中文字幕的影片 + 中文文稿。完整流程包含下載、本地 Whisper 逐詞轉寫、翻譯潤色、燒錄字幕(可選雙語或水印)與產出 Markdown。

claude-video 是什麼?

此技能專為 AI 代理(如 Claude Code、Cursor、Codex)設計,提供完整的影片轉寫與翻譯管線。它能自動下載影片(支援 URL 或本地檔案)、使用本地 faster-whisper 進行逐詞轉寫以獲得精確時間戳、由 AI 代理執行專業翻譯與潤色(遵循 8 條規則,包含 ASR 錯誤修正、斷句、標點去除等),最後將字幕燒錄回影片並生成 Markdown 文稿。支援單一中文字幕與中英雙語字幕(透過 ASS 格式實現中文大、英文小的排版),並可選加水印。此技能已內建於 SKILL.md 中,代理只需讀取並依序執行各步驟即可,無需手動撰寫複雜程式碼。

相容平台✓Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/shushuitie2017/claude-video/tree/HEAD/skills/video-translate

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

/video-translate — 影片翻譯與轉寫

能力與意圖識別(必須嚴格遵守)

  • 轉寫出文件:抓取字幕或音頻轉寫 → 輸出 Markdown 文件(有字幕優先,快且免費)。
  • 翻譯影片:轉寫 → 翻譯潤色 → 燒錄中文字幕 → 輸出帶字幕的影片檔案 + Markdown 文件。

判定規則:

  • 用戶說"轉寫""轉文字""出文件""轉 markdown" → 只生成 Markdown 文件(走「只出文件」流程)。
  • 用戶說"翻譯""翻譯影片""配字幕""加字幕" → 必須執行完整翻譯管線(提取音頻 → Whisper 轉寫 SRT → 翻譯潤色 → 燒錄字幕到影片 → 同時生成 Markdown),不能只輸出文件就結束。
  • 輸入是 URL → 先下載再處理;本地文件路徑 → 直接處理。

Python 直譯器: 本 skill 所有命令按 Windows 寫法用 python。macOS/Linux 換成 python3。

解析 SKILL_DIR(執行任何命令前先做)

把 SKILL_DIR 設為你剛 Read 的這份 SKILL.md 所在目錄的絕對路徑,腳本永遠在 SKILL_DIR/scripts/ 下。先守衛:

SKILL_DIR="<你 Read 的 SKILL.md 所在目錄絕對路徑>"
if [ ! -f "$SKILL_DIR/scripts/transcribe_srt.py" ]; then
  echo "ERROR: scripts not found under SKILL_DIR=$SKILL_DIR" >&2
  exit 1
fi

步驟 -1:解析輸出根(⛔ 強制,先於一切)

執行任何命令/寫任何文件前,必須先讀設定拿 output_dir 作為 <輸出根>:

python -c "import sys; sys.path.insert(0, r'${SKILL_DIR}/scripts'); import config; c = config.load_translate_config(); config.ensure_output_root(c['output_dir']); print(c['output_dir'])"
  • 設定文件在 ~/.config/video-skills/translate.json(首次可跑 python "${SKILL_DIR}/scripts/setup.py" 生成模板)。
  • output_dir 必須是絕對路徑或以 ~ 開頭。缺失/無效時上面的命令會報錯——立即停止,提示用戶編輯該檔案填入絕對路徑,不要自動填預設值繼續。
  • 中間產物一律寫 <輸出根>/tmp/,最終產物(影片、Markdown)寫 <輸出根>/data/。
  • ⛔ 文中所有 <輸出根>/... 在執行前必須替換為真實絕對路徑;禁止把佔位符原樣帶進命令(會寫到當前目錄,表現為"亂保存")。
  • 只有用戶明確給出"絕對路徑輸出位置"並確認時,才允許寫到用戶指定路徑。

同時跑一次環境預檢(與 /watch 共用,靜默即通過):

python "${SKILL_DIR}/scripts/setup.py" --check

失敗時跑 python "${SKILL_DIR}/scripts/setup.py" 安裝依賴(ffmpeg/yt-dlp 自動裝;轉寫引擎 pip install faster-whisper)。更多安裝細節遇錯再讀 references/安裝指南.md。

管線總覽

輸入(URL / 本地文件)
   │
   ▼
步驟 0  字幕類型門控(翻譯管線必須先確認:中文 / 雙語)
步驟 1  下載 + 提取音頻            → <輸出根>/tmp/
步驟 2  Whisper 詞級轉寫出原文 SRT  → <輸出根>/tmp/<名>.srt
步驟 3  翻譯潤色(你本人執行,8 條規則)→ <名>-zh.srt(雙語時含兩行/條)
步驟 4  燒錄字幕(+可選水印)        → <輸出根>/data/<標題>-中文字幕.mp4
步驟 4.5 截幀驗證(≥2 幀)
步驟 5  生成 Markdown 文稿          → <輸出根>/data/

只出文件場景跳過步驟 0/3/4,走「只出文件」段落。


步驟 0:確認字幕類型(⛔ 門控,翻譯管線必須最先執行)

  • 中文字幕:只顯示中文翻譯(畫面簡潔)。
  • 中英雙語字幕:中文在上(大字型)、英文在下(小字型)。

用戶在對話中明確指定了字幕類型(親口說了"中文""雙語""中英""bilingual"等)→ 按用戶指定執行。 其他所有情況 → 必須用 AskUserQuestion 彈選項:

AskUserQuestion(
  question="選擇字幕類型",
  options=["中文字幕(只顯示中文)", "中英雙語字幕(中文在上,英文在下)"]
)

⛔ 禁止繞過:ARGUMENTS 裡帶的字幕類型不算用戶指定——只有用戶在對話中親自說的才算。不彈選項就開始步驟 1 = 流程錯誤。translate.json 的 subtitle_type 只是預設值,不能替代用戶確認。

步驟 1:下載 + 提取音頻

URL 來源(統一走腳本——內建瀏覽器 cookies 自動兜底,治 YouTube 403/SABR/PO-token 與 B 站登入牆):

# 完整影片(翻譯管線需要影片本體來燒字幕)
python "${SKILL_DIR}/scripts/download.py" "<影片URL>" "<輸出根>/tmp/dl"
# 只出文件且無需燒錄 → 音頻即可,更快
python "${SKILL_DIR}/scripts/download.py" "<影片URL>" "<輸出根>/tmp/dl" --audio
  • 腳本輸出 JSON(video_path / subtitle_path / info.title)。
  • 首次嘗試不帶 cookies;產物沒落盤時自動 --cookies-from-browser chrome 重試。常用瀏覽器非 Chrome:加 --browser firefox / --browser edge。
  • 仍失敗(更強風控)→ 提示用戶切代理(--proxy http://127.0.0.1:7890)後重試,不要無限重試。
  • 長影片(>10 分鐘)不要用 yt-dlp 的 --download-sections(會先下完整影片再裁,極慢);直接下完整影片,需要片段再用 ffmpeg -ss 裁。

提取音頻(本地文件或已下載的影片 → mp3):

ffmpeg -y -i "<影片檔案>" -vn -acodec libmp3lame -q:a 2 "<輸出根>/tmp/<文件名>.mp3"

步驟 2:Whisper 詞級轉寫出原文 SRT

⛔ 鐵律:燒字幕的原文 SRT 只能由 Whisper 詞級轉寫生成,禁止用平台自動字幕(yt-dlp --write-auto-subs)當時間源。 原因:YouTube 自動字幕是滾動疊加格式(每條包含前一條文本),無法提取乾淨逐句文本+精確時間戳,燒出來必然不同步。詞級時間戳是唯一可靠時間源。

python "${SKILL_DIR}/scripts/transcribe_srt.py" "<輸出根>/tmp/<文件名>.mp3" \
  --output "<輸出根>/tmp/<文件名>.srt"
# 語種誤判 / 多語言混軌時強制指定:加 --language en(或 zh/ja/…)
  • 預設引擎 = 本地 faster-whisper(詞級時間戳,零 API 費,首次運行自動從 HuggingFace 下模型)。
  • faster-whisper 裝不上 → 配 GROQ_API_KEY/OPENAI_API_KEY 後加 --engine api(API 詞級兜底,與本地路線共用同一套斷句邏輯)。API 未返回詞級時間戳時腳本會降級 segment 級並在 stderr 明示"字幕精度下降"——把這一點轉告用戶。
  • ⛔ 不要在對話裡現寫轉寫 Python 代碼——腳本按「句子+停頓」切(segment 作基礎 / 超 6s 才按詞拆 / <400ms 才合併),繞開腳本自己寫 greedy 切分會把 A 句尾巴+B 句開頭擠進同一幀(實戰踩坑根治)。
  • --max-line-ms 控制單條最大時長(預設 6000ms),--pause-ms 控制斷句停頓閾值(預設 500ms)。

步驟 3:翻譯潤色(你本人執行——這是 LLM 工作,沒有腳本)

讀入步驟 2 的原文 SRT,逐條翻譯潤色,輸出潤色後的 SRT 到 <輸出根>/tmp/<文件名>-zh.srt。你的角色:專業字幕文案編輯,擅長中文寫作、口語還原與字幕排版規範。

潤色 8 條規則(核心)

  1. 糾正 ASR 識別錯誤:同音/近音字、專有名詞拼寫(如 Claude 被聽成 cloud、MCP 被聽成 NCP)、數字/縮寫/單位。可參考影片畫面輔助判斷。
  2. 標點與書面化:先補全標點把口語轉書面(保留說話人語氣),但最終輸出的字幕文本去掉所有標點符號(逗號句號問號感嘆號全去);英文和中文之間加一個英文空格(如:這是 Google 的產品)。
  3. 去冗餘:刪無信息量的口頭語、重複、語氣詞("那個""呃""就是說"),保證語義連續不丟關鍵信息。寧可略冗餘,不可丟意思。
  4. 時間戳對齊(嚴格):原始時間戳嚴格保留,不得隨意偏移。絕不手動提前 start time(會讓字幕跑在說話人前面)。超長掛屏裁剪:一條時間跨度 >6 秒且文本較短 = Whisper 把語音後的靜音/BGM 算進了同一段,用 ffmpeg 靜音檢測精確定位語音結束點,不要公式估算:
    ffmpeg -i <音頻> -ss <start> -to <end> -af silencedetect=n=-30dB:d=0.5 -f null - 2>&1 | grep silence_start
    
    取第一個 silence_start(加回 start 偏移)作為裁剪後的 end;整段都有聲就不裁。一條 >8 秒且文本長可拆成多條,時間戳在原範圍內合理分配。禁止合併相鄰條目,只允許拆分;拆分後重新連續編號;禁止時間戳重疊。
  5. 斷句與分段:核心原則可拆不可合。一條原文對應一條譯文,超 12 字按語義斷點拆兩條(時間戳按比例分配)。以單行為主,每行 ≤12 個中文字元(含空格和英文),在語氣停頓處斷開,不把完整短語拆到兩條裡。寧可多拆短條,不在螢幕上堆多行。
  6. 專有名詞:人名/地名/公司/產品保留原文(首字母大寫);技術術語保留英文(API、GPU、AI、ASR);廣為人知的品牌不翻(Google、iPhone、YouTube);生僻術語首次出現可附簡短中文釋義。
  7. 語言風格:符合當代年輕人用語習慣,網路用語/俚語翻得自然接地氣,避免翻譯腔("這是非常令人興奮的"→"這真的很酷")。旁白用簡潔書面語,對話/歌詞保留口語感。
  8. 歌詞:用 ♪ 包裹(♪ 歌詞 ♪),重意境押韻不逐字直譯,與旁白交替時保證觀眾能區分。

輸出格式(嚴格 SRT)

1
00:00:00,000 --> 00:00:03,500
這是第一條字幕內容

2
00:00:03,500 --> 00:00:07,200
這是第二條字幕內容

序號從 1 連續;時間戳 HH:MM:SS,mmm(逗號分毫秒);文本無標點;中英間有空格;條間空行;檔案末尾空行。

雙語模式(用戶步驟 0 選了雙語時)

產出「雙語 SRT」:每條兩行——中文在上、英文(原文)在下,時間戳與原文 SRT 一句對一句完全對齊(不重新斷句、不合併;原文怎麼切中文就怎麼對)。中文行照常去標點、規範術語;英文行保留原文(僅修 ASR 識別錯誤):

1
00:00:19,239 --> 00:00:21,239
大家好嗎
Hello everyone, how are you?

長影片(>10 分鐘)分段並行

字幕條數多時分段並行翻譯:每段約 500 條,developer 並行子任務翻譯,翻完合併重新編號。合併後全局校驗:時間戳無重疊無跳躍、序號連續、語義連貫、格式合規。

⛔ 管線不停頓:潤色完成後立即執行步驟 4(燒錄),不輸出中間報告、不等用戶確認。整條管線只在最終產物(影片 + Markdown)全部完成後報告一次。

步驟 4:燒錄字幕(+可選水印)

統一走 burn.py——不要手拼 ffmpeg 命令。腳本集中處理了:Windows 路徑在 filter 裡的轉義(C:\a.srt → 'C\:/a.srt',手拼十拼九錯)、音頻強制轉 AAC(yt-dlp 的 Opus 音軌會讓 X/微信/微博上傳失敗,⛔ 禁 -c:a copy)、水印 fontfile 解析與時間點分佈、字幕+水印同一條 -vf 一次編碼(避免二次畫質損失)。

中文單語(SRT 直燒):

python "${SKILL_DIR}/scripts/burn.py" "<影片檔案>" \
  --subs "<輸出根>/tmp/<文件名>-zh.srt" \
  --output "<輸出根>/data/<影片標題>-中文字幕.mp4"

中英雙語(先轉 ASS 再燒——⛔ 必須走 ASS):

python "${SKILL_DIR}/scripts/bilingual_ass.py" "<輸出根>/tmp/<文件名>-zh.srt" \
  --output "<輸出根>/tmp/<文件名>-zh.ass" [--cn-size N] [--height 影片高度]
python "${SKILL_DIR}/scripts/burn.py" "<影片檔案>" \
  --subs "<輸出根>/tmp/<文件名>-zh.ass" \
  --output "<輸出根>/data/<影片標題>-中文字幕.mp4"
  • ⛔ 為什麼雙語必須 ASS:subtitles 濾鏡的 force_style FontSize 對整條統一,做不到一條內中文大英文小;SRT 裡的 inline {\\fsN} 會被 ffmpeg 的 srt 解碼器剝離(實測三檔字型燒出 md5 全同)。只有真 ASS 餵 libass 才能一條內 \N 換行 + inline 切字型。bilingual_ass.py 就是幹這個的,不要手寫 ASS。
  • 字型:用戶在對話裡明確給了中文字型(如"字型 24")→ 傳 --cn-size 24,英文自動按 中文/1.7 算;沒給 → 腳本按解析度選預設。中文︰英文 ≈ 1.7 是實測乾淨的反差比例。
  • ⛔ ASS FontSize/MarginV 是相對 PlayResY=288 的相對值,不是像素。libass 會按影片解析度自動縮放,不要按解析度線性放大字型(1080p 的 17 乘 2 到 4K 會佔滿半屏);1080p 裡 MarginV=N 實際 ≈ N×3.75px 距底(MarginV=110 ≈ 畫面正中,不是 110px),別按像素直覺調。

水印(預設關閉;translate.json 的 settings.watermark_enabled: true 或用戶要求時開):

python "${SKILL_DIR}/scripts/burn.py" "<影片檔案>" --subs <字幕> \
  --watermark-text "<水印文字>" --output <輸出>

時間點按時長自動分佈(<30min 3 次 4s / 30-60min 5 次 5s / >60min 每 15 分鐘一次 10s;首尾固定),透明度 0.28、0.5s 漸隱漸出、左上角。參數可用 --watermark-opacity/--watermark-fontsize 等覆蓋;對話中指定的參數優先於設定檔。

原影片底部已有硬字幕時的避讓:新字幕需上移,不能遮擋原字幕:

# 單行硬字幕
python "${SKILL_DIR}/scripts/burn.py" <影片> --subs <字幕> --avoid-hardsub single ...
# 兩行或動態變行(一句 1 行一句 2 行)→ 按兩行避讓;1 行段中文稍高是可接受代價
python "${SKILL_DIR}/scripts/burn.py" <影片> --subs <字幕> --avoid-hardsub double ...

避讓檔位(single=MarginV 42/FontSize 19,double=MarginV 60/FontSize 19)是經驗值,截幀驗證不過時用 --margin-v 微調 ±3-5 重燒。

拿不準最終命令時先 --dry-run 打印命令審查再真跑。

步驟 4.5:截幀驗證(⛔ 必做,≥2 幀)

燒錄後必須抽幀用 Read 查看確認:字幕完整顯示、不遮擋原有硬字幕、雙語字型反差明顯、中文無方塊(字型缺失):

ffmpeg -y -i "<輸出影片>" -ss <時間點1> -vframes 1 "<輸出根>/tmp/check1.jpg"
ffmpeg -y -i "<輸出影片>" -ss <時間點2> -vframes 1 "<輸出根>/tmp/check2.jpg"

有避讓需求時兩幀要分別選原字幕 1 行和 2 行的時刻,兩幀都不遮擋才算過。只看一幀就交付 = 踩過的坑。 有問題調 --margin-v/--font-size 重燒再驗。

步驟 5:生成 Markdown 文稿

通用規則(所有場景):

  • 讀取轉寫文本(SRT 去序號和時間戳行,或 vtt_to_text.py 清洗後的文本),嚴禁增刪改原文,只做標點、合句、分段。必須覆蓋全部內容,不得遺漏。
  • 中文內容:合併短句、規範標點、按語義分段 → 輸出 1 個檔案 <輸出根>/data/<影片標題>-中文.md。⛔ 中文內容嚴禁使用翻譯規則。
  • 非中文內容:先按原文語言生成 <輸出根>/data/<影片標題>-原文.md(同樣不得增刪改),再讀 references/深度文稿規則.md 按其規則創作 <輸出根>/data/<影片標題>-中文.md(深度文章體,非逐句直譯)。
  • Front matter 僅含 title、source_url。

只出文件場景(用戶只要轉寫/文稿,不燒字幕)

  1. 有字幕的影片優先抓字幕(免費最快;⛔ 僅限出文件——燒字幕禁用此路線,見步驟 2 鐵律):
    python "${SKILL_DIR}/scripts/download.py" "<影片URL>" "<輸出根>/tmp/dl" --captions-only
    python "${SKILL_DIR}/scripts/vtt_to_text.py" "<輸出根>/tmp/dl/<字幕>.vtt" --output "<輸出根>/tmp/cleaned.txt"
    
    清洗後的純文字省約一半 token。讀 cleaned.txt 按步驟 5 出文件。
  2. 無字幕 → 下音頻(--audio)→ transcribe_srt.py 轉寫 → SRT 去序號時間戳得純文字 → 按步驟 5 出文件。

臨時文件與清理

  • 中間產物(音頻、SRT、ASS、截幀)都在 <輸出根>/tmp/,處理完可清理;最終產物在 <輸出根>/data/ 不受影響。
  • 轉寫 SRT 可保留用於調試;用戶可隨時手動清空 tmp/。

錯誤處理

症狀處理
下載失敗(403/風控/登入牆)腳本已自動 cookies 重試;仍失敗換 --browser firefox/edge,或建議用戶配代理;確認是地區鎖/付費內容就直說
faster-whisper 未安裝pip install faster-whisper;裝不了走 --engine api(需 API key)
轉寫語種誤判加 --language en(或對應語種)強制重轉
燒錄後中文是方塊字型缺失——burn.py 預設按平台選(Windows 雅黑/macOS 蘋方/Linux Noto CJK),Linux 需 sudo apt install fonts-noto-cjk;也可 --font-name 指定
字幕遮擋原硬字幕`--avoid-hardsub single
磁碟空間不足清理 <輸出根>/tmp/
依賴類報錯讀 references/安裝指南.md 按指引裝好後回到主流程

依賴檢查原則:直接執行主流程,遇錯再查——不要預先逐項檢查依賴浪費時間,預設環境已配好(步驟 -1 的 --check 已覆蓋基礎項)。

相關技能