video2ppt 是做什麼的?
把影片中的投影片畫面提取成圖片,再合成為 PPTX(每頁一張圖)或 PDF。 三個能力可單獨使用,也可一鍵串聯:
| 腳本 | 作用 | 典型場景 |
|---|---|---|
scripts/video2ppt.py | 一鍵流水線:影片 → 幀 → PPTX/PDF | 使用者只要最終 PPT/PDF(優先使用) |
scripts/video_to_frames.py | 從影片智慧抽幀,輸出圖片序列 | 使用者需要截圖、或想人工篩選後再合成 |
scripts/images_to_pptx.py | 圖片資料夾 → PPTX | 已有截圖/圖片,要產生簡報 |
scripts/images_to_pdf.py | 圖片資料夾 → PDF | 已有截圖/圖片,要產生 PDF |
所有命令均在本 Skill 根目錄(包含本檔案的目錄)下執行;腳本也會寫日誌到 stderr,可配合 --json 讀取 stdout 的機器可讀摘要。
0. 環境準備(首次使用)
python scripts/check_env.py
- 結束碼 0 表示依賴齊全;結束碼 3 表示缺少必裝依賴。
- 缺依賴時安裝:
python -m pip install -r scripts/requirements.txt - 必需:
opencv-python、numpy、python-pptx、Pillow;可選增強:scikit-image(SSIM 去重)、img2pdf(PDF 串流合併,缺失時自動回退 Pillow)。 - 腳本不讀取任何 API Key 或環境變數,無硬編碼憑證。
1. 一鍵流水線(推薦入口)
python scripts/video2ppt.py -i <影片檔案/目錄/萬用字元> [-o <輸出目錄>] --formats pptx,pdf --json
-o 可省略:預設輸出到第一個影片所在目錄(不與 Skill 根目錄混在一起)。
範例:
# 整個影片 → PPT + PDF
python scripts/video2ppt.py -i lecture.mp4 -o ./out --json
# 只處理 00:05:00 ~ 00:40:00,輸出保持比例不變形
python scripts/video2ppt.py -i lecture.mp4 -o ./out --start 00:05:00 --end 00:40:00 --fit fit
# 批次處理目錄內所有影片,只產生 PPTX
python scripts/video2ppt.py -i ./videos -o ./out --formats pptx
產物:<outdir>/frames/(提取的畫面)、<outdir>/<name>.pptx、<outdir>/<name>.pdf。
--name 可指定輸出檔案基名,預設取第一個影片的檔名。例如 video/2_1.mp4 省略 -o 時輸出到 video/frames/、video/2_1.pptx、video/2_1.pdf。
2. 分步執行
2.1 影片抽幀
python scripts/video_to_frames.py -i <影片/目錄> [-o <幀目錄>] [參數] --json
-o可省略,預設輸出到第一個影片所在目錄下的frames/。- 關鍵參數:
--start/--end(秒或HH:MM:SS)、--similarity(預設 0.8)、--skip(預設 15)、--crop all(去除黑邊)。 - 輸出檔名形如
<影片名>_ppt_001_frame_000123.png,按頁碼自然排序。
2.2 圖片 → PPTX
python scripts/images_to_pptx.py -i <圖片目錄> -o <輸出.pptx> --fit fit --json
--fit stretch(預設,全螢幕拉伸)或--fit fit(保持比例,居中留白)。- 可選
--title 課程名、--slide-width/--slide-height(英吋,預設 16×9)、--bg 255,255,255。
2.3 圖片 → PDF
python scripts/images_to_pdf.py -i <圖片目錄> -o <輸出.pdf> --json
- 預設開啟壓縮(
--max-width 1920、--jpeg-quality 85);用--no-compress保留原畫質。 --max-width 0表示不縮放。
3. 參數調節指南
| 問題 | 調整 |
|---|---|
| 提取的頁太少 | 提高 --similarity(0.8 → 0.85~0.9),降低 --skip 和 --min-interval |
| 重複頁太多 | 降低 --similarity(0.8 → 0.7~0.75),提高 --skip / --min-interval |
| 截到轉場動畫/模糊幀 | 提高 --delay-frames(如 8~12),保持穩定性檢查開啟 |
| 畫面一直判為不穩定 | 降低 --stable-threshold(0.95 → 0.9)或加 --no-stable-check |
| 輸出帶黑邊 | --crop all;噪點導致檢測異常時用 --crop-mode fixed 配合邊距參數 |
| 影片有 4:3 內容但輸出變形 | 合成時改用 --fit fit |
| PDF 太大 | 保持壓縮開啟,降低 --jpeg-quality(85→60)或 --max-width(1920→1280) |
| 處理太慢 | 提高 --skip(如 25)、降低 --resize(480→320)、關閉 --verbose |
完整參數表見 references/parameters.md(僅在需要細調時閱讀)。
4. 結果校驗與異常處理
- 先看結束碼:
0成功;1未產出任何結果(幀數為 0 / 輸入為空);2參數錯誤;3缺少依賴;130被中斷。 - 使用
--json時解析 stdout(日誌在 stderr),關鍵欄位:- 抽幀:
frames_saved、output_dir、errors - 流水線:
frames、outputs.pptx.slides、outputs.pdf.pages、errors
- 抽幀:
- 成功後確認輸出檔案存在且大小 > 0,並向使用者報告頁數與絕對路徑。
- 常見失敗:
- 無法開啟影片:路徑含特殊字元或編碼不支援。先用 ffmpeg 轉碼為 H.264 MP4:
ffmpeg -i in.mov -c:v libx264 -c:a aac out.mp4。 - frames_saved = 0:按第 3 節提高相似度敏感度後重試。
- 匯入 cv2/numpy 時出現 OpenBLAS / 記憶體分配錯誤:腳本預設已把
OPENBLAS_NUM_THREADS/OMP_NUM_THREADS設為 1 來規避常見的執行緒緩衝分配失敗;若仍然報錯,重建虛擬環境(python -m venv .venv後重裝requirements.txt),或python -m pip install --force-reinstall numpy opencv-python。check_env.py與抽幀腳本已用子程序隔離探測,會以結束碼 3 報出該問題而不是直接崩潰。 - 中文路徑/日誌亂碼:腳本已強制 UTF-8 輸出;若終端仍亂碼,先執行
export PYTHONIOENCODING=utf-8(Windows:set PYTHONIOENCODING=utf-8)。
- 無法開啟影片:路徑含特殊字元或編碼不支援。先用 ffmpeg 轉碼為 H.264 MP4:
- 不要用 GUI 版參數檔案互動;本 Skill 的腳本全部無介面、可重複執行。
5. 環境變數
無必需的環境變數,腳本不包含硬編碼的金鑰、密碼或權杖,也不存取網路(僅首次安裝依賴時 pip 需要聯網)。
可選:OPENBLAS_NUM_THREADS、OMP_NUM_THREADS —— 腳本會將其預設設為 1,避免部分 Windows 機器上 OpenBLAS 執行緒緩衝分配失敗導致 import numpy/cv2 崩潰;機器正常時可按需調大(如 8)。