media-transcription · diff
git:20260223.b8eecd8 to git:20260223.cae670e
6 added, 6 removed. Audit A to A.
---
name: media-transcription
description: 影片/音訊逐字稿轉錄（faster-whisper）
allowed-tools: mcp__ching-tech-os__run_skill_script
metadata:
ctos:
requires_app: file-manager
mcp_servers: ching-tech-os
---
【影片/音訊逐字稿轉錄（faster-whisper）】
將影片或音訊檔轉錄為繁體中文逐字稿。使用 faster-whisper 本地語音辨識，免費、無需 API 金鑰。
轉錄流程為非同步：啟動轉錄 → 查詢進度 → 取得逐字稿。
**可用 scripts：**
1. **transcribe** — 啟動轉錄（非同步，立即回傳 job ID）
- `run_skill_script(skill="media-transcription", script="transcribe", input='{"source_path":"ctos://linebot/videos/2026-02-23/a1b2c3d4/video.mp4"}')`
- - source_path：要轉錄的音訊/影片檔的 ctos:// 路徑
+ - source_path：要轉錄的音訊/影片檔路徑（支援 `ctos://`、`shared://` 等格式）
- 可選參數 model：whisper 模型大小（base/small/medium/large-v3，預設 small）
- 支援格式：影片（.mp4、.mkv、.webm）、音訊（.mp3、.m4a、.wav、.ogg、.flac）
- 立即回傳 job_id，轉錄在背景執行
2. **check-transcription** — 查詢轉錄進度（同步）
- `run_skill_script(skill="media-transcription", script="check-transcription", input='{"job_id":"之前取得的job_id"}')`
- 回傳轉錄狀態（extracting_audio/transcribing/completed/failed）
- - 完成時回傳 ctos_path（逐字稿 .md 檔）和 transcript_preview（前 500 字預覽）
+ - 完成時回傳 ctos_path（逐字稿 .md 檔路徑）、transcript_preview（前 500 字預覽，可直接用於簡短摘要）、duration（音訊時長）
**典型使用流程：**
1. 使用者透過 media-downloader 下載影片，取得 ctos_path
2. 呼叫 transcribe 啟動轉錄，取得 job_id
- 3. 呼叫 check-transcription 查詢進度，完成後取得逐字稿 ctos_path
- 4. 用 read_knowledge_attachment 或 read_document 讀取逐字稿內容
- 5. 依使用者要求整理摘要/總結/重點筆記
+ 3. 呼叫 check-transcription 查詢進度，完成後取得逐字稿 ctos_path 和 transcript_preview
+ 4. 讀取逐字稿全文：用 `get_nas_file_info(file_path=ctos_path)` 取得實際路徑，再用 Read 工具讀取 .md 檔。**注意：逐字稿是 .md 格式，read_document 不支援 .md，不要使用 read_document**
+ 5. 依使用者要求整理摘要/總結/重點筆記（若只需簡短摘要，check-transcription 的 transcript_preview 已有前 500 字，可直接使用）
6. 使用 add_note 存入知識庫，或 archive_to_library 歸檔到圖書館
**AI 行為指引：**
- 當使用者下載了影片/音訊後問「幫我整理內容」、「這在講什麼」等，主動建議先轉錄
- - source_path 必須是 `ctos://` 開頭的完整路徑，來源可能是：media-downloader 的 check-download 回傳的 ctos_path、search_nas_files 搜尋結果、list_library_folders 瀏覽結果、知識庫附件路徑等。**務必從對話歷史或工具回傳結果中取得確切路徑，不要自行猜測或拼湊**
+ - source_path 支援 `ctos://` 和 `shared://` 等路徑格式。來源可能是：media-downloader 的 check-download 回傳的 ctos_path、search_nas_files 搜尋結果（`shared://` 格式）、archive_to_library 回傳路徑（`shared://library/...` 格式）、list_library_folders 瀏覽結果、知識庫附件路徑等。**務必從對話歷史或工具回傳結果中取得確切路徑，不要自行猜測或拼湊**
- 對於短音訊（< 5 分鐘）建議使用 base 模型（速度快）；較長或需要高品質時建議 small 或 medium
- **嚴禁使用 sleep 等待轉錄完成**。轉錄可能需要數分鐘，啟動後只需查詢一次進度：
- 若仍在轉錄中：直接回覆使用者「轉錄進行中，請稍後再詢問進度」，**結束本次回應**
- 若已完成：讀取逐字稿並提供摘要
- 不要在同一次回應中反覆 sleep + check，這會導致超時