DeckSnag

Automatically capture video presentations and convert them to PowerPoint slides using AI-powered slide detection.

When watching an online course, webinar, or live presentation where slides aren't provided, DeckSnag automatically detects slide changes and saves them to a PowerPoint file. No more manual screenshots!

Highlights

• AI-Powered Detection - CLIP neural network understands slide content semantically
• Multiple Comparison Methods - Choose between AI (CLIP), SSIM, or MSE based on your needs
• Multiple Output Formats - Export to PowerPoint (.pptx), PDF, or image folder
• Modern GUI & CLI - Use the intuitive graphical interface or automate with command-line
• Cross-Platform - Works on Windows, macOS, and Linux

Table of Contents

• Installation
• Quick Start
• AI-Powered Slide Detection
• CLI Reference
• Configuration
• GUI Features
• API Usage
• Contributing
• Troubleshooting

Installation

From PyPI (Recommended)

pip install decksnag

From Source

git clone https://github.com/foxintheloop/DeckSnag.git
cd DeckSnag
pip install -e .

Development Installation

pip install -e ".[dev]"

Quick Start

GUI Mode

Launch the graphical interface:

decksnag --gui

Or use the dedicated GUI command:

decksnag-gui

Or use Python module syntax:

python -m decksnag --gui

CLI Mode

Basic usage with interactive region selection:

decksnag -o my_presentation.pptx

With AI-powered detection (recommended for complex presentations):

decksnag -M clip -o my_presentation.pptx

The program will:

1. Ask you to click and drag to select the capture region
2. Start capturing slides (press END key to stop)
3. Save the presentation to the specified file

AI-Powered Slide Detection

DeckSnag uses CLIP (Contrastive Language-Image Pre-training) from OpenAI for intelligent slide detection. Unlike traditional pixel-based methods, CLIP understands the semantic content of images.

Why Use AI Detection?

Scenario	Traditional (MSE/SSIM)	AI (CLIP)
Mouse cursor moving	May trigger false positives	Ignores minor visual noise
Video player UI overlays	Detects as changes	Focuses on slide content
Animations/transitions	Multiple false captures	Waits for content change
Presenter video overlay	Constant false triggers	Understands slide vs presenter
Lighting changes	Sensitive to brightness	Semantic understanding

Comparison Methods

Method	Speed	Accuracy	Best For
clip	Slower	Excellent	Complex videos, animations, presenter overlays
ssim	Fast	Good	Clean recordings with minimal noise
mse	Fast	Basic	Simple, static presentations

Enable AI detection:

# CLI
decksnag -M clip -o presentation

# Or in GUI: Select "CLIP AI" from the comparison method dropdown

How CLIP Works

1. Captures a screenshot of the selected region
2. Encodes the image into a semantic embedding vector using CLIP's vision transformer
3. Compares the embedding with the previous slide using cosine similarity
4. Detects a new slide when similarity drops below threshold (default: 0.85)

This approach means CLIP understands that two slides with different text are different content, even if they look visually similar (same template, colors, layout).

CLI Reference

decksnag [OPTIONS]

Options:
  -o, --output PATH         Output file path (default: ./presentation)
  -f, --format FORMAT       Output format: pptx, pdf, images, all (default: pptx)
  -i, --interval SECONDS    Capture interval in seconds (default: 5)
  -t, --threshold FLOAT     Change sensitivity 0-1 (default: 0.005)
  -s, --sensitivity PRESET  Sensitivity preset: low, medium, high
  -M, --method METHOD       Comparison method: mse, ssim, clip (default: mse)
  -m, --monitor NUMBER      Monitor to capture (default: 0 for primary)
  -r, --region X1,Y1,X2,Y2  Preset capture region (skip selection)
  -k, --hotkey KEY          Stop hotkey (default: end)
  -v, --verbose             Enable verbose logging
  --list-monitors           List available monitors and exit
  --gui                     Launch graphical interface
  -V, --version             Show version and exit
  -h, --help                Show help message

Examples

Use AI-powered comparison (recommended):

decksnag -M clip -o presentation

Export as PDF:

decksnag -o lecture -f pdf

High sensitivity for subtle slide changes:

decksnag -s high -i 3

Capture specific region (skip interactive selection):

decksnag -r 100,100,1920,1080 -o presentation

Export to all formats:

decksnag -f all -o my_slides

Capture from second monitor:

decksnag -m 2 -o presentation

List available monitors:

decksnag --list-monitors

Configuration

Sensitivity Presets

Each comparison method has optimized thresholds for sensitivity presets:

MSE (Mean Squared Error):

Preset	Threshold	Description
low	0.01	Only detects major slide changes
medium	0.005	Balanced detection (default)
high	0.001	Catches subtle changes

SSIM (Structural Similarity):

Preset	Threshold	Description
low	0.90	Only detects major slide changes
medium	0.95	Balanced detection (default)
high	0.98	Catches subtle changes

CLIP (AI-Powered):

Preset	Threshold	Description
low	0.80	Only detects major content changes
medium	0.85	Balanced detection (default)
high	0.92	Catches subtle content changes

Capture Interval

The interval (in seconds) between screenshots. Default is 5 seconds.

• Faster interval (1-3s): Better for fast-paced presentations
• Slower interval (5-10s): Better for slower presentations, less CPU usage

GUI Features

The graphical interface provides:

• Region Selection - Click a button to select capture area visually
• Monitor Selection - Dropdown to choose which monitor to capture
• Settings Panel:
  • Interval slider (1-30 seconds)
  • Sensitivity dropdown (Low/Medium/High)
  • Comparison method selection (MSE/SSIM/CLIP AI)
  • Output format selection
• Live Preview - Thumbnails of captured slides
• Progress Tracking - Slide count and elapsed time
• Start/Stop Controls - Easy capture management
• Mini Mode - Compact floating widget during capture

How It Works

1. Region Selection: You select an area of your screen to monitor
2. Initial Capture: Takes a screenshot of the selected region
3. Continuous Monitoring: Every N seconds, takes a new screenshot
4. Change Detection: Compares new screenshot to previous using selected method (MSE, SSIM, or CLIP)
5. Slide Addition: If change exceeds threshold, adds new slide to presentation
6. Export: Saves to your chosen format when you stop capture

API Usage

You can also use DeckSnag as a Python library:

from decksnag import ScreenCapture, ImageComparator, PresentationManager

# Initialize components
capture = ScreenCapture()
comparator = ImageComparator(method="clip")  # Use AI-powered detection
presentation = PresentationManager()

# Select region interactively
region = capture.select_region_interactive()

# Create presentation
presentation.create("my_slides.pptx")

# Capture and add slides
previous = capture.capture_region(region)
presentation.add_slide(previous)

# ... capture loop ...
current = capture.capture_region(region)
if comparator.is_different(previous, current):
    presentation.add_slide(current)
    previous = current

# Save
presentation.save()

Available Classes

Class	Description
ScreenCapture	Multi-monitor screen capture with region selection
ImageComparator	Image comparison with MSE, SSIM, or CLIP methods
PresentationManager	PowerPoint creation and slide management
Exporter	Export to multiple formats (PDF, images)
Config	Configuration management

Requirements

• Python 3.9 or higher
• Dependencies (installed automatically):
  • mss - Fast multi-monitor screenshots
  • pynput - Keyboard/mouse input handling
  • Pillow - Image processing
  • python-pptx - PowerPoint file creation
  • scikit-image - Image comparison (MSE, SSIM)
  • customtkinter - Modern GUI framework
  • img2pdf - PDF export
  • sentence-transformers - CLIP model for AI-powered comparison
  • torch - PyTorch for neural network inference

Building Standalone Executable

Create a standalone executable that doesn't require Python:

pip install pyinstaller
pyinstaller decksnag.spec

The executable will be in the dist/ folder.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Run tests (pytest)
4. Commit your changes (git commit -m 'Add some AmazingFeature')
5. Push to the branch (git push origin feature/AmazingFeature)
6. Open a Pull Request

Development

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run linting
ruff check decksnag/

# Format code
black decksnag/ tests/

Troubleshooting

"No slides captured"

• Make sure the capture region covers the entire slide area
• Try increasing sensitivity (use -s high or lower threshold)
• Check that the presentation is actually changing slides
• Try using CLIP method (-M clip) for better detection

"Too many slides captured"

• Decrease sensitivity (use -s low or higher threshold)
• Increase the capture interval (-i 10)
• Use CLIP method (-M clip) to ignore visual noise

Region selection doesn't work

• Make sure you click and drag (not just click twice)
• Try running with administrator privileges
• On Linux, ensure you have the required X11 libraries

GUI doesn't start

• Ensure CustomTkinter is installed: pip install customtkinter
• On Linux, install Tk: sudo apt-get install python3-tk

CLIP model is slow to start

• The first time you use CLIP, it downloads the model (~350MB)
• Subsequent runs use the cached model and start faster
• Consider using SSIM for quick captures where AI isn't needed

Support

• Issues: GitHub Issues
• Repository: github.com/foxintheloop/DeckSnag

License

This project is licensed under the MIT License - see the LICENSE.txt file for details.

Acknowledgments

• Built with CLIP for AI-powered image understanding
• Uses sentence-transformers for efficient CLIP inference
• Built with CustomTkinter for the modern GUI
• Uses python-pptx for PowerPoint generation