EasyX Viewer

EasyX Viewer is a private, self-hosted media library for videos and images. It is the viewing half of the EasyX suite: it works on its own with any media folder today and is designed to integrate with EasyX Downloader without replacing it.

[!IMPORTANT] EasyX is for adults viewing content they are legally allowed to access and retain. The current release is intended for a private LAN or an authenticated reverse proxy. Do not expose it directly to the public internet.

Current foundation

• Recursive, non-destructive video and image indexing
• Search, media-type filters, performer folders with automatic content covers, and multiple sort modes
• Dedicated home shelves for in-progress, oldest unfinished, recent videos, and recent photos
• Dedicated theater-style video/photo pages with HTTP Range streaming
• On-demand optimized photo thumbnails, midpoint video thumbnails, and cached whole-video GIF previews through FFmpeg
• Viewport-aware media loading that keeps off-screen shelves and horizontal cards out of the critical path
• Hover previews that sample evenly spaced moments without loading the original video
• Favorites, watch progress, 90% completion detection, view counts, history, and exact resume playback
• Library filters for performer, source, watch state, favorites, media type, and sort order
• SQLite application state with a read-only media mount
• Automatic background scans and manual rescan
• Local automatic subtitles with original-language detection and optional translations
• Manual WebVTT/SRT subtitle imports from the player
• Custom player with exact resume, keyboard controls, persistent audio, subtitles, fullscreen, and filter-aware autoplay
• Shareable URLs for every page, video, photo, performer search, and active library filter
• Single-container Docker deployment for the viewer and local subtitle processing
• English-only interface for the initial releases

This is the first functional slice of a broader Stash-class library. Tags, studios, galleries, richer metadata editing, duplicate review, playlists, and the Downloader event bridge are tracked in the product roadmap.

Quick start

git clone https://github.com/raccommode/EasyX-Viewer.git
cd EasyX-Viewer
mkdir -p data media
# Put media in ./media, or change the host side of the media volume.
docker compose up -d

Open http://localhost:3220. The first scan starts automatically.

For an existing library, change the volume in compose.yaml:

volumes:
  - ./data:/data
  - /path/to/your/library:/media:ro

The media mount is read-only by default. EasyX Viewer stores thumbnails, animated previews, favorites, and playback state only in ./data.

Local subtitles

The EasyX Viewer container includes its local subtitle worker. Open Settings → Automatic subtitles, enable it, then select any additional translation languages. The original spoken language is always detected and transcribed. If an additional language matches the original, EasyX Viewer reuses the original track instead of translating it.

Whisper and NLLB run inside the same container as EasyX Viewer; audio and generated text never leave the Docker installation. The first enabled job downloads the models into the persistent ./data/subtitle-models directory; reserve roughly 6 GB for the default model cache. Processing uses one CPU thread and stays idle while the feature is disabled.

You can also import an existing .vtt or .srt file from the subtitle menu in the player without enabling automatic generation.

Container packages

Every push runs tests, builds the complete single-container application, and publishes it to GitHub Container Registry:

docker pull ghcr.io/raccommode/easyx-viewer:latest

main publishes latest; every push also publishes branch and immutable sha-<commit> tags.

Development

Requires Node.js 22.5+ and FFmpeg for generated video thumbnails.

npm install
npm run dev

• Web interface: http://localhost:5173
• API: http://localhost:3220/api

Run the complete local check with npm run check.

License

MIT