OrbitTv/docs/refinement-notes.md

Refinement notes

Paul's approach, 2 November 2026: build in pieces, learn by using it, and note every refinement, so the next user gets a much easier time because we did the refining. Each note says what happened and what a new user should get by default. These feed "Build your own network" on the roadmap.

Channels and pools

• Rules let in misfits. Family films, shorts, blockbusters and foreign films reached After Dark until year, rating, genre and score rules tightened. A new user should get channels that fit first time, and never have to judge a long list.
• Lists of well-known titles work best. Curated lists found nearly everything in Paul's library (Orbit 2 31 of 31, Sci-Fi 48 of 48). Rules are for growing a pool, not starting one.
• Reviewing is tiring. Paul said he'd need to go through each one again, and can't judge every title. Filling automatically and taking out what's wrong suits better than ticking what's right.
• Rating alone is not a signal. Filling by highest rating in 0.74 brought UFC events, wrestling and obscure films with a 10 from a few votes. Emby's type and genre don't separate a film from a recorded event. A director needs popularity or vote counts, an event filter, and a check against title lists. Until then, lists are better.
• TMDb could supply that signal (Paul's suggestion, 2 November 2026). Vote counts, popularity, country, original language and keywords, matched by the TMDb id Emby usually holds. Optional only, since Paul's director idea is local with no mandatory cloud. It needs each user's own free key, and its terms must be checked before any public release.
• Titles still suggests by rating, and ticks new suggestions by default. Fix this before a new user sees it.
• A film channel needs about 100 films to go a week without a repeat. With 45 it repeats in 3 to 4 days. Tell the user if their library falls short.
• Library details have limits. Nothing tells a British film or hand-drawn animation apart, so those need title lists or other sources.
• Names vary by library. WWE Raw and IMPACT! Wrestling were found under different names from those guessed. Matching should cope with this, and show what it couldn't find.
• The same show on two channels at once looks wrong, and is now avoided. Check this across every new source of programmes, such as the Drive-In.

Playback

• Some files can't play on some boxes. The MP3 audio on Transformers failed every time, and Forensic Files had sound with no picture. Leave these out before they're scheduled, and never show an error on air.
• Transcoding is not a safe default. Paul decided against it, and a provider may not allow it.
• Foreign audio needs catching: Recess came up not in English.

Screens

• Paul prefers uncluttered screens, showing only what's needed. Test tools and technical readouts confused the flow, and took 0.73 to clear out.
• Real artwork beats drawn scenes. Drawn channel backdrops looked off brand; real Emby artwork was "clean af", and his own Drive-In pictures beat my drawn ones.
• Screenshots are blocked on the box, so text placed over artwork needs a photo to check. Fixed-height lines fixed the first attempt.
• Remote reach: check every screen by remote. The gear couldn't be reached from the first column until 0.73.1.

Idents

• Check them in motion. Paul caught what stills hid: planets outside their rings, a burst covering a letter.
• Flat layers look blocky. Real 3D in Blender is a big step up, and Blender's free. It takes about 25 minutes per ident on a mid-range graphics card.

Games

• OrbitHive recreates Beehive Bedlam's rules. The names are changed and the art is its own, but check this properly before any public release.

Size and upkeep

Paul, 2 November 2026: keep an eye on optimisation, size and cache management.

• Measure each release. App size, and what it holds on the box, in the verification note.
• Idents are the biggest item, at 8 MB. Keep them small, or fetch them after install if the app grows.
• Keep the box tidy. Artwork is capped at 150 files. Check the channel files stay in bounds as pools grow, and remove the unused code and channel backgrounds behind the removed screens.
• Release builds should shrink code and resources, which debug builds don't do.

First run, for the next user

• One screen at a time: sign in, channels ticked from what the library holds, then the main menu.
• Smart schedules on by default. Today a fresh sign-in starts every channel off, and needs 29 presses.
• Numbers in blocks like Sky from the start, so there's never a move to make. The one move we made missed two channels until a test caught it.

OrbitHive blue screen (0.79.3)

Inside the app's WebView on the box, 100vh came out as 0, so the game's canvas had no height while the game ran and played sound behind it. Only the page's blue showed. Canvas sized with position:fixed and 100% instead. Don't use viewport units in pages hosted in the app's WebView. Screenshots stay allowed while OrbitHive is open, because they are what gets a future problem like this checked on the box.

Drive-In tune time

Tickets, reminders and the 20:00 start all worked on the TV. The film took 7.9 s to be ready after tuning. Worth preloading it from the reminder, as the idents do for the next show.