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.
Use a current stable Node.js release in one of these supported lines: 22.23.4+, 24.22.1+ or 26.12.1+. Earlier releases are rejected before Virelo creates data or starts a server. These minimums include the October 2026 Node.js security fixes.
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 in your browser. On first use or after upgrading from a version without accounts, create the first administrator using this localhost address on the PC running Virelo, then sign in to your library.
Folder discovery runs in the background without waiting to show the interface.
Hidden entries and nested node_modules directories are excluded from scanning
and monitoring. .ts files are checked for transport-stream packets so TypeScript
source files are not mistaken for recordings. The startup screen remains visible
while scripts or styles load and offers recovery if those resources fail.
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, queue controls and pitch-preserving 0.25–2× speed. | |
| 🎛️ | Video settings | Fit or crop to fill, rotate in 90° steps, and adjust brightness, contrast and saturation without modifying files or changing quality. |
| 📱 | Shorts | A vertical feed for portrait videos with swipe-friendly controls. |
| 💜 | Favorites | Save videos and Shorts with the heart; browse every saved item in Favorites. |
| ☷ | Playlists | Save named, ordered collections per account; edit, shuffle and play them across devices connected to the same server. |
| 🖼️ | 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, local accounts, per-user library permissions, no telemetry, and no advertising. |
The interface supports English, Japanese, Simplified Chinese, Korean and Russian. Change language in Settings → Appearance → Language or on the sign-in screen. Every account can save its own choice. See Localization to add a language.
Open Settings → Appearance to choose Virelo, Streamline, Theater or Centerstage controller layouts and an accent color. Custom colors are adjusted for readable controls. Appearance settings are saved to the signed-in account on the server and can be changed by every user, including non-administrators. Controller layouts apply to normal videos; Shorts keep their vertical controls. No video files are changed.
Open Playlists from Library or the desktop navigation. Add a video from its details, or use Save queue as playlist during playback. Reorder with the drag handle or keyboard, remove references, then select Save changes. Queue edits stay temporary until explicitly saved. Deleting a playlist never deletes videos, favorites or watch history. Playlists are private to their account, and library permissions continue to apply. Conflicting saves require a reload instead of silently overwriting another edit.
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
--reset-password <username>
Recover an administrator's password locally, then exit
-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.
Use Settings → Sharing → Share Virelo to share this server, or Share video beside a video's details/playback actions. QR codes have rounded modules and finder corners, a centered Virelo logo, and a self-contained PNG download. On the server PC, a LAN address is offered only when Virelo is already listening on that interface. Sharing never starts a tunnel, opens a port, includes a session token or bypasses sign-in/library permissions. Personal playlist/settings URLs are not shared. Other devices must be able to reach the selected address.
Enable Settings → Playback → Volume leveling, or Player Settings → Audio → Volume leveling, to reduce loudness differences during playback. It is off by default, saved on this device, and shared by normal videos, Shorts and selected audio tracks. Leveling only turns audio down; it never boosts quiet recordings. Without a saved measurement, live stereo-weighted estimates and a peak limiter protect playback with the existing 30ms lookahead. Manual volume and mute remain in control.
Administrators can enable Settings → Libraries → Analyze audio during scans and run a scan to measure integrated LUFS and true peak for each audio track. This option is off by default and requires FFmpeg/ffprobe. Analysis runs in the background after library indexing and thumbnail repair; long videos take longer. Measurements are cached in Virelo's database and invalidated when a file changes. Analyzed tracks use a constant, non-positive gain targeting −18 LUFS with −3dB peak headroom, preserving the quiet/loud contrast within the video. Quiet tracks remain quieter rather than being amplified. No source files are rewritten. Browser audio processing support is required. Safari/iOS WebKit is left on original audio to avoid its native-HLS audio-routing limitation; the controls explain when leveling is unavailable.
Administrators can send plain-text messages in Settings → Announcements to all currently enabled users or selected users. Recipients use the header bell; read state is stored separately per account. Active clients check about every 30 seconds. Messages expire after 90 days, with 200 announcements and 100,000 recipient records allowed per server. Administrators can withdraw messages; new accounts do not inherit old announcements. This is server-local in-app delivery, not email, OS push or announcements from Virelo's developers.
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
- on-demand 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 → Metadata. Source video files are never sent to the metadata provider.
Audio and subtitle choices, including subtitle Off, are saved in your browser. Compatible track configurations restore the selected track even if stream IDs or order change. Different configurations use that video's defaults without overwriting the saved choices; ambiguous or unsupported tracks are not guessed.
The default data directory is ~/.virelo:
~/.virelo/
virelo.db
thumbnails/
artwork/
cache/
segments-v1/ # requested video/audio segments, shared size limit
hls/ # extracted text subtitles and legacy caches
Videos stay in their original folders and are never copied into the data directory. Use --data <path> to choose another location.
The current directory or --media folders are temporary for the current run.
Use Settings → Libraries → Save library to keep one, or Add folder to save
any other readable folder. Saved libraries remain available when Virelo starts
elsewhere using the same data directory. Previous startup folders do not fill
Account Manager; administrators can restore them from Previously used folders.
Older databases retain those folders and their watch history without guessing
which ones were intentionally saved. See Library storage.
New playback sessions default to Original Quality on both local and network connections. Explicit quality choices are remembered. Favorites has Play all to queue the entire matching collection, including items beyond the first page.
Converted playback uses two-second segments generated only when the browser requests them, at the requested resolution/audio track. Choosing Auto does not pre-convert every rendition or the whole movie. Directly playable files still use HTTP Range playback without conversion. Compatible H.264 can avoid video re-encoding when each requested segment has verified keyframe boundaries and no reordered frames; other sources safely fall back to encoding.
Media tools share two heavy-work slots and one reserved audio/remux slot per server process. Probing and subtitle extraction share the heavy slots with video conversion; scanning runs at most one background tool at a time. Bounded, per-account round-robin queues keep a single viewer from filling the waiting list. Abandoned segment requests are cancelled; overload returns a retryable 503 with Retry-After. These limits protect the host, not guarantee a viewer count: actual capacity depends on codecs, resolution, CPU, storage and network bandwidth. Original-quality Range playback does not consume a conversion slot.
Playback cache is limited to 512 MiB by default across video and audio. Unused least-recently-used files are removed automatically; currently served segments are protected. Legacy whole-film caches are included in the budget and pruned on normal server startup. Originals, the library database, artwork and thumbnails are outside this playback-cache budget. Deleted converted segments can be regenerated from the originals when needed.
Set VIRELO_CACHE_MAX_MB before starting the server to change the playback-cache budget (128–65536 MiB). This controls disk usage, not the browser's short playback buffer.
Administrators can open Settings → Data management to view the data directory and storage used by the database, thumbnails, artwork and playback cache. Clear cache removes only unused generated playback files, with confirmation. Active segments, extracted subtitles and unrelated files are retained. The cache is recreated as needed; accounts, library settings, metadata, favorites and watch history are not reset. Cleanup is refused if the cache overlaps a current or previous media library, or contains filesystem links.
Virelo is a player: it never deletes, moves, renames or edits source video files.
Scan also checks the files behind cached images, even when source videos have not changed. Missing, empty or invalid/truncated image containers are regenerated, and missing technical details are probed again. Changed videos get fresh thumbnails; short clips fall back to their first frame if necessary. Cached image checks inspect container headers and endings, not every decoded pixel. Missing downloaded artwork is fetched again when online metadata and images are enabled; manually cleared metadata stays cleared. The scan result reports completed video checks, additions, updates, newly generated and restored thumbnails, and errors (including failed artwork downloads). Lists and failed images refresh after completion without a page reload. A playing Shorts feed keeps its ordering until you leave it, so a scan cannot switch its video. Source changes use a separate subtitle cache key rather than deleting cache folders.
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.0Startup prints a URL for every detected IPv4 address the server listens on, including Wi-Fi, Ethernet, VPN and virtual adapters, with adapter names. With --host ::, it also prints browser-compatible IPv6 addresses (and IPv4 addresses if dual-stack listening is available). Scoped/link-local IPv6 addresses that browsers cannot open are omitted. URLs use the actual selected port, including --random-port.
Local-only startup explains how to enable network access. Displayed addresses do not guarantee reachability: routing, firewall rules and Virelo's Host allowlist still apply.
The npm server requires a local Virelo account. On first use (including upgrades), open the server's localhost address on the PC running Virelo to create the first administrator. Remote devices cannot claim an unconfigured server. Existing favorites and watch history are copied to this first account; video files and libraries are preserved.
In Settings → Account Manager, administrators can search the user table and edit each account through Profile, Libraries, Permissions, Data and Activity tabs. They can add, disable or delete users, reset passwords, promote administrators, and choose allowed libraries. New users see no libraries until granted access. Select all libraries (including future additions), or an explicit list. Access applies to search, Home, Shorts, playback, subtitles and artwork, not just navigation. Favorites, watch history and playlists are separate for every account.
The Data tab shows personal-data counts and confirmed controls to clear that user's history, favorites, playlists or activity events, or revoke their sessions. Original videos and shared library data are never deleted by these controls.
Under the Admin settings group, Admin → Monitor activity optionally enables online/playback status and retained sign-in, playback and operation logs. It is off by default. Users receive a notice before sign-in and in the application; sessions are recorded only after acknowledging the current notice. Activity shows current sessions and past events, with user filtering and log deletion. Retention defaults to 30 days (7/30/90 selectable), with at most 10,000 events. Playback state is client-reported, not a tamper-proof audit. See PRIVACY.md for the exact collection and deletion behavior.
Passwords may be short PINs; no minimum length or complexity rule is imposed. Use a stronger password or localhost-only administration on untrusted networks.
Playback, transcoding, library management, scanning and metadata editing can be granted separately to regular users. Adding/removing libraries is a trusted filesystem-management permission: that user can add folders readable by the server. Global server settings and Account Manager remain administrator-only. Administrators may limit their own browsing, but can change permissions, so this is not a security boundary between administrators.
Accounts without conversion permission play the original quality and default audio without overwriting saved playback preferences. Source formats unsupported by the browser still need an administrator to allow conversion.
Use Settings → Account to change your display name, username or password (with the current password), or sign out. Account and permission changes invalidate existing sessions. Do not share administrator credentials.
Settings → Admin also offers Administrators can only access from localhost. Change this option on the server PC. It blocks all administrator access from non-loopback connections, including normal browsing, while regular users can still connect over the network. Forwarding headers cannot turn a remote request into a local request. A local reverse proxy or tunnel that hides the client address is an exception: see SECURITY.md before using this option behind a proxy.
If you forget an administrator password, stop Virelo, then run this locally on the server PC, using the same data directory:
virelo --data /path/to/virelo-data --reset-password your-usernameThis prints a new temporary password once, re-enables that administrator, and revokes their sessions. Restart Virelo, sign in on localhost and replace the password in Account settings. Omitting --data uses the default data directory. Recovery never deletes libraries or video files.
Passwords do not encrypt HTTP traffic. Use a trusted LAN, HTTPS reverse proxy or a trusted VPN; do not expose the HTTP port directly to the internet. For HTTPS termination at a proxy, set VIRELO_SECURE_COOKIES=1 and configure the trusted Host as described in SECURITY.md.
See SECURITY.md before exposing Virelo beyond the host computer.
In Settings → External tools, a directly connected localhost administrator can register a CLI tool and start or stop it with a button. This is available in the npm server, not the browser-only Web edition. Install the tool and complete any provider registration or login on the server PC first; Virelo does not install tools, create provider accounts, or start commands automatically.
Enter a button name, an executable name or full path, and one argument per line
without surrounding quotes. The {url} placeholder expands to Virelo's current
local HTTP address, including its actual port. Arguments are literal: pipes,
redirection and shell expansion are not interpreted. Windows batch files need an
explicit interpreter. Tools run in Virelo's data directory, without interactive
input, and must remain in the foreground.
For a reverse proxy or tunnel, optionally configure either a fixed public URL (an HTTPS origin without a path or query) or a generated URL domain. In the latter case, Virelo accepts the first HTTPS origin printed by that command whose hostname matches that domain or one of its subdomains. Only the exact active hostname is added to the Host allowlist, not a wildcard; it is removed when the command stops. Preserve the public Host and overwrite untrusted forwarding headers at the proxy. Public-host session cookies are Secure without changing localhost cookies. Localhost-only administrator restrictions remain in effect.
The launcher shows process state and recent output, with a Copy URL action when an address is available. A running process is not a connectivity or playback health check. Eight definitions can be saved and two commands can run at once. Virelo stops its launched foreground processes on normal server shutdown; it cannot manage separately launched or daemonized services. Login throttling still uses the direct connection address, so clients behind one proxy share its limit.
Commands are not sandboxed. They run with the server's OS permissions and can change files or expose data. Only register tools and arguments you trust. Use the tool's credential storage rather than passing secrets as arguments. Provider terms, content rights, fees and traffic limits still apply; a custom launcher does not create an exemption or endorse a provider for video delivery. See SECURITY.md and PRIVACY.md.
git clone https://github.com/VireloHQ/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.
Update Node.js to a supported version before upgrading. Back up the Virelo data directory with the server stopped, then use the same data directory with the new version. Create the first administrator from localhost on the server PC; existing libraries, favorites and watch history are preserved. Startup folders are now temporary unless explicitly saved in Libraries. See CHANGELOG.md for account, library and license changes.
Git pushes do not publish to npm. To prepare a package for manual publication, run
npm run check and npm pack, inspect the archive, then publish that archive with
npm publish ./virelo-<version>.tgz --access public.
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, cloud account registration, or automatic update checks. Server accounts and permissions stay in your local data directory. Metadata matching sends parsed filenames and media identifiers only; video files remain on your device. An administrator can disable online metadata and artwork in Settings.
See PRIVACY.md for details.
Copyright (c) 2026 Virelo contributors.
The current project is licensed under the GNU Affero General Public License, version 3 only (AGPL-3.0-only). Commercial use and sale are permitted under its terms. Distribution requires the corresponding source, and modified versions that users access over a network must offer those users the corresponding source at no charge. Private modifications used only by their author do not need to be published.
Source and build instructions are available in this repository. When distributing or hosting a modified build, provide the source and build instructions for that exact build and update the app's source link. Your video files and library data are not subject to this source-code requirement.
This change does not revoke permissions already granted for copies previously released under MIT. The original notice is preserved in LICENSES/LEGACY-MIT.txt; it does not license new changes under MIT. Third-party dependencies and assets retain their own licenses and required notices.
The software is provided without warranty; see LICENSE for the full terms.