mcpField
M
markdown-video

markdown-video

github.com/jykim创意与媒体5048 次安装5 周前更新
代码仓库

关于 markdown-video

Markdown Video Skill 使用生成的幻灯片图像和语音合成音频，将 Markdown 幻灯片转换为带旁白的 MP4。适合演示文稿制作者，支持逐页或按章节制作视频，并可仅重新生成有变更的内容。

主要功能

  1. 01使用 Gemini 生成幻灯片图像
  2. 02根据演讲者备注用 OpenAI TTS 生成旁白
  3. 03仅重新生成已更改的幻灯片
  4. 04选择多种视觉风格
  5. 05制作逐页或按章节的视频

适用场景

  1. 01将 Markdown 幻灯片制作为带旁白的 MP4
  2. 02编辑部分幻灯片后更新视频
  3. 03为长演示文稿生成章节信息图

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/jykim/claude-obsidian-skills --skill markdown-video

安装后在 Claude Code 中输入/markdown-video确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

create_audio_mapping.py
create_section_video.py
create_slides_from_markdown.py
create_slides_gemini.py
create_video_script.py
generate_audio.py
generate_section_images.py
README.md
requirements.txt
slides_to_video.py

详细介绍

Markdown 视频技能

将 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（全高清）
  • 时长：每张幻灯片的显示时长与其音频旁白时长一致
  • 文件命名：{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

使用增量更新后，后续运行仅需为有变更的幻灯片付费。

错误处理

未找到演讲者备注
  • 幻灯片需要带有 ^ 前缀的演讲者备注才能生成旁白
  • 示例：^ This is the speaker note for this slide.
发音问题
  • 在演讲者备注中将专业术语替换为表音拼写
  • 先使用 --dry-run 测试
API 错误
  • 检查 API 密钥环境变量
  • Gemini 速率限制：脚本会在每次生成之间间隔 1 秒

质量检查清单

完成前，请确认：

  • 已配置 OpenAI 和 Gemini API 密钥
  • Markdown 文件包含以 ^ 为前缀的演讲者备注
  • 音频文件已成功生成
  • 幻灯片图片已成功生成
  • 视频播放正常，且音频已同步
  • 分辨率为 1920x1080

图片生成模式

生成视觉内容有两种方式：

模式脚本适用场景
逐张幻灯片create_slides_gemini.py标准演示文稿、需要精确控制
按章节generate_section_images.py长篇演示文稿、信息图风格
何时使用按章节模式
  • 演示文稿包含 20 张以上幻灯片
  • 内容自然地划分为多个逻辑章节
  • 更喜欢每章一张信息图概览，而非单独的幻灯片图片
  • 希望降低 API 成本（减少图片数量）

按章节工作流（替代方案）

对于包含许多幻灯片的演示文稿，可以为每个章节生成一张信息图，而不是为每张幻灯片生成图片。

对比
方面逐张幻灯片按章节
图片每张幻灯片 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"

评论

支持 Markdown