/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): 直接進入預設選擇。
流程:
- 始終先顯示預設 — 絕不跳過直接套用一個。 顯示方式取決於表面:
- Claude 應用程式(或任何可以渲染互動式小部件的表面): 顯示預設圖庫 — 每個預設一個磁貼供使用者選擇,並附有一個套用按鈕,該按鈕將選擇作為生成請求發送回。這是首選方式。
- CLI / Antigravity / Codex / 任何沒有互動渲染的地方(通用後備方案): 附加
assets/style_presets.png(靜態預覽)並執行node scripts/style.mjs --list-presets以獲得文字選單。 兩者都來自相同的預設。分組短格式(9:16)/ 長格式(16:9)。使用者可以選擇一個預設或描述任何樣式(例如「黃色文字,黑色輪廓,在底部」)。根據方向建議一個預設(直向 → 短格式,橫向 → 長格式),但讓他們選擇。僅在使用者選擇或描述後才套用。
- 套用。 在背景中執行 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>以便輸出命名不同。
- 從 Perso STT 專案: