Communitygithub.com

video2ppt

Intelligently extract PPT frames from videos/screen recordings and generate PPTX presentations or PDFs (one image per page). Use when a user provides a video, screen recording, lecture recording, or meeting replay and wants slides/PPT/PDF; also suitable for batch converting a folder of images into PPT or PDF. Supports time range extraction, SSIM-based deduplication, delayed capture + clarity-based frame selection, black border cropping, and PDF compression.

What is video2ppt?

video2ppt is an AI agent skill designed to transform video content—such as lectures, meetings, and screen recordings—into editable slide decks (PPTX) or printable documents (PDF) by extracting key frames that represent slide pages. It addresses the common need to generate presentation materials from visual media without manual screenshotting. The skill supports multiple platforms: it runs as a Python-based command-line tool set, compatible with any AI agent or developer environment (e.g., Claude Code, Cursor, or Codex). It operates through three modular scripts that can be used independently or chained: `video_to_frames.py` for intelligent frame extraction (with deduplication, cropping, and stability checks), `images_to_pptx.py` for assembling images into PPTX, and `images_to_pdf.py` for PDF creation with compression. The flagship script `video2ppt.py` provides a one-shot pipeline from video to final output. Key features include time range selection, SSIM-based similarity thresholding to eliminate duplicates, delayed frame capture to skip transitions, black border auto-cropping, and configurable PDF compression. The skill logs to stderr and outputs JSON summaries to stdout, making it easy for agents to parse results programmatically.

Works with~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/knoyuuki/skills-video2ppt/tree/HEAD/video2ppt

Ask in your favorite AI

Open a new chat with this agent skill pre-loaded.

Documentation

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:

ScriptPurposeTypical Scenario
scripts/video2ppt.pyOne-shot pipeline: video → frames → PPTX/PDFUser only wants final PPT/PDF (preferred)
scripts/video_to_frames.pySmart frame extraction from video, output image sequenceUser needs screenshots or wants to manually filter before assembling
scripts/images_to_pptx.pyImage folder → PPTXAlready have screenshots/images, want to create a presentation
scripts/images_to_pdf.pyImage folder → PDFAlready 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
  • -o is optional; defaults to frames/ under the first video's directory.
  • Key arguments: --start / --end (seconds or HH: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-compress to retain original quality.
  • --max-width 0 means no scaling.

3. Parameter Tuning Guide

IssueAdjustment
Too few pages extractedIncrease --similarity (0.8 → 0.85~0.9), decrease --skip and --min-interval
Too many duplicate pagesDecrease --similarity (0.8 → 0.7~0.75), increase --skip / --min-interval
Transition animation/blurry frames capturedIncrease --delay-frames (e.g., 8~12), keep stability check enabled
Frames always judged unstableDecrease --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 distortedUse --fit fit during assembly
PDF is too largeKeep compression on, reduce --jpeg-quality (85→60) or --max-width (1920→1280)
Processing too slowIncrease --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

  1. Check the exit code first: 0 success; 1 no output produced (0 frames / empty input); 2 parameter error; 3 missing dependencies; 130 interrupted.
  2. 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
  3. After success, verify output files exist and size > 0, and report page count and absolute paths to the user.
  4. 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_THREADS to 1 to avoid common thread buffer allocation failures; if error persists, rebuild virtual environment (python -m venv .venv and reinstall requirements.txt), or python -m pip install --force-reinstall numpy opencv-python. check_env.py and 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).
  5. 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).

Related Skills