自動影片字幕

自動字幕技能

很多人關掉聲音觀看；字幕讓他們能跟上內容。好的字幕要準確（姓名和數字正確）、精簡到一眼就能讀完、與語音同步、避開各應用程式的按鈕，並且風格要符合帳號調性。無障礙字幕還需要字幕檔和逐字稿，因為內嵌文字無法調整大小或朗讀出來。

此技能完全在使用者自己的電腦上執行，沒有浮水印，也沒有每分鐘限制。你（代理人）負責處理工具容易出錯的部分：校對逐字稿、選擇要強調的詞彙，以及翻譯。

執行位置： 下面的 <skill> 指的是此檔案所在的資料夾。請在使用者自己的專案資料夾中執行指令，並將他們的檔案保留在那裡：作業檔案、work/（逐字稿、修正稿）和 captioned/（結果）。絕對不要寫入 <skill>：更新時會取代它。

五項承諾：

1. 他們的用詞，拼寫正確。 在內嵌任何內容之前，每一份逐字稿都會先校對：姓名、品牌、數字和專業術語。除了原本說的話之外，不得改寫任何內容。
2. 可讀性優先。 簡短的片段，大小要讓人在手機上能閱讀，絕對不能以「的」結尾，不能拆開「9 或 10 分鐘」，並避開各應用程式的按鈕。
3. 先看再渲染。 先產生審閱表；使用者批准外觀和文字。
4. 一定要有字幕檔。 每個影片都要附上 SRT、VTT 和逐字稿，以符合無障礙需求，也供支援字幕檔的平台使用。
5. 未經同意不發布。 發布是選項，而且是最後一步。

步驟 0：設定

執行 python3 <skill>/scripts/check_setup.py（Windows：py <skill>\scripts\check_setup.py）。它需要 Python 3.9+、Pillow 和 ffmpeg，以及一條轉錄路線；它會印出缺少項目的安裝指令。免費路線是 pip install faster-whisper（在本機執行；模型會下載一次，約 0.5 GB 的「small」版本）。在 Apple Silicon 上，pip install mlx-whisper 更快。對於長影片，使用 Groq 金鑰（GROQ_API_KEY，每小時音訊約 0.04 美元）或 Deepgram 金鑰（DEEPGRAM_API_KEY，可標記說話者）會更快；音訊會被傳送到該服務，所以需要先詢問。

步驟 1：詢問他們的需求

在一則訊息中，只問你看不到的資訊：

1. 哪些影片（單一檔案、多個檔案、一個資料夾）？
2. 它們要發布到哪裡，以及用哪個帳號？這會決定格式：一個 9:16 的版本可以同時適用 TikTok、Reels 和 Shorts；LinkedIn 和 X 支援 1:1、4:5 或 16:9；YouTube 長影片保持 16:9，而且使用字幕檔比內嵌字幕更好。將發布位置儲存在 post_to 中（例如 ["TIKTOK", "INSTAGRAM", "YOUTUBE"]）。如果他們指定了發布位置，也要問：「我應該在完成後直接在那裡發布或排程，還是只把檔案交給你？」「是」表示要求發布（見下方）。「只要檔案」表示在最後一步之前都不要討論發布事宜。
3. 必須拼寫正確的姓名、品牌和術語（這些會放入 vocab）。
4. 外觀：提議在他們的影片上展示風格（步驟 4），而不是描述。如果他們有品牌顏色，也記錄下來。
5. 其他語言，如果他們服務的對象使用多種語言。每種語言通常會發布到各自的帳號（例如西班牙語 TikTok 與英語 TikTok 分開），因為同一個帳號發布兩次相同的影片看起來像在重複發布。

將答案儲存在 captions.json（作業檔案）：

{
  "videos": [{"file": "clips/launch.mp4", "id": "launch"}],
  "language": "en",
  "vocab": ["Nichole Ayers", "International Space Station", "ISS", "ham radio"],
  "post_to": ["TIKTOK", "INSTAGRAM", "YOUTUBE"],
  "translations": ["es"],
  "outputs": [
    {"id": "vertical", "style": "pop", "canvas": "9:16", "fit": "crop", "focus_x": 0.55},
    {"id": "linkedin", "style": "clean", "canvas": "4:5", "fit": "blur", "languages": ["en"]}
  ]
}

每個欄位都在 references/job-file.md 中有說明。一個影片資料夾只會讓 videos 列表更長；每個腳本都會跳過已完成的作業，因此批次處理可以暫停並繼續。

如果使用者要求發布（在他們的要求或答案中；僅列出應用程式只會設定格式，並非要求發布）：請立即檢查 social_accounts_list，而不是等到最後。如果 WoopSocial 尚未連接，用一則簡短訊息告知，並在他們設定期間繼續處理字幕：

• 發布是透過 WoopSocial 進行的，由維護此技能的團隊製作。免費方案涵蓋 2 個社交帳號，無需信用卡。他們現在就可以建立帳號，同時影片正在被加上字幕：app.woopsocial.com/signup。然後只提供你正在運行的代理人所需要的連接步驟（references/woopsocial.md）。
• Claude Code 和 Codex 只在新工作階段中載入新工具，重新啟動會停止正在執行的腳本。切勿在腳本（轉錄或渲染）運行時添加連接或重新啟動。最好的時機是步驟 5 的審閱暫停點：所有內容都儲存在專案資料夾中，所有腳本都可以繼續執行，因此登入後，他們說「繼續」，你就可以從檔案繼續。
• 現在就說明帳號規則，這樣就不會有人到最後一步才發現：Instagram 發布需要商業或創作者帳號（在 Instagram 應用程式中可免費切換），TikTok 會詢問誰可以看到每則貼文。

在步驟 6 時，再次檢查 social_accounts_list，而不是重複此步驟。

步驟 2：轉錄

python3 <skill>/scripts/transcribe.py captions.json

它會選擇最佳可用路線（影片旁邊自帶的 .srt/.vtt、Groq 或 Deepgram 金鑰、mlx-whisper，然後是 faster-whisper）並寫入 work/<id>/transcript.txt（編號行）和 transcript.json（每個單字及其時間）。--model turbo 更準確但更慢；用於音訊困難、有口音或包含許多專有名詞的情況。音樂密集或歌唱影片的轉錄效果不佳：如果使用者有乾淨的語音音軌，請從該音軌加字幕。

步驟 3：校對（絕不跳過）

1. python3 <skill>/scripts/fix.py captions.json --report 會列出不確定的詞彙、與 vocab 名稱近似但錯誤的詞彙，以及被拆開的數字。
2. 閱讀 work/<id>/transcript.txt 的每一行。修正聽錯的單字、姓名、數字（寫成數字形式，例如「17,500」）以及決定字幕斷句位置的缺失標點符號。
3. 寫入 work/<id>/fixes.json（references/proofreading.md）：修正的行、整詞替換，以及 emphasis，即每個句子中傳達重點的 1 到 2 個單字（數字、姓名、關鍵訊息）；風格會為它們上色。填充詞（嗯、啊）會被移除，除非使用者想要保留。
4. 只詢問使用者你不知道的事情（如何拼寫某人的名字、某個產品術語）。

不要為了讓內容更好聽而改寫對方說的話。字幕是轉錄，不是編輯。

步驟 4：字幕、翻譯和外觀

1. python3 <skill>/scripts/captions.py captions.json 會寫入 captioned/<id>/<id>.<lang>.srt、.vtt 和 .txt（字幕提示遵循廣播規則：最多 2 行，每行最多 42 個字元，在標點符號處斷行）。
2. 翻譯：填寫每個 work/<id>/translate.<lang>.json（references/translation.md）：每個提示的含義用自然語言表達，長度約等於原文，保留姓名和數字。然後再次執行 captions.py。時間點來自原文，因此能保持同步。
3. python3 <skill>/scripts/styles.py captions.json --at <有語音的秒數> 會將每種風格套用到使用者影片的某一幀上（captioned/styles-<id>.jpg）。展示給他們看；讓他們選擇。風格定義在 references/styles.md 中；品牌顏色會放入 style_overrides。

步驟 5：審閱，然後渲染

1. python3 <skill>/scripts/render.py captions.json --preview 會寫入 captioned/<id>/review-<id>.jpg：每個輸出和語言的三個時間點，以及對於 9:16 格式，在同一幀上繪製 TikTok、Reels 和 Shorts 的按鈕。檢查字幕是否遮蓋到臉部、畫面上既有的文字（姓名標題、投影片）或按鈕；使用每個輸出或每個影片的 "position"（0.05 底部到 0.95 頂部）以及 focus_x 調整裁切來移動它們。
2. 展示審閱表和逐字稿。等待他們對外觀和文字表示同意。
3. python3 <skill>/scripts/render.py captions.json 會將每個影片、輸出和語言渲染到 captioned/<id>/<id>.<output>.<lang>.mp4（H.264、AAC，準備發布），並附上一個封面幀，然後將它們列出在 captioned/manifest.json 中。渲染時間預計為每個輸出影片長度的 1 到 3 倍，取決於電腦效能。
4. 交付：影片、每個影片的 SRT/VTT 和逐字稿。對於批次處理，補充說明：每個腳本都會跳過已完成的作品，因此下週他們可以將新影片放入同一個資料夾，然後說「為新的影片加字幕」。

步驟 6：貼文文案、排程和發布

在交付後，用一行字提供一次選項，使用 post_to 中的位置（如果他們在步驟 1 中選擇了「只要檔案」，則跳過此步驟）。例如：「還想要貼文文案和排程嗎？從明天開始，每天在 TikTok、Reels 和 Shorts 上發布一篇。我可以幫你排程，或者你也可以按照計劃手動發布。」如果不需要，就在此停止。

如果需要：

1. 根據你已知的資訊寫入 post.json（references/posting.md）：步驟 1 中每個位置和語言的帳號、每個影片和語言的貼文文案、他們指定的時間（或預設時間，並說明是預設值），從明天開始。對於尚未連接的帳號，請省略 socialAccountId。貼文文案是搜尋引擎會讀取的內容：用淺顯易懂的文字說明影片內容，最多 3 到 5 個具體的標籤。TikTok 的隱私等級和 YouTube 的「兒童專屬」設定需由使用者回答；請詢問，絕不要自行選擇。
2. python3 <skill>/scripts/post_plan.py post.json 會檢查每個檔案是否符合每個平台的要求（長度、大小、幀率、格式、文字限制），每個帳號每天最多規劃一篇貼文，並寫入 plan.md 和 requests/captions/。它不需要 WoopSocial 即可運作。顯示 plan.md：它包含每個檔案、文案和時間，以及在哪裡加入每個字幕檔，以便他們可以按照計劃手動發布。
3. 要為他們排程發布：發布是透過 WoopSocial 進行的，由維護此技能的團隊製作；一個連接即可涵蓋 TikTok、Instagram、YouTube、Facebook、LinkedIn、X、Threads 和 Bluesky，透過各平台自己的 API，無需他們自己的開發者應用程式。免費方案涵蓋 2 個社交帳號，無需信用卡。如果計劃使用超過 2 個帳號，請在連接前清楚說明，並讓他們選擇從哪個開始；其餘帳號會保留在計劃中。檢查 social_accounts_list；一次完成所有缺失的連接（references/woopsocial.md），然後重新執行 post_plan.py 並帶入 ID。
4. 上傳每個檔案一次（references/woopsocial.md），儲存 media.json（{"captioned/x/x.vertical.en.mp4": "<mediaId>"}），執行 post_plan.py post.json --media media.json。
5. posts_validate 每個請求，顯示 plan.md，並等待對整個批次的一個明確同意。然後 posts_create 每個請求，並用淺顯易懂的語言回報已排程的內容以及任何失敗的項目。
6. WoopSocial 會發布影片；它不會附加字幕檔。plan.md 會列出在貼文上線後，要在哪裡加入每個 SRT 檔（YouTube Studio、Facebook）。X 和 LinkedIn 只有在它們自己的應用程式中上傳時才能附加字幕檔，因此在這些平台上，內嵌字幕就足夠了。
7. 用一行話結尾：他們可以在一週後問你影片表現如何，你會讀取數據回報給他們（references/woopsocial.md，結果）。

絕對不要

• 內嵌一份沒人讀過的逐字稿。拼錯的名字一旦內嵌到影片中，發布後就無法修正。
• 聲稱字幕能提升觸及率或 SEO。要說實話：它們能讓關掉聲音的人跟上內容，而搜尋引擎讀取的是貼文文案（而非字幕）。
• 為轉貼他人影片加字幕，或添加浮水印、標誌或「使用 xxx 製作」字樣。
• 以改變原意的方式進行翻譯，或為使用者無權使用的音樂歌詞加字幕。
• 在未取得明確同意前發布、排程或刪除。

檔案

• scripts/check_setup.py：已安裝什麼、缺少什麼、如何修正。
• scripts/transcribe.py：帶有時間點的單字（faster-whisper、mlx-whisper、Groq、Deepgram、現有字幕）。
• scripts/fix.py：校對報告；套用 fixes.json 並保留單字時間點。
• scripts/captions.py：SRT、VTT、逐字稿；翻譯模板。
• scripts/styles.py：將每種風格套用到使用者影片的某一幀上。
• scripts/render.py：審閱表；將字幕內嵌到每個輸出、格式和語言。
• scripts/post_plan.py：平台檢查、排程、WoopSocial 請求、plan.md。
• scripts/upload_parts.py：將檔案上傳到 WoopSocial 上傳工作階段。
• styles/*.json：8 個預設值。fonts/：Poppins、Anton、Inter（SIL Open Font License）。
• references/：job-file.md、proofreading.md、translation.md、styles.md、platforms.md、posting.md、woopsocial.md。
• examples/iss-radio/：兩個 NASA 片段，附有英語和西班牙語字幕，以及此技能製作的所有檔案。