WakaChobii/tiktok-text

為影片添加 TikTok 風格文字

此技能的檔案位於 ${CLAUDE_PLUGIN_ROOT}/skills/add-text/：

• scripts/add_text.py：請使用此腳本。 它能用兩個指令完成整個工作。
• scripts/caption_match.py（偵測/調整/檢查）和 scripts/tiktok_text.py（繪製+燒錄）：引擎核心。
• scripts/setup_check.py：首次執行設定與檢查。
• fonts/：TikTok Sans（開源，OFL 授權）。

這些樣式是根據實際 TikTok 應用程式內的效果測量而得。請勿使用任何其他方式渲染文字（ffmpeg drawtext、一般字型等），否則無法匹配。

步驟 0：設定（每次執行；完成後約需 2 秒）

使用 PATH 上的 python 或 python3 執行：

python "${CLAUDE_PLUGIN_ROOT}/skills/add-text/scripts/setup_check.py" "${CLAUDE_PLUGIN_DATA}"

• 首次執行會在插件資料夾中建立私有的 Python 環境，並安裝套件（約需 1-2 分鐘）。請告知使用者正在發生什麼事。

• 最後一行會顯示 READY PY=<path>。請使用該 <path> 作為以下所有指令的 Python 直譯器（以下簡稱 PY）。

• NOT READY: ... 會顯示缺少什麼以及確切的修復方法：

  • ffmpeg：詢問使用者，然後執行提供的安裝指令（Windows 用 winget，Mac 用 brew，Linux 用 apt）。在 Windows 上，可能需要新的終端機才能找到 ffmpeg。如果是這樣，請告訴使用者重新啟動 Claude Code。
  • 沒有 Python 3.9+：使用者必須自行安裝（python.org）並重新啟動 Claude Code。

  然後再次執行設定。

• 沒有 python 指令？嘗試 python3，或在 Windows 上使用 py。

在以下指令中，S = ${CLAUDE_PLUGIN_ROOT}/skills/add-text/scripts。請為每個路徑加上引號。在 PowerShell 中，每個指令開頭請加上 & （例如 & "PY" "S/add_text.py" ...）。

規則

• 輸出影片保持輸入影片的尺寸和幀率（TikTok：1080x1920）。將含文字版本儲存在原始檔案旁，命名為 <名稱> (WITH TEXT).mp4，且絕不覆蓋原始檔案。
• 內容： TikTok 會對誤導性聲明進行處罰。避免絕對的結果聲明（如「已治癒」、「三天內修復」、「保證」）。當參考影片的鉤子（hook）包含某種聲明時，調整措辭（保持相同節奏和行數），並告知使用者你做了哪些修改及其原因。如果不確定，請先詢問。
• 輸入的文字必須與 iPhone 產生的內容一致：
  • 使用 … 而非 ...
  • 如果參考影片使用了彎曲引號，則使用 ’ “ ”
  • 表情符號使用實際的表情符號字元
• 開頭和結尾的空格很重要：TikTok 會將每行文字（含其空格）置中對齊。fit 指令會為你加入這些空格。

A. 複製參考 TikTok 的文字

在使用者的影片旁建立一個工作資料夾，例如 text work/。

1. 開始： "PY" "S/add_text.py" start "REF.mp4" "WORKDIR"
   • 輸出每個說明文字的資訊：開始/結束時間（精確到幀，參考影片的時間軸）、樣式、填充顏色和邊框。
   • 寫入 WORKDIR/captions.json，其中包含 "text": "??"，以及每個說明文字的放大裁剪圖 WORKDIR/caption_<n>.png。
   • 它會跳過 TikTok 自身的「TikTok @user」浮水印。
   • 需要先下載參考影片嗎？如果已安裝 yt-dlp 就可以使用。否則請使用者提供檔案。
2. 填入文字。 查看每張裁剪圖，並將每個 "??" 替換為實際文字。
   • 保留其他欄位。_ 開頭的欄位（_ref_t、_bbox_1080 等）會由 finish 指令使用。
   • 換行使用 \n，表情符號則使用字元。不必擔心開頭或結尾的空格。
   • 如果兩行之間的間距大約是正常行距的兩倍，則表示中間有一個空白行：請使用 "A\n\nB"。
   • 如果一個說明文字中有兩個獨立的文字框（尺寸差異很大、間距很大，或未對齊同一 X 軸中心）：請將其拆分為兩個條目，具有相同的 start/end、_ref_t 和 style。為每個條目指定各自的 _bbox_1080：即其 _lines_1080（偵測會輸出每行的邊框和高度）中所有行的聯集，以便 fit 調整時能正確對應。範例：第 1 行：[346,1126,735,1167] 以及第 2+3 行 → [346,1126,735,1167] 和 [204,1272,887,1389]。
   • style 回傳 custom / custom_outline？這表示使用了其他字型、背景框或其他顏色，此工具不支援。請告知使用者，並選擇最接近的樣式。不要在不告知的情況下自行猜測。
   • 如果需要重設時間，請在此處進行： 如果使用者的剪輯與參考影片不同，請編輯 start/end（秒數，end 為排除時間）。Fit 和 check 仍會根據參考影片的自身時間（_ref_t）進行檢查。
3. 完成： "PY" "S/add_text.py" finish "REF.mp4" "VIDEO.mp4" "WORKDIR"
   • 將大小、位置和空格調整為符合 json 的設定，並寫入 WORKDIR/fit_<n>.png（上方為參考影片，下方為我們的結果）。
   • 任何超過影片長度的說明文字會自動在影片結尾處結束。
   • 在影片旁燒錄 VIDEO (WITH TEXT).mp4（如果原始檔名為 (no text) 則改為 (WITH TEXT)）。第四個參數可指定其他輸出檔名。
   • 檢查結果並寫入 WORKDIR/check.jpg（左側為參考影片，右側為我們的結果）。
   • 輸出 SUMMARY: PASS 或 REVIEW 以及原因。
4. 查看 check.jpg 並在使用者確認完成前顯示給他們看。
   • 低重疊率但附帶 「邊緣與參考影片差距在 Npx 以內」：表示大小和位置正確。即使壓縮後的金色或黃色文字分數可能只有 0.45-0.7，也是正確的。只需肉眼確認措辭即可。
   • 低重疊率且附帶 「邊緣差距 Npx」：通常是打字錯誤、漏掉換行、使用了錯誤的樣式，或在拆分後 _bbox_1080 設定錯誤。請修正 json 並重新執行 finish。
   • 若要保留手動調整的大小/y/x 設定，請加上 --no-fit 參數。

B. 全新說明文字（無參考影片）

撰寫一個 captions.json 檔案：

[{"text": "第一行\n第二行", "start": 0, "end": 3.5, "style": "outline", "size": 70, "y": 0.5}]

然後執行 "PY" "S/add_text.py" new "VIDEO.mp4" "WORKDIR/captions.json"。它會燒錄文字並在 json 檔案旁寫入 preview.jpg（每個說明文字一張預覽圖）。請顯示給使用者看。

• style： classic（純白）、outline（白+黑邊框）、yellow（淺黃）、yellow_gold（金黃）、lilac（淡紫）。
• size： 約 50（小）到 85（大）。典型的鉤子文字大小為 54-77。
• y： 0.4-0.5 = 螢幕中間，0.65 = 下方三分之一處。請遠離底部 20%（TikTok 的說明/UI 區域）和右側邊緣（按鈕）。
• 可選參數： x（水平中心點，預設 0.5）、weight、color（"#RRGGBB" 自訂填充顏色）。
• 換行位置應模擬一般人在手機上打字的方式。在 size 70 下，每行約可容納 20-28 個字元。

快速預覽（不需渲染完整影片）："PY" "S/tiktok_text.py" --png "文字\n更多文字" out.png（經典樣式）。

注意事項

• 典型耗時：開始約 25 秒，完成需 1-3 分鐘（取決於說明文字數量，有邊框的說明文字調整最慢），使用 --no-fit 約 40 秒。
• 表情符號：每個新的表情符號只會下載一次（Apple 表情符號集，來自 jsDelivr 的 emoji-data CDN），因此首次使用需要網路連線。如果下載失敗，腳本會拋出錯誤。請告知使用者，而不是直接省略表情符號。
• 刻意不加入陰影：真實的 TikTok 文字沒有陰影。與壓縮後的參考影片相比，看起來「更乾淨」是正常的，一旦 TikTok 重新編碼上傳後這個差異就會消失。
• 只有 2 行文字時，fit 的空間修正器無法判斷哪一行偏移中心。如果 fit_<n>.png 顯示某一行偏移約 5 像素，且重疊率低於約 0.6，請嘗試手動在每行文字前後加入空格（開頭或結尾），然後重新執行。
• Windows：如果在其他 Python 片段中表情符號顯示異常，請設定 PYTHONIOENCODING=utf-8。這些腳本已處理此問題。