halcyon-video

Your Jellyfin or Plex library as a walkable 1990s video rental store, self-hosted

Automatically checked · GitHub checked 2026-11-12

halcyon-video

Overview

Halcyon Video — the video store in your browser

Discord Enter the store Version License Stars

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.

STARLIGHT VIDEO with its slate cone canopy and dimensional sign

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.

Shield emblem, sage walls, warm carpet and customers in the 1993 store

Dimensional shield sign and the daylight brick storefront

Later store styling, alternate palette, tall ceiling and wall decoration

MOONLIGHT VIDEO with freestanding exterior lettering at sunset

Compact independent shop with wooden shelving and tiled ceiling

Independent storefront after dark

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 current Halcyon sales floor, with stocked aisles and its destination cursor

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.

The later-era store and its revised counter layout

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.

Ceiling-mounted CRTs above the rental-store aisles

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.

Kids Club shelving and its in-store television

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

Browsing VHS cases along a stocked shelf

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.

Inspecting a VHS rental case

The back of a rental case, with its synopsis and movie information

Store copies, checkout and carry-out

Rental bag with store copies at the checkout counter

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.

Store-copy sleeve with monochrome metadata

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

A conversation with the clerk at the counter

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

The RomM 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

Building an original emblem in Emblem Studio

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?

Jellyfin   Plex   Emby

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.

SourceWhat Halcyon does with it
JellyfinMovies, series, art, versions, playback, resume points, and watch history
PlexThe same core store through Plex code sign-in and server discovery
EmbyDirect server sign-in, member cards, movies, series, artwork, playback, resume points, and saved store settings
Streaming servicesZero-setup browsing, service choice at checkout, and a link to that service
Jellyseerr / Overseerr / SeerrCollection gaps, discovery stock, requests, and staff picks
RomMPlatform bays, game packaging, cover scans, and optional emulator launch
SteamAn opt-in personal games shelf and launch through native support or the approved Steam Companion
Nothing yetA 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.

PlatformLauncher
Windowsstart.cmd
macOSstart.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 deploymentAvailable route
Windows, macOS and Linux computersBrowser and local launchers; Tauri desktop shell available from source
Android phones and tablets, iPhone and iPadBrowser with touch controls; 3D needs a compatible WebGL browser
Living-room PCs and HTPCsBrowser kiosk, keyboard, gamepad or TV remote; optional local mpv playback
Android TV and Fire TVNative launcher or Remote Play
Raspberry Pi and older or low-power hardwareHTML/CSS 2.5D mode, or Remote Play from a stronger host
Docker hosts, home servers and NAS systems that support DockerServe Halcyon to a browser; rendering happens on the client or Remote Play host
Compatible WebXR headsetsFirst-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

InstallationUpdate command
Clone and launchergit pull, then run the launcher again
Clone and npmgit pull && npm install && npm run build
Compose from this repositorygit pull && docker compose up -d --build
Published image in Composedocker compose pull && docker compose up -d
Published container with docker runPull 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.

Optional support for Halcyon Video on Ko-fi

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.