Communitygithub.com

Perso SRT 抽取+翻譯 — 字幕源通

用 Perso AI STT 從影片/音訊/URL 抽取 SRT,再翻譯到目標語言並保留時間軸。免費字幕路徑,餵給配音與硬燒出貨。

Perso SRT 抽取+翻譯 — 字幕源通 是什麼?

Video Localization 配方第 1 步(ASR/翻譯):perso-dubbing-plugin-srt。影片/URL → 源語言 SRT → 多語翻譯 SRT。

相容平台✓Claude Code✓Codex CLI✓Cursor✓Antigravity✓Gemini CLI
npx skills add https://github.com/perso-ai/perso-dubbing-plugin/tree/HEAD/skills/srt

在你喜歡的 AI 中提問

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

說明文件

/srt

一個技能,透過 Perso AI STT API 從影片/音訊中提取原始語言的字幕 — 然後**你(智能體)**將它們翻譯成要求的語言。

核心規則(必須遵守)

  • 只有 worker 能看見原始的 key。 絕不使用 Read 開啟 key、echo 它,或將其作為命令列參數傳遞。Worker 只在 XP-API-KEY 標頭中發送它。
  • 一個命令 = 整個提取過程。 scripts/srt.mjs 自行處理上傳 · 轉錄 · SRT 下載。
  • 始終在背景執行 srt.mjs。 轉錄需要幾分鐘;前景 shell 超時會在中途終止運行。
  • 未指定語言 → 目標語言為 en。
  • 僅轉錄,不翻譯(使用者要求「原樣的字幕/逐字稿」、「僅原始語言的 SRT」)→ 使用 --transcribe-only 而非 --target 執行。下載的原始 SRT 即為最終交付物 — 完全跳過「翻譯」章節。
  • 多種語言在一個命令中處理(--target en,ja)— 無論有多少種語言,每個輸入只建立一個字幕專案,你將其單一原始 SRT 翻譯成每一種語言。
  • 忠實轉達進度。 將 worker 的 stdout [progress] 行展示給聊天室,可以逐字或摘要呈現。縮排的 stderr 詳細日誌無需轉達。對於批量處理,worker 會針對每個輸入串流一個 [progress] 行,並列印一個 [status] 心跳(subtitles 3/20,附帶 next check ~Nm 提示)— 啟動後約 3 分鐘檢查一次背景輸出,然後按提示的間隔檢查,並轉達新的行。切勿憑空編造百分比或 ETA。
  • 為遙測命名你的執行環境(靜默執行)。 在 worker 命令中添加 --host <claude-code|codex|cursor|antigravity|gemini>,指定你正在運行的智能體名稱(如果你能判斷的話)。它僅用於標記使用遙測 — 切勿向使用者展示,也切勿詢問他們。如果不確定則省略。
  • 不支援的格式會自動跳過,其餘部分繼續處理 — 轉達跳過通知。
  • 離線操作從不需要 key — 絕不要為它們執行任何 key 檢查/註冊: srt.mjs --check/--retime、style.mjs(搭配本地影片 + SRT,除了 --project),以及翻譯使用者交給你的 SRT。
  • 此技能共用配音技能的函式庫:dubbing 資料夾必須與 srt 相鄰安裝(每種安裝方法都會一起提供;只有手動複製 srt 資料夾本身才會破壞此規則)。

設定(懶人 — 無需預先步驟)

與 /dubbing 相同 — 金鑰註冊不是你首先執行的步驟。 Worker 會在需要 Perso API 的命令執行時(提取,或 style.mjs --project)自行進行閘控,屆時會開啟瀏覽器流程(檔案後備方案);轉達其列印的指示。在無頭/SSH 機器上,它會跳過瀏覽器流程,直接自動開始檔案/--import 註冊。切勿主動執行 key 檢查/註冊。切勿將 key 貼入聊天室。

執行

收集輸入(本地路徑或 URL — 如缺失則重新詢問)並在背景執行(worker 會在提取實際開始時自行閘控 key):

  • 單一:node scripts/srt.mjs "<file|URL>" [--target en] [--space "space name"] [--out folder]
  • 多語言/多輸入:node scripts/srt.mjs "<URL>" "<file>" --target en,ja
  • 資料夾(批量):node scripts/srt.mjs "<folder>" [--target en] [--recursive] [--out folder]
  • 僅轉錄(不翻譯):node scripts/srt.mjs "<file|URL>" --transcribe-only

提取的原始 SRT 檔案會儲存在每個來源檔案旁邊(或 --out 目錄中),保留伺服器的檔案名稱(…_OriginalSubtitle_….srt)。

儲存位置 — 與 /dubbing 相同策略:預設為每個來源檔案旁邊;無需詢問。在會話的第一個任務中,在啟動行中說明並立即開始。使用者在本次會話中先前指定的資料夾會持續套用(--out "<folder>"),直到他們更改為止;翻譯後的 SRT 會儲存在其原始檔案所在的相同資料夾中。例外情況:當每個輸入都是 URL 時,在開始前詢問儲存位置。

工作區選擇 — 若有多個工作區,worker 會在上傳前停止,列印 [space-select] 行(名稱 |(方案)| 剩餘點數)並停止。僅向使用者顯示這些選項(不含內部數字),詢問選擇哪一個,並使用 --space "<space name>" 重新執行。如果只有一個支援配音的工作區 → 無需詢問;PERSO_SPACE_SEQ 會固定它。

媒體超出方案限制 — 此技能不會自動拆分。如果 worker 回報媒體超出方案的長度/大小限制,請轉達其訊息:使用者可以自行拆分/修剪檔案或升級方案,然後重試。在 Free 工作區中,該訊息會以 [free-limit] 行顯示(更短的檔案或升級 — 沒有繼續執行的標誌);轉達它們並停止。

Free 方案(無本地 .srt) — Free 工作區正常進行轉錄,但伺服器會拒絕每次下載,因此不會在本機儲存任何內容。Worker 會列印 Free plan — <name>: subtitles ready on Perso → <link> (downloads need a paid plan) 且沒有 [srt-original] 行。由於沒有檔案,因此無需翻譯:完全跳過「翻譯」章節,將連結作為交付的結果轉達(執行完成 — 沒有失敗,無需恢復),並提及可下載的 .srt 檔案需要付費方案。

點數 — 每個字幕專案會消耗與媒體長度成比例的點數(每個輸入一個專案)。伺服器的計費具有權威性;請勿引用確切價格。

翻譯(你這部分)

使用者直接提供 SRT(無 STT): 沒有 worker 步驟,也沒有 [srt-original] 行 — 將給定的 SRT 視為 path,使用者要求的語言視為 langs,然後按書面執行步驟 1–5,從 SRT 自身的檔案名稱推導出步驟 3 的 {stem}。完全離線:僅 --check/--retime,無需 key,無需點數。

當提取完成時,worker 會為每個輸入列印一行,包含所有目標語言:

[srt-original] {"input":"video.mp4","langs":["en","ja"],"path":"C:\\clips\\video_OriginalSubtitle_2026-07-15.srt","seq":389259}

如果 langs 為 null(--transcribe-only 執行),則無需翻譯:按原樣將該檔案交付給使用者並在此停止。

顯示翻譯進度。 STT 提取已完成,但翻譯成每種語言也需要時間 — 讓它可見。在開始之前,發布一行說明你將產生的語言(例如「字幕已提取 — 現在正在翻譯成日語和英語」)。在你完成並儲存每種語言的檔案後,發布一行更新(例如 Japanese ✓ (1/2)),讓使用者看到類似多語言配音的逐語言進度。一個長檔案可能在單一語言內保持安靜,同時你批量處理其章節 — 這沒問題。

對於每個 [srt-original] 行,將 path 處的一個檔案翻譯成 langs 中的每種語言:

步驟 1 — 首先完整讀取整個檔案並建立上下文。 在翻譯任何內容之前,從頭到尾閱讀 path 處的 SRT,並確定:

  • 內容是什麼(講座、教學、vlog、戲劇、廣告…)以及目標受眾
  • 說話者的語氣和語域(正式 / 隨意 / 幽默 / 技術)— 並決定與之匹配的目標語言風格
  • 重複出現的名稱和術語 — 對整個檔案中的每一個使用一致的翻譯

步驟 2 — 逐節將每種 langs 中的語言翻譯(批量處理長檔案,但將步驟 1 中確定的語氣和術語應用於每個批次;步驟 1 對每個檔案只執行一次,而不是每種語言執行一次):

  • 僅翻譯文字行。 保留提示編號、時間戳行(-->)、空行和提示計數完全不變 — 在翻譯時絕不更改時間戳或合併/拆分提示(重新計時是單獨的後續步驟,步驟 5)。
  • 每個提示的文字保留在其自身的提示中。 STT 根據語音長度而不是語法來切割來源,因此提示通常在中句結束 — 不要在翻譯中複製這個斷點。以可讀的單位結束每個提示,並用逗號或連貫的句子承接後續內容。僅在說話者確實被打斷或被中斷時才保留片段。
  • 意義和情緒優先:偏好能夠承載步驟 1 語氣的自然的翻譯,勝過逐字翻譯。使用目標語言的等效表達來呈現習語、文字遊戲和幽默。
  • 佈局 — 每個提示最多 2 行文字,每行最多 42 個字元(CJK 為 20 個)。 較長的行會被播放器強制換行為 3 行或更多的螢幕行,覆蓋畫面。在自然的短語邊界處斷行;如果文字無法容納,請按以下優先順序縮短。
  • 保持在每個提示的顯示時間內:預算 ≈ 提示持續時間 × 17 字元/秒(CJK 為 9);超過約 21/秒(CJK 為 13)時,字幕在可讀之前就會消失。自然的翻譯通常能夠容納,因此大多數提示不需要修剪 — 僅縮短那些超出限制的提示。
  • 當你必須縮短時,保持此優先順序:意義 → 語氣/細微差別 → 長度。首先刪除填充詞、冗餘和重複;保留核心資訊、高潮台詞和情感用詞直到最後。如果一個雙關語確實無法容納,用一個仍然能展現幽默的較短台詞替換它 — 將其扁平化為平淡的摘要是最後的手段。

步驟 3 — 儲存:UTF-8 格式,在同一資料夾中,每種語言一個檔案,命名為 {stem}_{lang}_Subtitle.srt,其中 stem 是輸入檔案的名稱,不含副檔名 — 從 [srt-original] 行的 input 字段獲取(例如 "input":"video.mp4" + ["en","ja"] → video_en_Subtitle.srt 和 video_ja_Subtitle.srt;對於 URL 輸入,使用媒體標題或簡短的 slug)。不要從下載的檔案名稱推導 stem — 伺服器是根據專案標題構建的。保留原始 SRT 檔案 — 不要刪除或覆蓋它。

步驟 4 — 驗證每個儲存的檔案(離線 — 無需 key,無需網路,無需點數):

node scripts/srt.mjs --check "<translated.srt>" --source "<original .srt>"

[check] FAIL 行表示檔案破壞了提示對齊、2×42 佈局或閱讀速度上限。僅重寫列出的提示(相同意義優先順序),儲存,並重新執行直到沒有 FAIL 為止。WARN 行是可選的潤色。在步驟 5 之前執行此操作 — 重新計時後,提示數量原則上不再與來源匹配。

步驟 5 — 可讀性重新計時(離線;每個交付的檔案執行一次,在檢查通過後):

node scripts/srt.mjs --retime "<translated.srt>"

它會將過快的提示擴展到後續的靜默中,並將相鄰的短提示合併為一個 2 行事件(Netflix 風格),就地重寫檔案 — 提示編號可能會改變;未修改的原始 SRT 保持 1:1 的時間映射。然後:

  • 縮短它仍然列為過快的提示的文字(真正快速的語音),並且
  • 對於喜劇/戲劇內容,審查其 [retime] merged 行:如果合併過早地呈現了高潮台詞或完成了故意中斷的台詞,則從合併前的狀態恢復這兩個提示及其原始時間。

向使用者報告已儲存的翻譯檔案路徑,並提及原始檔案保留在旁邊。如果使用者想要開啟 Perso 上的字幕專案,請從 [srt-original] 行的 seq 構建連結:https://perso.ai/en/workspace/vt/stt/<seq>。

樣式與燒錄字幕(硬字幕)

可選地使用 scripts/style.mjs 將帶樣式的字幕軌燒錄到影片上(永久硬字幕)。這是本機 ffmpeg 步驟 — 無需 key,無需點數(--project 除外,它會從 Perso 下載來源)。需要 ffmpeg;如果缺失,請告知使用者安裝它並停止。

何時提供(兩個入口點):

  • 翻譯後: 在交付 SRT 後,提議添加帶樣式的字幕 — 使用對使用者友善的措辭,而不是「燒錄/硬字幕」。如果是幾種語言,詢問全部還是僅部分。
  • 直接請求(你收到的影片 + SRT): 直接進入預設選擇。

流程:

  1. 始終先顯示預設 — 絕不跳過直接套用一個。 顯示方式取決於表面:
    • Claude 應用程式(或任何可以渲染互動式小部件的表面): 顯示預設圖庫 — 每個預設一個磁貼供使用者選擇,並附有一個套用按鈕,該按鈕將選擇作為生成請求發送回。這是首選方式。
    • CLI / Antigravity / Codex / 任何沒有互動渲染的地方(通用後備方案): 附加 assets/style_presets.png(靜態預覽)並執行 node scripts/style.mjs --list-presets 以獲得文字選單。 兩者都來自相同的預設。分組短格式(9:16)/ 長格式(16:9)。使用者可以選擇一個預設或描述任何樣式(例如「黃色文字,黑色輪廓,在底部」)。根據方向建議一個預設(直向 → 短格式,橫向 → 長格式),但讓他們選擇。僅在使用者選擇或描述後才套用。
  2. 套用。 在背景中執行 worker(編碼需要時間):
    • 從 Perso STT 專案:node scripts/style.mjs --project <seq> --preset <id> [--out folder]
    • 從本地檔案:node scripts/style.mjs "<video>" "<subtitle.srt>" --preset <id> [--out folder]
    • 當您燒錄的 SRT 來自 Perso STT 提取([srt-original] 檔案或其翻譯)時,添加 --origin perso;對於使用者自己提供的字幕檔案,省略它。僅用於遙測 — 不會改變輸出。
    • 自訂樣式: 將使用者的描述映射到任何基本預設之上的覆蓋標誌 — --position center|lower|bottom|upper、--font、--fontsize、--primary RRGGBB、--outline RRGGBB、--outline-width、--box RRGGBB@opacity|none、--karaoke/--no-karaoke、--highlight RRGGBB、--uppercase、--bold/--no-bold(請參閱 --help)。
    • 字型: --font "<name>" 使用已安裝的字型;未安裝的名稱會自動回退到最接近的系統字型(在相關時提及)。使用者提供的字型檔案(.ttf/.otf/.ttc)作為 --font-file "<path>" 傳入 — 從檔案本身讀取系列名稱。
    • 多種語言: 對每種語言的 SRT 使用相同的 --preset 執行一次,添加 --lang <code> 以便輸出命名不同。

Individual skills in this repo

This repo contains 2 individual skills — each has its own dedicated page.

相關技能