Hipshot

I got tired of repeating myself. Hipshot is a Python tool for capturing desktop and mobile screenshots of websites. Automatically handles ChromeDriver setup, supports multiple viewports, parallel processing, and intelligent popup dismissal.

Features

• Auto ChromeDriver Management - No manual driver downloads needed
• Multiple Viewport Presets - Desktop, mobile, tablet, and specific device sizes
• Parallel Processing - Screenshot multiple URLs simultaneously
• Retry Logic - Automatic retries with exponential backoff
• Full-Page Screenshots - Capture entire page, not just viewport
• Smart Popup Dismissal - Auto-dismiss cookie banners and modals
• Progress Tracking - Real-time progress bars
• Configuration Files - YAML/JSON config support
• Comprehensive Logging - Detailed logs for debugging
• Error Handling - Robust error handling and validation

Quick Start

1. Installation

# Create virtual environment
python3 -m venv venv

# Activate virtual environment
source venv/bin/activate  # On macOS/Linux
# or
venv\Scripts\activate  # On Windows

# Install dependencies
pip install -r requirements.txt

2. Basic Usage

# Screenshot a single URL
python hipshot.py screenshot https://www.example.com

# Screenshot multiple URLs
python hipshot.py screenshot https://www.example.com https://www.google.com

# Custom viewports
python hipshot.py screenshot https://www.example.com --viewports desktop,mobile,tablet

# Use configuration file
python hipshot.py screenshot --config hipshot_config.yaml

CLI Commands

Screenshot Command

python hipshot.py screenshot [URLs...] [OPTIONS]

Options:

• --config, -c - Path to config file (JSON/YAML)
• --output, -o - Output directory (default: screenshots)
• --headless/--no-headless - Run browser in headless mode (default: headless)
• --viewports, -v - Comma-separated viewport presets (default: desktop,mobile)
• --full-page/--viewport-only - Capture full page or viewport only (default: full-page)
• --parallel, -p - Number of parallel workers (default: 3)
• --timeout, -t - Page load timeout in seconds (default: 30)
• --retry, -r - Number of retry attempts (default: 3)
• --dismiss-popups/--no-dismiss-popups - Auto-dismiss popups (default: enabled)

Examples:

# Screenshot with custom settings
python hipshot.py screenshot https://example.com \
  --output my_screenshots \
  --viewports desktop,iphone_12,ipad \
  --parallel 5

# Viewport-only screenshots (no full page)
python hipshot.py screenshot https://example.com --viewport-only

# Run browser with GUI (not headless)
python hipshot.py screenshot https://example.com --no-headless

# Higher timeout and retry for slow sites
python hipshot.py screenshot https://slow-site.com --timeout 60 --retry 5

List Viewports

python hipshot.py list-viewports

Shows all available viewport presets:

• desktop - 1920x1080
• laptop - 1366x768
• tablet - 768x1024
• mobile - 375x812
• iphone_se - 375x667
• iphone_12 - 390x844
• iphone_14_pro - 393x852
• ipad - 810x1080
• ipad_pro - 1024x1366

Initialize Config

python hipshot.py init-config [OUTPUT_FILE]

Generates a sample configuration file:

# Create YAML config
python hipshot.py init-config hipshot_config.yaml

# Create JSON config
python hipshot.py init-config hipshot_config.json

Configuration File

Create a hipshot_config.yaml file:

urls:
  - https://www.example.com
  - https://www.google.com

output_dir: screenshots
headless: true
timeout: 30
retry_attempts: 3
retry_delay: 2
full_page: true

viewports:
  - desktop
  - mobile
  - tablet

dismiss_popups: true
max_workers: 3

Then run:

python hipshot.py screenshot --config hipshot_config.yaml

Output Structure

Screenshots are organized by page title:

screenshots/
├── Example Domain/
│   ├── Example Domain_desktop.png
│   ├── Example Domain_mobile.png
│   └── Example Domain_tablet.png
├── Google/
│   ├── Google_desktop.png
│   └── Google_mobile.png
└── hipshot.log

Advanced Features

Filename Sanitization

Page titles are automatically sanitized to remove invalid filesystem characters (:, /, *, etc.)

Full-Page Screenshots

Automatically calculates and captures the entire scrollable page height

Popup Dismissal

Intelligently detects and dismisses common cookie banners and modals using multiple strategies

Retry Logic

Failed requests automatically retry with exponential backoff:

• Attempt 1: Immediate
• Attempt 2: Wait 2 seconds
• Attempt 3: Wait 4 seconds

Parallel Processing

Process multiple URLs simultaneously with configurable worker count for optimal performance

Logging

Logs are written to both console and hipshot.log file with timestamps and log levels:

2025-10-05 10:30:15 - INFO - Starting screenshot capture for 3 URL(s)
2025-10-05 10:30:16 - INFO - ✓ Screenshot saved: screenshots/Example/Example_desktop.png
2025-10-05 10:30:17 - WARNING - Timeout for https://slow-site.com (attempt 1/3)

Troubleshooting

ChromeDriver issues:

• The app automatically downloads and manages ChromeDriver
• If you encounter version mismatches, delete the cached driver and rerun

Memory issues with parallel processing:

• Reduce --parallel value (try 1-2 for low-memory systems)

Slow performance:

• Enable headless mode (default)
• Reduce number of viewports
• Disable popup dismissal if not needed

Timeouts:

• Increase --timeout value
• Increase --retry attempts

Legacy Files

The repository contains older versions for reference:

• app.py - Original hardcoded version
• V0_app.py - Initial prototype
• cli_version.py - Early CLI implementation

Use hipshot.py for the latest version with all features.

Requirements

• Python 3.9+
• Chrome browser installed (Chromium in the future, not a fan of Corporate Surviellance)
• Internet connection (for ChromeDriver auto-download)