LlamaCasty/TASKS/task-09-live-stream-management.md

TASK 9 — YouTube Live Stream Management

Catalog: TASKS.md — status and requirements live here.

Goal: Create/bind broadcasts, monitor YouTube-side stream health — the v3 way.

Status: ⏳ In progress — items 1–3 SHIPPED (reusable stream 2026-08-16; report-by-exception health 2026-08-16); item 4 SHIPPED (status reconciled 2026-09-01); item 5 open; item 6 is the Day 2 release-visibility work, with a development/test Private safeguard; item 7 scoped to core fields — advanced tab is out-of-product

1. ☑ Broadcast creation — title/description/privacy/scheduledStartTime via API, with the v3 flags above (SHIPPED: CreateBroadcast sends enableAutoStart/Stop, enableMonitorStream=false, latencyPreference=low, selfDeclaredMadeForKids=false)
2. ☑ Reusable stream — create once, cache + reuse; bind to broadcast (SHIPPED: GetOrCreateReusableStreamAsync lists-then-inserts the variable/isReusable stream, cached via LayoutStore Settings, bound at broadcast insert via boundStreamId; _rtmpUrlProvider yields the ingest URL so go-live actually encodes + pushes)
3. ☑ Health monitoring — poll liveStreams.list healthStatus + configurationIssues[], surface banner only on warning/error (SHIPPED: GetStreamHealthAsync(streamId) 30s while live; pure StreamHealthReporter.BannerFor = report-by-exception; banner strip under the top bar, amber warning / dark-red error, via HealthIssueBanner/HealthIssueBackground; poll failures log-only; ONE integration test GetStreamHealthAsync_Report_By_Exception_Banner_Only_On_Warning_Or_Error)
4. ☑ Live chat — poll liveChat/messages, render in right panel, support Super Chat + membership badges — SHIPPED (status reconciled 2026-09-01: YouTubeChatService polls + parses superChatEvent/newSponsorEvent with badge/level on ChatMessage; the panel MOVED to the left-panel live state by Control Surface UX, "right panel" superseded; the remaining reward types land with the monetization chain, TASK 10 → related work)
5. ☐ Error handling — the YouTube error codes: errorStreamInactive, invalidTransition, redundantTransition, liveStreamDeletionNotAllowed, liveStreamModificationNotAllowed, liveBroadcastBindingNotAllowed
6. ☐ Release visibility flow — persist a default of Private; offer Private/Unlisted/Public in the ON-AIR preflight with an explicit “Start Broadcast — [scope]” action; apply the selected value at creation and via UpdateBroadcast while live. Development/test runs stay forced Private.
7. 🔶 Full broadcast form — RESCOPED 2026-09-01, not the old two-tab plan. Core fields (SHIPPED as the Text drawer, 2026-08-24): title, description, tags, and made-for-kids; release visibility is item 6. Scheduling: ships as TASK 34 (Scheduled checkbox + datetime in the same drawer). Advanced settings remain out of product: latency, DVR/record-from-start, embed, projection, and captions stay at fixed defaults. Category selection and tag updates through the video API, plus thumbnail upload, remain follow-ups; categoryId is video metadata, not a liveBroadcast field. Monetization enablement (if ever needed) rides the reward-events chain via liveBroadcasts.update, not a form field.

Design decisions (v3)

1. One-click go-live — liveBroadcasts.insert with enableAutoStart=true, enableAutoStop=true, enableMonitorStream=false, selfDeclaredMadeForKids=false, latencyPreference=low. No transition(live) call, no testing stage, no liveStarting polling. Encoder starts → YouTube brings it live by itself.
2. Variable reusable stream — cdn.resolution=variable, cdn.frameRate=variable, isReusable=true. Create once per channel, cache ingestion URL + stream name, reuse for every broadcast. Any quality tier works without recreation; auto step-down needs no API calls.
3. Report-by-exception — poll liveStreams.list; banner only on healthStatus warning/error issues (configurationIssues[]). Bottom strip = YouTube logo + green/red connection dot (clickable → opens the dialog).
4. Go-live preflight — ON-AIR opens a scope preflight using the saved visibility default; the creator explicitly confirms with “Start Broadcast — [scope]”.
5. Live edits in Release — liveBroadcasts.update with part=snippet,status applies title/description/privacy changes. Development/test runs remain Private.
6. End stream — stop encoder → transition(complete), with enableAutoStop as the safety net. SHIPPED 2026-09-01 (EndBroadcastAsync, wired into StopStream after RTMP EOF; the call had been specced since TASK 9 but never existed — found during recording verification). Hardened 2026-09-22: a blind complete 403s invalidTransition once autoStop/YouTube marks the broadcast complete (seen on every 2026-09-22 end) — the call now pre-flights liveBroadcasts.list→lifeCycleStatus and only transitions from live/testing, skipping already-complete broadcasts silently (enableAutoStop finishes every skip).
7. Broadcast ID == Video ID — one ID to track status, health, and the auto-created VOD (recordFromStart + enableDvr).

Requirements:

1. Broadcast creation — title/description/privacy/scheduledStartTime via API, with the v3 flags above
2. Reusable stream — create once, cache + reuse; bind to broadcast
3. Health monitoring — poll liveStreams.list healthStatus + configurationIssues[], surface banner only on warning/error
4. Live chat — poll liveChat/messages, render in right panel, support Super Chat + membership badges
5. Error handling — the YouTube error codes: errorStreamInactive, invalidTransition, redundantTransition, liveStreamDeletionNotAllowed, liveStreamModificationNotAllowed, liveBroadcastBindingNotAllowed
6. Visibility picker — Private/Unlisted/Public from the go-live dialog
7. Full broadcast form — Core + Advanced tabs with all API-supported fields