📸 WebShot

Shoot your favorite Websites!!!

A beautiful CLI tool for capturing screenshots, videos, and complete HTML snapshots of websites using Puppeteer. Features an interactive "shoot mode" with a pastel-themed terminal UI.

╦ ╦╔═╗╔╗ ╔═╗╦ ╦╔═╗╔╦╗
║║║║╣ ╠╩╗╚═╗╠═╣║ ║ ║
╚╩╝╚═╝╚═╝╚═╝╩ ╩╚═╝ ╩

Shoot your favorite Websites!!!
────────────────────────────────

✨ Features

• 📷 Multiple export formats: PNG, JPG, WEBP, PDF, MP4/WebM video, HTML with assets
• 🎯 Interactive shoot mode: Press spacebar when ready or wait for countdown
• 🎨 Beautiful terminal UI: Pastel-colored spinners and progress indicators
• 📜 Custom automation scripts: Execute Puppeteer code before capture
• 🐛 Debug mode: Built-in Node.js inspector support
• ⚡ Fast video recording: Efficient screenshot-loop method with ffmpeg
• 🌐 Complete HTML snapshots: Download websites with all assets
• 📱 Flexible viewports: Custom dimensions or mobile presets

🚀 Installation

# Clone or download the repository
git clone <your-repo-url>
cd webshot

# Install dependencies
pnpm install

# Make executable (if needed)
chmod +x webshot

# Optional: Link globally to use from anywhere
npm link
# or add to your PATH

Requirements

• Node.js (v14 or higher recommended)
• ffmpeg (required for MP4/WebM video recording)

  # Debian/Ubuntu
  sudo apt install ffmpeg
  
  # macOS
  brew install ffmpeg
  

📖 Usage

Basic Commands

# Interactive screenshot with shoot mode
webshot -u https://github.com

# Quick screenshot without delay
webshot -u https://example.com --no-delay

# Specify output path
webshot -u https://example.com -o screenshots/github.png

Export Formats

PNG (default)

webshot -u https://example.com -f png

JPEG with quality control

webshot -u https://example.com -f jpg --quality 95

WEBP for smaller file sizes

webshot -u https://example.com -f webp --quality 90

PDF documents

webshot -u https://github.com/features -f pdf

MP4 video recording

# 10 second video at 30 FPS
webshot -u https://bruno-simon.com -f mp4 --duration 10000 --fps 30

# WebM format (VP9 codec)
webshot -u https://bruno-simon.com -f mp4 -o output.webm --duration 5000

Complete HTML with assets

# Downloads all images, CSS, JS to assets/ subdirectory
webshot -u https://stripe.com -f html -o stripe/index.html

Custom Automation Scripts

Execute custom Puppeteer code before capturing:

# Use a built-in example
webshot -u https://example.com -s examples/dark-mode.js

# Chain multiple behaviors
webshot -u https://example.com -s examples/scroll-animation.js -f mp4 --duration 8000

Available example scripts:

• scroll-animation.js - Scroll to bottom and back to top
• dark-mode.js - Attempt to enable dark mode
• interact-form.js - Fill out forms with demo data
• hover-effects.js - Simulate hover states
• mobile-view.js - Switch to mobile viewport
• animated-sections.js - Trigger scroll-based animations

Create your own script:

// my-script.js
console.log('🎬 Running custom automation...');

// You have access to the 'page' object
await page.evaluate(() => {
  document.body.style.backgroundColor = '#ff69b4';
});

await new Promise(resolve => setTimeout(resolve, 1000));
console.log('✓ Done!');

Viewport Configuration

# Custom dimensions
webshot -u https://example.com -w 1280 -h 720

# Mobile viewport (use with script)
webshot -u https://example.com -s examples/mobile-view.js

Custom Shoot Delay

# 5 second delay
webshot -u https://example.com 5000

# 10 second delay
webshot -u https://example.com 10000

Debug Mode

# Enable debug logging and Node.js inspector
webshot -u https://example.com --debug

# Connect to chrome://inspect in Chrome DevTools
# or use: node inspect localhost:9229

# Custom debug port
DEBUG_PORT=9230 webshot -u https://example.com --debug

# Debug slow or complex websites
webshot -u https://heavy-site.com --debug --wait-until load --timeout 60000

🎯 Wait Strategies

Control when navigation is considered complete:

# Wait for window.load event (fastest)
webshot -u https://example.com --wait-until load

# Wait for DOM ready
webshot -u https://example.com --wait-until domcontentloaded

# Wait for network to be mostly idle (default, best for most sites)
webshot -u https://example.com --wait-until networkidle2

# Wait for complete network silence (slowest, most complete)
webshot -u https://example.com --wait-until networkidle0

# Increase timeout for slow sites
webshot -u https://slow-site.com --timeout 60000

📋 Command Reference

Options

Option	Description	Default
-u, --url <url>	Target URL to capture	required
-f, --format <format>	Export format: png, jpg, webp, pdf, mp4, html	png
-o, --output <path>	Output file path	<hostname>-<timestamp>.<format>
-s, --script <path>	Custom Puppeteer automation script	-
-w, --width <px>	Viewport width	1920
-h, --height <px>	Viewport height	1080
--no-delay	Skip interactive shoot delay	false
--full-page	Capture full page (scrollable content)	true
--quality <1-100>	Image quality for JPG/WEBP	90
--duration <ms>	Video duration for MP4	5000
--fps <fps>	Video FPS for MP4	30
--wait-until <state>	Page load state: load, domcontentloaded, networkidle0, networkidle2	networkidle2
--timeout <ms>	Navigation timeout	30000
--debug	Enable debug mode with Node.js inspector	false
--help	Show help message	-

Arguments

Argument	Description	Default
[delay]	Shoot delay in milliseconds	3000

🌐 Cool Websites to Try

# 3D interactive portfolio
webshot -u https://bruno-simon.com -f mp4 --duration 10000

# WebGL demos and examples
webshot -u https://threejs.org/examples -f webp

# Beautiful modern design
webshot -u https://stripe.com -f pdf

# Modern UI with animations
webshot -u https://linear.app -f png

🎨 Terminal UI

WebShot features a beautiful pastel-themed terminal interface:

• Animated spinners with rotating frames (◐ ◓ ◑ ◒)
• Progress bars for video rendering
• Color-coded output using pastel colors (mint, sky, lavender, peach, coral)
• Interactive countdown with spacebar to shoot
• File overwrite prompts to prevent accidents

🔧 How It Works

Screenshot Capture

1. Launches headless Chromium via Puppeteer
2. Sets viewport and navigates to URL
3. Waits for fonts and network activity
4. Executes custom script (if provided)
5. Shows interactive shoot mode countdown
6. Captures screenshot using Puppeteer's page.screenshot()

Video Recording

1. Creates temporary frames directory
2. Captures JPEG screenshots in a fast loop
3. Writes frames to disk with sequential naming
4. Uses ffmpeg to convert frames to video:
   • MP4: H.264 codec with -preset fast -crf 23
   • WebM: VP9 codec with -crf 30
5. Duplicates frames to reach target FPS
6. Cleans up temporary frames

HTML Export

1. Extracts all resource URLs (images, CSS, JS, favicon)
2. Downloads each resource using Puppeteer
3. Saves to assets/ subdirectory
4. Rewrites HTML to use local paths
5. Returns to original page

📦 Package Details

• Name: @valknarness/webshot
• Version: 1.0.0
• Main: Single-file executable (webshot)
• Dependencies: puppeteer@^24.26.0
• License: MIT
• Author: valknar@pivoine.art

🤝 Contributing

This is a personal project, but suggestions and improvements are welcome!

📄 License

MIT License - feel free to use and modify as needed.

⚠️ Security Notes

• Custom scripts are executed with eval() and have full access to Node.js APIs
• Only use trusted scripts from reliable sources
• Be cautious when capturing websites with sensitive information
• Video recording creates temporary files that are cleaned up automatically

🐛 Troubleshooting

ffmpeg not found

# Install ffmpeg
sudo apt install ffmpeg  # Debian/Ubuntu
brew install ffmpeg      # macOS

Puppeteer installation issues

# Clear cache and reinstall
rm -rf node_modules pnpm-lock.yaml
pnpm install

Timeout errors on slow sites

# Increase timeout and use faster wait strategy
webshot -u https://slow-site.com --timeout 60000 --wait-until load

Video recording too slow

# Reduce FPS or duration
webshot -u https://example.com -f mp4 --fps 24 --duration 3000

Debug complex issues

# Enable debug mode to see detailed logs
webshot -u https://example.com --debug

💡 Tips

• Use --no-delay in scripts and automation
• WebP format offers the best quality-to-size ratio for screenshots
• For video recording, 30 FPS is smooth for most content
• Use networkidle2 (default) for most sites, load for fast captures
• Mobile viewport scripts work best with responsive websites
• HTML export is great for offline archiving or analysis
• Debug mode shows all network requests and page console output

---

Made with 💜 by valknar