name: ppt-to-video description: "This skill converts PDF presentation slides, a speech manuscript, and a reference voice into a complete narrated presentation video with synchronized subtitles. It should be used when the user wants to generate a presentation video from PPT/PDF slides with voice cloning, text-to-speech, and subtitle generation. Trigger phrases include PPT to video, generate presentation video, slides to video, 演講影片, PPT轉影片, 幻燈片生成影片, voice cloning presentation, or any request involving converting slide decks into narrated videos with speech synthesis."

PPT轉影片：演講影片生成器

概述

本技能將 PDF 幻燈片 + 演講稿轉換為帶同步字幕的完整演講影片。所有處理均在本地執行（Qwen3-TTS）或使用免費線上服務（edge-tts），無需付費 API。

TTS 引擎（二選一，優先 Qwen3-TTS）： - Qwen3-TTS（推薦）：阿里通義千問團隊開源語音合成模型，本地執行，支援聲音克隆（提供參考音訊即可復刻音色），也支援預設音色 - edge-tts（備選）：微軟免費線上 TTS 服務，無需 GPU，需聯網，僅支援預設音色（不支援聲音克隆）

7w4.net小蔥技能站，你的AI助手技能庫。

核心流水線：演講稿處理 → 語音合成（可選聲音克隆） → 影片生成 → 最終合併

🎬 Remotion 模式（原生元件）

當用戶明確要求使用 Remotion 生成影片時，啟用此模式。

核心規則（強制）

禁止使用 PPT/PDF 截圖作為影片內容。必須用 Remotion 原生 TSX 元件重新設計每一頁的視覺內容。

動畫觸發幀必須與 timing_data.json 中對應句子的時間戳對齊。禁止使用固定幀數或固定迴圈觸發動畫。

原因：截圖解析度低、有白邊、無法動畫、無法響應字幕節奏；原生元件全向量、動畫精確可控、體積更小。

工作流差異

詳細規範

完整的設計規範、佈局模板、hooks 使用規則、字幕同步機制見：

references/remotion-guide.md

前置條件

開始前，請確認以下工具和模型已安裝。

🔍 一鍵環境檢查（推薦）

首次使用前，執行環境檢查指令碼確認所有依賴已就緒：

python {SKILL_DIR}/scripts/check_environment.py

該指令碼會檢查： - ✅ 系統工具（FFmpeg、ffprobe） - ✅ Python 核心依賴（numpy、PyMuPDF） - ✅ TTS 引擎（qwen-tts 或 edge-tts） - ⚠️ 可選依賴（whisper、demucs 等） - 📦 已快取的 Qwen3-TTS 模型 - 🔤 系統字型

如果檢測到缺失依賴，指令碼會給出具體的安裝命令。

必需的系統工具

• FFmpeg（含 ffprobe）：brew install ffmpeg-full（macOS，完整版）或系統包管理器
• Python 3.8+ 及 pip

必需的 Python 包

pip install numpy PyMuPDF

TTS 引擎（至少安裝其一）

# 方式一（推薦）：Qwen3-TTS — 本地高質量語音合成
pip install -U qwen-tts

# 方式二：edge-tts — 微軟線上 TTS，無需 GPU
pip install edge-tts

可選（增強功能）

• openai-whisper（pip install openai-whisper）：語音轉文字（步驟1篩選參考片段時需要）
• Demucs（pip install demucs）：人聲分離（僅需從影片中提取人聲時使用）
• pdf2image + Poppler：備用 PDF 轉換後端

⚡ 快速安裝所有推薦依賴

# 核心依賴
pip install numpy PyMuPDF

# 推薦 TTS 引擎
pip install -U qwen-tts

# 可選：完整功能
pip install edge-tts openai-whisper demucs

工作流程

步驟 0（必需）：LLM 整理演講稿格式

重要：使用者提供的演講稿可能是各種格式（Word 匯出、筆記軟體匯出、手動編寫等），在呼叫 step2_process_speech.py 之前，必須先使用 LLM 將演講稿整理成標準格式。

整理標準

演講稿必須符合以下 Markdown 結構：

## 第 1 頁 幻燈片標題

第 1 頁的演講內容第一段。

第 1 頁的演講內容第二段。

---

## 第 2 頁 另一頁標題

第 2 頁的演講內容。

LLM 整理提示詞

當用戶提供了演講稿但格式不符合標準時，執行以下步驟：

1. 呼叫 LLM 整理格式：

你是一個專業的演講稿整理助手。請將使用者輸入的演講稿整理成標準格式。

## 輸出格式要求
1. 使用 ## 第 X 頁 標題 的格式來標識每一頁幻燈片的開始
2. 每頁內容放在標題下方，使用連續的自然段落
3. 刪除所有與演講內容無關的元資訊（如備註、作者、時間戳、郵箱等）
4. 保留演講的核心文字內容和標點符號
5. 清理特殊格式字元，但保留標點
6. 如果原稿件沒有明確的頁碼劃分，請根據內容邏輯合理分頁（每頁建議200-400字）
7. 保持原文語義不變，不要新增或刪減實質內容
8. 使用 --- 作為頁面之間的分隔符

## 示例

### 示例輸入（混亂格式）：
各位朋友大家好
Page 1
歡迎致辭
今天非常高興...

### 示例輸出：
## 第 1 頁 歡迎致辭
各位朋友大家好，今天非常高興。

---

## 第 2 頁 主題介紹
...

2. 將 LLM 返回的標準格式內容寫入檔案（如 output/step0_manuscript_formatted.md）

3. 後續步驟使用整理後的檔案，而非原始檔案

輸入要求

📋 輸入檔案校驗（推薦）

執行流水線前，可使用校驗指令碼檢查輸入檔案格式：

python {SKILL_DIR}/scripts/validate_inputs.py \
    --speech_md <演講稿.md> \
    --slides_pdf <幻燈片.pdf> \
    --reference_voice <參考音訊.wav>  # 可選

該指令碼會檢查： - PDF 檔案有效性和頁數 - 演講稿格式是否符合標準（## 第 X 頁 格式） - 演講稿頁數與 PDF 頁數是否匹配 - 參考音訊時長和格式（如果提供） - 特殊字元和數字的 TTS 相容性

如果發現問題，指令碼會給出具體的修復建議。

快速開始 — 一鍵執行

使用 Qwen3-TTS + 聲音克隆（推薦，需提供參考音訊）

python {SKILL_DIR}/scripts/run_pipeline.py \
    --speech_md <演講稿.md> \
    --slides_pdf <幻燈片.pdf> \
    --output_dir <輸出目錄> \
    --tts_engine qwen3 \
    --reference_voice <參考音訊.wav>

使用 Qwen3-TTS + 預設音色（無參考音訊時）

python {SKILL_DIR}/scripts/run_pipeline.py \
    --speech_md <演講稿.md> \
    --slides_pdf <幻燈片.pdf> \
    --output_dir <輸出目錄> \
    --tts_engine qwen3 \
    --speaker "Vivian"

指定使用 edge-tts

python {SKILL_DIR}/scripts/run_pipeline.py \
    --speech_md <演講稿.md> \
    --slides_pdf <幻燈片.pdf> \
    --output_dir <輸出目錄> \
    --tts_engine edge \
    --edge_voice "zh-CN-XiaoxiaoNeural"

將 {SKILL_DIR} 替換為本技能目錄的絕對路徑。

常用選項：

Qwen3-TTS 可用音色

edge-tts 推薦語音

分步執行

如需更精細控制，可逐步執行：

（步驟 0 在上方"步驟 0（必需）"中說明，推薦在所有步驟之前執行）

步驟 1：提取人聲並篩選參考片段（可選）

從參考影片/音訊中提取純淨人聲，自動篩選最佳參考片段（5~10秒）。

處理流程： 1. 僅提取前 3 分鐘音訊（避免長影片全量處理） 2. 使用 Demucs 分離人聲與背景噪聲 3. 使用 Whisper 轉錄人聲為帶時間戳的文字 4. 自動篩選一句 5~10 秒、語句獨立、聲音清晰的片段 5. 擷取該片段的音訊與文字，傳給第3步聲音克隆

python {SKILL_DIR}/scripts/step1_extract_voice.py \
    --input <影片或音訊路徑> \
    --output_dir <輸出目錄>/step1_voice

指令碼位置：scripts/step1_extract_voice.py

篩選評分維度： - 時長適中（接近 7 秒最佳，滿分 30） - 語句完整（以句號結尾更佳，滿分 20） - 聲音清晰（RMS 能量 + 靜音比例，滿分 30） - 文字長度合理（20~80字，滿分 10） - 位置偏好（靠前片段通常更好，滿分 10）

輸出： - reference_voice.wav — 最佳參考音訊片段（5~10秒） - reference_text.txt — 對應的轉錄文字 - reference_info.json — 片段詳細資訊（時間、文字、評分等）

步驟 2：處理演講稿

解析並清洗 Markdown 演講稿，生成結構化 TTS 資料。

python {SKILL_DIR}/scripts/step2_process_speech.py \
    --input <演講稿.md> \
    --output <輸出目錄>/step2_speech_data.json

指令碼位置：scripts/step2_process_speech.py

處理流程： 1. 從 ## 第 X 頁 標題解析頁面邊界 2. 清洗 Markdown 格式：移除 **粗體**、*斜體*、時間標註、引用 3. 將破折號轉換為逗號以符合自然語流 4. 在標點處拆分句子 5. 處理超長句子（>80字元）在逗號處拆分 6. 生成 TTS 友好的發音文本（tts_sentences），包括： - 術語發音規範化（從 config/pronunciation_map.json 載入） - 目錄路徑讀音轉換：自動將路徑轉為口語化表達

目錄路徑讀音規則：

字幕（sentences）保持原始書面寫法不變，TTS 文本（tts_sentences）按以下規則轉換：

💡 智慧去重：如果路徑後面已有"目錄"或"下"等字樣，不會重複追加"目錄"。例如 scripts/ 目錄下 → "scripts 目錄下"。

輸出：包含每頁句子的結構化 JSON

步驟 3：語音合成

使用 Qwen3-TTS（支援聲音克隆）或 edge-tts（預設音色）生成演講音訊。

# Qwen3-TTS + 聲音克隆
python {SKILL_DIR}/scripts/step3_clone_voice.py \
    --speech_json <演講資料.json> \
    --output_dir <輸出目錄>/step3_tts \
    --tts_engine qwen3 \
    --reference_voice <參考音訊.wav>

# Qwen3-TTS + 預設音色
python {SKILL_DIR}/scripts/step3_clone_voice.py \
    --speech_json <演講資料.json> \
    --output_dir <輸出目錄>/step3_tts \
    --tts_engine qwen3 \
    --speaker "Vivian"

# edge-tts（預設音色）
python {SKILL_DIR}/scripts/step3_clone_voice.py \
    --speech_json <演講資料.json> \
    --output_dir <輸出目錄>/step3_tts \
    --tts_engine edge \
    --edge_voice "zh-CN-XiaoxiaoNeural"

指令碼位置：scripts/step3_clone_voice.py

處理流程： 1. 自動檢測可用的 TTS 引擎（Qwen3-TTS 優先，edge-tts 備選） 2. Qwen3-TTS 模式： - 有參考音訊 → 聲音克隆模式（使用 Base 模型，克隆參考音色） - 無參考音訊 → 預設音色模式（使用 CustomVoice 模型，內建音色） 3. edge-tts 模式：使用微軟線上預設音色（不支援聲音克隆） 4. 逐句生成音訊 5. 插入句子間停頓（0.4秒）和頁面間停頓（1.0秒） 6. 記錄精確的時間後設資料 7. 拼接為完整演講音訊

輸出： - full_speech.wav — 完整演講音訊 - timing_data.json — 精確時間資料（含 tts_engine 欄位標記引擎） - sentences/ — 逐句音訊檔案 - slides/ — 逐頁音訊檔案

步驟 4：生成幻燈片影片

將 PDF 幻燈片轉換為與音訊時長匹配的影片。

python {SKILL_DIR}/scripts/step4_generate_video.py \
    --pdf <幻燈片.pdf> \
    --timing_json <時間資料.json> \
    --output_dir <輸出目錄>/step4_video

指令碼位置：scripts/step4_generate_video.py

輸出：slides_video.mp4 — 無聲幻燈片影片

步驟 5：合併影片、音訊和字幕

將所有元件合併為最終演講影片。

python {SKILL_DIR}/scripts/step5_merge_all.py \
    --video <幻燈片影片.mp4> \
    --audio <完整音訊.wav> \
    --timing_json <時間資料.json> \
    --output <最終輸出.mp4>

指令碼位置：scripts/step5_merge_all.py

字幕樣式：白色文字，PingFang SC 字型，黑色描邊，半透明陰影，底部居中。

輸出：final_presentation.mp4 — 帶字幕的完整演講影片

🔄 重新生成單句 TTS 音訊

如果對某一句的 TTS 效果不滿意，可以使用 --regenerate 引數只重新生成指定的句子，其餘句子複用已有音訊，然後自動重新拼接併合成最終影片。

檢視當前所有句子：

# 檢視 timing_data.json 中的句子列表
cat <輸出目錄>/step3_tts/timing_data.json | python3 -c "
import json,sys
data=json.load(sys.stdin)
for s in data['slides']:
    for sent in s['sentences']:
        print(f\"slide{s['slide_number']}_sent{sent['index']:03d}: {sent['text'][:60]}\")
"

重新生成指定句子（支援多種格式）：

# 格式1: slide<頁碼>_sent<句號>
python {SKILL_DIR}/scripts/run_pipeline.py \
    --speech_md <演講稿.md> \
    --slides_pdf <幻燈片.pdf> \
    --output_dir <輸出目錄> \
    --reference_voice <參考音訊.wav> \
    --regenerate slide1_sent000 slide3_sent002

# 格式2: <頁碼>:<句號>（更簡潔）
python {SKILL_DIR}/scripts/run_pipeline.py \
    --speech_md <演講稿.md> \
    --slides_pdf <幻燈片.pdf> \
    --output_dir <輸出目錄> \
    --regenerate 1:0 3:2

# 格式3: 整頁重新生成
python {SKILL_DIR}/scripts/run_pipeline.py \
    --speech_md <演講稿.md> \
    --slides_pdf <幻燈片.pdf> \
    --output_dir <輸出目錄> \
    --regenerate slide2

注意事項： - 使用 --regenerate 時，步驟 1（聲音提取）和步驟 2（演講稿處理）會自動跳過 - 指定句子的音訊檔案會被新生成的檔案覆蓋 - 所有頁面音訊和完整音訊會自動重新拼接 - timing_data.json 會自動更新 - 由於固定了隨機種子（seed=42），同樣的文本會生成一樣的結果；如需不同效果，可配合 --temperature 0.5 使用 - 也可直接呼叫 step3 指令碼單獨使用 --regenerate

演講稿格式

演講稿應遵循標準 Markdown 結構（詳見上方"步驟 0"）。step2_process_speech.py 會自動清洗以下格式：

自動清洗處理： - Markdown 粗體/斜體：**文字** → 文字 - 時間標註：**（約 1 分鐘）** → 移除 - 引用塊：> 文字 → 文字 - 程式碼反引號：`程式碼` → 程式碼 - 破折號：—— → ，（符合自然語流）

常見問題排查

程序安全與斷點續傳

流水線內建了三重防護機制，避免併發衝突和重複工作：

1. 程序鎖（Process Lock）：run_pipeline.py 和 step3_clone_voice.py 均使用 fcntl.flock() 檔案鎖。同一輸出目錄下只允許一個流水線例項執行，重複啟動會立即報錯退出，不會產生多個程序競爭寫入的問題。
2. 斷點續傳（Resume）：步驟 3（TTS 生成）會自動檢測已有的有效音訊檔案。如果流水線中途中斷後重新執行，已成功生成的句子音訊會被跳過，只生成缺失的部分，大幅節省時間。
3. 引擎一致性檢查（Engine Consistency）：輸出目錄會記錄上次使用的 TTS 引擎。如果本次執行切換了引擎（如從 qwen3 切換到 edge），會自動清除舊引擎生成的音訊並重新生成，避免混用不同引擎的音訊導致音色不一致。

TTS 引擎問題

• Qwen3-TTS 載入失敗：確保已安裝 pip install -U qwen-tts，需要較大記憶體（建議 8GB+）
• edge-tts 連線失敗：檢查網路連線，edge-tts 需要訪問微軟 TTS 服務
• 兩個引擎都沒安裝：至少安裝一個 — pip install -U qwen-tts 或 pip install edge-tts

PDF 轉換

• 安裝 PyMuPDF（pip install PyMuPDF）作為主後端
• 降級方案：pip install pdf2image + 安裝 poppler

字幕渲染

• 驗證字型存在：fc-list | grep "PingFang"
• Linux 系統：使用 Noto Sans CJK SC 替代 PingFang SC
• Windows 系統：使用 Microsoft YaHei 替代

音影片同步

• 確保 timing_data.json 時間資料一致
• 驗證整個流水線使用 24kHz 取樣率
• 檢查 FFmpeg 版本支援 AAC 編碼

相關資源

• 流水線技術指南：references/pipeline_guide.md — 詳細技術架構與設計
• 指令碼目錄：scripts/ — 所有可執行的流水線指令碼

這個 Skill 功能豐富，能把幻燈片和演講稿自動生成帶配音和字幕的影片，支援克隆真實人聲，整體質量不錯。文件寫得很詳細，環境檢查指令碼也很實用。但使用前最好檢查一下，某些參考資料檔案可能缺失，可能導致部分功能無法正常工作。總體來說是一個實用性較強的工具，但建議等待作者完善後再使用。