h-play/README.md

h-player

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, or Kodi.

The sidebar holds app navigation, search, and rescanning controls. Movies and series appear in the main collection grid, similar to Jellyfin-style library browsing. Selecting a collection card opens that movie or series folder with its metadata, seasons, episodes, and playable files.

Episodes are shown as thumbnail cards. h-player generates cached animated WebP thumbnails with ffmpeg when a thumbnail does not already exist, including thumbnails for newly added episodes discovered during scans. Clicking an episode opens it in the fullscreen player. Play all starts a playlist for the selected movie or series and advances through each episode in order.

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 when run directly. Docker Compose sets HOST=0.0.0.0 inside the container so Docker's port forward can reach the app, while still publishing the host port only 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.

To enable rich AniDB fallback metadata, register an AniDB HTTP API client and set ANIDB_CLIENT_NAME plus ANIDB_CLIENT_VERSION. Without those values, h-player can still use AniDB's cached public title dump for fallback matching, but rich descriptions and images come from AniList unless AniDB API credentials are configured.

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
ANIDB_CLIENT_NAME=my_registered_client
ANIDB_CLIENT_VERSION=1

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

Title details show the description as normal read-only text by default. Use the Edit button to change:

• 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.

The Metadata button searches AniList first and falls back to AniDB if AniList has no usable result or is unavailable. Provider metadata only fills missing local fields by default, so manually edited descriptions and thumbnails are preserved.

Privacy Notes

• External metadata lookup is performed only when the Metadata button is used.
• Optional Basic Auth is available through AUTH_USERNAME and AUTH_PASSWORD.
• Do not expose this container directly to the public internet.