diff --git a/README.md b/README.md index 0ab3c95..c896111 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,8 @@ A native Android TV prototype for review on Paul's Xiaomi TV Box S 3rd Gen. +Roadmap and plans: [docs/roadmap.md](docs/roadmap.md), [programming bible](docs/programming-bible.md), [metadata and matching](docs/metadata-and-matching.md), [asset inventory](docs/asset-inventory.md). + ## Revision 0.6.0 — one scheduled Emby channel Paul confirmed the 0.5.0 strip hides and displays correctly. The next increment adds a diff --git a/design/references/orbit-lineup-concept-sheet.png b/design/references/orbit-lineup-concept-sheet.png new file mode 100644 index 0000000..45b7d55 Binary files /dev/null and b/design/references/orbit-lineup-concept-sheet.png differ diff --git a/docs/asset-inventory.md b/docs/asset-inventory.md new file mode 100644 index 0000000..3f9f847 --- /dev/null +++ b/docs/asset-inventory.md @@ -0,0 +1,43 @@ +# Orbit TV asset inventory + +As of 1 November 2026. + +After Dark is the only channel with production assets, and even it has no in-app playback bug or ident yet. One concept sheet covers 17 channels. The boards for the eight new channels haven't arrived, so only their written direction is available. + +### Concept references + +| Reference | Covers | Status | +| --- | --- | --- | +| Your line-up concept sheet | Vortex, ToonZ, Rewind, Orbit X, Heroes, Wonder, Orbit VHS, Orbit Gold, Orbit Three, Orbit 1, Orbit 2, Orbit Sci-Fi, Orbit Horror, After Dark, Orbit Premiere, Orbit Romance, Orbit Action, plus an Orbit logo and astronaut bee | Saved as `design/references/orbit-lineup-concept-sheet.png`. Reference only. | +| Eight new boards | Ring X, Riot, Dark Files, Terra, Odyssey, PixelZ, Evidence, Paradox | Not received yet. | + +The sheet is visual direction only, with nothing to be embedded in the app. Its After Dark line says "uncut classics", which the app doesn't claim. + +### After Dark: what exists + +| Asset | State | Where | +| --- | --- | --- | +| Primary logo | Designed, not used in the app | `design/channels/orbit-after-dark-v02/exports` | +| Compact guide logo | In the app | `orbit_after_dark_epg.webp` | +| Background with lit windows | In the app | `orbit_after_dark_background.webp` | +| Playback bug | Exported, not in the app | `orbit_after_dark_bug_app.webp` | +| Ident, 1.6 seconds | Motion test, not in the app | `orbit-after-dark-v02` | +| Ident, 4.2 seconds, night windows | Proof, not in the app | `orbit-after-dark-motion-03` | +| Editable sources | Kept | VectorCraft, PhotoCraft and EffectCraft files in those folders | + +The other network assets are the Orbit wordmark, the banner, the drive-in ticket concept and the OrbOffice artwork, whose name is still to change. + +### Still required + +The remaining 24 channels each need the full set below, using After Dark's sizes unless testing shows otherwise. + +| Asset | Tool | Target | +| --- | --- | --- | +| Primary logo | VectorCraft | SVG source, 1600 x 640 transparent export | +| Compact guide logo | VectorCraft | 256 x 80 transparent WebP | +| Playback bug | VectorCraft | About 144 x 48 at 1080p, transparent | +| Static background | PhotoCraft | 1920 x 1080 WebP | +| Animated ident | EffectCraft | Silent H.264 at 720p and 25 fps, about 1 to 1.5 seconds for a first test | +| Palette and type rules | Manifest | Yellow stays reserved for remote focus | + +Make assets only as each channel goes live, to keep APK size down and avoid art for channels nobody has built. Check Riot and Orbit Action against photosensitivity guidance before use, because their idents call for fast cuts or flashes. diff --git a/docs/briefs/creative-direction-brief.md b/docs/briefs/creative-direction-brief.md new file mode 100644 index 0000000..591bc9b --- /dev/null +++ b/docs/briefs/creative-direction-brief.md @@ -0,0 +1,1811 @@ +# ORBIT — Creative Direction, Product Evolution & Incremental Development Brief + +**Project:** Orbit +**Status:** Existing application under active development +**Development environment:** Codex desktop +**Purpose:** Establish the next creative and architectural direction for Orbit without rebuilding or destabilising existing functionality. + +--- + +# 1. Important instructions — Read first + +Orbit is NOT a new application proposal. + +Orbit already exists and has working functionality, including: + +- Emby connectivity. +- Media library discovery and metadata access. +- Generated television channels. +- Clock-driven linear television scheduling. +- A working Toonami channel. +- An existing application interface and development architecture. + +These are existing foundations, not features to recreate. + +**Before proposing or implementing anything:** + +1. Inspect the existing repository and documentation. +2. Understand the application stack, component structure, styling, data models and current UI. +3. Identify how Emby connectivity, metadata discovery, channel generation and playback currently operate. +4. Identify the existing schedule engine and how playback offsets are calculated. +5. Inspect the existing navigation, dashboard, settings and any theme systems. +6. Identify existing tests, build processes and development conventions. +7. Determine which capabilities described below already exist, which can be extended, and which require new modules. +8. Document current functionality before designing changes. + +Do not assume the project needs a new framework, database, frontend architecture or playback engine. + +**Preserve existing working behaviour. Do not replace it simply to accommodate new ideas.** + +This brief represents the intended long-term direction. It does not authorise immediate implementation of every feature. + +All significant changes should be proposed, reviewed and approved before implementation. + +--- + +# 2. Product vision + +## What Orbit is + +Orbit is a modern, personal television experience inspired by the British satellite and cable television era of the 1990s and early 2000s. + +It combines: + +- Traditional linear television schedules. +- Modern media-server integration. +- Automatically generated channels. +- Customisable channel presets. +- Recognisable channel branding. +- Box Office-style movie events. +- Family profiles and parental controls. +- Optional interactive games. +- Future teletext-style information services. + +Orbit is not simply another media-library browsing application. + +It restores the experience of turning on a television and discovering something already playing. + +## Emotional direction + +**"Had enough of today's world. Take me back."** + +Secondary creative direction: + +"All the convenience of today. A little of the magic of yesterday." + +The nostalgic inspiration includes: + +- 1990s and 2000s Sky Digital. +- Cartoon Network. +- Fox Kids. +- Toonami. +- BBC Three. +- Sky Box Office. +- Video rental shops. +- Drive-in cinemas. +- Sky interactive games. +- Ceefax and Teletext. + +These are references for the emotional experience, not brands or creative assets to reproduce directly. + +Orbit must establish its own distinctive identity. + +## Product philosophy + +- User ownership and control. +- No content lock-in. +- No mandatory cloud account. +- No forced recommendations. +- No unnecessary telemetry. +- No unwanted external AI dependency. +- The user's connected media remains under their control. +- Modular capabilities rather than a bloated application. +- A simple television experience first, advanced customisation second. + +**Orbit provides the broadcasting experience. The user provides their authorised media sources.** + +--- + +# 3. Preserve the linear television foundation + +Orbit must retain its existing clock-driven scheduling model. + +Example: + +Dragon Ball Z begins at 09:00. + +The viewer tunes in at 09:12. + +Playback begins approximately twelve minutes into the scheduled episode. + +This is essential to the product identity. + +Do not unintentionally replace this behaviour with conventional playlist playback. + +Investigate how the existing system handles: + +- Schedule creation and persistence. +- Programme duration. +- Channel switching. +- Playback offset calculations. +- Programme boundaries. +- Application restarts. +- Time zones and daylight-saving changes. +- Missing or inaccessible media. +- Schedule continuity. +- Seeking and playback errors. + +Preserve the existing implementation wherever it works correctly. + +Any new channel preset or event feature must integrate with the established scheduling engine. + +--- + +# 4. Orbit visual identity + +## Overall design direction + +Orbit should resemble an alternative history of television: what if the colourful, experimental satellite TV experience of 1999 had continued evolving into modern technology? + +The interface should retain: + +- Warm nostalgia. +- Strong channel personalities. +- Futuristic metallic surfaces. +- CRT and VHS-inspired details. +- Bold colours. +- Recognisable visual identities. +- Playful 90s typography. +- Premium cinema-inspired presentation. +- Modern responsiveness and usability. + +Avoid making the application feel like a generic streaming service. + +Avoid excessive visual noise in functional screens. + +The goal is **retro personality combined with contemporary usability**. + +## Existing UI compatibility assessment + +Before designing or changing components, review the current UI and answer: + +1. Does the existing layout accommodate the proposed branding? +2. Can the current EPG display different channel logos effectively? +3. Can the existing player support optional logo overlays? +4. Can channel transitions be added without interfering with media playback? +5. Can the existing dashboard support featured events and programme highlights? +6. Can the navigation grow without becoming crowded? +7. Are existing fonts, spacing, contrast and components compatible with these designs? +8. Which existing UI elements should be preserved? +9. Which visual changes could be implemented incrementally? + +Do not redesign the application until this compatibility review is complete. + +The supplied channel concept artwork should be treated as visual references, not necessarily final production assets. + +--- + +# 5. Approved channel lineup and programming identities + +These are Orbit's current proposed default presets. + +The channel definitions are creative targets. Actual programme availability must be determined from the connected user's media library. + +## VORTEX — Action Anime + +**Inspiration:** 1990s/2000s Toonami action programming. + +Programming references: + +- Dragon Ball Z. +- Naruto. +- Gundam Wing. +- Yu Yu Hakusho. +- Samurai Jack. +- Batman Beyond. +- The Powerpuff Girls. + +Branding: + +- Brushed chrome typography. +- Metallic blue and silver surfaces. +- Electric purple highlights. +- Space vortices. +- Dynamic angular lettering. +- High-energy futuristic presentation. + +Suggested ident: + +A rotating cosmic vortex forms behind the logo. Metallic letters assemble while blue and purple energy travels around the screen. + +Suggested channel bug: + +Compact chrome V emblem, with subtle blue or purple accents. + +--- + +## TOONZ — Classic Cartoons + +**Identity:** Traditional animated comedy across generations. + +Programming references: + +- Looney Tunes. +- Tom & Jerry. +- The Flintstones. +- The Jetsons. +- Popeye. +- Hanna-Barbera classics. + +Branding: + +- Bright yellow. +- Electric cyan. +- Hot pink. +- Comic-book bursts. +- Graffiti-inspired typography. +- A prominent oversized graffiti **Z**. +- Energetic doodles and cartoon shapes. + +Suggested ident: + +Paint splashes appear across the screen as letters bounce into place, finishing with a dramatic pink graffiti Z. + +Suggested channel bug: + +The distinctive pink Z, or a compact ToonZ wordmark. + +--- + +## REWIND — Cartoon Network Gold / After-School Classics + +Programming references: + +- Dexter's Laboratory. +- Johnny Bravo. +- Scooby-Doo. +- Courage the Cowardly Dog. +- Ed, Edd n Eddy. +- Recess. + +Branding: + +- Warm orange and yellow. +- Retro purple. +- Analogue television imagery. +- VHS tracking effects. +- Rainbow streaks. +- Familiar, comfortable, after-school atmosphere. + +Suggested ident: + +An old CRT television powers on, briefly displays static, and reveals the Rewind logo. + +Suggested channel bug: + +A miniature retro television featuring a rewind emblem. + +--- + +## ORBIT X — 90s Action Cartoons + +**Inspiration:** Fox Kids-era action and adventure. + +Programming references: + +- Digimon. +- Biker Mice from Mars. +- Gargoyles. +- Power Rangers. +- Medabots. +- Transformers. +- He-Man. +- ThunderCats. + +Branding: + +- Metallic silver. +- Aggressive red X. +- Black backgrounds. +- Sharp motion graphics. +- Extreme 90s action styling. + +Suggested ident: + +A red X slices through the screen, revealing the channel logo through sparks and energetic motion. + +Suggested channel bug: + +A strong red X with a small Orbit identifier where appropriate. + +--- + +## HEROES — Superhero Animation + +Programming references: + +- Batman: The Animated Series. +- Superman: The Animated Series. +- Spider-Man (1994). +- X-Men: The Animated Series. +- Batman Beyond. +- Spider-Man Unlimited. + +Branding: + +- Metallic silver. +- Deep red. +- Royal blue. +- Heroic shield imagery. +- City skylines. +- Searchlights. +- Classic comic-book confidence. + +Suggested ident: + +Searchlights move across a night-time skyline before converging to reveal the Heroes emblem. + +Suggested channel bug: + +A simplified shield or H emblem. + +### Programming overlap rule + +Some titles legitimately fit multiple channels. + +For example, Batman Beyond belongs to Heroes but also fits the Vortex programming identity. + +Support channel priorities and permitted crossovers rather than forcing every title into one exclusive category. + +The matching algorithm must avoid accidental excessive repetition while allowing intentional crossover programming. + +--- + +## WONDER — Magical Family Cinema + +**Identity:** Disney-style animated family films and other magical family cinema. + +Programming references: + +- Aladdin. +- The Lion King. +- Beauty and the Beast. +- Toy Story. + +Branding: + +- Midnight blue. +- Lavender clouds. +- Warm gold typography. +- Stars. +- Magical trails. +- Dreamlike cinema atmosphere. + +Suggested ident: + +A trail of stars sweeps through a magical night sky and reveals the Wonder logo. + +Suggested channel bug: + +A golden W with a small star. + +--- + +## ORBIT VHS — Nostalgic Cinema + +Programming references: + +- The Goonies. +- Back to the Future. +- Gremlins. +- The Lost Boys. + +Branding: + +- VHS tape labels. +- Retro rental-shop imagery. +- Rainbow stripes. +- Analogue distortion. +- Chunky 1980s/1990s lettering. + +Suggested ident: + +A VHS cassette enters a player. Tracking lines briefly roll across the screen before the Orbit VHS logo appears. + +Suggested channel bug: + +A simplified VHS cassette or VHS wordmark. + +--- + +## ORBIT GOLD — Classic British Comedy + +Programming references: + +- Only Fools and Horses. +- Father Ted. +- Blackadder. +- Fawlty Towers. + +Branding: + +- Warm gold. +- Dark charcoal. +- Heritage-inspired lettering. +- Familiar and comfortable presentation. + +Suggested ident: + +Gold lettering appears with a subtle sweep of light. + +Suggested channel bug: + +Compact gold wordmark. + +--- + +## ORBIT THREE — Alternative and Scottish Comedy + +**Inspiration:** BBC Three-era alternative comedy and Scottish television favourites. + +Programming references: + +- Still Game. +- Limmy's Show. +- The Mighty Boosh. +- Two Pints of Lager and a Packet of Crisps. +- Gary: Tank Commander. +- Family Guy. + +Branding: + +- Magenta. +- Purple. +- Bold geometric typography. +- Playful asymmetry. +- Alternative youth-channel energy. + +Suggested ident: + +Large geometric shapes and playful lettering animate into the number three. + +Suggested channel bug: + +Stylised number 3. + +--- + +## ORBIT 1 — Flagship Entertainment + +**Identity:** Relaxed, broad-appeal television. + +Programme direction: + +- Family favourites. +- Familiar sitcoms. +- Easy-watching classics. +- General entertainment. +- Comfort television. + +Branding: + +- Orbit blue. +- Silver. +- Soft cyan. +- Simple satellite-inspired design. + +This should feel like the flagship general entertainment channel. + +--- + +## ORBIT 2 — Discovery and Variety + +**Approved direction:** General entertainment with an emphasis on cult television, forgotten favourites and unexpected discoveries. + +Potential programming: + +- Cult TV series. +- Game shows. +- Documentaries. +- Lesser-known sitcoms. +- Forgotten 1990s/2000s television. +- Interesting library discoveries. + +Branding: + +- Metallic silver. +- Purple. +- Dark blue. +- Orbit 1 visual family with a more experimental personality. + +Suggested programming principle: + +**"Something you might never have chosen yourself."** + +Avoid making Orbit 2 simply a duplicate of Orbit 1. + +--- + +# 6. Additional movie channels + +| Channel | Programming | Visual identity | Transition | +|---|---|---|---| +| Orbit Sci-Fi | Science-fiction films and series | Chrome, blue, cyan, planets | Planet orbit and hyperspace | +| Orbit Horror | Slashers, supernatural and creature features | Crimson, black, eerie moonlight | Scratched lettering and dark reveal | +| Orbit After Dark | Adult-oriented late-night films and cult cinema | Purple, magenta, neon skyline | Midnight neon illumination | +| Orbit Premiere | Featured films and premium movie nights | Gold, black, marquee lights | Cinema spotlights and curtain reveal | +| Orbit Romance | Romantic films and feel-good cinema | Pink, rose, sunset gold | Soft glowing cursive reveal | +| Orbit Action | Action, martial arts, thrillers and adventure | Red, orange, steel | Impact flashes and motion streaks | + +Keep genre-specific Horror distinct from the broader late-night programming identity of After Dark. + +--- + +# 7. Channel branding asset system + +Create a reusable specification for channel artwork. + +Each channel should eventually support: + +### Primary logo + +Full-resolution channel identity for menus, promotional artwork and screens. + +### Compact EPG logo + +Simplified logo designed for readability at small dimensions. + +### On-screen channel bug + +Small, transparent branding placed in the bottom-left corner during playback. + +### Animated ident + +Optional transition between scheduled programmes. + +### Programme title card + +Optional visual introducing a programme or themed block. + +### Channel colour palette + +A channel-specific set of colours that can be used consistently throughout Orbit. + +### Asset requirements + +Investigate suitable formats including: + +- SVG for scalable logos where appropriate. +- Transparent PNG or WebP alternatives. +- WebM with transparency where supported. +- Compact video or animation assets for idents. + +Determine actual asset requirements from the current rendering engine and supported playback environments. + +Do not assume every format will work. + +## Important + +The branding system should be driven by reusable configuration, not hardcoded separately into every channel component. + +A custom user-created channel should be able to use the same asset system. + +--- + +# 8. Bottom-left channel logo overlay + +Investigate adding an optional television-style logo overlay during playback. + +Requirements: + +- Bottom-left placement by default. +- User-configurable visibility. +- Suitable opacity. +- Appropriate sizing. +- Safe margins. +- Respect subtitles and accessibility. +- Avoid covering playback controls. +- Minimal performance impact. +- No unnecessary re-rendering. +- Compatible with fullscreen playback where possible. + +Suggested settings: + +- Off. +- Always visible. +- Briefly visible when changing channels. +- Visible when playback begins. + +Consider additional positioning options if needed. + +**Important:** Do not burn the channel logo into the original media. + +The overlay belongs to Orbit's presentation layer. + +The overlay must never interfere with media streaming, seeking or the existing scheduling engine. + +--- + +# 9. EffectCraft animated transitions + +EffectCraft is the intended creative tool for producing optional channel transitions and idents. + +Investigate how rendered EffectCraft assets could fit into the current application. + +Do not introduce EffectCraft as a mandatory runtime dependency. + +Prefer exporting compatible animation assets that Orbit can play independently. + +Possible transition behaviour: + +1. Scheduled programme ends. +2. If enabled and scheduling permits, play the channel ident. +3. Begin the next programme at the correct clock-relative playback position. +4. If the ident is unavailable, continue directly to the programme. + +Do not allow animations to break schedule synchronisation. + +Consider whether idents should occupy explicitly scheduled time or whether short visual effects can be presented during an existing transition without changing the programme start time. + +Provide a recommendation based on the current scheduling architecture. + +Transition settings should include: + +- Enabled/disabled. +- Per-channel settings. +- Reduced-motion support. +- Optional audio. +- Fallback when an asset fails. + +Create one proof-of-concept transition before expanding to the full channel lineup. + +--- + +# 10. Library connectivity and first-run onboarding + +When another user installs Orbit, the application should introduce them to the available connection options. + +Potential providers: + +- Emby. +- Plex. +- Silo, subject to its actual API and capabilities. +- Other compatible servers. +- Custom supported server connections. +- Optional M3U playlists for authorised live television sources. + +Do not assume every proposed provider has the same authentication model or functionality. + +Investigate integrations individually. + +The existing Emby connector is the starting point and should be preserved. + +## Proposed first-run flow + +### Step 1 — Welcome to Orbit + +Introduce the user to the idea of creating a personal television network from their own connected media. + +Offer a simple setup experience. + +### Step 2 — Connect your media + +Display available media providers. + +Allow the user to connect an authorised library. + +Securely handle credentials and tokens. + +Avoid storing unnecessary personal information. + +### Step 3 — Discover your library + +Read available programme metadata and identify suitable content. + +Show: + +- Total recognised shows and films. +- Categories discovered. +- Content availability. +- Any incomplete or unrecognised metadata. + +### Step 4 — Choose your experience + +Offer: + +**Orbit Presets** + +"Let Orbit suggest channels based on your library." + +**Create your own** + +"Build your television channels from scratch." + +Allow users to combine both approaches. + +### Step 5 — Review suggested channels + +Present the available Orbit presets. + +Each preset should show: + +- Channel name and logo. +- Programming identity. +- Matching titles. +- Available episode count where applicable. +- Missing suggested titles. +- Potential alternatives. +- An enable/disable checkbox. + +Do not imply missing titles are available. + +### Step 6 — Customise your lineup + +Allow users to: + +- Remove channels. +- Rename channels. +- Change branding. +- Add or remove programmes. +- Create channels. +- Assign channel numbers. +- Accept suggested alternatives. + +### Step 7 — Create profiles + +Offer profile creation and optional family controls. + +### Step 8 — Enter Orbit + +The user arrives at the main dashboard with their selected channels, events and preferences. + +## Onboarding principles + +- Keep the process simple. +- Support going back and editing choices. +- Allow setup to be revisited in Settings. +- Avoid requiring users to configure everything before watching television. +- Provide helpful defaults. +- Preserve existing configured users when adding onboarding to the application. + +--- + +# 11. Orbit channel recommendation algorithm + +Design a transparent, metadata-driven matching engine. + +Avoid mandatory AI or cloud-based recommendation services. + +The first version should use structured metadata and explainable rules. + +## Inputs + +Potential metadata fields: + +- Title. +- Original title. +- Release year. +- Media type. +- Genres. +- Actors. +- Directors. +- Production studio where available. +- Collections and franchises. +- Series and episode information. +- Content ratings. +- Runtime. +- Provider-specific identifiers. +- Stable external identifiers where legitimately available. +- User preferences and exclusions. + +## Metadata normalisation + +Design an internal provider-independent media representation. + +Emby, Plex and other sources should map their metadata into a common model. + +Do not rely on one provider's internal media IDs as universal identifiers. + +Preserve provider-specific playback references separately. + +## Matching approach + +Use a layered process. + +### Layer 1 — Known programme matching + +Each Orbit preset maintains a curated set of preferred programmes. + +Match exact recognised titles and verified aliases first. + +For example: + +Vortex prefers Dragon Ball Z, Naruto and Gundam Wing. + +Rewind prefers Dexter's Laboratory, Scooby-Doo and Recess. + +### Layer 2 — Similarity matching + +If titles are unavailable, score candidate programmes using: + +- Genre. +- Decade. +- Animation style or programme category where metadata supports it. +- Franchise associations. +- Audience suitability. +- User-selected interests. +- Relevant thematic tags. + +### Layer 3 — Suitability filtering + +Exclude content that: + +- Cannot currently be played. +- Violates profile restrictions. +- Is explicitly excluded by the user. +- Conflicts with channel content rules. +- Has insufficient identification confidence. + +### Layer 4 — Recommendations + +Show the user suggested additions. + +Explain each suggestion, for example: + +"Suggested for Rewind because it is a 1990s animated comedy." + +### Layer 5 — User confirmation + +The user decides what gets added. + +User changes override preset defaults. + +Do not silently add unwanted content after the initial setup. + +## Potential scoring model + +Investigate an initial weighted scoring system: + +- Known title match: highest priority. +- Genre and category relevance. +- Era relevance. +- Audience suitability. +- User preference. +- Series and franchise compatibility. + +Weights should be configurable and testable. + +Do not treat this example as a fixed implementation requirement. + +## Cross-channel behaviour + +Allow content to appear across multiple channels when appropriate. + +However: + +- Prefer the most relevant primary channel. +- Avoid excessive duplication in default presets. +- Allow intentional special programming and crossover events. +- Respect explicit user placement. + +## Explainability + +The application should be able to explain why a title was suggested. + +Keep matching decisions inspectable during development. + +--- + +# 12. OrbitOffice — The personal Box Office + +OrbitOffice is a major part of the long-term experience. + +It is inspired by: + +- Sky Box Office. +- 1980s/1990s video rental shops. +- Classic cinema marquees. +- Drive-in movie theatres. +- Movie marathons. +- Seasonal film programming. + +It should not feel like another generic VOD catalogue. + +**OrbitOffice is about creating an occasion around watching something.** + +## Visual direction + +Imagine a nostalgic drive-in theatre at dusk. + +A line of cars faces a large cinema screen beneath a starry sky. + +Nearby is an illuminated cinema marquee displaying: + +**TONIGHT'S PRESENTATION** + +The scene might show: + +- Classic parked cars. +- A retro cinema sign. +- Warm lights. +- A large outdoor projection screen. +- A ticket-booth motif. +- Film posters. +- A programme board. +- Upcoming movie events. + +The aesthetic should be charming, nostalgic and recognisably Orbit. + +Keep the presentation navigable and efficient rather than requiring users to interact with a complicated 3D environment. + +A visually rich background with practical, accessible event cards may be the better initial implementation. + +## OrbitOffice programming + +Examples: + +**Arnie Triple Bill** + +- Total Recall. +- Terminator 2. +- Twins. + +**Tremors Marathon** + +A sequence of available Tremors films from the user's library. + +**Late Night Spooks** + +A selection of horror and supernatural films. + +**Seasonal Events** + +- Halloween horror. +- Christmas family films. +- Summer blockbusters. +- Winter comfort cinema. + +**Director or Actor Nights** + +Films organised around a director, actor or creative theme. + +## OrbitOffice algorithm + +Use the connected user's library. + +Generate potential events from: + +- Existing collections. +- Recognised franchises. +- Shared actors. +- Shared directors. +- Similar genres. +- Decades. +- Seasonal relevance. +- User preferences. +- Channel identities. + +When an event cannot be completed, suggest alternatives. + +Never invent playable titles. + +Never modify a user's schedule without their approval. + +## Event creation + +Allow users to: + +- Accept a suggested event. +- Reject it. +- Change the movies. +- Reorder the programme. +- Name the event. +- Select a date and time. +- Create their own marathon. +- Hide events from the dashboard. + +## Scheduling + +Consider using the existing clock-driven schedule engine to support event channels or scheduled takeovers. + +Do not duplicate scheduling logic unnecessarily. + +Investigate how an event could temporarily replace regular programming and then return to the existing schedule. + +A scheduled event should have clear start times and remain synchronised. + +## Dashboard integration + +Enabled events should appear on the dashboard. + +Potential displays: + +- Tonight at OrbitOffice. +- Coming this weekend. +- Seasonal specials. +- Recommended for you. +- Upcoming marathons. + +The user controls which recommendations are displayed. + +--- + +# 13. Main dashboard and navigation + +Review the current interface before altering its layout. + +The intended direction is a television-style main menu. + +## Left navigation + +Potential content categories: + +- Entertainment. +- Movies. +- Kids. +- Animation. +- Documentaries. +- Comedy. +- Sports, where supported. +- Other categories based on enabled channels. + +The categories should reflect the user's actual channel lineup. + +Do not show empty categories unnecessarily. + +## Dashboard presentation + +Include an interactive programme-highlight area showing: + +- What's on now. +- What's on next. +- Featured channels. +- Programme artwork. +- Upcoming OrbitOffice events. +- Seasonal recommendations. + +The slideshow should feel like a television promotional carousel, not a crowded streaming-service homepage. + +Keep remote-control and keyboard navigation straightforward. + +## Suggested primary navigation + +- Home. +- TV Guide. +- OrbitOffice. +- Catch Up. +- Games. +- Settings in the top-right. + +Adapt this to the existing navigation structure rather than forcing a replacement. + +## Settings access + +A visible settings control should be available in the top-right area. + +Settings should eventually include: + +- Connected media sources. +- Channel creation and editing. +- Categories. +- Channel ordering. +- Preset management. +- Profile management. +- Parental controls. +- Themes. +- Branding and overlays. +- Transitions. +- Customisation. +- Data import/export. + +--- + +# 14. Catch Up — What you may have missed + +Introduce a future section inspired by classic television catch-up services. + +The experience should remain connected to the user's linear channels. + +Potential sections: + +- Recently aired. +- Missed yesterday. +- Earlier this week. +- Continue watching. +- Popular on your channels. +- Recommended catch-up. + +## Important technical distinction + +Orbit may not be recording television broadcasts. + +Catch Up can initially work by referencing the episodes or films that previously appeared on the user's generated channels. + +Example: + +A programme aired yesterday at 18:00. + +The user missed it. + +If the same media item remains accessible through their authorised provider, Orbit offers direct on-demand playback from the beginning. + +Do not imply Orbit recorded the programme unless a genuine recording capability exists. + +## Visual direction + +Use the look of early digital catch-up television: + +- Clean programme tiles. +- Channel branding. +- Broadcast dates. +- A "Previously on Orbit" presentation. +- Nostalgic but uncluttered navigation. + +Reuse existing media playback where possible. + +--- + +# 15. Profiles and parental controls + +Orbit should eventually support multiple profiles. + +Examples: + +- Adult. +- Child. +- Guest. +- Custom profile. + +## Profile art + +Create optional profile avatars with playful, original 90s-inspired characters. + +Potential themes: + +- Retro television mascot. +- Space explorer. +- Cartoon robot. +- Friendly alien. +- Astronaut bee. +- Arcade-style pixel characters. + +Users should also be able to choose simple icons or customise a profile. + +## Adult profiles + +Support an optional four-digit PIN. + +Investigate secure PIN storage, rate limiting and protections against trivial bypasses. + +A four-digit PIN is a household convenience control, not strong authentication. + +## Child profiles + +Support: + +- Age-appropriate content filtering. +- Restricted channels. +- Restricted media visibility. +- Protected adult profile switching. +- Protected access to settings. +- Preventing direct playback of restricted titles. + +Filtering must apply beyond the dashboard. + +The recommendation engine, search results and playback access should consistently enforce the active profile's rules. + +## Profile preferences + +Profiles may eventually have independent: + +- Channel favourites. +- Recommendations. +- Watch history. +- Dashboard preferences. +- Theme choices. + +Assess the scope of existing application state before designing profile persistence. + +--- + +# 16. Themes and customisation + +Themes are part of Orbit's long-term flexibility. + +Potential included themes: + +**Orbit Classic** + +The primary late-90s/early-2000s television identity. + +**Orbit Modern** + +A clean contemporary presentation using the same underlying functionality. + +**Orbit Retro** + +An intentionally older CRT, analogue or early digital-TV aesthetic. + +## Theme settings + +Potential customisations: + +- Colour palette. +- Typography. +- Background. +- Logo presentation. +- Channel bug position and visibility. +- Transition settings. +- Navigation styling. +- Animation intensity. + +## Custom CSS imports + +Investigate whether optional user-supplied CSS can be supported safely. + +Requirements: + +- Must be opt-in. +- Must not damage the application permanently. +- Must have a reset-to-default option. +- Should support preview before applying. +- Should preserve access to essential controls. +- Must respect the actual application's rendering environment. + +If the app uses an embedded web interface, assess CSS isolation and security boundaries. + +Do not promise support before inspecting the current architecture. + +--- + +# 17. Games — Orbit Arcade + +Orbit may eventually include a small optional games section. + +The games area should feel inspired by early interactive satellite television. + +## First game: OrbitHive Bedlam + +An original space-themed puzzle game inspired by the experience of classic television puzzle games. + +### Visual direction + +- Deep-space background. +- Planets. +- Colourful stars. +- Floating puzzle arena. +- Honeycomb-style arrangements. +- Bright puzzle pieces. +- Friendly bee character wearing an astronaut helmet. +- Orbit visual identity. + +### Skins + +**Classic** + +A restrained nostalgic television-game presentation using original Orbit assets. + +**Retro** + +A polished early-2000s interactive-TV-inspired appearance. + +**Orbit** + +A full cosmic theme with planets, futuristic honeycombs and the astronaut bee. + +The game should use original code, artwork, audio, level design and branding. Inspiration should not require copying original protected assets. + +## Controls + +Prioritise: + +- Remote-control navigation. +- Arrow keys. +- Select/confirm. +- Back. +- Controller support where practical. + +The game should remain simple to understand and play. + +## Modular installation assessment + +Investigate two strategies. + +### Option A — Small bundled game + +Suitable if the game has a small, self-contained footprint and minimal dependencies. + +### Option B — Optional downloadable game module + +Suitable if game engines, graphical assets or other dependencies significantly increase application size. + +Do not choose solely on assumptions. + +Measure: + +- Installed size. +- Memory use. +- Startup cost. +- Packaging complexity. +- Update complexity. +- Security implications. +- Supported platforms. + +Recommend the simplest maintainable approach. + +The Games menu should degrade gracefully if no games are installed. + +--- + +# 18. Future feature — OrbText + +OrbText is a future optional information module inspired by Ceefax and Teletext. + +It is not an immediate development priority. + +## Potential pages + +- 100 — Main Index. +- 101 — News. +- 200 — Entertainment. +- 300 — Sports. +- 302 — Football Scores. +- 400 — Weather. +- 500 — Games. +- 600 — TV Listings. +- 700 — OrbitOffice Events. + +## Visual direction + +- Classic blocky teletext typography. +- Black background. +- Bright primary colours. +- Numbered pages. +- Coloured navigation keys. +- Retro text layout. + +## Potential data sources + +Investigate authorised APIs or feeds for: + +- News. +- Football scores. +- Fixtures. +- League tables. +- Weather. +- Orbit's own schedule. +- Upcoming events. + +Avoid unnecessary network requests. + +Cache information appropriately and respect third-party data licences. + +OrbText should be a separate module and should not complicate the main playback engine. + +--- + +# 19. Media-source and licensing boundaries + +Orbit must not bundle copyrighted television programmes or films as part of its public software distribution without appropriate rights. + +Default channel definitions should describe intended programming and matching rules, not promise particular media is included. + +The user's authorised connected media library determines availability. + +External playlists must be user-supplied or otherwise appropriately authorised. + +Do not include piracy directories, unauthorised streaming endpoints or credentials. + +Do not use third-party channel logos, music or idents as bundled default branding without permission. + +The Orbit channel identities should use original assets. + +Investigate API terms, metadata licences and redistribution constraints before implementing integrations for public distribution. + +--- + +# 20. Technical architecture principles + +The long-term capabilities should remain modular. + +Suggested conceptual boundaries: + +**Media Providers** + +Emby, Plex and future supported sources. + +**Media Catalogue** + +Normalised library metadata and playback references. + +**Preset Engine** + +Curated channel definitions, matching and suggestions. + +**Schedule Engine** + +Existing linear television functionality. + +**Branding Layer** + +Channel artwork, overlays and idents. + +**OrbitOffice** + +Movie events, marathons and recommendations. + +**Profiles** + +User preferences, visibility and parental controls. + +**Catch Up** + +Previously scheduled content discovery. + +**Games** + +Optional interactive entertainment. + +**OrbText** + +Optional information service. + +These are conceptual responsibilities, not instructions to create ten services or rewrite the repository. + +Prefer adapting existing modules and abstractions. + +Avoid unnecessary infrastructure. + +Keep the application lightweight and maintainable. + +--- + +# 21. Incremental development roadmap + +Do not attempt to deliver everything in one implementation. + +Analyse the existing codebase and propose the smallest practical sequence of changes. + +## Phase 0 — Existing application audit + +**Goal:** Establish the current technical baseline. + +Tasks: + +- Inspect architecture. +- Review working Emby connection. +- Review channel discovery. +- Review the schedule engine. +- Review the current interface. +- Review configuration and persistence. +- Review relevant tests. +- Identify implementation gaps. + +Deliverables: + +- Current-state report. +- Architecture summary. +- Existing-feature inventory. +- Risk assessment. +- Proposed incremental roadmap. + +Acceptance: + +The team understands how the existing application works without having modified its behaviour. + +## Phase 1 — Reliable media catalogue and channel presets + +**Goal:** Build upon existing metadata discovery to support the approved Orbit channel definitions. + +Tasks: + +- Audit metadata completeness. +- Normalise relevant fields as needed. +- Define channel preset configuration. +- Implement or extend matching rules. +- Support missing-title suggestions. +- Support user approval and exclusions. +- Preserve existing channels and data. + +Acceptance: + +A connected Emby library can be matched against Orbit presets, showing accurate matches and suggested alternatives without disrupting existing channels. + +## Phase 2 — Channel selection and editing + +**Goal:** Give users control over their generated channels. + +Tasks: + +- Enable/disable presets. +- Add/remove programmes. +- Create a custom channel. +- Rename and reorder channels. +- Persist user changes. +- Support programme overlap where intended. + +Acceptance: + +A user can customise the recommended lineup and retain the changes after restarting the application. + +## Phase 3 — Channel branding foundation + +**Goal:** Introduce channel identities within the existing UI. + +Tasks: + +- Define branding asset configuration. +- Test logo formats. +- Implement compact EPG logos. +- Apply channel colours where suitable. +- Validate readability. +- Assess compatibility with current themes. + +Acceptance: + +Orbit can display distinct channel identities without affecting playback or making navigation harder. + +## Phase 4 — Optional player overlays + +**Goal:** Add the bottom-left channel logo option. + +Tasks: + +- Implement the overlay layer. +- Add visibility settings. +- Test fullscreen and subtitles. +- Test playback performance. +- Test channel switching. + +Acceptance: + +Channel logos can be enabled or disabled without interrupting playback. + +## Phase 5 — Animated idents + +**Goal:** Integrate optional EffectCraft-produced transitions. + +Tasks: + +- Determine compatible exported formats. +- Test one transition. +- Confirm playback timing behaviour. +- Add graceful fallback. +- Add reduced-motion and on/off settings. + +Acceptance: + +One channel can play an optional ident without altering scheduled programme timing unexpectedly. + +## Phase 6 — Dashboard evolution + +**Goal:** Improve the main menu while preserving existing navigation. + +Tasks: + +- Add programme highlights. +- Add channel artwork. +- Add what-is-on-now/next presentation. +- Refine left-side categories. +- Prepare space for featured events. + +Acceptance: + +The dashboard makes it easy to begin watching immediately, while communicating the distinctive Orbit identity. + +## Phase 7 — OrbitOffice foundation + +**Goal:** Introduce themed events using existing media. + +Tasks: + +- Define event configuration. +- Match event titles against connected libraries. +- Suggest alternatives. +- Support user approval. +- Display upcoming events. +- Investigate schedule integration. + +Acceptance: + +A user can create a three-film event from available media and see it displayed without automatic unwanted schedule changes. + +## Phase 8 — Additional media providers and first-run onboarding + +**Goal:** Support a broader audience without destabilising Emby. + +Tasks: + +- Define a minimal provider interface from actual existing requirements. +- Assess Plex and Silo integrations. +- Implement one additional provider at a time. +- Build connection selection. +- Build preset-selection onboarding. +- Support existing installations without forcing reconfiguration. + +Acceptance: + +New users can connect a supported provider and configure recommended channels, while existing users retain their setup. + +## Phase 9 — Profiles and parental controls + +**Goal:** Support household use. + +Tasks: + +- Profile creation. +- Avatars. +- PIN protection. +- Child-safe visibility. +- Playback restrictions. +- Profile-based preferences. + +Acceptance: + +Restricted content cannot be accessed from a child profile through ordinary navigation, search, recommendations or direct playback. + +## Phase 10 — Themes and user customisation + +**Goal:** Allow users to personalise Orbit. + +Tasks: + +- Theme selection. +- Channel appearance preferences. +- Branding options. +- Transition settings. +- Investigate optional custom CSS. +- Import/export of suitable configuration. + +Acceptance: + +Users can customise Orbit while retaining a safe and recoverable default interface. + +## Phase 11 — Catch Up + +**Goal:** Surface recently scheduled content for on-demand playback. + +Tasks: + +- Use scheduling history. +- Link to accessible media. +- Add missed-programme views. +- Preserve channel attribution. + +Acceptance: + +A user can find a recently aired programme and play it on demand when the connected provider still makes it available. + +## Phase 12 — Optional Games + +**Goal:** Add OrbitHive Bedlam without bloating the television application. + +Tasks: + +- Assess game packaging. +- Build a minimal original playable prototype. +- Test remote and controller input. +- Add optional themes. +- Measure resource use. + +Acceptance: + +Games can run independently without negatively affecting the television experience. + +## Phase 13 — OrbText research + +**Goal:** Explore a teletext-inspired information service. + +Tasks: + +- Review possible data providers. +- Investigate rendering. +- Define a minimal page model. +- Assess resource use and licensing. + +Acceptance: + +A small standalone proof of concept demonstrates numbered teletext-style pages using appropriately sourced data. + +--- + +# 22. Important development rules + +Codex should follow these rules throughout the project. + +1. **Do not rebuild functioning systems unnecessarily.** +2. Inspect before modifying. +3. Use existing architectural conventions. +4. Avoid installing heavy dependencies without justification. +5. Prefer incremental changes. +6. Add tests for new logic where appropriate. +7. Never silently migrate or discard user data. +8. Maintain separation between proposals and approved work. +9. Protect media-server credentials. +10. Avoid introducing mandatory cloud services. +11. Ensure optional modules remain optional. +12. Keep settings reversible. +13. Preserve accessibility and remote-control navigation. +14. Prioritise performance on modest hardware. +15. Keep the channel schedule reliable. +16. Maintain current functionality throughout development. +17. Document significant architectural decisions. +18. Obtain approval before destructive changes or broad refactoring. + +--- + +# 23. What I want Codex to do NOW + +**Do not implement this entire brief.** + +Start by inspecting the existing Orbit project. + +Then produce the following: + +### A. Current-state assessment + +Explain what Orbit currently has, including the Emby connection, scheduling engine, channel creation, interface and settings. + +Distinguish verified functionality from assumptions. + +### B. Compatibility assessment + +Explain whether the new branding, channel presets, dashboard, overlays and transition ideas fit the current application architecture and UI. + +Identify what can be achieved through small extensions. + +### C. Channel preset proposal + +Propose how the approved channel lineup could be represented using the existing data structures. + +Include a recommendation for metadata matching and user-controlled alternatives. + +### D. Visual integration proposal + +Explain how channel logos, EPG artwork, optional bottom-left overlays and EffectCraft idents could be integrated with minimal changes. + +Use the supplied visual references as inspiration. + +### E. Incremental roadmap + +Review the suggested phases and adjust them based on actual project dependencies. + +Separate: + +- Existing functionality. +- Immediate priorities. +- Near-term enhancements. +- Future modules. +- Research-only ideas. + +### F. First implementation recommendation + +Recommend **one small, low-risk next step**. + +Include: + +- Why it should come first. +- Files or components likely to be affected. +- Dependencies. +- Risks. +- Acceptance criteria. +- Testing strategy. +- Rollback approach. + +Do not begin implementation until the proposal is reviewed and approved. + +--- + +# Final creative principle + +Orbit should feel like travelling back to a better-loved era of television without losing the freedom modern technology provides. + +It should combine the magic of old broadcasting with the convenience of modern media libraries. + +**The original television experience is the foundation. Everything else builds around it.** + +The goal is not an endless catalogue of thumbnails. + +The goal is switching on the television, finding something interesting already playing, and feeling like you've travelled back to 1999. + +**Orbit — All the convenience of today. A little of the magic of yesterday.** \ No newline at end of file diff --git a/docs/briefs/roadmap-update-2026-11-01.md b/docs/briefs/roadmap-update-2026-11-01.md new file mode 100644 index 0000000..8695565 --- /dev/null +++ b/docs/briefs/roadmap-update-2026-11-01.md @@ -0,0 +1,1014 @@ +# ORBIT — Roadmap Update: Channel Expansion, Personalisation & Programming Intelligence + +## Purpose + +Update the existing Orbit project roadmap with the latest approved creative and programming decisions. + +**Orbit is an existing, functioning application. This is a roadmap update, not a request to rebuild the project or immediately implement all proposed features.** + +Current known functionality includes: + +- Working Emby connectivity. +- Media discovery and channel generation. +- Clock-driven linear TV scheduling. +- Existing channel playback. +- Working Toonami channel. +- Orbit After Dark branding and animated ident proof of concept. +- Existing Orbit Classic interface and TV guide. + +Inspect the repository and current roadmap to verify the exact implementation status before making changes. + +Preserve all working functionality. + +Do not replace the existing architecture, rebuild the interface or introduce unnecessary dependencies. + +--- + +# 1. Update the Channel Programming Bible + +Add the following channel identities and programming intentions to the existing roadmap. + +These are **Orbit preset definitions**, not bundled content. + +All programmes must be matched against the user's connected and authorised media libraries. + +Users may accept, remove, edit, rename or completely replace the suggested channels. + +## Existing and approved channel lineup + +| Channel | Programming identity | Example content | +|---|---|---| +| Orbit 1 | Family favourites and relaxed general entertainment | Sitcoms, comfort television, familiar classics | +| Orbit 2 | Discovery, cult television and forgotten favourites | Game shows, documentaries, cult TV and unexpected discoveries | +| Orbit Three | Alternative comedy, BBC Three-era favourites and Scottish comedy | Still Game, Limmy's Show, Mighty Boosh, Two Pints, Gary: Tank Commander, Family Guy | +| Orbit Gold | Classic British comedy | Only Fools and Horses, Father Ted, Blackadder, Fawlty Towers | +| Vortex | Action anime and Toonami-style programming | DBZ, Naruto, Gundam Wing, Yu Yu Hakusho, Samurai Jack | +| ToonZ | Traditional cartoons across generations | Looney Tunes, Tom & Jerry, The Flintstones, The Jetsons, Popeye | +| Rewind | 90s and 2000s after-school animation | Dexter's Laboratory, Johnny Bravo, Scooby-Doo, Courage, Ed, Edd n Eddy, Recess | +| Orbit X | 80s/90s action cartoons and Fox Kids-era favourites | Digimon, Gargoyles, Transformers, Power Rangers, He-Man, ThunderCats | +| Heroes | Superhero animation | Batman TAS, Superman TAS, Spider-Man 1994, X-Men, Batman Beyond, Spider-Man Unlimited | +| Wonder | Traditional animated family cinema and fairy tales | Aladdin, The Lion King, Beauty and the Beast | +| PixelZ | CGI animated family films | Toy Story, Monsters, Inc., A Bug's Life, Shrek, The Incredibles | +| Orbit VHS | Nostalgic 80s/90s films | Back to the Future, The Goonies, Gremlins, The Lost Boys | +| Orbit Sci-Fi | Science-fiction films and television | Space, time travel, futuristic adventures | +| Orbit Horror | Horror cinema | Slashers, supernatural horror, creature features | +| Orbit After Dark | Late-night cult cinema and mature programming | Horror, cult films, midnight movie selections | +| Orbit Action | Action and adventure films | Thrillers, martial arts, blockbusters | +| Orbit Romance | Romance and feel-good cinema | Romantic comedy, romance films | +| Orbit Premiere | Featured films and special presentations | Premium movie nights and featured selections | +| Dark Files | True crime, investigations, mysteries and paranormal nonfiction | Cold cases, forensic documentaries, unexplained phenomena | +| Terra | Natural history and wildlife documentaries | Blue Planet, Planet Earth, Frozen Planet | +| Odyssey | General documentary exploration | Science, history, engineering, geography, astronomy | +| Evidence | Scripted crime and procedural drama | CSI, NCIS and similar investigative drama | +| Paradox | Cult sci-fi, supernatural and mystery television | The X-Files, Buffy, Supernatural, Fringe, modern Doctor Who | +| Ring X | Wrestling television and events | WWF/WWE, WCW, ECW, TNA, AEW, classic PPVs | +| Riot | Adult animation, sitcoms and alternative comedy | It's Always Sunny in Philadelphia, South Park, The Simpsons, Trailer Park Boys, Friends, How I Met Your Mother | + +Preserve existing channel numbers and IDs. Do not renumber channels based on this table. + +Where an existing channel already has configured content, preserve it. + +The examples above are references for matching and curation, not hardcoded requirements that every user must possess. + +--- + +# 2. Specific programming rules for new channels + +## Ring X — Wrestling Network + +Ring X should support deliberate weekly programming instead of treating wrestling as a random collection. + +Suggested weekly programming: + +**Monday — Monday Night Wars** + +- WWF/WWE Attitude Era. +- WCW Monday Nitro. +- Classic rivalry-era programming. +- Chronological matching where episode metadata supports it. + +**Tuesday — Impact Night** + +- Classic TNA. +- Impact Wrestling. +- AJ Styles, Samoa Joe, Kurt Angle-era programming where available. + +**Wednesday — AEW** + +- AEW television programming. +- Relevant specials. + +**Thursday to Sunday — Wrestling Vault** + +- Classic PPVs. +- ECW. +- Older wrestling episodes. +- Historic matches. +- Themed wrestler or promotion marathons. + +These are default suggestions, not enforced schedules. + +Important: recognise promotion, episode date, event date, chronological order, show type and PPV status where metadata permits. + +Do not automatically claim a chronological episode match when metadata is insufficient. + +The user may change or disable the entire weekly structure. + +### Ring X visual identity + +Use the accompanying concept board. + +Creative direction: + +- Metallic chrome. +- Aggressive red X. +- Dark arena atmosphere. +- Steel trusses. +- Spotlights. +- High-energy 1990s wrestling broadcast aesthetic. + +Suggested EffectCraft ident: + +Arena lights illuminate, metallic lettering forms and an enormous red X completes the logo. + +Avoid rapid flashing that violates photosensitive-safety guidance. + +--- + +## Riot — Comedy & Chaos + +Riot is a personalised comedy channel with the energy of 1990s/2000s alternative youth television. + +It combines: + +- Adult animation. +- Irreverent sitcoms. +- Cult comedy. +- Familiar comfort comedy. +- Selected mainstream sitcoms. + +Example programming: + +- South Park. +- The Simpsons. +- It's Always Sunny in Philadelphia. +- Trailer Park Boys. +- Friends. +- How I Met Your Mother. + +Distinguish Riot from Orbit Three: + +**Orbit Three** focuses on British/Scottish alternative comedy and the early BBC Three feel. + +**Riot** focuses on broader alternative comedy, adult animation, North American sitcoms and irreverent programming. + +Allow overlap where users want it. + +### Riot visual identity + +Use the attached design concept. + +- Electric lime. +- Hot pink. +- Cyan. +- Purple. +- Torn-paper collage. +- Graffiti-like lettering. +- CRT television graphics. +- Bold, chaotic 90s youth-TV styling. + +Suggested EffectCraft ident: + +Static appears on a retro television, colourful graphic shapes burst onto the screen and the Riot logo assembles through a fast collage-style reveal. + +--- + +## Dark Files — Crime, Mystery & Paranormal + +Dark Files should include: + +- True-crime documentaries. +- Cold cases. +- Forensic investigations. +- Missing-person investigations. +- Historical mysteries. +- Unexplained phenomena. +- Paranormal documentaries and investigations. + +Create a suggested time-of-day programming personality. + +**Daytime:** Crime documentaries and investigations. + +**Early evening:** Unsolved mysteries and unusual historical cases. + +**Mid-evening to late night:** Paranormal investigations, unexplained phenomena and darker documentary programming. + +This timing is a suggested preset, not a mandatory restriction. + +Keep Dark Files distinct from Evidence and Paradox: + +- **Dark Files:** Mainly nonfiction investigations, true crime and paranormal documentaries. +- **Evidence:** Scripted crime procedural drama. +- **Paradox:** Fictional supernatural, mystery and science-fiction series. + +If metadata cannot confidently distinguish documentary from scripted fiction, do not silently classify it. + +### Dark Files visual identity + +- Midnight navy. +- Steel grey. +- Evidence red. +- Case folders. +- Investigative photography. +- Desk lamps. +- Mystery and suspense. + +Suggested ident: + +An evidence folder opens under a desk lamp. Photographs and case details briefly appear before the Dark Files logo is revealed. + +--- + +## Evidence — Scripted Crime & Procedural Drama + +Programming includes: + +- CSI franchise. +- NCIS franchise. +- Similar police procedurals. +- Forensic dramas. +- Investigation-focused scripted series. + +Matching should consider: + +- Scripted crime genre. +- Police procedural classification. +- Forensic themes. +- Series relationships. +- Franchise identifiers. +- Release era. + +Do not automatically treat real-world crime documentaries as Evidence content. + +### Evidence visual identity + +Use the supplied board featuring: + +- Deep navy. +- Steel blue. +- Forensic cyan. +- Evidence yellow. +- Fingerprint imagery. +- Laboratory textures. +- Crime-scene investigation motifs. + +Suggested EffectCraft ident: + +A cyan forensic scanning beam passes over a fingerprint, reveals its pattern and transitions into the Evidence logo. + +--- + +## Paradox — Cult Supernatural & Mystery Television + +Programming examples: + +- The X-Files. +- Buffy the Vampire Slayer. +- Supernatural. +- Fringe. +- Modern Doctor Who. +- Similar cult mystery and supernatural shows. + +This channel should feel like staying awake late at night watching mysterious television. + +Channel matching should favour: + +- Supernatural fiction. +- Cult science fiction. +- Mystery drama. +- Paranormal fiction. +- Time travel. +- Alternate realities. +- Monster-of-the-week storytelling. + +Distinguish Paradox from: + +- **Orbit Sci-Fi:** Broader science-fiction films and series. +- **Dark Files:** Primarily documentary and nonfiction mysteries. +- **Orbit Horror:** Horror films. + +### Paradox visual identity + +Use the attached design board. + +- Deep indigo. +- Purple. +- Magenta. +- Teal. +- VHS distortion. +- Strange radio signals. +- Dimensional portals. +- Retro-futuristic mystery. + +Suggested EffectCraft ident: + +A distorted television signal reveals a glowing dimensional ring. The Paradox wordmark resolves through subtle VHS interference. + +--- + +## PixelZ — CGI Family Animation + +Focus on digitally animated family films. + +Primary programming inspiration: + +- Pixar-style CGI animation. +- DreamWorks animated movies. +- Other family-friendly CGI cinema. + +Maintain separation from Wonder. + +**Wonder:** Traditional storybook animation and magical Disney-style classics. + +**PixelZ:** Computer-animated film adventures. + +Recognise that studios and styles can overlap. The user should be able to reassign any film. + +### PixelZ visual identity + +- Electric cyan. +- Lime green. +- Bright purple. +- Rounded 3D-inspired lettering. +- Floating geometric cubes. +- Digital pixels. +- Early computer-animation energy. + +Suggested EffectCraft ident: + +Bright cubes and pixels assemble into the PixelZ logo, ending with an oversized lime-green Z bouncing into place. + +--- + +## Terra — Nature & Wildlife + +Prioritise: + +- Wildlife. +- Oceans. +- Forests. +- Natural environments. +- Ecology. +- Natural history. +- Planet Earth-style documentaries. + +Visual identity: + +- Ocean blue. +- Forest green. +- Turquoise. +- Earth imagery. +- Natural landscapes. +- Organic orbital motion. + +Suggested ident: + +A camera rises from the ocean, reveals a sweeping landscape and transitions into a view of Earth as the Terra logo appears. + +--- + +## Odyssey — Science, History & Exploration + +Prioritise: + +- Science. +- Astronomy. +- Space exploration. +- Engineering. +- Human history. +- Travel. +- Geography. +- Major discoveries. +- Historical documentaries. + +Use Odyssey as the home of documentary curiosity and discovery. + +Visual identity: + +- Expedition blue. +- Atlantic teal. +- Silver. +- Gold. +- Maps. +- Distant horizons. +- Exploration and discovery. + +Suggested ident: + +A glowing orbital line traces a path over Earth before transitioning between landscapes, maps and a starfield to reveal Odyssey. + +--- + +# 3. The Orbit Personalisation Algorithm + +## Core philosophy + +**Orbit should reduce the number of decisions needed to enjoy media, not simply create more recommendations.** + +It must not become another endless streaming catalogue. + +The purpose of the algorithm is to gently help users create television experiences around their tastes and existing libraries. + +Orbit should behave like a thoughtful television programmer. + +It can make suggestions, but the user always has the final decision. + +## Fundamental principles + +1. User preferences override algorithmic recommendations. +2. Never add unwanted channels or programmes automatically after setup without permission. +3. Use the user's connected library as the source of playable content. +4. Explain recommendations in simple language. +5. Avoid excessive recommendations. +6. Support occasional discovery and surprises. +7. Respect content ratings and household profiles. +8. Keep recommendations independent of mandatory AI services. +9. Avoid commercial engagement-maximisation objectives. +10. Allow users to disable personalisation or clear locally stored preference history. + +--- + +# 4. Content metadata and tagging strategy + +The first technical priority is improving the classification and metadata foundation. + +Inspect existing metadata structures before designing new ones. + +## Suggested metadata fields + +- Media title. +- Original title. +- Release year. +- Release decade. +- Media type. +- Genre. +- Subgenre. +- Description. +- Series/franchise. +- Studio or production company. +- Cast. +- Director. +- Content rating. +- Runtime. +- Season and episode. +- Original air date. +- Documentary versus scripted classification. +- Animation style where reliably known. +- Country or region. +- Connected provider. +- Provider playback reference. +- Stable metadata identifiers where available. + +## Add Orbit-specific classification concepts + +Investigate a flexible tagging layer separate from provider metadata. + +For example: + +**The X-Files** + +- Scripted series. +- Science fiction. +- Supernatural mystery. +- Cult television. +- 1990s. +- Primary preset: Paradox. +- Possible crossover: Orbit Sci-Fi. + +**CSI** + +- Scripted series. +- Crime. +- Police procedural. +- Forensic investigation. +- Primary preset: Evidence. + +**Blue Planet** + +- Documentary. +- Wildlife. +- Ocean. +- Natural history. +- Primary preset: Terra. +- Possible crossover: Odyssey. + +**The Burbs** + +- Film. +- Horror comedy. +- Cult cinema. +- 1980s. +- Primary preset: Orbit VHS. +- Possible crossover: Orbit After Dark. + +**Dragon Ball Z** + +- Animated series. +- Action anime. +- Fantasy. +- Primary preset: Vortex. + +These classifications should be suggestions unless explicitly confirmed by a user. + +Do not permanently modify provider metadata unnecessarily. + +Keep Orbit-specific tags separately where appropriate. + +--- + +# 5. Recommendation and classification pipeline + +Investigate implementing the following pipeline using existing application architecture. + +## Stage A — Library discovery + +Read the connected provider's available content. + +Determine what is playable by the current user. + +Do not confuse a catalogue entry with guaranteed playback availability. + +## Stage B — Metadata normalisation + +Map available provider metadata into a common internal representation. + +Preserve source references and identifiers. + +Avoid duplicate records where possible. + +## Stage C — Content identification + +Prioritise reliable identifiers and verified title matching. + +Handle: + +- Alternate titles. +- Remakes. +- Series with similar names. +- Different release years. +- Franchise collections. +- Incomplete metadata. +- Duplicate library entries. + +Do not confidently classify uncertain matches. + +## Stage D — Orbit tag enrichment + +Apply additional channel-oriented metadata. + +Sources may include: + +- Existing provider genres. +- Curated title rules. +- Release era. +- Known series/franchise relationships. +- Cast and director information. +- User-approved tags. +- Optional licensed metadata integrations. + +Distinguish reliable metadata from inferred classifications. + +## Stage E — Preset matching + +Calculate channel suitability using explainable rules. + +Illustrative scoring priorities: + +| Signal | Relative importance | +|---|---| +| Verified curated title match | Very high | +| User explicitly selected title | Highest | +| Strong subgenre or format match | High | +| Audience suitability | Required filter | +| Channel era preference | Medium | +| Genre similarity | Medium | +| Cast/studio/franchise association | Context dependent | +| User preference | Medium to high | +| Weak keyword similarity | Low | + +The exact weights should be proposed after inspecting the existing dataset and matching logic. + +Do not hardcode arbitrary scoring weights without testing. + +## Stage F — Review suggestions + +Show only a small selection of meaningful suggestions. + +Example: + +**Paradox — 8 matching series found** + +"These programmes match your interest in cult science fiction and supernatural mysteries." + +Allow: + +- Add. +- Remove. +- Replace. +- Ignore. +- View why recommended. + +Avoid presenting fifty recommendations at once. + +## Stage G — Schedule generation + +Feed confirmed channel content into the existing linear scheduling engine. + +Do not replace the scheduling engine. + +Respect: + +- Programme duration. +- Episode order preferences. +- Time-of-day programming rules. +- Profile restrictions. +- Existing user schedules. +- Content availability. + +## Stage H — Repeat management + +Avoid repetitive schedules where possible. + +Investigate: + +- Recently played history. +- Episode progression. +- Configurable repeat cooldowns. +- Minimum variety. +- Series rotation. +- Film rotation. +- Intentional repeats. + +These rules should adapt to library size. + +A channel containing only three films cannot obey the same repeat rules as one containing hundreds. + +Do not create empty schedules simply to satisfy repeat limits. + +--- + +# 6. Gentle Personalisation + +Orbit should learn only from information the user chooses to provide or enables. + +Possible signals: + +- Selected favourite genres. +- Favourite decades. +- Preferred channels. +- Manually accepted recommendations. +- Rejected recommendations. +- Selected event themes. +- Optional local watch history. +- Explicit exclusions. + +Avoid building a highly invasive behavioural profile. + +## Recommendation presentation + +Prefer a small number of useful suggestions. + +Examples: + +"Your library has enough classic action cartoons to create Orbit X." + +"You have seven supernatural series that could fit Paradox." + +"Fancy a 90s action movie night on Friday?" + +"We found three available films featuring Arnold Schwarzenegger." + +"Your Terra channel could include two additional wildlife documentaries." + +Each suggestion should have a clear reason and easy dismissal. + +Dismissed suggestions should not continually reappear without cause. + +## Discovery and surprise + +Support gentle discovery. + +Examples: + +- A lesser-known film from a favourite decade. +- A forgotten animated series. +- A documentary fitting a selected interest. +- A cult comedy that matches Riot. + +Surprises should remain relevant and playable. + +Allow the user to control how adventurous recommendations become. + +Possible future preference: + +- Familiar favourites. +- Balanced discovery. +- Surprise me. + +Do not turn this into an engagement-maximisation mechanism. + +--- + +# 7. Personalised OrbitOffice Events + +Apply the same matching and preference principles to OrbitOffice. + +OrbitOffice should feel like Sky Box Office, Blockbuster and a classic drive-in cinema. + +It should suggest special viewing experiences rather than endless movie lists. + +Examples: + +**Arnie Triple Bill** + +- Total Recall. +- Terminator 2. +- Twins. + +**Monster Movie Marathon** + +Choose available monster or creature-feature films. + +**Saturday Family Cinema** + +Choose suitable films from the household's library and preferences. + +**Late Night Spooks** + +Select suitable horror, supernatural or mystery films. + +**Wrestling PPV Night** + +Suggest an available wrestling event for Ring X. + +**Seasonal Events** + +Suggest relevant films for Halloween, Christmas or other occasions. + +## Event rules + +- Only suggest accessible content. +- Identify missing titles honestly. +- Offer alternatives where possible. +- Do not automatically schedule events. +- Allow user edits. +- Avoid overwhelming the dashboard. +- Respect parental restrictions. +- Support event dismissal. +- Keep events optional. + +Allow users to turn OrbitOffice suggestions off entirely. + +--- + +# 8. User Control and Preset Customisation + +When a user connects their media library, Orbit should offer the approved channel presets based on the content actually discovered. + +For each preset show: + +- Branding. +- Programming description. +- Number of matching titles. +- Suggested additions. +- Unavailable reference titles. +- Suitability indicators. +- Enable/disable control. + +The user can: + +- Accept a preset. +- Reject a preset. +- Edit its content. +- Change its name. +- Choose different branding. +- Create a custom channel. +- Build a channel entirely from scratch. + +Never force the default Orbit channel structure on another user. + +Presets should be portable configurations rather than permanent hardcoded channel definitions. + +Support future preset import/export if appropriate. + +--- + +# 9. Channel Artwork and Design References + +I will attach the approved channel branding mockups alongside this brief. + +These include the newly designed: + +- Ring X. +- Riot. +- Dark Files. +- Terra. +- Odyssey. +- PixelZ. +- Evidence. +- Paradox. + +Use these as visual direction references. + +**Do not treat generated concept images as final production artwork.** + +Review the existing Orbit design system first. + +Investigate producing original assets using: + +- **FigCraft:** Mockups, layouts and visual design exploration. +- **PhotoCraft:** Artwork, textures, backgrounds and compositions. +- **VectorCraft:** Logos, icons, scalable graphics and playback bugs. +- **EffectCraft:** Channel idents, transitions and animated assets. + +Each channel should eventually support: + +- Primary logo. +- Compact EPG logo. +- Transparent playback bug for the optional bottom-left overlay. +- Static ident background. +- Animated ident. +- Colour palette. +- Typography rules. +- Lightweight optimised exports. + +Preserve Orbit's shared visual identity while allowing each channel its own personality. + +Continue using Orbit After Dark as the reference for a complete channel branding workflow. + +Its existing animated ident and integration should be inspected, not rebuilt unnecessarily. + +--- + +# 10. Roadmap Priorities + +The additional channels and artwork should not distract from the core development priorities. + +Recommend organising the work into the following sequence, adjusting it to the actual state of the repository. + +### Priority 1 — Catalogue and metadata reliability + +- Larger Emby library import. +- Better metadata normalisation. +- Duplicate handling. +- Classification. +- Genre and subgenre mapping. +- Reliable available-media identification. + +### Priority 2 — Preset matching + +- Curated channel definitions. +- Matching rules. +- Explainable suggestions. +- User overrides. +- Channel suitability scoring. + +### Priority 3 — Schedule quality + +- Better programme rotation. +- Episode order. +- Repeat cooldowns. +- Time-of-day programming. +- Cross-channel duplication controls. +- Reliable clock-driven playback. + +### Priority 4 — Branding integration + +- Register new channel identities. +- Add branding references. +- Reuse existing EPG, overlay and ident patterns. +- Create new original channel assets incrementally. + +### Priority 5 — User-facing recommendations + +- Gentle channel suggestions. +- Small recommended content lists. +- Explanations. +- Dismissal and preference controls. + +### Priority 6 — OrbitOffice recommendations + +- Themed events. +- Marathons. +- Seasonal programming. +- Actor and franchise collections. +- Optional scheduled specials. + +### Later priorities + +- Multi-provider onboarding. +- Plex/Silo/custom source adapters. +- Authorised IPTV and external EPG integration. +- Household profiles and PIN controls. +- Additional themes and customisation. +- Catch Up. +- OrbitHive Bedlam and optional games. +- OrbText. +- Optional self-hosting and public distribution. + +Do not interpret these priorities as instructions to complete everything immediately. + +--- + +# 11. Specific Instructions to Codex + +**For this task, update the roadmap and supporting documentation only.** + +Before making changes: + +1. Read the existing roadmap and relevant project documentation. +2. Identify the canonical location of the programming bible, design references and feature roadmap. +3. Compare the existing roadmap with this amendment. +4. Preserve previous approved decisions and implementation history. +5. Identify potential conflicts or duplicated channel definitions. +6. Preserve existing channel numbering. +7. Treat attached artwork as visual references. +8. Do not overwrite existing branding assets. +9. Do not alter the active Emby integration or scheduling engine. + +Prepare a proposed documentation update. + +Separate: + +- **Implemented:** Verified working features. +- **Approved direction:** Decisions made for the product. +- **Proposed:** Ideas needing technical review. +- **Future:** Longer-term concepts. +- **Blocked or uncertain:** Features requiring external dependencies, licences or further research. + +Do not describe proposed features as already implemented. + +Do not silently convert suggestions into mandatory functionality. + +## Requested deliverables + +### A. Updated programming bible + +All approved channels, identities, programming intentions and suggested time-of-day rules. + +### B. Metadata and tagging strategy + +A proposal grounded in the application's existing catalogue structure. + +### C. Recommendation-engine design + +An explainable, user-controlled approach to preset matching, personalisation and discovery. + +### D. Updated asset inventory + +List the attached concept artwork and identify production assets still required. + +### E. Roadmap changes + +Show the proposed additions and their dependencies without discarding existing milestones. + +### F. Next development step + +Recommend one small, testable improvement that supports the metadata and preset system. + +Include: + +- Scope. +- Files likely to be involved. +- Risks. +- Acceptance criteria. +- Tests. +- Rollback plan. + +## Approval boundary + +Do not begin implementation, install dependencies, migrate data or modify the application based on this brief alone. + +Present the proposed roadmap/documentation changes for review first. + +--- + +# Final Principle + +**Orbit is not trying to make people browse more content. It is trying to make enjoying content effortless again.** + +Let the user connect their library. + +Understand their tastes through transparent, optional preferences. + +Suggest relevant channels. + +Programme television intelligently. + +Create opportunities for discovery. + +Make movie nights feel like occasions. + +And always leave the final decision with the viewer. + +**Orbit should feel like television made for you, not an algorithm trying to keep you watching forever.** diff --git a/docs/metadata-and-matching.md b/docs/metadata-and-matching.md new file mode 100644 index 0000000..249ee23 --- /dev/null +++ b/docs/metadata-and-matching.md @@ -0,0 +1,98 @@ +# Orbit TV metadata and matching + +Approved direction, 1 November 2026. This is a design: none of it is built yet except the coverage check described in [the roadmap](roadmap.md). + +## Metadata and tagging strategy + +Orbit keeps only a thin record per title today, so the plan is to widen it and keep Orbit's own tags in a separate layer. The Emby data itself is never edited. + +### What the code keeps now + +| Record | Fields held | Used for | +| --- | --- | --- | +| `SampleItem` | ID, title, type, minutes, format, duration | Everything scheduled | +| `AfterDarkMovie` | Item, year, rating, up to 8 genres | Film review for 102 | +| `SeriesCandidate` | ID, title, year, rating, variant label | Series review for 103 | +| `EpisodeCandidate` | ID, title, season, episode, duration, media label | Episode order | +| `ScheduledMedia` | Item, locked source ID, locked duration | The timeline | + +### What to add + +| Need | Field | Status | +| --- | --- | --- | +| Better identification | Original title, stable external IDs, collections | Not requested today | +| Classification | Genres on all types, tags, studios, overview | Genres on films only | +| Era and order | Year, original air date, season, episode | Partly held | +| Suitability | Content rating | Held on films and series, not used for any filtering | +| Curation | Cast, director | Not requested today | + +Emby's documentation has to confirm each field's request name, and the coverage check in the roadmap shows how often the provider fills them. + +### Orbit's own tag layer + +Each tag records its value, where it came from and how sure Orbit is. Sources rank in this order: user-confirmed, curated title rule, provider metadata, then inferred. Only user-confirmed tags count as settled, and an unknown value stays unknown. + +| Example | Format and genre tags | Primary preset | Possible crossover | +| --- | --- | --- | --- | +| The X-Files | Scripted, science fiction, supernatural mystery, cult, 1990s | Paradox | Orbit Sci-Fi | +| CSI | Scripted, crime, procedural, forensic | Evidence | None | +| Blue Planet | Documentary, wildlife, ocean, natural history | Terra | Odyssey | +| The 'Burbs | Film, horror comedy, cult, 1980s | Orbit VHS | After Dark | +| Dragon Ball Z | Animated series, action anime, fantasy | Vortex | None | + +Documentary versus scripted, and traditional versus CGI, need explicit values including "unknown". Ring X adds promotion, show type, event date and PPV status. + +### Three limits in today's code + +- **Saved data cap:** saved setup is capped at 512 KiB in one encrypted file, too small for a real library. The catalogue needs its own encrypted local store, chosen after the audit gives real record sizes. +- **Hardcoded channels:** saved state has fixed slots for `one`, `toonami` and `afterDark`, and only accepts 101 to 103. Adding channel 26 needs a generic channel list with a tested migration. +- **Listed isn't playable:** a catalogue entry only proves a title is listed. Keep separate states for listed, source checked and failed, and recheck when tuning, as Orbit does now. + +## Recommendation engine design + +The engine should behave like a TV programmer who proposes and waits: it suggests from rules it can explain, and nothing reaches a channel until the viewer accepts it. It runs on the box, with no AI or cloud service. + +### Pipeline + +Each stage builds on what Orbit has, and the existing clock schedule stays as the last step. + +| Stage | What happens | What it reuses or needs | +| --- | --- | --- | +| A. Discovery | Paged read of what this account can see | `EmbyClient`, with new paging and rate-limit handling | +| B. Normalise | Map provider data to one internal record, keeping provider IDs separate | Existing validation and text limits | +| C. Identify | Match by stable ID first, then title and year. Handle remakes, alternate titles and duplicates. | `labelSeriesVariants` already flags duplicate entries | +| D. Tag | Add Orbit tags with source and confidence | New, from the tag layer above | +| E. Match | Rank titles against each preset | New | +| F. Review | Show a short list with ticks and reasons | Existing review screens as the pattern | +| G. Schedule | Feed confirmed titles to the clock engine | `SampleChannel`, with new limits | +| H. Repeats | Rotation and cooldowns scaled to library size | New | + +### How matching decides + +Titles are ranked in tiers, because exact weights shouldn't be picked before the audit shows real data. + +1. **User decisions:** explicit picks and exclusions always win. +2. **Hard filters:** rating, playability and low-confidence identity can remove a title, whatever else matches. +3. **Curated title match:** the preset's own list and verified aliases. +4. **Strong signals:** format or subgenre, such as documentary or police procedural. +5. **Medium signals:** genre, era and stated preference. +6. **Context signals:** cast, studio or franchise, where they make sense for that preset. +7. **Weak signals:** keyword similarity can add a candidate but never justify one alone. + +Every suggestion stores the reasons behind it, so "why recommended" reads directly from them. A three-film channel can't follow the repeat rules of a large one, and Orbit shouldn't create empty schedules to satisfy a rule. + +### What the viewer sees + +A suggestion is short and gives its reason: "Paradox: 8 matching series found. These match your interest in cult science fiction and supernatural mysteries." + +- **Controls:** add, remove, replace, ignore and view why. +- **Missing titles:** shown unticked and marked unavailable, never implied as playable. +- **Dismissals:** remembered, so a dismissed idea doesn't keep returning without a new reason. +- **Discovery:** familiar favourites, balanced discovery or surprise me. This is a possible later preference. +- **Remote use:** a few items per screen, since the viewer is using a D-pad from the sofa. + +### Privacy and control + +Orbit learns only from what the viewer chooses or enables: favourite genres and decades, accepted and rejected suggestions, explicit exclusions, and optional local watch history. Personalisation can be turned off, its history cleared, and it never adds channels or titles by itself after setup. There are no engagement goals. + +OrbitOffice uses the same matching for events such as an Arnie Triple Bill or a Wrestling PPV Night. Events are optional, never scheduled automatically, name missing films honestly and can be switched off entirely. diff --git a/docs/programming-bible.md b/docs/programming-bible.md new file mode 100644 index 0000000..07dea37 --- /dev/null +++ b/docs/programming-bible.md @@ -0,0 +1,81 @@ +# Orbit TV programming bible + +Approved by Paul on 1 November 2026. Channels are presets matched against each viewer's own library, never bundled content. + +The bible holds 25 presets, and only three have numbers: 101, 102 and 103. The rest stay unnumbered until you map them, as you said on 1 November. Example titles guide matching, and no user is expected to own them all. Users can accept, remove, edit, rename or replace any preset. + +### Entertainment and comedy + +| Channel | Identity | Example titles | Look | +| --- | --- | --- | --- | +| Orbit 1 (101) | Family favourites and relaxed entertainment | Sitcoms, comfort TV, familiar classics | Orbit blue, silver, soft cyan | +| Orbit 2 | Discovery, cult TV, forgotten favourites | Game shows, documentaries, cult TV | Silver, purple, dark blue | +| Orbit Three | BBC Three-era and Scottish comedy | Still Game, Limmy's Show, Mighty Boosh, Two Pints, Gary: Tank Commander, Family Guy; from your earlier list, Gavin & Stacey, Little Britain | Magenta, purple, geometric type | +| Orbit Gold | Classic British comedy | Only Fools and Horses, Father Ted, Blackadder, Fawlty Towers; from your earlier list, Ghosts, The Good Life, The Green Green Grass, Vicar of Dibley, Porridge, Taskmaster, 8 Out of 10 Cats | Warm gold, charcoal | +| Riot | Adult animation, North American sitcoms, alternative comedy | South Park, The Simpsons, It's Always Sunny, Trailer Park Boys, Friends, How I Met Your Mother | Lime, hot pink, cyan, purple, torn-paper collage | + +### Animation + +| Channel | Identity | Example titles | Look | +| --- | --- | --- | --- | +| Vortex (103, shown today as Toonami) | Action anime and Toonami-style blocks | DBZ, Naruto, Gundam Wing, Yu Yu Hakusho, Samurai Jack | Brushed chrome, blue, electric purple | +| ToonZ | Traditional cartoons across generations | Looney Tunes, Tom & Jerry, Flintstones, Jetsons, Popeye | Yellow, cyan, pink graffiti Z | +| Rewind | 90s and 2000s after-school animation | Dexter's Laboratory, Johnny Bravo, Scooby-Doo, Courage, Ed Edd n Eddy, Recess, The Powerpuff Girls | Orange, yellow, purple, CRT and VHS | +| Orbit X | 80s and 90s action cartoons | Digimon, Gargoyles, Transformers, Power Rangers, He-Man, ThunderCats, Biker Mice from Mars | Silver, red X, black | +| Heroes | Superhero animation | Batman TAS, Superman TAS, Spider-Man 1994, X-Men, Batman Beyond, Spider-Man Unlimited | Silver, deep red, royal blue, skyline | + +### Films + +| Channel | Identity | Example titles | Look | +| --- | --- | --- | --- | +| Wonder | Traditional animated family films and fairy tales | Aladdin, The Lion King, Beauty and the Beast | Midnight blue, lavender, gold | +| PixelZ | CGI family films | Toy Story, Monsters Inc., A Bug's Life, Shrek, The Incredibles | Cyan, lime, purple, rounded 3D type | +| Orbit VHS | Nostalgic 80s and 90s films | Back to the Future, The Goonies, Gremlins, The Lost Boys | Tape labels, rainbow stripes | +| Orbit Sci-Fi | Science fiction films and series | Space, time travel, futuristic adventures | Chrome, blue, cyan, planets | +| Orbit Horror | Horror cinema | Slashers, supernatural, creature features | Crimson, black, moonlight | +| Orbit After Dark (102) | Late-night cult cinema and mature programming | Horror, cult films, midnight selections | Silver crescent, magenta orbit, lit skyline (approved) | +| Orbit Action | Action and adventure films | Thrillers, martial arts, blockbusters | Red, orange, steel | +| Orbit Romance | Romance and feel-good films | Romantic comedies | Pink, rose, sunset gold | +| Orbit Premiere | Featured films and special presentations | Movie nights, themed weekends | Gold, black, marquee lights | + +### Factual, drama and wrestling + +| Channel | Identity | Example titles | Look | +| --- | --- | --- | --- | +| Dark Files | Non-fiction crime, mystery and paranormal | Cold cases, forensic documentaries, unexplained phenomena | Midnight navy, steel grey, evidence red | +| Terra | Nature and wildlife | Blue Planet, Planet Earth, Frozen Planet | Ocean blue, forest green, turquoise | +| Odyssey | Science, history, exploration | Engineering, geography, astronomy documentaries | Expedition blue, teal, silver, gold | +| Evidence | Scripted crime and procedurals | CSI, NCIS | Navy, steel blue, forensic cyan, evidence yellow | +| Paradox | Cult sci-fi, supernatural and mystery series | The X-Files, Buffy, Supernatural, Fringe, modern Doctor Who | Indigo, purple, magenta, teal, VHS distortion | +| Ring X | Wrestling television and events | WWF/WWE, WCW, ECW, TNA, AEW, classic PPVs | Chrome, red X, dark arena, trusses | + +### Keeping similar channels apart + +Overlap is allowed, with one primary channel per title by default. Explicit user placement always wins. + +| Pair | The dividing line | +| --- | --- | +| Dark Files, Evidence, Paradox | Non-fiction, scripted crime, and fictional supernatural or mystery series | +| Paradox, Orbit Sci-Fi | Cult mystery series, and broader science fiction | +| Orbit Horror, After Dark | Horror films, and wider late-night cult films | +| Orbit Three, Riot | British and Scottish comedy, and North American or adult animation | +| Wonder, PixelZ | Traditional animation, and CGI. Any film can be reassigned. | +| Terra, Odyssey | Natural world, and human discovery. Blue Planet may cross over. | + +If metadata can't separate documentary from fiction, the title goes to the user for review and isn't classified silently. + +### Suggested programming rules + +These are defaults that can be changed or turned off. None of them can run on today's schedule engine, as the roadmap explains. + +| Channel | When | Programming | +| --- | --- | --- | +| Ring X | Monday | Monday Night Wars: Attitude Era and Nitro, chronological where metadata supports it | +| Ring X | Tuesday | Impact Night: classic TNA and Impact | +| Ring X | Wednesday | AEW television and specials | +| Ring X | Thursday to Sunday | Wrestling Vault: PPVs, ECW, historic matches, themed marathons | +| Dark Files | Daytime | Crime documentaries and investigations | +| Dark Files | Early evening | Unsolved mysteries and unusual historical cases | +| Dark Files | Mid-evening to late night | Paranormal and darker documentaries | + +Ring X shouldn't claim a chronological match without enough promotion, date or event metadata to prove it. Clock times stay undefined until the engine work is designed. diff --git a/docs/roadmap.md b/docs/roadmap.md new file mode 100644 index 0000000..816952d --- /dev/null +++ b/docs/roadmap.md @@ -0,0 +1,168 @@ +# Orbit TV roadmap + +Approved by Paul on 1 November 2026. Companion documents: [programming bible](programming-bible.md), [metadata and matching](metadata-and-matching.md), [asset inventory](asset-inventory.md). Source briefs are in [briefs](briefs/). + +## Decisions + +Paul approved these on 1 November 2026. + +| Conflict found | What the sources say | Decision | +| --- | --- | --- | +| 103 name | Installed as "Toonami". The bible has Vortex, and 103's search list also holds titles the bible now gives to Heroes and Orbit X. | Rename the display to Vortex, keep 103 and its lineup. Toonami is a third-party brand, and the creative brief bars those as default branding. | +| 101 name | Installed as "Orbit One", bible says "Orbit 1". | Use Orbit 1 on screen, keep 101. | +| Box office and game names | The app and its artwork say OrbOffice and OrbHive. Both briefs say OrbitOffice and OrbitHive. | Use OrbitOffice and OrbitHive going forward. Rename the app and artwork in a later build. | +| Orbit X and Ring X look | Both call for silver or chrome with an aggressive red X, and the bugs will sit on the same screen. | Keep the red X for Orbit X's cartoon slash. Give Ring X a distinct silhouette, decided when its board arrives. | +| 102 content | Built from Horror, Thriller and Science Fiction film searches. The bible separates Orbit Horror and defines After Dark as cult and late-night. | Keep 102 as built. Change its rules when presets arrive, and don't claim adult controls before profiles exist. | +| Title moves | Toy Story moves from Wonder to PixelZ. Batman Beyond and The Powerpuff Girls drop off Vortex in the new table. | Latest table wins. Batman Beyond stays a permitted crossover and The Powerpuff Girls moves to Rewind. Existing 103 choices stay. | +| Order of work | Your earlier order had controlled refresh and the grid guide. The new priority list names neither. | Keep both, as shown in section E. | +| Profiles | Listed as a later priority, yet matching treats audience suitability as a required filter. | Capture ratings early and show them. Treat real enforcement as a gate before anyone outside your household uses mature channels. | + +## Current status + +The status below comes from the source code, the verification notes and Paul's reports from the box. The roadmap update's list of working features is right in spirit, but discovery and channel generation are much narrower than it implies. + +### Implemented + +These are working, with Paul's confirmation noted where given. + +| Feature | Actual extent | Confirmed by | +| --- | --- | --- | +| Emby sign-in and remembered login | One fixed provider. Encrypted saved token, no saved password. | Paul, on 0.14 | +| Metadata access | Hand-triggered, small queries: 20 items per page, 10 series per search, 5 episodes per series. No full library read. | Paul, on 0.3 | +| Clock-driven channels | Repeating UTC timeline. Joins in progress, real Now and Next, automatic rollover. | Paul, on 103 | +| 101 Orbit One | Built from the checked sample, up to three titles. | Partly: built and saved | +| 103 Toonami | One to three approved series, up to five episodes each, from a 23-title search list. | Paul | +| 102 Orbit After Dark | Two or three approved films from genre searches. | Paul: played, with a tuning-screen issue | +| After Dark artwork in the app | Compact logo and lit-window background, on the review and guide screens. | Paul | +| Programme strip and channel switching | Strip hides after five seconds. Switching works between built channels. | Paul for the strip; switching not separately reported | +| Demo guide grid, ticket previews, Services page | Fictional data, not connected to Emby. | Paul, on 0.2 | + +0.16 replaces the blue tuning panel and passes 87 tests and lint. It was installed on the box on 1 November 2026, and Paul's test of it is outstanding. + +### Approved direction + +- The 25-channel lineup in section A, as presets matched against each user's library, never bundled content. +- Tick-based selection: available titles can be ticked, and missing titles stay visible, unticked and marked unavailable. +- The clock-driven schedule stays, and new work plugs into it. +- Original Orbit assets only. Concept art is reference, and After Dark is the reference workflow. +- Optional, explainable personalisation, with no mandatory AI or cloud service. +- OrbitOffice as occasions, not a catalogue. + +### Proposed + +These need technical review: sections B, C and F, time-of-day and weekly programming, repeat rules, and the catalogue storage choice. + +### Future + +Profiles and PINs, more providers, authorised IPTV and external guide data, themes, Catch Up, OrbitHive Bedlam, OrbText, first-run onboarding, self-hosting and public distribution. + +### Blocked or uncertain + +- **Metadata quality:** unknown until tested. Nobody has measured how much of it the provider returns. +- **Provider load:** the provider's rate limits and any rules on full library reads are unknown. +- **Playability at scale:** each title needs its own playback check, and only direct-play sources work because transcoding is off. +- **Names and rights:** clearance isn't established for Orbit or any channel name. Curated title lists and references to other brands need review before public release. +- **Transparent video idents:** support is unproven on the box, and current idents are opaque H.264. +- **New concept boards:** the eight new boards haven't been received. + +## Roadmap changes + +The roadmap gains two steps the update doesn't name, the metadata audit and a generic channel list, and keeps every earlier milestone. P1 to P6 are your priorities, and arrows show what must exist first. Branding can run alongside the other work once channels exist. + +```mermaid +flowchart TD + fix["Now: 0.16 tuning fix, test on 102"] --> audit["Metadata audit"] --> cat["P1 Catalogue and refresh"] + cat --> preset["P2 Preset matching"] + cat --> list["Generic channel list"] + preset --> rec["P5 Recommendations"] + list --> grid["Grid guide restored"] --> brand["P4 Branding rollout"] + list --> sched["P3 Schedule quality"] --> office["P6 OrbitOffice"] +``` + +Gate before mature channels reach other households: profiles and enforced ratings. + +Later: more providers, IPTV, themes, Catch Up, OrbitHive Bedlam, OrbText, public release. + +The grid guide comes before most new channels, because switching one at a time gets unwieldy past a handful. That follows your earlier request to bring the guide back as channels grow. + +### What each step needs from today's code + +The clock engine stays. These limits are the parts that have to change, and only the last row changes how the clock behaves. + +| Today | Why it matters | Needed for | +| --- | --- | --- | +| Queries capped at 20 items, by hand | No library-wide view | P1 | +| 512 KiB saved state, fixed channel slots, numbers 101 to 103 only | Can't store a catalogue or a fourth channel | P1, channel list | +| Channel lineups of 2 to 15 unique titles | Too small for real channels, and blocks intentional repeats | P3 | +| One repeating loop anchored to UTC | No concept of weekday, evening, local time or daylight saving | Dark Files, Ring X, OrbitOffice | + +For that last row, I'd keep the loop as the default and add an optional local-time block layer that hands each block a lineup. It needs its own design and your approval before any work starts. That also meets your rule against replacing the engine. + +### Earlier milestones kept + +| Milestone | Where it now sits | +| --- | --- | +| Original channel set: 101, 102, 103 | Done, pending the 0.16 test | +| Controlled refresh, previewing additions and removals without shifting what's playing | P1 | +| Reusable and custom channel creation with ticks | P2 and channel list | +| Grid guide with real Now and Next | After channel list | +| Bottom-left bug, off by default | P4 | +| Optional idents with reduced-motion setting, never delaying the clock | P4 | +| Dashboard: On now, Coming up, OrbitOffice presents | With P5 and P6 | +| First-run onboarding and more providers | Later, Emby preserved | +| Profiles, Kids, PIN | Later, with the gate shown above | +| Themes, Catch Up, Games, OrbText | Later, unchanged | +| Seasonal programming and themed weekends | P3 and P6 | + +The gate only applies once someone else's household is involved, so it doesn't hold up your own box. Until then, Orbit shouldn't describe any channel as age-protected. + +## Next development step + +I recommend a read-only metadata coverage check as 0.17, after you've confirmed 0.16 on the box. It answers the question every later decision depends on: how much usable metadata does your provider return? Nothing gets built on guesses, and your channels are untouched. + +### Scope + +- **Entry point:** a new "Check metadata coverage" action under Menu, Connect Emby. +- **Requests:** one sample each of films, series and episodes, at most 20 items each, and only when you press it. +- **Result:** counts only, such as "Genres 18 of 20", for each field in section B. No titles are shown. +- **Sampling:** existing queries sort by name, which favours titles starting with A. This one should take a spread across the library and label itself a sample. + +It won't save anything, change a channel or schedule, classify titles, or build the catalogue. + +### Files likely to be involved + +| File | Change | +| --- | --- | +| `MetadataAudit.kt` (new) | Build the requests, count field coverage | +| `EmbyConnectionScreen.kt` | The action and the results screen | +| `MetadataAuditTest.kt` (new) | Fixture tests | +| `app/build.gradle.kts`, `EmbyClient.kt`, `SecureMediaDataSource.kt` | Version bump, as in past releases | +| `VERIFICATION-0.17.0.md` (new) | Release notes and evidence | + +### Risks + +| Risk | Handling | +| --- | --- | +| Provider load or rate limits | Three small requests, only on demand. Existing cooldown applies, and a rate-limit reply stops the check. | +| Oversized replies from extra fields | Existing 2 MiB response cap, with a clear message if hit | +| Sample misleads | Label results as a sample, not a library total | +| A field name differs from Emby's documentation | Check the documentation first, and report a missing field as zero, not as an error | +| Private catalogue exposure | Counts only, nothing saved or logged | + +### Acceptance criteria + +- [ ] One press sends at most three requests, each capped at 20 items. +- [ ] The screen shows coverage counts for each item type and field, with no titles. +- [ ] 101, 102 and 103 keep their lineups and timing, and saved setup is byte-for-byte unaffected by the check. +- [ ] An expired login or rate limit gives a clear message and stops. +- [ ] You can run it with the remote, then read or photograph the result for me. + +### Tests + +Fixture tests cover the request limits and the token staying in the header, not the URL. They also cover missing and malformed fields, a server ignoring the limit, rate-limit and expired-login stops, and no saved-state writes. The full 87 existing tests and lint must still pass, and you then run it on the box. + +### Rollback + +Reinstall the 0.16 APK kept in `outputs/revision-0.16.0`. The saved data format doesn't change, so your login and channels should survive, which I'd confirm during the test. + +The project is now in git, so each release can also be rolled back from its commit, which the channel-list migration will need later.