halcyon-video
Your Jellyfin or Plex library as a walkable 1990s video rental store, self-hosted
Automatically checked · GitHub checked 2026-11-12

Overview
Halcyon Video — the video store in your browser
Current release: 0.25.0. Explore the store configurations below, then see release notes and downloads.
The video store you remember, stocked with what you can watch.
Free and open source. Nothing to purchase in Halcyon: no paid edition, feature unlocks, or required donation. Your existing media and streaming subscriptions remain yours; Halcyon itself costs nothing.
Halcyon Video turns movie night into a visit to the video store. Glide down real 3D aisles, pick up a VHS or DVD case, flip it to read the back, and take your choice to the counter — right down to the glossy rental bag.
Enter Halcyon Video — no signup, installation, media server, or API key required. The browser store opens with movies on the shelves, ready to browse. Choose a title and open its streaming service; Halcyon does not host movies or provide subscriptions.
Prefer your own collection? Connect your Jellyfin, Plex, or Emby library, and add RomM for a games department. Browse with a keyboard, gamepad, TV remote, or phone.

Need help or want to show your store? Join the
Discord community for setup help, release
notes, and the #your-store gallery.
Make the store your own
Choose an emblem, colours, dimensional exterior sign, storefront architecture, store era and environment. Carpet dye and wall paint, ceilings, counters, shelving and decoration can be configured independently. Ten regulars have their own browsing tastes, with automatic traffic that is quiet in the morning and busiest at sunset. Customer habits and population need no setup.
Store Settings gives each choice one home: Catalog for streaming apps, carried libraries and release dates; Browsing & Rentals for camera and checkout behavior; and Overhead TVs for programs and feeds. Store Look, Store Brand, Playback, Video Games, Performance and Connection keep their own controls.






These are captures of the running app with its original public assets and explicit settings. Interior and case demonstrations use the bundled illustrative harness stock; game photographs use real RomM metadata. The browser store uses its streaming catalog when you enter it. The earlier screenshot tour shows additional configurations from version 0.19.0.
Watch the silent flycam tour of the running app. The footage uses the app’s recorder and illustrative demo stock, with automated keyboard flight. The capture revision and recording details are documented beside the video.
A media library you can walk through

The room is built from your catalog. Libraries become aisles, genres become sections, popular titles get deeper stock, and multiple quality versions collapse into one box. Choose VHS or DVD cases, three shelf arrangements, period fit-outs, day through night lighting, and one of several modeled storefronts without changing the library underneath.

Halcyon is meant to be used from the couch. A keyboard, gamepad, TV remote, or phone can drive the same remote-first interface. First-person walk mode adds mouse look and WebXR when a headset is available.
A store worth spending time in
Let it take you on a tour. Attract mode moves from the storefront into the aisles, past the counter, and across the sales floor. Touch a control to return to browsing. The store remains a working place throughout the tour.
Ceiling CRT ambience. Suspended televisions play ambient video above the aisles, giving the room that familiar video-store glow and motion. Choose the screens and fallback presentation to suit your store.

Extreme attention to detail. Rental cases have format-specific proportions, readable spines and printed backs; seasonal displays, dimensional signs, period fixtures, a working return chute, receipts and a deforming checkout bag make the store feel lived in. Customers browse the floor and the clerk follows its actual layout. These details carry through from the facade to the counter.

Choose when it is. The Catalog menu's release-date pin limits the shelves to titles released by your chosen store date. That date advances with real time; an optional setting also matches the store's era to it. Your underlying media library stays intact.
The parts that make it feel like a store
Browse, inspect, and search

Shelf browsing moves case by case without duplicate dead ends. Pick up a title to see its real cover on a correctly proportioned rental shell, then flip it for synopsis, cast, runtime, ratings, and a technical table generated from the file's media streams. TV seasons use box sets, and the clerk's CRT searches by title, director, or genre.


Store copies, checkout and carry-out

Flip the artwork case and its store-copy sleeve together to read the back. Streaming checkout chooses one provider before the counter and carry-out.

Carry several tapes to the counter and the clerk bags them in soft-body plastic that deforms around the cases. The checkout sequence ends in a living room with the rentals and receipt on the coffee table, ready for the VCR. Optional rental mode adds period due dates and a lockout until the tapes are returned through the counter chute.
A clerk who knows the shelves

The clerk is rendered from an original Blender character model into a directional sprite atlas. She walks the actual floor plan, restocks, works the terminal, and comes to recommendation clasps around the store. Her reasons come from the catalog and watch history — collections, directors, actors, studios, and genres — rather than generated copy.
Connect Jellyseerr or Overseerr and she can also surface gaps in a collection, shelve discovery titles as request cases, and place an order without leaving the store.
A real games department

Point Halcyon at RomM and enabled platforms become a dedicated department. Cardboard cartons, clamshells, and jewel cases use platform-specific proportions; native builds can hand a selected game to an emulator.
One identity throughout the store

Build an emblem from editable layers in Emblem Studio, or use an SVG or
transparent PNG. The Brand Editor changes the name, subtitle, colors and
typeface across storefronts, rental cases, aisle signs, counters and bags.
The STARLIGHT and MOONLIGHT storefronts above show two original store names.
Brand packs can also supply era-specific fonts, palettes, surfaces and wraps;
private assets stay in the git-ignored public/user-assets/ directory.
What can stock the shelves?
Works with Jellyfin, Plex and Emby servers. These marks identify compatible services; Halcyon Video is an independent project, not an official client or endorsed product. Plex and the Plex logo are trademarks of Plex and used under a license. Logo sources and usage guidance.
| Source | What Halcyon does with it |
|---|---|
| Jellyfin | Movies, series, art, versions, playback, resume points, and watch history |
| Plex | The same core store through Plex code sign-in and server discovery |
| Emby | Direct server sign-in, member cards, movies, series, artwork, playback, resume points, and saved store settings |
| Streaming services | Zero-setup browsing, service choice at checkout, and a link to that service |
| Jellyseerr / Overseerr / Seerr | Collection gaps, discovery stock, requests, and staff picks |
| RomM | Platform bays, game packaging, cover scans, and optional emulator launch |
| Steam | An opt-in personal games shelf and launch through native support or the approved Steam Companion |
| Nothing yet | A working opening-day store locally, or the stocked hosted demo |
The built-in streaming choices are Netflix, Amazon Prime Video, Disney+, Hulu, Max / HBO Max, Apple TV+ / Apple TV, Paramount+ and Peacock. Availability depends on region and the catalog source. These are discovery and link-out integrations; you still need the provider's own access or subscription. Streaming-service logos are not bundled or used in this presentation.
Streaming aisles do not require Jellyfin, Plex, Jellyseerr, or a TMDB key. The setup terminal asks which services you use and stocks the store from a bundled snapshot. Browse the films first; the store-copy sleeve shows availability and lets you choose one service before completing checkout and the handoff. A configured TMDB or Jellyseerr source can refresh that data later. There is no built-in folder scanner; shelving personal files requires Jellyfin, Plex, or Emby.
Watching something
Three routes cover three kinds of deployment:
- Browser player: direct streams when the browser can decode the file, HLS fallback when it cannot, audio and subtitle selection, resume points, and automatic next episodes.
- HTPC with mpv: a server running on the same machine can launch the local file in mpv for HDR, lossless audio, and native display handling.
- Streaming aisle: titles hand off to the provider's search or watch page; Halcyon does not impersonate a streaming player.
Quick start
Try it before installing
Open the hosted demo. It scales the demo catalog to the browser's measured GPU headroom, from a smaller phone store to the full layout on a discrete GPU.
Local launchers
Clone the repository, then run the launcher for your platform. It checks Node, installs dependencies on first use, builds the app, serves it on port 1420, and opens a browser.
| Platform | Launcher |
|---|---|
| Windows | start.cmd |
| macOS | start.command |
| Linux | ./start.sh |
Pass demo to open the bundled catalog or dev for hot reload. The manual
equivalent is:
git clone https://github.com/halcyon-video/halcyon-video
cd halcyon-video
npm install
npm run dev
The opening-day terminal can connect Jellyfin, Plex, or Emby, select streaming services, or open the store empty and configure it later at the manager CRT.
Docker
Use the published image:
docker run -d --name halcyon --network host --restart unless-stopped \
ghcr.io/halcyon-video/halcyon-video
Or build from a clone with docker compose up -d --build. Host networking lets
WebRTC advertise an address other devices can reach; ordinary browser-only use
can publish port 1420 instead. The compose file documents GPU, allowed-host,
and optional shared-service settings.
Steam remains off unless a user enables it. Native Halcyon includes Steam
support; browser, hosted, and Docker deployments use the optional
Halcyon Steam Companion installed on the computer that will run the games.
The container never receives Steam credentials, display access, or host process
permissions. Download the companion archive from the matching release and see
STEAM-COMPANION.md inside it. Each Halcyon address requires explicit approval.
For browser cryptography, open Halcyon through HTTPS or as localhost on the
gaming computer; plain HTTP addresses on another LAN host cannot enable Steam.
Prefill Jellyfin for visitors (Docker)
Set HALCYON_JELLYFIN_URL when starting the published container. No source
checkout, build arguments, or custom image is needed:
services:
halcyon:
image: ghcr.io/halcyon-video/halcyon-video:latest
ports:
- "1420:1420"
restart: unless-stopped
environment:
HALCYON_JELLYFIN_URL: https://jellyfin.example.com
This example uses ordinary browser rendering. For Remote Play, use the host
networking and other options in the repository's compose file; replace its
build: . with image: to use the published image.
Use an address reachable from visitors' browsers, including Jellyfin's base
path if needed, and HTTPS when Halcyon uses HTTPS. It prefills the Jellyfin
login field; visitors still sign in with their own accounts and can edit the
address. Their saved server takes priority. Do not include credentials, query
strings, or fragments in the address. Runtime VITE_JELLYFIN_URL is also
accepted as an alias; HALCYON_JELLYFIN_URL takes precedence. Runtime username
and password variables are never exposed by this configuration endpoint.
Update with the same compose file:
docker compose pull
docker compose up -d
The replacement container keeps the configured address without rebuilding.
To change it, edit the environment setting and run docker compose up -d
again. Existing visitors' saved server choices are preserved.
HTPC kiosk
./launch.sh
./deploy/install.sh
sudo loginctl enable-linger $USER
The kiosk service restarts after crashes, reloads for maintenance while idle, and renders nothing when the store is still. Halcyon is designed to remain on for days rather than burn the GPU behind an unchanged frame.
Where you can run it
| Device or deployment | Available route |
|---|---|
| Windows, macOS and Linux computers | Browser and local launchers; Tauri desktop shell available from source |
| Android phones and tablets, iPhone and iPad | Browser with touch controls; 3D needs a compatible WebGL browser |
| Living-room PCs and HTPCs | Browser kiosk, keyboard, gamepad or TV remote; optional local mpv playback |
| Android TV and Fire TV | Native launcher or Remote Play |
| Raspberry Pi and older or low-power hardware | HTML/CSS 2.5D mode, or Remote Play from a stronger host |
| Docker hosts, home servers and NAS systems that support Docker | Serve Halcyon to a browser; rendering happens on the client or Remote Play host |
| Compatible WebXR headsets | First-person browser mode where WebXR is available |
Apple TV is planned, not shipped. Roku is unsupported. Published desktop bundles are also still planned; the source shell is not a finished download.
Fast browsing and low-power modes
Halcyon is built for responsive shelf browsing and case inspection. Rendering quality adapts to measured GPU headroom, and a still store holds its frame instead of continuously redrawing. Performance settings expose High, Medium and Low quality, reflection options and a 30 FPS cap, so you can trade visual detail for less GPU work. Speed depends on your device and store size.
For the lightest local experience, 2.5D mode renders the same libraries and cases in HTML and CSS. Remote Play lets another machine do the 3D rendering for your phone or television.
Phone and television controls
On a phone, enter the 3D store in walking mode and use the thumbstick and touch controls. Computers start with the whole-store overview. Drag along the cases to browse; choose a streaming service on the store-copy sleeve, take the title to the counter, and carry the rental bag outside before opening its provider.
Remote Play streams the live canvas and audio over WebRTC while control returns through the same connection. A shared mirror follows the living-room store; private instances give remote visitors their own browser-rendered store. Off-LAN sessions can use Halcyon's optional TURN relay. Read the wire protocol and deployment notes.
See the Android TV and Fire TV launcher for native setup and the Apple TV plan for its current status.
Hosting security
Upgrade to v0.19.2 or later and restart the server or recreate the container. The integration proxy now accepts only operator-configured service URLs. Shared Jellyseerr credentials provide read-only catalog access; creating a movie request uses the signed-in Jellyfin user's linked Jellyseerr account, with that account's permissions, request limits, and approval policy. Sign in to Jellyseerr with the same Jellyfin account once (or have the host import it) before requesting. This linking requirement applies only to movie requests through the host's Jellyseerr service. Browsing the store and watching existing titles do not require a Jellyseerr account or a separate Jellyseerr login. Halcyon verifies the session against Jellyseerr's configured Jellyfin server; anonymous visitors cannot submit requests. Visitors supplying their own request-service credentials keep using those credentials. Connection checks and request acknowledgments do not return account details, and catalog responses omit private upstream fields. Redirects are refused; configure the final service URL directly.
For a browser connection using your own credentials, the server operator must
allow its base URL in HALCYON_PROXY_ALLOWED_URLS (comma-separated absolute
HTTP/HTTPS URLs, optionally including a base path). This does not supply any
credentials or grant write access with the shared server key. Native desktop
connections continue to use their existing direct transport.
Playback controls, F8 feedback storage, and Remote Play endpoints now default to
direct loopback access. HALCYON_TRUSTED_NETWORK_CONTROLS=1 restores network
access only for a trusted private installation. These controls have no
application login: never enable that setting on a publicly reachable instance.
Public reverse proxies must block these endpoints and must replace incoming
Forwarded/X-Forwarded-* headers with their own forwarding metadata. Keep
server credentials in HALCYON_* runtime settings, never public VITE_* bundles.
Thank you to Gibbeth (t-nician) for privately reporting the unauthenticated requests, response-data exposure, and unrestricted proxy destination issues that led to this security update.
Updating
| Installation | Update command |
|---|---|
| Clone and launcher | git pull, then run the launcher again |
| Clone and npm | git pull && npm install && npm run build |
| Compose from this repository | git pull && docker compose up -d --build |
| Published image in Compose | docker compose pull && docker compose up -d |
| Published container with docker run | Pull the new image and recreate the container with the same environment and volumes |
This repository's compose file builds from the clone. docker compose pull
alone therefore does not fetch new application code.
Privacy and network access
Halcyon is local-first. Your media-server login, library, watch history, and private brand assets remain on your devices. Fonts, core textures, models, and the streaming fallback snapshot ship with the app.
Optional features reach outside the local network only when used:
- streaming discovery may contact TMDB or Jellyseerr and load poster art;
- Remote Play performs WebRTC discovery and may use your TURN relay;
- streaming titles open their provider in a new page.
Server operators can provide RomM or Jellyseerr defaults through HALCYON_*
environment variables. Those credentials stay server-side and are injected
only into the small set of allowed proxy requests. Do not put shared secrets
in VITE_* variables on a public deployment; Vite embeds them in downloaded
JavaScript.
Frequently asked questions
Do I need a gaming PC?
No. The renderer scales to the hardware and idles on a held frame. Low-end devices can use 2.5D mode, while Remote Play lets a stronger machine render for a phone or television.
Can I use only streaming subscriptions?
Yes. Select the services at opening day and the store stocks their aisles from the bundled snapshot. A media server is needed only for personal files and in-app playback.
Can I make it look like the store I remember?
Yes. Era, shelving, media format, facade, lighting, signage, fixtures, brand, and case art are independent layers. The public project ships only its original fictional identity; private reference-derived art stays in local user assets.
Does Plex work?
Yes. Choose Plex at the terminal, enter the short code at plex.tv/link, and select a server. Shelves, playback, collections, resume points, and watch history work through the Plex provider. Plex membership cards and cast-photo wall decor are omitted because Plex does not expose those lists efficiently.
Does Emby work?
Yes. Choose Emby at the opening-day terminal or Connection Center, enter your server address, and select your member card or sign in with your Emby server username and password. Pick the libraries to put on the shelves. Halcyon remembers the connection and keeps playback progress on that server; Emby can also be combined with Jellyfin and Plex sources in the same store.
Use a server address reachable from the device running Halcyon, including any
reverse-proxy base path. An existing trailing /emby is accepted. HTTPS pages
need an HTTPS server address; a local Halcyon install can reach HTTP servers.
This is direct server sign-in, not Emby Connect. Verified with Emby Server
4.10.0.40, including direct video, HLS, artwork and account settings; available
transcoding still depends on the server's configuration and permissions.
What is not shipped yet?
A published desktop bundle and the Apple TV client remain on the roadmap. The source tree contains the Tauri shell and tvOS groundwork, but neither is presented here as a finished download.
Support and project policy
Halcyon is free, with nothing to purchase and no paid features. If it made you grin, the in-store tip jar links to Ko-fi. It is optional, switchable in Store Look, and never gates a feature.
Bug reports are welcome. The project does not accept pull requests: it is a single-owner product shared under an open license, not a design-by-committee project. See CONTRIBUTING.md before filing.
Development builds must pass npm run build; the complete unit suite is
npm test.
License
Halcyon Video is licensed under GPL-3.0. Fork it, modify it, and ship your own store, while keeping distributed derivatives open under the same license.
Halcyon Video is an original fictional brand. This repository contains no real
video-rental chain's name, logo, trade dress, or typefaces. Demo movie art is
public-domain or CC-licensed and credited in
public/demo-posters/ATTRIBUTION.md.
Screenshots of the games department use metadata from the author's private
RomM library. The project is not affiliated with any past or present rental
company.
The bundled streaming snapshot and live TMDB or Jellyseerr lookups contain title data and poster art, not streaming-service logos. This product uses the TMDB API but is not endorsed or certified by TMDB.
