GitHub - tyrm/quickview

A real-time media viewer that monitors folders and displays new images and videos in a customizable grid layout. Define any grid size from 1x1 up to 10x10 to match your screen and workflow. Perfect for watching screenshot folders, download directories, or any folder where media files appear. Videos play automatically in a muted loop.

Features

• Real-time Updates: Automatically displays new media files as they appear in the watched folder
• Multi-Format Support: Handles images (PNG, JPG, GIF) and videos (MP4)
• Auto-Playing Videos: MP4 files play automatically, muted, and loop continuously
• Memory Management: Videos are properly unloaded when replaced to prevent memory bloat
• Customizable Grid Layout: Define any grid size up to 10x10 (width x height)
• Multi-Window Support: Media files flow seamlessly across multiple browser windows
• WebSocket Communication: Smooth, flicker-free media updates
• Pause Individual Frames: Click any media to pause/unpause that frame
• Customizable Media Fit: Control how media fills their frames
• Filename Display: Shows the filename in the lower left of each media item
• Window ID in Title: Each window shows its unique ID in the browser title
• Cross-Platform: Works on Windows, macOS, and Linux

Installation

# Clone or download the quickview package
go get github.com/yourusername/quickview

# Install dependencies
go get github.com/gorilla/websocket
go get github.com/fsnotify/fsnotify
go get github.com/patrickmn/go-cache

Usage

Basic Usage

# Watch current directory with default 3x1 grid
go run main.go

# Set default grid to 2x2
go run main.go -width=2 -height=2

# Watch with a 4x3 grid for more media
go run main.go
# Then open: http://localhost:8080/?width=4&height=3

# Set default 4x3 grid and watch specific directory
go run main.go -dir=/path/to/media -width=4 -height=3

Layouts

Grid Layouts

Define custom grid dimensions by adding ?width=X&height=Y to the URL:

Maximum grid size: 10x10 (100 media items)

Image/Video Fit Options

Control how media fills their frames with the fit parameter:

Combining Options

# 4x3 grid with full media visible
http://localhost:8080/?width=4&height=3&fit=contain

# 2x2 grid with cropped media
http://localhost:8080/?width=2&height=2&fit=cover

# Single column with 5 media items
http://localhost:8080/?width=1&height=5&fit=contain

Multi-Window Support

QuickView intelligently distributes images across multiple windows:

1. Open multiple browser windows with different layouts
2. New images fill frames across ALL windows in sequence
3. Once all frames are filled, it cycles back to the first window
4. Window count is displayed in the info bar

Example Multi-Window Setup

# Window 1 - Main monitor (3x2 grid)
http://localhost:8080/?width=3&height=2

# Window 2 - Secondary monitor (4x4 grid)
http://localhost:8080/?width=4&height=4&fit=contain

# Window 3 - Vertical monitor (2x5 grid)
http://localhost:8080/?width=2&height=5

Interactive Features

Pause/Resume Frames

• Click any media frame to pause it (red border appears)
• Click again to resume updates
• Paused frames are skipped when new media arrives
• Useful for keeping specific images or videos on screen

Video Playback

• Automatic: Videos start playing immediately when loaded
• Muted: All videos play without sound
• Looped: Videos restart automatically when they end
• Memory-Efficient: Videos are properly unloaded when replaced

Status Indicators

• Green "Connected": WebSocket connection active
• Red "Disconnected": Connection lost (auto-reconnects)
• Red border + "PAUSED": Frame is paused
• Window ID: Shown in browser title (e.g., "Quickview - Window 0")
• Filename: Displayed in lower left of each media item

Command Line Options

Examples

Watch Downloads Folder

go run main.go -dir=~/Downloads -ext=png,jpg,jpeg,gif,mp4

Video-Only Monitoring

go run main.go -dir=~/Videos -ext=mp4

Screenshot Monitoring

# Windows
go run main.go -dir=C:\Users\%USERNAME%\Pictures\Screenshots

# macOS
go run main.go -dir=~/Desktop -ext=png,jpg,mp4

Multi-Format Watching

go run main.go -ext=png,jpg,jpeg,gif,bmp,webp,mp4

Network Drive Monitoring

# Direct UNC path
go run main.go -dir=\\\\server\\share\\images

# Map network drive first, then use drive letter
net use Z: \\server\share
go run main.go -dir=Z:\images

Building

Build for Current Platform

Cross-Platform Builds

# Windows
GOOS=windows GOARCH=amd64 go build -o quickview.exe

# macOS
GOOS=darwin GOARCH=amd64 go build -o quickview-mac

# Linux
GOOS=linux GOARCH=amd64 go build -o quickview-linux

How It Works

1. File Monitoring: Uses fsnotify to watch for new media files in the specified directory
2. WebSocket Server: Establishes real-time connections with browser clients
3. Round-Robin Distribution: Distributes new media across all available frames
4. Base64 Encoding: Media files are encoded and sent via WebSocket for instant display
5. Smart Frame Management: Skips paused frames and handles multi-window coordination
6. Duplicate Filtering: Uses a 1-second cache to prevent processing the same file multiple times
7. Memory Management: Videos are unloaded when replaced to prevent memory bloat
8. Position Naming: Grid positions are named as r0c0, r0c1, etc. (row/column)

Requirements

• Go 1.16 or higher
• Modern web browser with WebSocket support

Troubleshooting

Media Not Appearing

• Check the file extension is included in -ext parameter
• Ensure the watched directory path is correct
• Verify the media files are valid
• For videos, only MP4 format is currently supported

Video Playback Issues

• Ensure your browser supports HTML5 video with MP4
• Check that videos are properly encoded (H.264 recommended)
• Very large video files may take time to load

Connection Issues

• Check if the port is already in use
• Ensure firewall allows the connection
• Try a different port with -port=XXXX

Performance

• For large media files, consider using smaller formats or lower resolutions
• Video files consume more memory than images
• Limit the number of simultaneous windows for better performance
• Videos are automatically unloaded when replaced to prevent memory issues

Network Drive Issues

If media files appear twice when monitoring network drives:

• The application uses a 1-second cache to filter duplicate events
• Try mapping the network drive to a letter first
• Network drives often trigger multiple file events, which are automatically filtered

Example for network drives:

# Direct UNC path
go run main.go -dir="\\\\nas\\photos"

# Or map to drive letter first
net use P: \\nas\photos
go run main.go -dir=P:\

License

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