Turn any folder into a private, streaming-style video library.
Quick start · Features · CLI · Development
Virelo runs on your machine, keeps your video files where they are, and gives them a fast web interface with search, progress tracking, favorites, and Shorts.
Run Virelo in the folder you want to serve:
npx vireloVirelo scans the current directory, starts at http://127.0.0.1:41777, and opens the library in your browser.
To serve another folder without changing directories:
npx virelo --media ~/VideosOn Android, install a current Termux release from F-Droid or Termux GitHub releases, then run:
pkg update && pkg upgrade
pkg install nodejs ffmpeg
termux-setup-storage
npx virelo --media "$HOME/storage/shared/Movies" --no-openOpen http://127.0.0.1:41777 in your browser. Pass --media explicitly instead of starting Virelo from your Termux home directory so package caches and other personal files are not treated as a media library.
If port 41777 is already in use, let the operating system choose an available one:
npx virelo --media ~/Videos --random-portWindows example
npx virelo --media "C:\Users\You\Videos" --random-port| 📚 | Library | Recursive scanning, folders, search, and sorting. |
| Playback | Range streaming, seeking, watch progress, and queue controls. | |
| 📱 | Shorts | A vertical feed for portrait videos with swipe-friendly controls. |
| 💜 | Favorites | Save videos for quick access from the library. |
| 🖼️ | Artwork | Automatic movie and series metadata, posters, backdrops, and episode images. |
| 🌐 | Responsive UI | Works on desktop, tablet, and mobile screens. |
| 📦 | PWA | Install Virelo as an app when supported by your browser. |
| 🔒 | Private by default | Localhost binding, no accounts, no telemetry, and no advertising. |
virelo [options]
-m, --media <path> Use a media directory (repeatable)
-d, --data <path> Store data and cache in this directory (default: ~/.virelo)
-H, --host <host> Bind address (default: 127.0.0.1)
-p, --port <port> HTTP port (default: 41777; use 0 for an available port)
--random-port Select an available HTTP port automatically
--no-open Do not open a browser
-h, --help Show help
-v, --version Show version
# Serve the current directory
npx virelo
# Serve multiple directories
npx virelo --media ~/Movies --media ~/Clips
# Use a custom data directory
npx virelo --media ~/Videos --data ~/.config/virelo
# Allow access from a trusted local network
npx virelo --host 0.0.0.0
# Select an available port explicitly
npx virelo --port 0If --media is omitted, Virelo serves the directory where the command is run. Supplying --media replaces that default for the current run.
Virelo recognizes common movie and episode naming patterns:
Movies/
Blade Runner (1982).mkv
Series/
Example Show/
Season 01/
Example.Show.S01E01.mkv
Example.Show.S01E02.mkv
Supported containers include MP4, M4V, MKV, WebM, MOV, AVI, WMV, MPEG, TS, M2TS, FLV, OGV, and 3GP. Browser codec support determines whether a file can play directly.
Virelo works without FFmpeg for formats supported by the browser. Installing ffmpeg and ffprobe adds:
- thumbnails and media probing
- codec detection
- selectable audio tracks and embedded text subtitles
- progressive audio-only AAC/HLS fallback for incompatible audio, without re-encoding video the browser can already play
- Auto video quality that adapts to network conditions, plus manual resolution selection up to the source quality
Virelo can automatically match filenames to movie and series metadata, then cache posters, backdrops, and episode artwork locally. Configure this from Settings → Network. Source video files are never sent to the metadata provider.
The default data directory is ~/.virelo:
~/.virelo/
virelo.db
thumbnails/
artwork/
cache/
hls/
Videos stay in their original folders and are never copied into the data directory. Use --data <path> to choose another location.
Virelo binds to 127.0.0.1 by default. To access it from another device on a trusted LAN:
npx virelo --host 0.0.0.0Virelo does not include user accounts or authentication. Use LAN binding only on a network you trust, or put an authenticated reverse proxy in front of it.
See SECURITY.md before exposing Virelo beyond the host computer.
git clone https://github.com/Riyoway/virelo.git
cd virelo
npm ci
npm run check
node dist/cli.js --no-open| Command | Purpose |
|---|---|
npm run build |
Build the server and web app |
npm run typecheck:web |
Type-check the web app |
npm test |
Run the test suite |
npm run check |
Build, type-check, test, and inspect the npm package |
npm run dev:web |
Start the Vite development server |
npm run dev:server |
Build and run the server in watch mode |
Read CONTRIBUTING.md before submitting a change.
Stack
The web app uses React, Vite, HeroUI, Tailwind CSS, TanStack Router, TanStack Query, Zustand, Phosphor Icons, and hls.js. The server uses Fastify, Node SQLite, chokidar, and optional FFmpeg tools.
Version tags matching v* trigger the npm publish workflow. Configure the repository's NPM_TOKEN secret before creating a release tag.
npm version patch
git push --follow-tagsThe package name virelo and the CLI command virelo are intentionally the same, so the published package starts with npx virelo.
Issues and pull requests are welcome. If you find a bug, include your operating system, Node.js version, Virelo command, and the relevant terminal output.
Virelo has no telemetry, analytics, advertising, account registration, or automatic update checks. Metadata matching sends parsed filenames and media identifiers only; video files remain on your device. Online metadata and artwork can be disabled in Settings.
See PRIVACY.md for details.