h-player is a small local web app for browsing a folder-based private video collection. The interface follows Kaizoku's dark purple glass-panel design, including the same card gradients, rounded controls, cover fallback treatment, and accent colors. The app remains a standalone private library browser and does not integrate with Plex, Jellyfin, Kodi, or any external metadata provider.

Folder Layout

Place media in this shape:

Library/
  Movie Or Series/
    filename.mp4
  Series With Seasons/
    Season 01/
      episode-01.mp4

Supported extensions: .mp4, .m4v, .mkv, .webm, .mov, .avi.

Run With Docker

docker compose up --build

Open http://localhost:3000.

The app binds to 127.0.0.1 by default, so it is only reachable from the same machine unless you explicitly set HOST. The compose file publishes the container on 127.0.0.1:3000. Your library is mounted read-only, while metadata and generated thumbnails are saved in /data inside the container.

The included compose file keeps the existing /mnt/ssd2/docker_data/h-play host data path so renaming the app to h-player does not hide metadata from an already-running instance. Move that directory yourself before changing the mount path.

To add a browser password prompt, uncomment AUTH_USERNAME and AUTH_PASSWORD in docker-compose.yml.

Run Without Docker

npm start

Optional environment variables:

HOST=127.0.0.1
PORT=3000
LIBRARY_DIR=/path/to/Library
DATA_DIR=/path/to/private-library-data
AUTH_USERNAME=viewer
AUTH_PASSWORD=change-me

Set HOST=0.0.0.0 only when you intentionally want the app reachable from other machines on the network. Use AUTH_USERNAME and AUTH_PASSWORD before exposing it beyond localhost.

Thumbnail generation requires ffmpeg on the host. Docker includes it.

Metadata Storage

Metadata is stored in SQLite at:

data/library.sqlite

If an older data/metadata.json file exists, the app imports it into SQLite on startup without deleting the JSON file.

Metadata Fields

Use the app to edit:

display title
short description
thumbnail path or URL

The Thumbnail button extracts a frame from the first video in a title and stores it under data/thumbnails.

Privacy Notes

No external metadata lookup is performed.
Optional Basic Auth is available through AUTH_USERNAME and AUTH_PASSWORD.
Do not expose this container directly to the public internet.