isputnik.video

An add-on for isputnik.home: its video engine. TV shows and movies, scanned, described and played behind the home server, which owns every screen and every library. It requires the isputnik.home container, is installed beside it and is reached only through home's /video gateway; this server has no pages and does nothing on its own.

How the two fit together: home's docs/video-architecture.md (short) and docs/apps-platform-plan.md (the whole plan, phases and contract).

Status: 0.14.0, alpha. Catalog, library sync and playback work, with each person's progress (resume, next episode, Continue watching). A file a browser plays as it is goes as it is; the rest are converted to HLS as they play — the sound to AAC, the picture to H.264 only when a browser can't show it. A film with several sound tracks plays the one chosen; subtitles inside it or beside it are offered too (text as WebVTT, images burned in). Posters come from beside the files, and from TMDB with the admin's key; films that belong together are grouped into sets, from the .nfo files or TMDB's collections.

The contract, from this side

• Reached only through home's gateway under /video. Every request carries the person's identity in X-Isputnik-* headers signed with GATEWAY_SECRET; without the secret a request is anonymous.
• X-Isputnik-Libraries lists the libraries the person may see. The engine keeps no users or permissions of its own and filters everything by that list.
• X-Isputnik-Profile-Id, when present, names the household viewing profile the person is watching as: watch history (progress, Continue watching, next up) is then that profile's, whoever is signed in. DELETE /video/api/admin/history/profiles/:id forgets a deleted profile's history.
• Home tells the engine about libraries (PUT/DELETE /video/api/admin/libraries/:id, POST …/sync); a library missing from a sync is only detached, kept 30 days.
• Home reads its events, log and a database copy for its backups; the engine never calls home.

Library layout

Show (Year) [imdbid-tt…]/Season 01/Show (Year) S01E01 - Title.mkv   (+ .nfo, tvshow.nfo)
Movie (Year) [tmdbid-…]/Movie (Year).mkv                            (+ movie.nfo)
Movie (Year)/Movie part1.avi, Movie part2.avi                        one film in two files
Set name/First film.mkv, Second film part-2.mkv                      a set of films

The layout Jellyfin and Kodi read. .nfo files come first; names fill in the rest, including release names as they are downloaded. A file written in the last two minutes is left for the next scan, so a copy in progress is never catalogued.

A movie folder holds one film unless its files say otherwise. Names that differ only by a part number counting from 1 (part 2, pt2, CD2, disc 2, часть 2, серия 2) are one film in parts, played in turn. Other files at least a fifth of the biggest's size are films of their own, in a set named after the folder and ordered by any part number in their names. Trailers and extras are left out by name (-trailer, Extras/), and a movie.nfo says the folder is one film.

Configuration

Running it

The image is ghcr.io/isputnikdotnet/isputnik.video (what the Unraid template pulls) and, the same bytes, isputnikdotnet/isputnik.video on Docker Hub; every release tag publishes both, and latest is the newest release. Mount /config (the catalog) and /media (the video share, read-only) — and, if you like, /transcode on RAM or a fast disk — then:

1. In home, Control panel → Settings → Apps → Video: Generate secret and copy it; paste it here as GATEWAY_SECRET. The container won't start without it.
2. On the same page, save the address: http://<host IP>:4300 with the port published, http://isputnik-video:4300 on a user-defined Docker network shared with the isputnik container, or http://<its IP>:4300 on br0 with a fixed IP. Test connection says Paired.
3. Add a library: Control panel → Library → Libraries → Add library → Video.

Unraid — the repository carries a Community Applications template, isputnik-video.xml, listed in CA as isputnik-video. It publishes port 4300 on bridge (safe: without the secret every request is answered 401), maps /config and the read-only video share, offers /transcode and /dev/dri for an Intel GPU, and asks for the gateway secret, which is made in home first because the field is required.

Home's guide docs/users/apps.md has the whole walk-through.

Development

npm install
npm run dev        # :4300, the developer identity, data/ under the repo
npm test
npm run typecheck && npm run lint

License: AGPL-3.0-only.