ai-context/streamhoard.md

StreamHoard Reference Card (CT104, 10.48.200.104)

What it is

Self-hosted Netflix-style media app — repo myronblair/kino-app (private), branded "StreamHoard" in the UI (internal names/container names still say kino, cosmetic only). FastAPI + React + MongoDB, Docker Compose in /opt/kino on CT104 (Debian 12 LXC on PVE1, 8 cores/12GB RAM/500GB disk).

Login: admin@streamhoard.local — password set via the app's own self-service "Change Password" (Settings page), not stored in this doc. App version shown in the navbar (GET /api/version, source of truth is backend/VERSION in the repo).

Container stack

Container	Role	Port (host)
streamhoard-frontend	React UI, reverse-proxies /api to backend	8080
streamhoard-backend	FastAPI — auth, catalog, streaming, transcode queue, library scan/cleanup	internal 8001
streamhoard-mongo	MongoDB pinned to 4.4 (PVE1's CPU lacks AVX, mongo:7+ SIGILL-crashes without this pin)	internal
streamhoard-gluetun	VPN gateway (NordVPN/WireGuard), real kill switch — iptables default policy DROP, only tun0/LAN/VPN-handshake traffic allowed out	proxies 7878/8989/9696/8082
streamhoard-radarr / -sonarr / -prowlarr / -qbittorrent	network_mode: service:gluetun — share gluetun's netns, so kill switch covers all their traffic, not just torrent	via gluetun
streamhoard-portainer	Docker management GUI (https://10.48.200.104:9443)	9443

Media/music mounts

• NAS (10.48.200.249) mounts happen on PVE1 itself, then pass into CT104 as LXC mountpoints (/etc/pve/lxc/104.conf) — unprivileged LXCs can't do NFS/CIFS client mounts directly.
• mp0: NFS /volume1/video → /mnt/nas-video (PVE1) → /mnt/nas/video (CT104). Radarr/Sonarr root folders /mnt/nas/video/movies, /mnt/nas/video/tv.
• mp1: CIFS Storage share → /mnt/nas-backups — MSP360 backup destination.
• mp2: CIFS music share (no NFS export exists for it) → /mnt/nas-music (PVE1, read-only) → /mnt/nas/music (CT104, read-only). Real content is under Music/<Artist>/<Album>/<Track>; sibling folders (Apple Music, Automatically Add to Apple Music, Downloads-Music) are Music.app-internal and deliberately not scanned — may contain DRM'd Apple Music subscription tracks, which no third-party player can decrypt/play.
• Backend container bind-mounts /mnt/nas/video and /mnt/nas/music read-only at their identical absolute paths, so Radarr/Sonarr/Library-Scan-reported file paths resolve with zero translation.

Library Scan (admin, separate from Radarr/Sonarr)

Walks the NAS mounts directly for movies/TV/music not already in the library — storage_type="scan" on the resulting Movie/Episode/Track record, fully integrated (streamable, transcodable, listed in Admin) same as Radarr/Sonarr imports. Select All / Deselect All per tab. Movie/TV scans are fast (filesystem stat only); music scan defers tag reads to import time (reading ID3/MP4 tags during the scan itself was the original bottleneck).

Music library

Track model (title/artist/album/track_number/duration/album_art_url), streamed via ranged /api/stream/track/{id}. Persistent bottom player (queue, seek, output-device picker via the Audio Output Devices API for already-paired Bluetooth speakers — Chrome/Edge only, browsers can't pair new BT devices). Album art: MusicBrainz + Cover Art Archive lookup (free, no key, 1 req/sec rate limit respected), triggered from Library Scan's Music tab; falls back to a branded placeholder (not a bare icon) until art is set. NAS mount is read-only, so Apple Music/iTunes can keep managing the same files independently.

Library Cleanup (admin)

Background job (POST .../scan/start, GET .../status, POST .../stop — has a real Stop button, not just a spinner) checking for: missing files, orphaned episodes/HLS output, stuck transcode jobs (running 2h+ with no completion), duplicate imports, orphaned subtitles, dangling watchlist/progress rows. Nothing deletes until you click Fix. File-existence checks run in a small thread pool off the event loop — an earlier version did this synchronously and froze the entire server for as long as the scan took (a plain GET /api/movies would hang); confirmed fixed, don't reintroduce blocking filesystem calls in an async endpoint here.

Transcode queue

One job at a time, nice -n 10 (was 19), threads divided across however many ABR variants a job has so the total stays near a fixed budget instead of each variant claiming the full count independently. Auto-transcode setting (off/quick/abr, in Settings) auto-queues new imports.

Three quality modes:

• quick — stream-copy both streams (fast, no quality loss, but doesn't fix incompatible audio).
• abr — full re-encode to multi-bitrate H.264/AAC HLS (slow — 4 variants, only way to fix HEVC/x265 video).
• audio — video stream-copied untouched, only audio re-encoded to AAC (fast — no video re-encoding). Fixes the single most common playback problem: BDRip/AVI sources very often carry AC3/DTS/EAC3 audio, which no browser can decode natively — browsers respond by hiding the volume control entirely, not by erroring. POST /transcode/queue/fix-audio-all cancels the pending backlog and replaces it with the fast audio-only fix library-wide; run a real ABR pass later for actual multi-bitrate quality once there's no urgency.

Retry (/transcode/queue/{id}/retry) and bulk retry-failed never delete the movie/episode — only the job history and hls_status flag change.

Requests → Radarr/Sonarr

Pending user requests can be Approved (Movie or TV) by an admin: looks up the title via Radarr/Sonarr's own lookup API, adds the best match with search-on-add enabled. Atomically claims the request (pending → approving → approved) so a double-click or two admins can't both add the same content; releases the claim back to pending on failure so it can be retried. Live status line (searching/queued/downloading/downloaded) reads from Radarr/Sonarr's own queue, polled every 15s — real data relayed through Radarr's own refresh cycle, not a direct qBittorrent connection.

MSP360 backup

Weekly full / daily incremental to the NAS (/mnt/nas-backups/MSPBackups, plan StreamHoard-Backup). Installed via dpkg-repack from the NovaCPX install (no public Linux .deb download exists). Excludes the media/music NAS mounts, the backup destination itself, Docker image layers, and the regenerable HLS transcode cache.

JARVIS agent

Registered as streamhoard104, watch_services: ["docker"] — watches the Docker daemon only, not individual containers. A /usr/local/bin/streamhoard-watchdog.sh cron (every 5 min) separately restarts any StreamHoard container that isn't running, since Docker's own restart: unless-stopped policy doesn't always trigger reliably.

Copyright

Repo has a NOTICE file ("Property of TomTom Enterprises."). Commits to this repo omit AI-authorship trailers.

Open items

• No reverse proxy/TLS in front of StreamHoard, no LAN-only firewall rule.
• Large transcode backlog from initial library import — being worked through via the fast audio-fix pass; a full ABR pass for real adaptive-bitrate quality is still pending for most of the library.