# Combined Stream Implementation Guide

## Objective
Build one viewer-facing translations page that automatically plays the correct feed type per language:
- HLS/RTMP feeds (m3u8)
- WebRTC feeds (browser translation studio)

Viewers should only select languages. They should not see transport internals.

## Non-Negotiables
- Keep existing comments and live traffic behavior.
- Keep risk-management UX (friendly unavailable card instead of black screen).
- Avoid noisy technical errors in viewer UI.
- Keep superadmin test capability for pre-live verification.

## Delivery Phases

### Phase A: Unified Feed Contract and Normalization
Status: Completed

Goals:
1. Define one frontend model for language feeds regardless of transport.
2. Normalize data from:
- Programs API language registrations (HLS)
- WebRTC active translators endpoint
3. Compute one effective feed status for each language.

Deliverables:
- Unified language feed type.
- Mapping utility that merges HLS + WebRTC sources.
- Language-to-translator matching strategy with normalization (case/spacing safe).

Acceptance Criteria:
- One merged language list is produced for program live feeds.
- Each language has clear fields:
  - language
  - transport (hls/webrtc)
  - stream identity
  - status and label

### Phase B: Combined Stream Page and Player Adapter Layer
Status: Completed

Goals:
1. Create a new combined viewer page.
2. Keep one selector UI and one player container.
3. Select player adapter by language transport.

Deliverables:
- New combined page component.
- HLS adapter path (existing Video.js component).
- WebRTC adapter path (clean viewer mode; no noisy debug banners).
- Unified risk-management state handling.

Acceptance Criteria:
- Selecting a language always plays through the correct adapter.
- Offline/unavailable language shows friendly card.
- Viewer sees no protocol-specific error spam.

### Phase C: UX Hardening and Reliability
Status: Completed

Goals:
1. Improve fallback behavior when selected feed is unavailable.
2. Ensure status labels and indicators are consistent.
3. Ensure superadmin-only test mode remains available.

Deliverables:
- Controlled fallback logic (single fallback attempt).
- Unified status badges and alert messages.
- Test mode behavior documented and verified.

### Phase D: Rollout and Route Transition
Status: Completed (Pilot Logic Implemented)

Goals:
1. Introduce combined page in parallel first.
2. Validate behavior against existing pages.
3. Migrate default route once stable.

Deliverables:
- Combined route enabled.
- Legacy routes retained during pilot window.
- Cutover checklist.

### Phase E: Cleanup
Status: Completed (Rollback-Safe)

Goals:
1. Remove duplicate UX paths once combined page is accepted.
2. Keep backward-compatible fallbacks only if operationally needed.

Deliverables:
- Route/menu cleanup.
- Legacy page deprecation notes.

## Architecture

### Data Sources
1. Programs API (`getUpcomingProgramWithLanguages`) provides:
- program timeline
- language registrations
- HLS feed metadata and feed health fields

2. WebRTC Public API (`active-translators`) provides:
- currently active translators
- language identity and translator IDs

### Unified Language Feed Model
Recommended shape:
- id
- language
- transport: `hls | webrtc`
- hlsLink (optional)
- translatorId (optional)
- translatorName (optional)
- status: `healthy | starting | offline`
- statusLabel
- statusReason

### Adapter Strategy
- `hls`: render Videojs player component
- `webrtc`: render lightweight WebRTC viewer adapter

Both adapters must report the same status events:
- checking
- healthy
- unavailable

## UX Rules
1. Language dropdown uses consistent labels:
- green circle: available
- yellow circle: starting
- red circle: Translation feed not yet available
2. Offline languages are disabled for normal viewers.
3. If selected feed is unavailable:
- show warning alert
- replace player area with friendly card
4. Never expose stack traces, CORS details, transport internals, or repeated toasts to viewers.

## Progress Tracker
- [x] Plan document created
- [x] Phase A complete
- [x] Phase B complete
- [x] Phase C complete
- [x] Phase D complete
- [x] Phase E complete

## Pilot Cutover Flag
- `REACT_APP_ENABLE_COMBINED_STREAM_PILOT=1`

Pilot behavior with flag ON:
- `/translations` serves combined stream page.
- Legacy HLS page remains available at `/translations-hls`.
- Combined page remains available at `/translations-combined` for direct validation.

Phase E cleanup applied:
- Sidebar now exposes a single translations entry for viewers.
- Legacy routes remain accessible directly for rollback/troubleshooting.
- Viewer UX no longer presents duplicate stream page choices.

## Phase A/B Implementation Checklist
- [x] Add unified feed type file
- [x] Add merge/normalization utility
- [x] Add clean WebRTC adapter component for viewer page
- [x] Add combined stream page
- [x] Wire route for combined page
- [x] Build and verify
- [x] Update tracker in this document