/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 條規則(核心)
- 糾正 ASR 識別錯誤:同音/近音字、專有名詞拼寫(如 Claude 被聽成 cloud、MCP 被聽成 NCP)、數字/縮寫/單位。可參考影片畫面輔助判斷。
- 標點與書面化:先補全標點把口語轉書面(保留說話人語氣),但最終輸出的字幕文本去掉所有標點符號(逗號句號問號感嘆號全去);英文和中文之間加一個英文空格(如:
這是 Google 的產品)。 - 去冗餘:刪無信息量的口頭語、重複、語氣詞("那個""呃""就是說"),保證語義連續不丟關鍵信息。寧可略冗餘,不可丟意思。
- 時間戳對齊(嚴格):原始時間戳嚴格保留,不得隨意偏移。絕不手動提前 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_startsilence_start(加回 start 偏移)作為裁剪後的 end;整段都有聲就不裁。一條 >8 秒且文本長可拆成多條,時間戳在原範圍內合理分配。禁止合併相鄰條目,只允許拆分;拆分後重新連續編號;禁止時間戳重疊。 - 斷句與分段:核心原則可拆不可合。一條原文對應一條譯文,超 12 字按語義斷點拆兩條(時間戳按比例分配)。以單行為主,每行 ≤12 個中文字元(含空格和英文),在語氣停頓處斷開,不把完整短語拆到兩條裡。寧可多拆短條,不在螢幕上堆多行。
- 專有名詞:人名/地名/公司/產品保留原文(首字母大寫);技術術語保留英文(API、GPU、AI、ASR);廣為人知的品牌不翻(Google、iPhone、YouTube);生僻術語首次出現可附簡短中文釋義。
- 語言風格:符合當代年輕人用語習慣,網路用語/俚語翻得自然接地氣,避免翻譯腔("這是非常令人興奮的"→"這真的很酷")。旁白用簡潔書面語,對話/歌詞保留口語感。
- 歌詞:用 ♪ 包裹(
♪ 歌詞 ♪),重意境押韻不逐字直譯,與旁白交替時保證觀眾能區分。
輸出格式(嚴格 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。
只出文件場景(用戶只要轉寫/文稿,不燒字幕)
- 有字幕的影片優先抓字幕(免費最快;⛔ 僅限出文件——燒字幕禁用此路線,見步驟 2 鐵律):
清洗後的純文字省約一半 token。讀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"cleaned.txt按步驟 5 出文件。 - 無字幕 → 下音頻(
--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 已覆蓋基礎項)。