Autoplay

Autoplay and Story Engine

This document describes the TV client's autoplay system and the story engine that powers the Stories, Photos, and Events features. It mirrors the structure of the UI Components guide so engineers can quickly cross-reference the moving parts that convert feature-level controllers into the continuous slideshow presented on signage and desktop builds.

Overview

The TV client uses a three-layer autoplay loop that continually cycles through user-selected content categories. Each feature (Stories, Photos, Events) encapsulates its own data loading, rendering, and navigation logic, while AutoplayComponent orchestrates the carousel and propagates user intents. Sessions target 24/7 uptime with deterministic ordering, instant manual navigation, and graceful fallbacks when data sources degrade.

System Architecture

Three-Layer Loop

1. RootComponent wires navigation, dependency scopes, and the initial state shared across screens.
2. Feature Components (Stories, Photos, Events) implement AutoplayFeature contracts and expose feature-specific state machines.
3. AutoplayComponent coordinates feature controllers, timers, and transition animations.

Navigation Flow

Screen	Purpose	Notes
Welcome Screen	Entry point with two CTAs (resume autoplay or open menu)	a starting point with two options
Menu Screen	User selects the active content categories and their order	Persists for the current process only
Autoplay Screen	Runs the carousel slideshow for chosen categories	Handles keyboard/remote events

Content Categories

Category	Feature Component	Content
Stories	StoriesAutoplayFeature	Celebrations (birthdays, anniversaries, new hires)
Photos	PhotosAutoplayFeature	Synology album slideshow
Events	EventsAutoplayFeature	Leader ID / calendar promo cards

Autoplay Component

Core Responsibilities

• Maintain the ordered list of active screens chosen in the Menu and expose it to AutoplayScreen.
• Manage carousel direction (forward/backward), looping, and transition animations via transitionKey for smooth wrap-around visuals.
• Dispatch global intents (play/pause, next/previous, back to menu) to the currently visible feature.

State Model

Field	Description
screens	Ordered list of active ContentCategory values
currentIndex	Carousel pointer into screens
isPlaying	Play/pause flag used by timers
direction	FORWARD or BACKWARD depending on user input
transitionKey	UUID used to force Compose transitions when the carousel wraps

Data Aggregation Pipeline

1. Loads the teammate roster from Notion and chunks requests.
2. Fetches supplemental data from Duolingo, Clockify, and Supernova in parallel.
3. Merges responses using email, username, or full-name matching.
4. Emits a StoriesPayload that bundles rendered stories plus warning metadata when any source partially fails.

Feature Provisioning and Lifecycle

FeatureProvider caches per-category controllers. Each feature implements AutoplayFeature, guaranteeing lifecycle callbacks for onEnter, onExit, and keyboard navigation events. StoriesAutoplayFeature hooks into these callbacks to reset indexes when direction changes.

Navigation and Input Handling

Autoplay uses two navigation layers:

• Screen level: Carousel switching between categories, handled by AutoplayComponent.
• Feature level: Within-screen navigation (next story/photo/event), handled by each feature's NavigationHandler.

Keyboard/remote mappings mirror the desktop and TV builds:

Key	Action
Left Arrow	Previous screen or previous story
Right Arrow	Next screen or next story
Space / Enter	Toggle play/pause
Esc / Back	Return to Menu screen

StoriesAutoplayFeature implements NavigationHandler to translate these events into StoriesIntent actions.

Timing and Looping Behavior

• Every feature targets a fixed 15-second dwell time per item.
• Direction changes update the internal pointer so backward traversal resumes from the last entry.
• When a category contains a single item, the component loops seamlessly without pausing.

Timer Implementation

StoriesComponent drives timers via coroutines that:

1. Calculate remaining duration using the current progress value.
2. Update the progress bar roughly every 16 ms (~60 FPS).
3. Advance to the next story automatically upon completion.

Error Handling and Diagnostics

• StoriesPayload exposes warnings so partially successful loads can still render while surfacing degraded sources to operators.
• Data provider errors trigger warning banners inside AutoplayScreen instead of halting the loop.
• If every upstream call fails, the feature reports a fatal error so the user can return to the menu and adjust selections.