Vloom

A fast, privacy-focused CLI tool for recording browser windows and generating LLM-optimized videos. Built in Rust for macOS.

Why Vloom?

When working with AI assistants like Claude, you often need to show them UI/UX changes. Traditional screen recording tools create large files that hit upload limits. Vloom solves this by:

• Targeting specific windows - Record only what you need, no desktop clutter
• Optimizing for LLMs - Auto-compresses to H.264/720p, targeting <10MB per minute
• Instant workflow - Path copied to clipboard, LLM-ready prompt generated
• Privacy-first - Everything stays local, no cloud uploads, no accounts

Features

• 🎯 Smart Window Targeting - Select any window by title
• 🎬 H.264 Encoding - Efficient MP4 output optimized for LLM visual analysis
• 📋 Clipboard Integration - File path automatically copied after recording
• 💬 LLM Prompt Generation - Pre-formatted prompt ready to paste
• ⏱️ Duration Control - Auto-stop or manual Ctrl+C
• 🔒 100% Local - No data leaves your machine

Requirements

• macOS 12.0 or later (Monterey+)
• ffmpeg - For video encoding
• Screen Recording permission - Granted to your terminal

Installation

From crates.io

cargo install vloom

From Source

# Clone the repository
git clone https://github.com/victory-sokolov/vloom.git
cd vloom

# Build release binary
cargo build --release

# Install to PATH
cargo install --path .

Install ffmpeg

# Using Homebrew
brew install ffmpeg

Usage

List Available Windows

vloom --list

Output:

Available windows:

  [1] Google Chrome - GitHub
  [2] VS Code - main.rs
  [3] Slack - general

Use --target "<title>" to select a specific window.

Record a Window

# Interactive selection (prompts if multiple windows match)
vloom

# Target specific window by title
vloom --target "GitHub"

# Auto-stop after 30 seconds
vloom --target "My App" --duration 30

All Options

vloom [OPTIONS]

Options:
  -t, --target <TARGET>      Window title filter (partial match)
  -d, --duration <SECONDS>   Auto-stop recording after N seconds
  -o, --output <PATH>        Output file path (default: ~/vloom-recordings/)
      --fps <FPS>            Frame rate (default: 30)
      --resolution <WxH>     Target resolution (default: 1280x720)
  -l, --list                 List available windows and exit
  -v, --verbose              Enable debug logging
  -h, --help                 Print help
  -V, --version              Print version

Workflow Example

# 1. List windows to find your target
vloom --list

# 2. Start recording (Ctrl+C to stop)
vloom --target "localhost:3000" --duration 60

# 3. Output:
Recording: localhost:3000 - My App
Press Ctrl+C to stop.
Recording... 45s elapsed
^C
Finalizing video...

Recording saved: /Users/you/vloom-recordings/vloom-2024-03-05_14-30-22.mp4
Duration: 45.2s
Size: 4.21 MB
Path copied to clipboard!

LLM Prompt:
────────────────────────────────────────
I recorded a video of a feature implementation. Please analyze this recording:

Video path: /Users/you/vloom-recordings/vloom-2024-03-05_14-30-22.mp4

The video shows my web application running in Chrome. Please:
1. Describe what you observe in the UI
2. Identify any potential UX improvements
3. Note any bugs or unexpected behavior

[Attach the video file to your message]
────────────────────────────────────────

How It Works

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   Window        │     │   Frame         │     │   FFmpeg        │
│   Enumeration   │────▶│   Capture       │────▶│   Encoding      │
│   (scap)        │     │   (30 FPS)      │     │   (H.264)       │
└─────────────────┘     └─────────────────┘     └─────────────────┘
                                                       │
                                                       ▼
                       ┌─────────────────────────────────────┐
                       │   Output                            │
                       │   - ~/vloom-recordings/vloom-*.mp4  │
                       │   - Clipboard: file path            │
                       │   - LLM prompt template             │
                       └─────────────────────────────────────┘

Architecture

Permissions

Vloom requires Screen Recording permission on macOS:

1. Open System Settings → Privacy & Security → Screen Recording
2. Enable your terminal app (Terminal.app, iTerm2, etc.)
3. Restart your terminal

If permission is not granted, Vloom will prompt you and offer to open System Settings.

Output Format

Roadmap

• Windows support (Desktop Duplication API)
• Linux support (PipeWire)
• Audio capture
• GIF output option
• Config file (~/.vloom.toml)
• Self-update command
• Homebrew formula

Contributing

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

Development Setup

# Clone and build
git clone https://github.com/victory-sokolov/vloom.git
cd vloom
cargo build

# Run tests
cargo test

# Run with debug logging
cargo run -- --verbose --list

Code Structure

src/
├── main.rs           # Entry point, recording workflow
├── cli.rs            # CLI argument definitions
├── error.rs          # Custom error types
├── capture/
│   ├── mod.rs
│   ├── window.rs     # Window enumeration & selection
│   └── recorder.rs   # Frame capture pipeline
├── encode/
│   ├── mod.rs
│   └── ffmpeg.rs     # FFmpeg subprocess management
└── output/
    ├── mod.rs
    └── clipboard.rs  # Clipboard & prompt generation

License

MIT License - see LICENSE for details.

Acknowledgments

• scap - Screen capture library
• clap - CLI framework
• ffmpeg - Video encoding