markdown-video

Markdown Video Skill

Markdown スライドを、AI 生成のビジュアルと TTS 音声ナレーションを使ってプレゼンテーション動画に変換します。

このスキルを使用する場面

次のような依頼があった場合に、このスキルを有効にします。

• Markdown スライドから動画を作成する
• プレゼンテーションを MP4 形式に変換する
• スライドからナレーション付き動画を生成する
• スライドから動画への変換を自動化する

主な機能

• Gemini AI 生成ビジュアル：絵文字と韓国語に完全対応した高品質なスライド画像
• OpenAI TTS ナレーション：スピーカーノートから自然な音声を生成
• 差分更新：変更されたスライドのみを再生成します（時間と API コストを節約）
• 複数のビジュアルスタイル：technical-diagram、professional、vibrant-cartoon、watercolor

入力要件

• ^ 接頭辞でスピーカーノートを記した Markdown ファイル
• 画像生成用の GEMINI_API_KEY 環境変数
• TTS 音声用の OPENAI_API_KEY 環境変数

出力仕様

• MP4 動画：1920x1080（フル HD）
• 長さ：各スライドの表示時間は、その音声ナレーションの長さに合わせます
• ファイル名：{input_filename}.mp4

---

ワークフロー

ステップ 1：音声ファイルを生成する

cd "{slides_directory}"
python /Users/lifidea/.claude/skills/markdown-video/generate_audio.py "{slides_filename}" --output-dir "audio"

差分更新：スピーカーノートが変更されたスライドの音声のみを再生成します。

• --force を使うと、すべての音声ファイルを再生成します

出力：

• audio/slide_0.mp3、slide_1.mp3、...（0 始まり）
• キャッシュファイル：audio/.audio_cache.json

ステップ 2：Gemini でスライド画像を生成する

cd "{slides_directory}"
python /Users/lifidea/.claude/skills/markdown-video/create_slides_gemini.py "{slides_filename}" \
  --output-dir "slides-gemini" \
  --style "technical-diagram" \
  --auto-approve

差分更新：内容が変更されたスライドの画像のみを再生成します。

• --force を使うと、すべてのスライド画像を再生成します

スタイルオプション：

スタイル	説明	最適な用途
technical-diagram	すっきりした線、インフォグラフィックのアイコン、落ち着いた青／グレー	技術、教育
professional	ミニマルな幾何学模様	企業、フォーマル
vibrant-cartoon	明るいグラデーション、フラットデザイン	マーケティング、スタートアップ
watercolor	柔らかなパステルカラー、有機的な形	クリエイティブ、個人向け

その他のパラメーター：

• --model：Gemini モデル（デフォルト：gemini-3-pro-image-preview）
• --aspect-ratio：16:9（デフォルト）、1:1、9:16、4:3、3:4
• --start-from N：スライド N から再開
• --dry-run：生成せずにプロンプトをプレビュー

出力：

• slides-gemini/1.jpeg、2.jpeg、...（1 始まり）
• キャッシュファイル：slides-gemini/.slides_cache.json

ステップ 3：最終動画を作成する

cd "{slides_directory}"
python /Users/lifidea/.claude/skills/markdown-video/slides_to_video.py \
  --slides-dir "slides-gemini" \
  --audio-dir "audio" \
  --output "{output_filename}.mp4"

---

差分更新

音声と画像の生成はどちらも差分更新に対応しており、変更されたもののみを再生成します。

仕組み

1. コンテンツのハッシュ化：各スライドのコンテンツをハッシュ化します（MD5）
2. キャッシュの保存：ハッシュを .audio_cache.json／.slides_cache.json に保存します
3. 変更の検出：次回の実行時に、変更されたスライドのみを再生成します
4. ファイルの検証：出力ファイルが存在するかどうかも確認します

出力例

✅ Found 20 slides
   20 slides with speaker notes

✨ Delta update: 17 slides unchanged, 3 to regenerate

🎵 Generating 3 audio files...
Progress |████████████████████████████████████████| 3/3 (100.0%)

✅ Audio generation complete!
   Generated: 3/3 files
   Unchanged: 17 files (skipped)

強制再生成

キャッシュを無視してすべてを再生成するには、次のコマンドを実行します。

# Force regenerate all audio
python generate_audio.py "slides.md" --output-dir "audio" --force

# Force regenerate all images
python create_slides_gemini.py "slides.md" --output-dir "slides-gemini" --force

---

クイックリファレンス

ワークフロー全体（初回実行）

cd "{slides_directory}"

# Step 1: Generate audio
python /Users/lifidea/.claude/skills/markdown-video/generate_audio.py "slides.md" --output-dir "audio"

# Step 2: Generate slide images
python /Users/lifidea/.claude/skills/markdown-video/create_slides_gemini.py "slides.md" \
  --output-dir "slides-gemini" \
  --style "technical-diagram" \
  --auto-approve

# Step 3: Create video
python /Users/lifidea/.claude/skills/markdown-video/slides_to_video.py \
  --slides-dir "slides-gemini" \
  --audio-dir "audio" \
  --output "presentation.mp4"

更新ワークフロー（変更後）

同じコマンドを実行します。差分更新は自動で行われます。

# Only regenerates changed slides
python generate_audio.py "slides.md" --output-dir "audio"
python create_slides_gemini.py "slides.md" --output-dir "slides-gemini" --auto-approve
python slides_to_video.py --slides-dir "slides-gemini" --audio-dir "audio" --output "presentation.mp4"

---

必要条件

システム依存関係

• Python 3.7+
• ffmpeg：brew install ffmpeg

Python パッケージ

pip install Pillow requests google-genai

環境変数

export OPENAI_API_KEY="sk-..."
export GEMINI_API_KEY="..."

---

コストの見積もり

コンポーネント	コスト	例（20 枚のスライド）
Gemini 画像	約 $0.04／枚	約 $0.80
OpenAI TTS	約 $0.015／1K 文字	約 $0.50
合計		約 $1.30

差分更新を使うと、2 回目以降は変更されたスライド分のコストのみがかかります。

---

エラー処理

スピーカーノートが見つからない

• ナレーションには、^ 接頭辞を付けたスピーカーノートが必要です
• 例：^ This is the speaker note for this slide.

発音の問題

• スピーカーノート内の専門用語を、発音しやすい表記に置き換えます
• まず --dry-run でテストします

API エラー

• API キーの環境変数を確認します
• Gemini のレート制限：スクリプトでは生成の間に 1 秒の待機時間を設けています

---

品質チェックリスト

完了としてマークする前に、以下を確認してください。

• OpenAI と Gemini の API キーが設定されている
• Markdown ファイルに ^ プレフィックス付きのスピーカーノートがある
• 音声ファイルが正常に生成されている
• スライド画像が正常に生成されている
• 音声と同期して動画が正しく再生される
• 解像度が 1920x1080 である

---

画像生成モード

ビジュアルを生成する方法は 2 つあります。

モード	スクリプト	最適な用途
スライドごと	create_slides_gemini.py	標準的なプレゼンテーション、精密な制御
セクションごと	generate_section_images.py	長いプレゼンテーション、インフォグラフィック形式

セクションごとの方法を使用する場合

• スライドが 20 枚以上あるプレゼンテーション
• コンテンツが自然に論理的なセクションにまとまる
• 個々のスライドよりも、セクションごとのインフォグラフィック概要を優先する
• API コストを削減したい（画像の生成枚数が少ない）

---

セクションごとのワークフロー（代替方法）

スライドが多いプレゼンテーションでは、スライドごとではなく、セクションごとにインフォグラフィック画像を 1 枚生成します。

比較

項目	スライドごと	セクションごと
画像	スライドごとに 1 枚	セクションごとに 1 枚
音声	スライドごと	スライドごと → セクションごとに結合
レビュー	Markdown 内で直接	動画スクリプトドキュメント
最適な用途	短いプレゼンテーション	長いプレゼンテーション（20 枚以上）

ステップ 1：音声ファイルを生成する

標準的なワークフローと同じです。

cd "{slides_directory}"
python /Users/lifidea/.claude/skills/markdown-video/generate_audio.py "{slides_filename}" --output-dir "audio"

ステップ 2：セクションのインフォグラフィック画像を生成する

cd "{slides_directory}"
python /Users/lifidea/.claude/skills/markdown-video/generate_section_images.py "{slides_filename}" \
  --output-dir "slides-section" \
  --style "infographic"

スタイルのオプション：

スタイル	説明
infographic	アイコンを使った、すっきりとしたプロフェッショナルなデザイン（デフォルト）
professional	ミニマルなコーポレートデザイン
vibrant	マーケティング向けの明るいグラデーション
technical	フローチャートと技術図

その他のパラメーター：

• --start-from N：セクション N から再開
• --force：すべての画像を再生成
• --dry-run：生成せずにセクションをプレビュー
• --delay N：API 呼び出しの間隔（秒）（デフォルト：2.0）

ステップ 3：動画スクリプトを作成する（任意）

ナレーションをレビューするための Markdown ドキュメントを生成します。

cd "{slides_directory}"
python /Users/lifidea/.claude/skills/markdown-video/create_video_script.py "{slides_filename}" \
  --output "video_script.md" \
  --image-dir "slides-section"

スクリプトドキュメントには、以下が表示されます。

• 埋め込み済みのセクション画像
• 各スライドのスピーカーノート
• 編集しやすい形式

ステップ 4：ナレーションをレビューして編集する

1. video_script.md を開きます
2. 引用ブロック内のナレーションを確認します
3. ドキュメント内で直接編集します
4. 変更内容を元の Markdown ファイルに反映します
5. 変更したスライドの音声を再生成します。

   python generate_audio.py "slides.md" --output-dir "audio"
   

ステップ 5：セクションごとの動画を作成する

cd "{slides_directory}"
python /Users/lifidea/.claude/skills/markdown-video/create_section_video.py \
  --slides "{slides_filename}" \
  --audio-dir "audio" \
  --image-dir "slides-section" \
  --output "presentation.mp4"

設定ファイルを使用する場合（カスタムのセクションマッピング用）：

python create_section_video.py \
  --config "sections.json" \
  --audio-dir "audio" \
  --image-dir "slides-section" \
  --output "presentation.mp4"

設定ファイルの形式：

{
  "sections": [
    {"id": 0, "name": "title", "audio_slides": [0]},
    {"id": 1, "name": "introduction", "audio_slides": [1, 2, 3]},
    {"id": 2, "name": "main_content", "audio_slides": [4, 5, 6, 7]}
  ]
}

---

セクションごとのクイックリファレンス

cd "{slides_directory}"

# Step 1: Generate audio
python /Users/lifidea/.claude/skills/markdown-video/generate_audio.py "slides.md" --output-dir "audio"

# Step 2: Generate section images
python /Users/lifidea/.claude/skills/markdown-video/generate_section_images.py "slides.md" \
  --output-dir "slides-section" \
  --style "infographic"

# Step 3 (optional): Create review document
python /Users/lifidea/.claude/skills/markdown-video/create_video_script.py "slides.md" \
  --output "video_script.md" \
  --image-dir "slides-section"

# Step 4: Create final video
python /Users/lifidea/.claude/skills/markdown-video/create_section_video.py \
  --slides "slides.md" \
  --audio-dir "audio" \
  --image-dir "slides-section" \
  --output "presentation.mp4"