Media to Text Workflow

將任何影片或音訊來源轉換為高品質逐字稿與結構化摘要。支援多語言自動偵測，可產出雙語版本（原文 + 繁體中文翻譯）。

觸發條件

當使用者提到以下任一情境時啟動：

• 輸入 /media-to-text
• 提到「轉逐字稿」「影片轉文字」「音訊轉文字」「會議記錄」「YouTube 摘要」等關鍵詞
• 提供影片 URL 或音訊檔案路徑並要求轉錄或摘要

使用方式

/media-to-text <input> [--lang auto|en|zh|ja|ko|...] [--bilingual] [--template auto|meeting|...] [--publish local|notion|notebooklm|all] [--output-dir ./output]

範例

# 基本用法（自動偵測語言，單語輸出）
/media-to-text https://youtube.com/watch?v=xxx

# 中文會議，單語輸出
/media-to-text ~/recordings/meeting.m4a --template meeting --publish notion

# 英文影片，雙語輸出（原文 + 繁體中文翻譯）
/media-to-text https://youtube.com/watch?v=xxx --bilingual

# 明確指定語言
/media-to-text ~/Videos/lecture.mp4 --lang en --bilingual --template lecture

參數

平台支援

後端自動偵測，程式碼統一使用 scripts/transcribe.py 抽象層。

Python 環境

本 skill 使用共用虛擬環境 ~/.claude/.venv，所有需要 Python 的地方都使用此路徑。

PYTHON="$HOME/.claude/.venv/bin/python"

為何用 ~/.claude/.venv：此 skill 可在任何專案目錄下觸發，使用固定的全域 venv 避免每個專案都要安裝一次依賴。Whisper 模型快取在 ~/.cache/huggingface/hub/，也是全域共用。

前置檢查

在開始前，用 Bash 工具執行以下檢查：

# 一次檢查所有依賴
echo "=== 依賴檢查 ==="
echo "平台: $(uname -s) $(uname -m)"
command -v yt-dlp   && echo "✅ yt-dlp"   || echo "❌ yt-dlp 缺失"
command -v ffmpeg   && echo "✅ ffmpeg"    || echo "❌ ffmpeg 缺失"
PYTHON="$HOME/.claude/.venv/bin/python"
[[ -x "$PYTHON" ]] && echo "✅ Python venv: $HOME/.claude/.venv" || echo "❌ .venv 缺失 → bash {skill_dir}/install.sh"

# Whisper 後端檢查（自動依平台）
if [[ "$(uname -s)" == "Darwin" && "$(uname -m)" == "arm64" ]]; then
    "$PYTHON" -c "import mlx_whisper" 2>/dev/null && echo "✅ mlx-whisper (Apple Silicon)" || echo "❌ mlx-whisper → pip install mlx-whisper"
else
    "$PYTHON" -c "import faster_whisper" 2>/dev/null && echo "✅ faster-whisper (CUDA/CPU)" || echo "❌ faster-whisper → pip install faster-whisper"
fi

"$PYTHON" -c "import opencc" 2>/dev/null && echo "✅ opencc" || echo "❌ opencc → pip install opencc-python-reimplemented"

若任何依賴缺失，告知使用者安裝指令後停止。

執行模式

提供兩種模式，優先使用一鍵模式：

一鍵模式（推薦）

Phase 1+2 用腳本一次完成擷取與轉錄，接著 Claude 執行 Phase 3-5：

bash {skill_dir}/scripts/media-to-text.sh "<input>" "<output_dir>"

腳本完成後 <output_dir>/ 會包含 transcript.md、transcript.txt、whisper_raw.json，直接跳到 Phase 3。

分步模式

若腳本不可用或使用者要求逐步執行，按以下 Phase 依序進行。

Phase 1：媒體擷取

目標：取得 16kHz mono WAV 音訊檔。

1.1 建立輸出目錄

OUTPUT_DIR="./output/$(date +%Y-%m-%d)_{safe_title}"
mkdir -p "$OUTPUT_DIR"

1.2 依輸入類型擷取音訊

URL（YouTube 等）：

yt-dlp -x --audio-format wav --audio-quality 0 -o "$OUTPUT_DIR/audio_raw.%(ext)s" "<url>"

本地影片（mp4/mkv/avi/mov/webm/flv）：

ffmpeg -y -i "<input>" -vn -acodec pcm_s16le "$OUTPUT_DIR/audio_raw.wav" -loglevel warning

本地音訊（mp3/wav/m4a/flac/ogg/aac/aiff）：直接使用原檔作為 audio_raw。

1.3 統一轉換為 16kHz mono WAV

ffmpeg -y -i "$OUTPUT_DIR/audio_raw"* -ar 16000 -ac 1 -c:a pcm_s16le "$OUTPUT_DIR/audio.wav" -loglevel warning

WHY 16kHz mono：Whisper 模型的原生輸入格式，減少不必要的降採樣計算。

1.4 報告

✅ Phase 1 完成：音訊擷取
   檔案：audio.wav (16kHz mono)
   時長：{用 ffprobe 取得}
   來源：{url 或檔名}

失敗回退：若 yt-dlp 失敗，提示使用者確認 URL。若 ffmpeg 失敗，檢查輸入格式。

Phase 2：語言偵測與轉錄

目標：偵測語言 → 用該語言轉錄 → 可選翻譯為繁體中文。

2.1 語言偵測（若 --lang auto）

用 transcribe.py 轉錄完整音訊，讀取結果中的 language 欄位（或用 Whisper 跑前 30 秒片段偵測）：

$HOME/.claude/.venv/bin/python {skill_dir}/scripts/transcribe.py \
    "$OUTPUT_DIR/audio.wav" "$OUTPUT_DIR/whisper_raw.json" \
    --language auto
# 讀取偵測到的語言
DETECTED_LANG=$($HOME/.claude/.venv/bin/python -c "
import json; d=json.load(open('$OUTPUT_DIR/whisper_raw.json'))
print(d.get('language', 'unknown'))
")

偵測到語言後，向使用者確認（除非使用者已用 --lang 指定）：

🌐 偵測到主要語言：{detected_language}

若偵測到非中文語言且使用者未指定 --bilingual，主動詢問：

   是否需要繁體中文翻譯版？(Y/n)

若使用者用 --lang 明確指定語言，跳過偵測直接使用。

2.2 原文轉錄

用偵測到的語言（或使用者指定的語言）執行 Whisper 轉錄。

關鍵原則：Whisper 的 language 參數必須設為音訊的實際語言。英文音訊就設 "en"，中文音訊就設 "zh"。跨語言轉錄（如對英文音訊設 language="zh"）品質極差，絕對禁止。

轉錄統一使用跨平台抽象層 transcribe.py（自動偵測 mlx-whisper 或 faster-whisper）：

中文音訊：

$HOME/.claude/.venv/bin/python {skill_dir}/scripts/transcribe.py \
    "$OUTPUT_DIR/audio.wav" "$OUTPUT_DIR/whisper_raw.json" \
    --language zh \
    --initial-prompt "以下是繁體中文的錄音，可能包含英文術語。"
# 然後用 OpenCC s2twp 簡轉繁，產生 transcript.md / transcript.txt

輸出：transcript.md、transcript.txt、whisper_raw.json

非中文音訊（如英文）：

$HOME/.claude/.venv/bin/python {skill_dir}/scripts/transcribe.py \
    "$OUTPUT_DIR/audio.wav" "$OUTPUT_DIR/whisper_raw_{lang}.json" \
    --language en \
    --initial-prompt "This is an English recording. It may contain technical terms."
# 不需要 OpenCC，直接輸出原文

非中文音訊的輸出檔名帶語言後綴：

• transcript_{lang}.md（如 transcript_en.md）
• transcript_{lang}.txt（如 transcript_en.txt）
• whisper_raw_{lang}.json（如 whisper_raw_en.json）

2.3 繁體中文翻譯（若 --bilingual 或使用者同意）

僅在以下情況執行翻譯：

• 使用者指定 --bilingual
• 偵測到非中文語言且使用者回答「是」

翻譯方式：用 Agent 工具發送翻譯任務（Claude 翻譯品質最好）。

Agent prompt:
  讀取 {output_dir}/transcript_{lang}.md 的英文逐字稿，
  翻譯成繁體中文（台灣用語），寫入：
  1. {output_dir}/transcript.md（含時間戳，每段 1:1 對應）
  2. {output_dir}/transcript.txt（純文字版）
  翻譯規則：
  - 保留所有專有名詞英文原文
  - 時間戳段落數必須與原文完全一致
  - 使用台灣用語（記憶體、程式、伺服器）

翻譯方式的選擇邏輯：

2.4 initial_prompt 語言適配

根據偵測到的語言自動調整 initial_prompt：

關鍵參數說明

報告

✅ Phase 2 完成：語音轉錄
   語言：{detected_language}
   字數：{char_count}
   段落：{segment_count}
   模式：{單語/雙語}
   輸出：{列出實際產生的檔案}

失敗回退：若 Whisper 記憶體不足，建議用較小模型 mlx-community/whisper-base。

Phase 3：範本偵測與摘要

目標：偵測最適範本，生成結構化 summary.md。

3.1 讀取逐字稿前 500 字

用 Read 工具讀取 {output_dir}/transcript.txt，取前 500 字用於範本偵測。

3.2 範本偵測邏輯

根據逐字稿內容的特徵判斷最適範本：

匹配方式：計算每個範本的關鍵詞命中數，選擇命中最多者。若命中數相同或都為 0，使用 general。

3.3 使用者確認

🔍 偵測到最適範本：{template_name}（{template_id}）
   依據：命中關鍵詞 [{matched_keywords}]
   使用此範本？(Y/n) 或輸入其他範本 ID：

等待使用者確認後繼續。若使用者指定了 --template 且非 auto，跳過偵測。

3.4 讀取範本 YAML

用 Read 工具讀取 {skill_dir}/templates/{template_id}.yaml。

其中 {skill_dir} 為此 SKILL.md 所在目錄的絕對路徑。

3.5 生成摘要

讀取主要逐字稿作為上下文（中文音訊用 transcript.txt，非中文音訊用 transcript_{lang}.txt），以範本 YAML 中的 system_prompt 設定角色，逐 section 生成摘要內容。

雙語模式：若為雙語輸出，先用原文逐字稿生成原文摘要（summary_{lang}.md），再翻譯為繁體中文摘要（`summa