What does video2ppt do?
Extract slide images from video and assemble them into PPTX (one image per page) or PDF. Three capabilities can be used independently or chained together:
| Script | Purpose | Typical Scenario |
|---|---|---|
scripts/video2ppt.py | One-shot pipeline: video → frames → PPTX/PDF | User only wants final PPT/PDF (preferred) |
scripts/video_to_frames.py | Smart frame extraction from video, output image sequence | User needs screenshots or wants to manually filter before assembling |
scripts/images_to_pptx.py | Image folder → PPTX | Already have screenshots/images, want to create a presentation |
scripts/images_to_pdf.py | Image folder → PDF | Already have screenshots/images, want to create a PDF |
All commands are executed from this Skill's root directory (the directory containing this file); scripts also write logs to stderr, and can output machine-readable summaries to stdout when using --json.
0. Environment Setup (First Use)
python scripts/check_env.py
- Exit code 0 means all dependencies are present; exit code 3 indicates missing required dependencies.
- To install missing dependencies:
python -m pip install -r scripts/requirements.txt - Required:
opencv-python,numpy,python-pptx,Pillow; optional enhancements:scikit-image(SSIM dedup),img2pdf(streaming PDF merge, falls back to Pillow if missing). - Scripts do not read any API keys or environment variables, and contain no hardcoded credentials.
1. One-Shot Pipeline (Recommended Entry Point)
python scripts/video2ppt.py -i <video file/directory/wildcard> [-o <output directory>] --formats pptx,pdf --json
-o is optional: defaults to the directory of the first video (not mixed with Skill root).
Examples:
# Entire video → PPT + PDF
python scripts/video2ppt.py -i lecture.mp4 -o ./out --json
# Process only 00:05:00 ~ 00:40:00, output maintains aspect ratio without distortion
python scripts/video2ppt.py -i lecture.mp4 -o ./out --start 00:05:00 --end 00:40:00 --fit fit
# Batch process all videos in a directory, generate only PPTX
python scripts/video2ppt.py -i ./videos -o ./out --formats pptx
Outputs: <outdir>/frames/ (extected frames), <outdir>/<name>.pptx, <outdir>/<name>.pdf.
--name specifies the output file base name; defaults to the first video's filename. For example, video/2_1.mp4 without -o outputs to video/frames/, video/2_1.pptx, video/2_1.pdf.
2. Step-by-Step Execution
2.1 Video Frame Extraction
python scripts/video_to_frames.py -i <video/directory> [-o <frames directory>] [arguments] --json
-ois optional; defaults toframes/under the first video's directory.- Key arguments:
--start/--end(seconds orHH:MM:SS),--similarity(default 0.8),--skip(default 15),--crop all(remove black borders). - Output filenames follow the pattern
<video_name>_ppt_001_frame_000123.png, sorted naturally by page number.
2.2 Images → PPTX
python scripts/images_to_pptx.py -i <image directory> -o <output.pptx> --fit fit --json
--fit stretch(default, fullscreen stretch) or--fit fit(maintain aspect ratio, center with padding).- Optional:
--title CourseName,--slide-width/--slide-height(inches, default 16×9),--bg 255,255,255.
2.3 Images → PDF
python scripts/images_to_pdf.py -i <image directory> -o <output.pdf> --json
- Compression is on by default (
--max-width 1920,--jpeg-quality 85); use--no-compressto retain original quality. --max-width 0means no scaling.
3. Parameter Tuning Guide
| Issue | Adjustment |
|---|---|
| Too few pages extracted | Increase --similarity (0.8 → 0.85~0.9), decrease --skip and --min-interval |
| Too many duplicate pages | Decrease --similarity (0.8 → 0.7~0.75), increase --skip / --min-interval |
| Transition animation/blurry frames captured | Increase --delay-frames (e.g., 8~12), keep stability check enabled |
| Frames always judged unstable | Decrease --stable-threshold (0.95 → 0.9) or add --no-stable-check |
| Output has black borders | --crop all; if noise causes detection issues, use --crop-mode fixed with margin parameters |
| Video has 4:3 content but output is distorted | Use --fit fit during assembly |
| PDF is too large | Keep compression on, reduce --jpeg-quality (85→60) or --max-width (1920→1280) |
| Processing too slow | Increase --skip (e.g., 25), reduce --resize (480→320), disable --verbose |
Full parameter table is in references/parameters.md (read only when fine-tuning).
4. Result Validation and Error Handling
- Check the exit code first:
0success;1no output produced (0 frames / empty input);2parameter error;3missing dependencies;130interrupted. - When using
--json, parse stdout (logs go to stderr). Key fields:- Frame extraction:
frames_saved,output_dir,errors - Pipeline:
frames,outputs.pptx.slides,outputs.pdf.pages,errors
- Frame extraction:
- After success, verify output files exist and size > 0, and report page count and absolute paths to the user.
- Common failures:
- Cannot open video: path contains special characters or unsupported encoding. First transcode to H.264 MP4 with ffmpeg:
ffmpeg -i in.mov -c:v libx264 -c:a aac out.mp4. - frames_saved = 0: Increase similarity sensitivity per Section 3 and retry.
- OpenBLAS / memory allocation errors on import cv2/numpy: Scripts already set
OPENBLAS_NUM_THREADS/OMP_NUM_THREADSto 1 to avoid common thread buffer allocation failures; if error persists, rebuild virtual environment (python -m venv .venvand reinstallrequirements.txt), orpython -m pip install --force-reinstall numpy opencv-python.check_env.pyand frame extraction scripts detect this via subprocess isolation and report exit code 3 instead of crashing. - Chinese path/log garbled: Scripts force UTF-8 output; if terminal still garbled, run
export PYTHONIOENCODING=utf-8(Windows:set PYTHONIOENCODING=utf-8).
- Cannot open video: path contains special characters or unsupported encoding. First transcode to H.264 MP4 with ffmpeg:
- Do not use GUI parameter file interaction; all scripts in this Skill are non-interactive and repeatable.
5. Environment Variables
No required environment variables; scripts contain no hardcoded keys, passwords, or tokens, and do not access the network (only pip needs internet for initial dependency installation).
Optional: OPENBLAS_NUM_THREADS, OMP_NUM_THREADS — scripts set these to 1 by default to prevent OpenBLAS thread buffer allocation failures on some Windows machines that crash import numpy/cv2; on stable machines, they can be increased (e.g., 8).