Video Clip (Local)
Requires yt-dlp, ffmpeg, and python3. Check with command -v.
Finding plugin scripts
The ASS karaoke generator is bundled with this plugin. Locate it once at the start (this only searches for the plugin's own bundled file):
CODEBLOCK0
Auto-highlight mode
When the user does NOT specify start/end times (e.g., "幫我剪這個影片的精華" or "clip the best parts"):
- 1. Download the full transcript (step 1–2 below)
- Read the entire transcript and identify 3–5 highlight segments. For each, note:
- Start and end timestamps
- A short description of why it's interesting (key insight, funny moment, dramatic turn, etc.)
- 3. Present the highlights to the user as numbered options and ask which ones to clip
- Clip only the segments the user picks, then continue with the normal pipeline (translate, subtitle, etc.)
Pipeline
1. Get video info and original language
CODEBLOCK1
The third line is the original language code (e.g., en, en-US, ja, zh-Hant). Use the base code (before -) for subtitle download.
2. Download original language subtitles
CODEBLOCK2
Replace <LANG> with the base language code from step 1 (e.g., en, ja). The * wildcard matches variants like en-orig. Do NOT use YouTube's auto-translated subs — they are low quality. All translation is done by you.
3. Trim VTT to clip range
When clipping a portion (e.g., 10–130s), filter the VTT to only include cues whose timestamps fall within the range. Keep the original absolute timestamps — do NOT adjust them. The --offset flag in ass-karaoke.py handles the time shift.
When filtering, strip any extra metadata from timestamp lines (e.g., align:start position:0%) — keep only HH:MM:SS.mmm --> HH:MM:SS.mmm. The ASS parser regex expects clean timestamp lines.
4. Translate subtitles
Write and execute a Python script that:
- 1. Parses the trimmed VTT (regex:
HH:MM:SS.mmm --> HH:MM:SS.mmm + text lines) - Collects all text lines into a list
- You translate the list (print a Python list of translated strings)
- Writes a new VTT with identical timestamps and translated text
Example structure:
CODEBLOCK3
Generate this script with the translations list filled in, then execute it. This ensures timestamps stay exact and VTT format is correct.
5. Generate ASS karaoke subtitles
CODEBLOCK4
- - First arg = original language VTT (karaoke timing on top line)
- INLINECODE20 = translated VTT (shown below karaoke line)
- INLINECODE21 = clip start time (adjusts timestamps relative to clip start)
Handles YouTube rolling caption dedup, CJK per-char splitting, and bilingual layout.
6. Resolve stream URLs and clip
Get both video + audio URLs in one call:
CODEBLOCK5
Then clip with ffmpeg:
- - With subtitles: INLINECODE22
- Without subtitles: INLINECODE23
- Input seeking:
-ss <START> before each INLINECODE25 - Separate streams: INLINECODE26
Whisper fallback (no YouTube subs)
If yt-dlp finds no auto-subs and user has GROQ_API_KEY set:
- 1. Download audio: INLINECODE28
- Transcribe:
POST https://api.groq.com/openai/v1/audio/transcriptions with model=whisper-large-v3, INLINECODE31 - Convert segments to VTT
If GROQ_API_KEY is not set, inform the user that no subtitles are available and ask how to proceed (clip without subs, or set the key).
Common issues
- - YouTube throttling: export cookies to a file and use INLINECODE33
- Missing CJK fonts for ASS:
brew install font-noto-sans-cjk-tc (macOS) - Groq 25MB audio limit: split audio for videos >50min
- Stream URLs expire ~6h: re-resolve if clip fails
- Subtitle burning re-encodes video (~1–3 min for 60s clip)
影片剪輯（本地端）
需要 yt-dlp、ffmpeg 和 python3。使用 command -v 檢查。
尋找外掛腳本
ASS 卡拉 OK 產生器與此外掛綁定。請在開始時定位一次（這僅搜尋外掛自帶的檔案）：
bash
ASS_SCRIPT=$(find ~/.claude/plugins -path /clip-local//scripts/ass-karaoke.py 2>/dev/null | head -1)
自動精華模式
當使用者未指定開始/結束時間時（例如「幫我剪這個影片的精華」或「clip the best parts」）：
- 1. 下載完整逐字稿（下方步驟 1–2）
- 閱讀完整逐字稿，找出 3–5 個精華片段。針對每個片段記錄：
- 開始與結束時間戳
- 簡短描述為何有趣（關鍵見解、有趣時刻、戲劇性轉折等）
- 3. 將精華片段以編號選項呈現給使用者，詢問要剪輯哪些片段
- 僅剪輯使用者選擇的片段，然後繼續正常流程（翻譯、字幕等）
流程
1. 取得影片資訊與原始語言
bash
yt-dlp --print title --print duration_string --print language \
--no-playlist --no-warnings --force-ipv4
第三行是原始語言代碼（例如 en、en-US、ja、zh-Hant）。下載字幕時使用基礎代碼（- 之前的部分）。
2. 下載原始語言字幕
bash
yt-dlp --write-auto-sub --sub-lang * --sub-format vtt --skip-download \
--no-playlist --no-warnings --force-ipv4 \
--extractor-args youtube:player-client=default,mweb \
-o subs
將 替換為步驟 1 中的基礎語言代碼（例如 en、ja）。* 萬用字元可匹配 en-orig 等變體。請勿使用 YouTube 的自動翻譯字幕——品質較差。所有翻譯由您自行完成。
3. 修剪 VTT 至剪輯範圍
剪輯部分內容時（例如 10–130 秒），過濾 VTT 僅保留時間戳落在範圍內的提示。保留原始的絕對時間戳——不要調整它們。 ass-karaoke.py 中的 --offset 標誌會處理時間偏移。
過濾時，移除時間戳行中的任何額外元資料（例如 align:start position:0%）——僅保留 HH:MM:SS.mmm --> HH:MM:SS.mmm。ASS 解析器的正則表達式需要乾淨的時間戳行。
4. 翻譯字幕
撰寫並執行一個 Python 腳本：
- 1. 解析修剪後的 VTT（正則表達式：HH:MM:SS.mmm --> HH:MM:SS.mmm + 文字行）
- 將所有文字行收集到一個列表中
- 您翻譯該列表（輸出一個翻譯後字串的 Python 列表）
- 使用相同的時間戳和翻譯後的文字寫入新的 VTT
範例結構：
python
import re
解析原始 VTT
with open(clip.vtt) as f:
content = f.read()
cues = re.findall(r(\d{2}:\d{2}:\d{2}\.\d{3} --> \d{2}:\d{2}:\d{2}\.\d{3})\n((?:(?!\d{2}:\d{2}).+\n?)*), content)
翻譯——在此填入您的翻譯，每個提示對應一個
translations = [
翻譯後的第一行,
翻譯後的第二行,
# ...
]
寫入翻譯後的 VTT
with open(clip_translated.vtt, w) as f:
f.write(WEBVTT\n\n)
for (timestamp, _), translation in zip(cues, translations):
f.write(f{timestamp}\n{translation.strip()}\n\n)
生成此腳本並填入 translations 列表，然後執行。這可確保時間戳精確且 VTT 格式正確。
5. 生成 ASS 卡拉 OK 字幕
bash
python3 $ASSSCRIPT -o subs.ass -t --offset SECONDS>
- - 第一個參數 = 原始語言 VTT（上方卡拉 OK 時間軸）
- -t = 翻譯後 VTT（顯示在卡拉 OK 行下方）
- --offset = 剪輯開始時間（相對於剪輯開始調整時間戳）
處理 YouTube 滾動字幕去重、中日韓逐字分割及雙語排版。
6. 解析串流網址並剪輯
一次呼叫取得影片+音訊網址：
bash
URLS=$(yt-dlp --get-url -f bv[height<=720]+ba/b[height<=720] \
--no-playlist --no-warnings --force-ipv4 \
--extractor-args youtube:player-client=default,mweb )
VIDEO_URL=$(echo $URLS | head -1)
AUDIO_URL=$(echo $URLS | tail -1)
然後使用 ffmpeg 剪輯：
- - 含字幕：-vf ass=subs.ass -c:v libx264 -preset fast -crf 23 -c:a aac -b:a 128k -movflags +faststart
- 不含字幕：-c copy -avoidnegativets make_zero
- 輸入定位：在每個 -i 前使用 -ss
- 分離串流：-map 0:v:0 -map 1:a:0
Whisper 備援（無 YouTube 字幕）
如果 yt-dlp 找不到自動字幕且使用者已設定 GROQAPIKEY：
- 1. 下載音訊：yt-dlp -f ba -x --audio-format mp3 --postprocessor-args ffmpeg:-ac 1 -ar 16000 -b:a 64k
- 轉錄：POST https://api.groq.com/openai/v1/audio/transcriptions 搭配 model=whisper-large-v3、responseformat=verbosejson
- 將片段轉換為 VTT
如果未設定 GROQAPIKEY，告知使用者無可用字幕，並詢問如何處理（無字幕剪輯，或設定金鑰）。
常見問題
- - YouTube 限流：將 cookies 匯出至檔案，使用 --cookies cookies.txt
- ASS 缺少中日韓字型：brew install font-noto-sans-cjk-tc（macOS）
- Groq 25MB 音訊限制：超過 50 分鐘的影片需分割音訊
- 串流網址約 6 小時過期：若剪輯失敗請重新解析
- 字幕嵌入會重新編碼影片（60 秒片段約需 1–3 分鐘）
