name: video-transcript-txt description: 將一個或多個本地影片轉寫為帶每段開始和結束時間的整理版 TXT。當用戶要求影片轉文字、影片轉寫、提取影片文本或字幕、批次生成帶時間戳 TXT、整理影片口述內容、統計影片處理耗時時使用。通過 uv、ffmpeg/ffprobe 和 openai-whisper 處理；中間檔案寫入系統臨時目錄並自動清理，永不刪除源影片。 metadata: short-description: 影片轉寫為帶起止時間的 TXT

影片轉寫為 TXT

發現更多技能外掛，請訪問7w4.net。

將完整下載的本地影片轉寫為帶逐段起止時間的純文本檔案。單影片生成一個 .txt；多影片時每個影片獨立生成一個 .txt，並在全部完成後彙總總影片時長與實際處理總耗時。

輸入與輸出

• 輸入：一個或多個本地影片檔案的絕對路徑。
• 預設輸出：每個影片同目錄下的 <影片檔名>_整理版.txt。
• 每段格式：［HH:MM:SS.mmm - HH:MM:SS.mmm］文本
• 輸出已存在時預設停止；只有使用者明確允許覆蓋後才傳 --force。
• 多影片完成後不生成額外匯總檔案；只在回覆中彙報彙總結果。

硬性規則

1. 不刪除、不移動、不修改源影片。
2. 拒絕處理 .downloading、.part、.partial 等未完成下載檔案。
3. 每個影片最終只保留一個 TXT；不得在影片目錄生成或保留 WAV、JSON、SRT、VTT、TSV、原始 ASR TXT。
4. 所有 Whisper 中間輸出必須進入系統臨時目錄，成功或失敗都要清理。
5. 不編造說話人，不根據猜測強行修改人名、數字、劑量或專業術語。
6. 使用者未指定語言時預設中文 zh；使用者明確指定時使用其語言。
7. 執行前檢查 uv、ffmpeg、ffprobe 是否可用。
8. 多影片並行必須限流；預設最多同時處理 2 個影片，資源充足且影片較短時最多 3 個。

單影片執行

uv run ~/.claude/skills/video-transcript-txt/scripts/video_transcript_txt.py \
  "/absolute/path/to/video.mp4"

指定輸出：

uv run ~/.claude/skills/video-transcript-txt/scripts/video_transcript_txt.py \
  "/absolute/path/to/video.mp4" \
  --output "/absolute/path/to/result.txt"

使用者已明確允許覆蓋時：

uv run ~/.claude/skills/video-transcript-txt/scripts/video_transcript_txt.py \
  "/absolute/path/to/video.mp4" \
  --force

可選引數：

• --model：Whisper 模型，預設 small。
• --language：語言程式碼，預設 zh。
• --model-dir：模型快取目錄，預設 ~/.cache/whisper。
• --force：覆蓋已存在的最終 TXT，僅在使用者明確允許時使用。

單影片工作流

1. 校驗輸入檔案、輸出字尾和依賴工具。
2. 使用 ffprobe 獲取影片時長。
3. 建立系統臨時目錄。
4. 用 uv run --with openai-whisper whisper 轉寫，所有格式輸出到臨時目錄。
5. 讀取臨時 JSON 中的 segments。
6. 將有效分段按時間順序寫成唯一最終 TXT。
7. 原子替換最終輸出並清理臨時目錄。
8. 彙報最終 TXT 絕對路徑、有效段落數量、影片時長、單影片處理耗時。
9. 讀取終端中的 SUMMARY_JSON: 行作為機器可讀摘要。

多影片並行工作流

當用戶提供多個影片時，由主 agent 統籌，多名子 agent 分批處理：

1. 主 agent 解析並列出全部影片絕對路徑。
2. 主 agent 先做批次預檢查：路徑存在、普通檔案、未命中未完成下載字尾、預設輸出路徑不衝突、輸出不存在或已獲覆蓋授權。
3. 如果輸出已存在且使用者未授權覆蓋，先詢問使用者選擇：跳過已有輸出、允許覆蓋、或停止批處理。
4. 記錄批處理開始時間。
5. 按併發上限分批派發子 agent：每個子 agent 只處理一個影片，只調用單影片指令碼。
6. 環境不支援子 agent 或並行時，降級為序列處理；仍執行同樣的彙總。
7. 單個影片失敗不阻塞其他影片；失敗原因進入最終彙總。
8. 所有影片完成後記錄結束時間，計算實際處理總耗時。
9. 彙總成功數、失敗數、每個 TXT 路徑、每個影片時長、每個單影片處理耗時、總影片時長和實際處理總耗時。

子 agent 回傳欄位

每個子 agent 完成後必須回傳：

• 源影片絕對路徑。
• 輸出 TXT 絕對路徑。
• status：success 或 error。
• 失敗原因；成功時為空。
• 影片時長秒數。
• 有效段落數。
• 單影片實際處理耗時秒數。
• 使用的模型和語言。

優先從指令碼輸出的 SUMMARY_JSON: 解析這些欄位；解析失敗時再從中文輸出中提取，並說明摘要解析失敗。

總時長彙報規範

使用者說“總時長”但未明確含義時，默認同時彙報兩類時長：

• 總影片時長：所有成功處理影片的媒體時長之和，來自 ffprobe。
• 實際處理總耗時：從主 agent 開始派發第一批任務到所有任務結束的牆鍾時間。

多影片並行時，實際處理總耗時通常小於各單影片處理耗時之和；最終回覆必須說明這一點。

彙總模板：

處理完成。

成功：3 個
失敗：1 個

成功檔案：
1. /path/a_整理版.txt
   影片時長：00:10:12.350
   處理耗時：00:03:05.120
   段落數：96

失敗檔案：
1. /path/c.mp4
   原因：輸出已存在，未獲覆蓋授權

彙總：
總影片時長：00:40:00.330
實際處理總耗時：00:06:28.500
說明：因為多個影片並行處理，實際處理總耗時不是各單影片處理耗時的簡單相加。

停機條件

出現以下情況時停止對應影片，不生成誤導性結果：

• 輸入不存在或不是普通檔案。
• 輸入是未完成下載檔案。
• 輸出不是 .txt。
• 輸出已存在且未明確允許覆蓋。
• uv、ffmpeg 或 ffprobe 不可用。
• Whisper 失敗、JSON 缺失或沒有有效文本段。

依賴缺失通常影響全部影片，應停止整批處理並提示使用者修復環境。單個輸入或單個轉寫失敗只停止該影片，其餘影片繼續。

反例黑名單

不要做以下事情：

• 不要把多個影片路徑一次性傳給單影片指令碼。
• 不要無限制啟動 agent；預設併發 2，最多 3。
• 不要在未獲明確授權時傳 --force。
• 不要在影片目錄留下 Whisper 中間檔案或批次彙總 JSON/TXT。
• 不要把失敗影片計入“成功處理的總影片時長”，除非回覆中明確單獨說明。
• 不要根據上下文猜測說話人、人名、數字、劑量或專業術語。
• 不要把“實際處理總耗時”說成“總影片時長”；兩者必須分開標註。

這個影片轉文字工具質量不錯，文件寫得清楚詳細，指令碼執行穩定可靠，能很好地保護原始檔安全。使用起來比較簡單，單個或多個影片都能處理。需要注意的是它依賴 ffmpeg 等外部工具，執行時需要等待轉寫過程，整體體驗較好但對環境配置有一定要求。