video2ppt は何をしますか?
動画のスライド部分を画像として抽出し、PPTX(1ページ1画像)またはPDFに合成します。 3つの機能を単独で使うことも、ワンコマンドで連結することもできます。
| スクリプト | 役割 | 典型的な利用シーン |
|---|---|---|
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 キーや環境変数を読み込まず、ハードコードされた資格情報はありません。
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のスクリプトはすべて非GUIで、繰り返し実行可能です。
5. 環境変数
必須の環境変数はありません。スクリプトはハードコードされたキー、パスワード、トークンを含まず、ネットワークにもアクセスしません(初回の依存関係インストール時に pip がインターネット接続を必要とする場合を除く)。
オプション:OPENBLAS_NUM_THREADS、OMP_NUM_THREADS —— スクリプトはデフォルトでこれらを 1 に設定し、一部の Windows マシンで発生する OpenBLAS スレッドバッファ割り当て失敗による import numpy/cv2 のクラッシュを回避します。マシンが正常な場合は必要に応じて増やせます(例:8)。