前言¶

錄完教學視頻後，常見流程是：按畫面切分片段、逐段 TTS、對齊音畫、再燒錄字幕。步驟多、工具雜，時間碼手寫還容易和幀率對不齊。若希望由 Agent 按固定流程代勞——先檢測環境、再選引擎與音色、生成配置並執行流水線，失敗還能從斷點續跑——SkillHub 上的「教學視頻配音字幕合成」面向的就是這類需求。它與「從零寫腳本拍片」不同，假定你已有源視頻和帶時間點的配音模板，重點在配音合成與字幕注入。

這是什麼¶

「教學視頻配音字幕合成」是 SkillHub 分類 design-media 下的 Agent Skill（包名在 CLI 中爲 @indiv-zhangwei/video-tutorial-v2-publish，當前版本 1.0.20）。技能文檔（SKILL.md）將其定位爲固定程序模式：通過對話收集路徑與 TTS 選項，由 AI 複製腳本、生成 job.yaml 並執行 pipeline.py，用戶無需手改配置文件。

公開頁 https://www.skillhub.cn/skills/user_a5827f21/video-tutorial-v2-publish 訪問時可能顯示 Skill 已下線；安裝與內容仍以 SkillHub CLI 拉取爲準。任務線索中的 API 地址 https://api.skillhub.cn/user_a5827f21/video-tutorial-v2-publish 對 GET 返回 405，不能當作文檔頁使用。

核心功能¶

下面介紹技能文檔中已寫明、且本地包內腳本對應的能力。

1. 對話式流程：確認源視頻路徑與字幕模板（.md）→ 自動環境檢測 → 選擇 TTS 引擎與音色 → 生成 job.yaml → AI 執行流水線並在對話中彙報進度。
2. 雙 TTS 引擎：默認推薦訊飛超擬人（需本地 tts_config.json 憑證）；無密鑰或用戶選擇時回退 edge-tts（免費，無需訊飛賬號）。
3. 六步流水線（pipeline.py）：01_check 解析模板 → 02_cut 按時間切分視頻 → 03_tts 配音 → 04_align 對齊（含 filler、加速、靜音等決策）→ 05_merge 聲畫合成 → 06_finalize 逐句字幕注入成品 MP4。
4. 容錯續跑：步驟失敗時按文檔執行 python _scripts/pipeline.py --job job.yaml --resume-from <步驟>。
5. 字幕模板工具：tools/subtitle-editor.html 支持瀏覽器內拖入視頻、按 F 鍵拍板標記時間點，導出 .md 模板；也可用 copy_template.py 複製 script_template.md 手寫時間碼。
6. 模板能力：支持 MM:SS、MM:SS,FF（SMPTE 幀）、MM:SS.mmm；數學符號可自動口語化；可選多音字 {拼音+聲調} 標註（訊飛）；| 可標記斷句等（詳見技能內 script_template.md）。

SkillHub 側統計（任務線索）：評分 99136，下載約 1013 次。

安裝與啓用¶

先做 CLI 是否可用的檢查，再把 Skill 裝到當前 Agent 的 skills 目錄（未指定 --dir 時默認 ./skills/，Agent 可能無法加載）。

command -v skillhub && skillhub --version

未安裝 CLI 時，可按 SkillHub 安裝說明執行完整安裝或僅 CLI：

curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash

安裝本 Skill（與 skillhub search video-tutorial-v2-publish 結果一致）：

skillhub install video-tutorial-v2-publish --namespace indiv-zhangwei --dir <你的 Agent skills 目錄>

常見 skills 目錄示例（來自 SkillHub 安裝文檔）：

• Cursor：~/.cursor/skills/
• Claude Code：~/.claude/skills/
• Codex：~/.codex/skills/ 或項目下 .agents/skills/

也可在對話中讓 AI 按官方提示安裝（文檔寫法爲引用 https://skillhub.cn/install/skillhub.md 並安裝對應包名）。安裝後需讓 Agent 重新加載 skills 目錄中的技能。

運行依賴（由 env_check.py 檢測，技能文檔摘要）：Python 3.7+、ffmpeg；選訊飛時需 websocket-client==1.8.0；選 edge 時需 edge-tts==7.2.8（Python 包，非微軟商店應用）。

典型用法¶

經過上面的安裝，在已啓用該 Skill 的 Agent 中，可按技能規定的階段操作。下面是可以復現的主路徑。

1、提供素材路徑

向 Agent 說明要合成視頻，並提供：

• 源視頻路徑（如 /home/user/video/demo.mp4）
• 配音模板路徑（如 /home/user/video/script.md）

若無模板，Agent 應執行（路徑中的 <本技能目錄> 換爲安裝後的技能根目錄）：

python <本技能目錄>/scripts/copy_template.py --to-dir <用戶項目目錄>

用戶在 script_template.md 中填寫時間點後繼續。

2、環境檢測（Agent 自動）

在用戶項目下創建 _scripts/ 並複製技能內 scripts/*.py，然後：

python _scripts/env_check.py --output env.json

缺 ffmpeg 時按文檔指引安裝；缺 Python 包時 Agent 可執行例如：

pip install websocket-client==1.8.0
pip install edge-tts==7.2.8

3、選擇引擎與音色

• 選 1（訊飛）：提供 APPID、APIKey、APISecret、WS URL（https://console.xfyun.cn），並選音色（如默認聆小糖 x5_lingxiaotang_flow），生成 tts_config.json。
• 選 2（edge-tts）：選曉曉 / 雲希 / 曉伊 等 Neural 音色，無需 tts_config.json。

4、執行任務

Agent 生成 job.yaml 後自行運行：

python _scripts/pipeline.py --job job.yaml

成功時成品路徑形如：output/{task_id}/06_final/final_with_subs_xxx.mp4。

5、用字幕編輯器制模板（可選）

用瀏覽器打開技能目錄下的 tools/subtitle-editor.html，設置工作目錄、拖入視頻、粘貼編號文案，播放時按 F 標記切換點，再導出 .md 交給 Agent。

適用場景與注意¶

適合：已有畫面教學視頻、需要按時間點批量配音並燒錄字幕的團隊或個人；希望由 Agent 代跑 ffmpeg + TTS 流水線、減少手工拼命令的場景。

注意：

• 訊飛憑證只應寫在本地 tts_config.json，技能文檔要求提醒用戶加入 .gitignore，勿提交倉庫。
• 模板時間碼與幀率：逗號格式按文檔默認 30fps 解析；切分與對齊邏輯在 changelog 中多次修訂，複雜模板建議先看 report.json 與技能 changelog。
• 同一作者另有「靈聲工坊視頻配音」（smart-dubbing-studio）等 Skill，能力側重不同；本文僅描述 video-tutorial-v2-publish 包內行爲。
• 若僅依賴網頁詳情，可能遇到「Skill 未找到」；以 CLI 安裝到的 SKILL.md 與腳本爲準。

結尾¶

「教學視頻配音字幕合成」把環境檢測、引擎選擇、任務配置和六步合成收斂成 Agent 可執行的固定流程，並附帶拍板式模板編輯器，降低教學片後期配音與字幕注入的門檻。安裝與檢索入口：

• SkillHub 安裝說明：https://skillhub.cn/install/skillhub.md
• 任務線索中的 Skill 地址：https://api.skillhub.cn/user_a5827f21/video-tutorial-v2-publish（文檔 GET 不可用；安裝請用 skillhub install video-tutorial-v2-publish --namespace indiv-zhangwei）