OrbitTv/docs/sample-scheduled-channel.md

One scheduled Emby channel — 0.6.0

Approved increment

Paul confirmed the classic overlay hides correctly on his Xiaomi and approved the next step: one real scheduled channel from a small Emby selection, accurate runtimes, joining in progress, automatic transitions and genuine Now/Next. This is a session-scoped proof, not a full importer.

Bounded setup

Menu → Connect Emby → Check 20 items → Create sample channel. The existing single-page limit remains 20. The builder checks playback metadata for at most five entries from that page and keeps up to three distinct direct-stream-eligible titles. At least two are required. It requests metadata with IsPlayback=false and does not open video streams during setup. Expired-login and rate-limit responses stop setup immediately. No account or server administration is performed. No new runtime dependency is introduced.

Timeline and source selection

Catalogue and source runtimes retain millisecond precision from Emby's 100-nanosecond ticks. The chosen source's runtime takes precedence, and its media-source ID is locked for later tuning. A usable runtime must be at least one second and at most seven days. The channel repeats its 2–3-item lineup against the Unix UTC epoch. Start/end times come from cumulative durations, not fixed half-hour slots or the time the app launched. Display times use the TV's local zone. The same lineup, order, source IDs and durations produce the same schedule when recreated. A changed provider sample or runtime can change the lineup; nothing is persisted in this increment.

The guide calculates current/upcoming broadcasts from the wall clock. No encoder or video process runs when the channel is unwatched. This prototype's real guide is inside the connected sample flow; the main three-channel fictional demo guide remains unchanged.

Tuning and transitions

Watch channel opens the source at the current programme's wall-clock offset. The player adjusts its initial join after preparation if buffering put it more than two seconds behind the target. A 250 ms clock tick detects the next programme boundary, releases the old player and negotiates its successor. It joins the successor at the current offset, so preparation delay does not reset programme start time. Brief buffering between programmes is possible; this is not a gapless server broadcast. A material source runtime change produces a rebuild message instead of silently changing the timeline. Failed slots are not repeatedly requested on every timer tick. A cancellable mutex serializes preparation, so a slow in-flight metadata call finishes before a newer clock slot starts another.

The existing auto-hiding strip displays 101 Orbit One, real current title and next title/time. This mode follows the clock: pause/seeking are disabled for now. On-demand sample playback keeps its existing pause/seek behaviour. Back from the channel returns to the sample TV guide; Back to sample returns to the 20-item list without signing out. Leaving that flow/backgrounding still stops playback and attempts logout through the existing temporary-session cleanup.

Quick transition check

Check transition temporarily shifts only the preview clock to ten seconds before the current programme ends (half its length if very short). Real durations are not shortened. It exercises exactly the same boundary/next-item path as normal viewing. The strip labels Transition check. Closing it returns the guide to the ordinary wall clock. Like normal viewing, joining near a programme's end may update or mark it watched in the provider's viewing history; the guide says so.

Evidence and limits

Tests use fictional items and scripted API replies, with no live account or media calls. They cover exact millisecond joins, end boundaries, repeated cycles, contiguous guides across midnight/DST dates, negative epochs, recreation, immutable lineups, duration/count validation, transition checking, a three-item/five-probe bound, rate limits and source/runtime locking. The three-item eligibility check is metadata-based and does not guarantee every codec/profile will decode on this TV. Real channel playback and rollover still require Paul's hardware test. Credentials, tokens, private titles and URLs remain outside development tooling and saved files. No VPS, firewall, persistent service, full library scan or new device permission is needed.

Primary references

https://dev.emby.media/reference/RestAPI/MediaInfoService/postItemsByIdPlaybackinfo.html https://dev.emby.media/doc/restapi/Playback-Guidelines.html https://dev.emby.media/doc/restapi/Video-Streaming.html