youtube-to-markdown

YouTube から Markdown へ

複数の動画：動画を 1 本ずつ順番に処理します。並行して抽出を実行しないでください。 ユーザーの承認を求めず、すべての手順を順番に実行します。TodoWrite を使用して進捗を追跡します。

Step 0: 抽出済みか確認する

python3 ./check_existing.py "<YOUTUBE_URL>" "<output_directory>"

整合性チェック：

• summary_valid: false の場合：問題点をユーザーに表示し、「ファイルが不完全です：[issues]。再処理しますか？」と尋ねます。はいの場合は Step 1 に進みます。
• transcript_valid: false の場合：ユーザーに尋ね、はいの場合は Steps 2〜3、7〜9 を再実行します。
• comments_valid: false の場合：ユーザーに尋ね、はいの場合はコメント分析を再実行します。

exists: true かつすべての有効性フィールドが true を返す場合は、更新ワークフローについて UPDATE_MODE.md を読み、その指示に従います。

Step 1: データを抽出する（メタデータ、説明、チャプター）

python3 extract_data.py "<YOUTUBE_URL>" "<output_directory>"

作成するファイル：youtube_{VIDEO_ID}metadata.md、youtube{VIDEO_ID}description.md、youtube{VIDEO_ID}_chapters.json

重要：抽出する字幕の言語を尋ねた場合、その言語を英語に翻訳しないでください。また、サブエージェントにも翻訳しないよう指示してください。元の言語とは別の言語をユーザーがリクエストした場合にのみ翻訳します。

Step 2: 字幕を抽出する

主要な方法（字幕が利用可能な場合）

動画の言語が en の場合は、そのまま進みます。英語以外の場合は、ダウンロードする言語をユーザーに尋ねます。

python3 extract_transcript.py "<YOUTUBE_URL>" "<output_directory>" "<LANG_CODE>"

作成するファイル：youtube_{VIDEO_ID}_transcript.vtt

重要：すべてのファイル出力は Step 2 で判明した言語と同じ言語にしてください。言語が英語ではない場合は、すべてのサブエージェントに原文の言語を維持するよう明示的に指示します。

動画が非公開、年齢制限付き、または地域制限されている場合、ダウンロードに失敗することがあります。

フォールバック（字幕を利用できない場合のみ）

ユーザーに尋ねます：「字幕がありません。Whisper で文字起こしを実行しますか？

• Mac／Apple Silicon：インストール済みの場合は MLX Whisper を使用します（高速です。SETUP_MLX_WHISPER.md を参照）
• すべてのプラットフォーム：OpenAI Whisper にフォールバックします（必要なもの：brew install openai-whisper または pip3 install openai-whisper）」

python3 extract_transcript_whisper.py "<YOUTUBE_URL>" "<output_directory>"

スクリプトは Mac 上の MLX Whisper を自動検出し、利用可能な場合はそれを使用します。それ以外の場合は OpenAI Whisper を使用します。

Step 3: 字幕の重複を削除する

Step 1 の出力から BASE_NAME を設定します（youtube_{VIDEO_ID}）

python3 ./deduplicate_vtt.py "<output_directory>/${BASE_NAME}_transcript.vtt" "<output_directory>/${BASE_NAME}_transcript_dedup.md" "<output_directory>/${BASE_NAME}_transcript_no_timestamps.txt"

Step 4: 自然な段落区切りを追加する

Step 5 と並行して実行します。

task_tool:

• subagent_type: "general-purpose"
• model: "sonnet"
• prompt:

INPUT: <output_directory>/${BASE_NAME}_transcript_no_timestamps.txt
CHAPTERS: <output_directory>/${BASE_NAME}_chapters.json
OUTPUT: <output_directory>/${BASE_NAME}_transcript_paragraphs.txt

Analyze INPUT and identify natural paragraph break line numbers.

Read CHAPTERS. If it contains chapters, use chapter timestamps as primary break points.

Target ~500 chars per paragraph. Find natural break points at topic shifts or sentence endings.

Write to OUTPUT in format:
15,42,78,103,...

python3 ./apply_paragraph_breaks.py "<output_directory>/${BASE_NAME}_transcript_dedup.md" "<output_directory>/${BASE_NAME}_transcript_paragraphs.txt" "<output_directory>/${BASE_NAME}_transcript_paragraphs.md"

Step 5: 字幕を要約する

Step 4 と並行して実行します。

task_tool:

• subagent_type: "general-purpose"
• model: "sonnet"
• prompt:

INPUT: <output_directory>/${BASE_NAME}_transcript_no_timestamps.txt
OUTPUT: <output_directory>/${BASE_NAME}_summary.md
FORMATS: ./summary_formats.md

1. Classify content type:
   - TIPS: gear reviews, rankings, "X ways to...", practical advice lists
   - INTERVIEW: podcasts, conversations, Q&A, multiple perspectives
   - EDUCATIONAL: concept explanations, analysis, "how X works"
   - TUTORIAL: step-by-step instructions, coding, recipes

2. Analyze content structure:
   - Identify meaningful content units (topic shifts, argument structure, narrative breaks)
   - If single continuous topic, omit content unit headers
   - Skip ads, sponsors, self-promotion ("like and subscribe", merch, etc.)
   - Merge content spanning ad breaks if thematically connected

3. Read FORMATS file and use format for detected content type. Target <10% of transcript bytes.


ACTION REQUIRED: Use the Write tool NOW to save output to OUTPUT file. Do not ask for confirmation.

Step 6: 要約を見直して簡潔にする

task_tool:

• subagent_type: "general-purpose"
• model: "sonnet"
• prompt:

INPUT: <output_directory>/${BASE_NAME}_summary.md
OUTPUT: <output_directory>/${BASE_NAME}_summary_tight.md
FORMATS: ./summary_formats.md

You are an adversarial copy editor. Cut fluff, enforce quality.

Rules:
- Read FORMATS - the format has been selected based on the content type - preserve format and do not count a reason to squeeze more from budget.
- Byte budget: <10% of transcript bytes
- Hidden Gems: Remove if duplicates main content
- Tightness: Cut filler words, compress verbose explanations, prefer lists over prose

Preserve original language - do not translate.

ACTION REQUIRED: Use the Write tool NOW to save output to OUTPUT file. Do not ask for confirmation.

Step 7: 音声認識のノイズを除去する

task_tool:

• subagent_type: "general-purpose"
• model: "haiku"
• prompt:

Read <output_directory>/${BASE_NAME}_transcript_paragraphs.md and clean speech artifacts.

Tasks:
- Remove fillers (um, uh, like, you know)
- Fix transcription errors
- Add proper punctuation
- Reduce or add implicit words to improve flow
- Preserve natural voice and tone
- Keep timestamps at end of paragraphs

ACTION REQUIRED: Use the Write tool NOW to save output to <output_directory>/${BASE_NAME}_transcript_cleaned.md. Do not ask for confirmation.

Step 8: トピック見出しを追加する

task_tool:

• subagent_type: "general-purpose"
• model: "sonnet"
• prompt:

INPUT: <output_directory>/${BASE_NAME}_transcript_cleaned.md
OUTPUT: <output_directory>/${BASE_NAME}_transcript.md

Read the INPUT file. Add markdown headings.

Read <output_directory>/${BASE_NAME}_chapters.json:
- If contains chapters: Use chapter names as ### headings at chapter timestamps, add #### headings for subtopics
- If empty: Add ### headings where major topics change

ACTION REQUIRED: Use the Write tool NOW to save output to OUTPUT file. Do not ask for confirmation.

Step 9: 出力ファイルを作成する

python3 finalize.py "${BASE_NAME}" "<output_directory>"

スクリプトはテンプレートを使って 2 つの最終ファイルを作成します。1 つはメタデータと要約を含む要約ファイル、もう 1 つは説明と字幕を含む字幕ファイルです。中間作業ファイルは削除されます。

出力：

• youtube - {title} ({video_id}).md - メインの要約
• youtube - {title} - transcript ({video_id}).md - 説明と字幕

中間作業ファイルを確認用に保持するには、--debug フラグを使用します。

Step 10: コメント分析

youtube-comment-analysis スキルが利用可能な場合は、同じ YouTube URL と出力ディレクトリを指定して実行します。