docs: reconcile Day 2 release policy and output tasks

This commit is contained in:
2026-11-04 11:18:16 -08:00
parent 6310f50c27
commit f921c0174b
17 changed files with 120 additions and 153 deletions
+3 -4
View File
@@ -13,7 +13,7 @@
4. ✅ **WASAPI audio capture SHIPPED** (2026-08-12) — NAudio loopback (desktop/game) + the picked mic feeding `AudioLevel`, so the realtime meter comes alive (see the ship step 4 plan below)
5. ✅ **Frame-pipeline wiring SHIPPED** (2026-08-12) — `CameraManager`/`ScreenCaptureManager` → compositor resolver → encoder, driven by a paced `FramePump` (see the ship step 5 plan below)
6. ✅ **Health stats SHIPPED** (2026-08-13) — `FramePump.HealthUpdated` (encoder's parsed bitrate/FPS/dropped/duration, already forwarded from `FfmpegEncoder.OnStderrLine`) now lands in the bottom bar: `MainViewModel.OnFramePumpHealthUpdated` marshals to the UI thread (the stderr loop raises on a background thread) and copies into `CurrentHealth` (the bottom bar's existing binding); `ResetHealth` zeroes dropped/duration on go-live and on End so stats never linger from a previous session (bitrate/FPS stay on the tier's targets). The bar lights up with real values once TASK 9 supplies the RTMP URL (until then the pump skips the encoder and the bar shows the tier's targets)
7. ✅ **One-click go live + private-only enforcement SHIPPED** (2026-08-14) — the Go Live dialog is **locked to Private** (no dropdown, `GoLiveViewModel.Visibility` is a get-only "Private"); `YouTubeStreamService.CreateBroadcast` **always sends `privacyStatus = "private"`** (dialog + service enforcement, requirement 8 — nothing can go out non-private) and gained an injectable `HttpClient? http = null` seam for tests; `BeginGoLive` now calls `CreateBroadcastAsync` and remembers `_currentBroadcastId` for TASK 9's bind/transition (failure → `StreamStatus.Error`, never a crash; `StopStream` clears the ID); the REC sign shows a **PRIVATE badge** (dark-red border, next to REC, `IsLivePrivate`) when the live stream is private; settings' dead "Default Visibility" dropdown + `MainViewModel.Visibilities`/`DefaultStreamVisibility` removed. The broadcast-insert integration test asserts the request body carries `"privacyStatus":"private"` (2 new tests → 173 passing, 0 warnings)
7. ✅ **One-click go live + initial Private development safeguard SHIPPED** (2026-08-14) — at the time, the Go Live dialog and `YouTubeStreamService.CreateBroadcast` forced `privacyStatus = "private"`; the broadcast-insert test pinned that behavior. The creator clarified 2026-11-04 that this is a development/test safeguard, not permanent product policy. See TASK 9 and `docs/ai/youtube-api.md` for the release visibility flow.
The pipeline chain the encoder needs doesn't exist yet: **scene compositing** (the master 1920×1080 frame
without the preview's editing chrome) → **audio capture** (WASAPI, feeds the meter) → **H.264+AAC encode**
@@ -46,8 +46,8 @@ until a frame source exists, so the compositor is ship step 1. The pipeline is
5. **Health stats** — bitrate, FPS, dropped frames reported live in the bottom bar (encoder-side)
6. **One-click go live** — defaults that work out of the box
7. **Audio capture (feeds the meter — this task ships the wiring)** — WASAPI loopback (desktop/game at unity, zero UI — "it just is") + the picked mic (`MicSourceName` from the `MicPickerDialog`). The mic capture feeds `AudioLevel` so the realtime meter comes alive (today it reads 0 — the mixer feed is pending, see `ai.md` audio notes). AAC mono/stereo @ 48 kHz per the compliance rules.
8. **Private-only go live until v1 (reputation guard, decided 2026-08-10)** — until the v1 release, go-live is **locked to private streams only** so a software error can never publish something public/unlisted that damages the creator's reputation. RTMP push itself has no privacy — privacy lives on the YouTube **live broadcast object**, which this app already controls via its OAuth API calls. So the lock is purely API-side: the Go Live flow always creates/updates the broadcast with `privacyStatus = "private"` and a guard **refuses** to set anything else (same spirit as the Live-only backdrop policy). The UI shows a clear "PRIVATE" badge next to the stream state so the creator always knows who can see them. Enforcement must be verifiable in the auth-service tests (fake the broadcast-insert/update call, assert `privacyStatus` is forced to private).
9. **v1 release gate: bundle the full license texts (decided 2026-08-10)** — `THIRD-PARTY-NOTICES.txt` currently links the canonical license texts rather than embedding them. At the **v1 (GA) release**, the full texts of every license it names (LGPL v2.1+, BSD-2-Clause, MIT, Apache-2.0) MUST be bundled alongside it (shipped in the app output, e.g. a `licenses/` folder next to the notices file, still reachable from the About screen). This is a **release blocker for v1, not a task to queue early** — do it in the release pass. The repo should treat this like the private-only go-live gate: a checkbox that cannot silently lapse.
8. **Development/test privacy safeguard (creator clarification 2026-11-04)** — force `Private` during development and test runs so unfinished captures cannot publish accidentally. This is not a permanent product lock: the released creator flow offers Private/Unlisted/Public, defaults to Private, and supports live visibility changes. Verify the environment-specific guard and release flow in tests.
9. **v1 release gate: bundle the full license texts (decided 2026-08-10)** — `THIRD-PARTY-NOTICES.txt` currently links the canonical license texts rather than embedding them. At the **v1 (GA) release**, the full texts of every license it names (LGPL v2.1+, BSD-2-Clause, MIT, Apache-2.0) MUST be bundled alongside it (shipped in the app output, e.g. a `licenses/` folder next to the notices file, still reachable from the About screen). This is a **release blocker for v1, not a task to queue early** — do it in the release pass; the checkbox cannot silently lapse.
#### Ship step 1 — Scene compositor (the frame source)
@@ -336,4 +336,3 @@ the validator → persisted), compositor bar overlay (top/bottom + above-flash),
(`SocialBarSnap`) were removed with the click-toggle supersession.
**Not included (say the word):** rewriting the healed entry's `ProfileUrl` to `https://mastodon.llamachile.tube/@gramps`.
+5 -6
View File
@@ -5,23 +5,23 @@
**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 = deliberate lock (TASK 36); item 7 scoped to core fields — advanced tab is out-of-product
### 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. ❌ **Visibility picker** — DELIBERATE TEST-PHASE LOCK (creator decision 2026-09-01), not open work: "always Private" stays during multi-month real-world testing so breakage VODs never clutter the channel. `recordFromStart`/DVR stay on — Private VODs are invisible review tapes; bulk-delete pre-GA. Unlock = TASK 36 gold-pass item (remove the override in `YouTubeStreamService.CreateBroadcast`, wire the dialog selection). See `ai.md` → YouTube Live API constraints.
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, visibility, made-for-kids — live-editable. **Scheduling:** ships as **TASK 34** (Scheduled checkbox + datetime in the same drawer). **Advanced tab is PERMANENTLY OUT** (the 10% margin): latency (locked `low`), DVR/record-from-start (locked on), embed, projection, CC, region restrictions stay fixed at sane defaults, invisible — every exposed field is a support ticket. `categoryId` removal: done (not a `liveBroadcast` field). Monetization enablement (if ever needed) rides the reward-events chain via `liveBroadcasts.update`, not a form field
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. **One dialog, three states** — `not connected` (sign-in) / `connected-offline` (all editable) / `live` (title + description + visibility editable; quality + account greyed out). Both entry points (Start Stream button + bottom strip) open it; prefilled from saved session profile.
5. **Live edits** — `liveBroadcasts.update` with part=`snippet,status` for title/description/privacy.
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`).
@@ -34,4 +34,3 @@
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
+1 -2
View File
@@ -54,5 +54,4 @@ The tasks below are ordered by dependency and risk. Each task builds on the prev
14. **TASK 35** — Scene-linked audio ("scenes remember the room").
15. **Text source (TASK 3 item 17)** + **the monetization-awareness chain + Alerts (TASK 10 related work → TASK 3 item 20)** — capture → report → journey → alerts, one slice per integration test.
16. **TASK 13** — Social media launch kit (MARCOM) — after features, before gold.
17. **TASK 36** — Gold pass, always last: visibility unlock + flash-live enable + screens/layers audit + native verification suite + expiry reminders + signing/installer/EULA/Velopack.
17. **TASK 36** — Gold pass, always last: verify the release visibility flow while development/test runs remain Private + flash-live enable + screens/layers audit + native verification suite + expiry reminders + signing/installer/EULA/Velopack.
+2 -4
View File
@@ -28,7 +28,5 @@ channel countdown; come Friday, one click goes live into the scheduled broadcast
confirmation. (b) delete semantics for a ready broadcast bound to a reusable stream.
6. ☐ Test (the ONE): schedule → persists + inserts (fake service captures a future scheduledStartTime
+ boundStreamId); start → adopts instead of inserting; uncheck → delete called.
- **Test-phase note:** dark by design while the visibility lock holds (Private notifies nobody); the
creator can still exercise insert/adopt/cancel. Full shine arrives with TASK 36's unlock — pleasing
coupling, deliberate.
- **Visibility note (updated 2026-11-04):** development/test scheduled broadcasts stay Private; the
released creator flow uses the saved default or scope selected in the ON-AIR preflight.
+2 -3
View File
@@ -6,8 +6,8 @@
**Goal:** the single deliberate pass that turns the dev product into the shipped product. Nothing here
may be done opportunistically mid-development — each item has a lock/comment pointing at this task.
1. ☐ **Visibility unlock** — remove the `CreateBroadcast` Private override (TASK 9 item 6); dialog
selection rules. The channel-protection stance ends at GA, by hand, here.
1. ☐ **Release visibility verification** — verify the Day 2 Private/Unlisted/Public creator flow,
including live `UpdateBroadcast`; development/test runs must remain forced Private.
2. ☐ **Branding flash goes live** — end the preview-only pre-GA posture: composite the escalating
obnoxious-promo flash onto output + recordings for free users. Paid removes it; that stays the
ONLY paid delta. (Escalation curve finalized here, first.)
@@ -65,4 +65,3 @@ flash is preview-only (see ai.md → Monetization; TASK 36 flips it live).
*If a future session is tempted by anything on this list, the answer is already written. New ideas
must survive this page before they get a task number.*
+4 -5
View File
@@ -24,10 +24,9 @@ inject mock chat, with alert/event triggers for subscriber, membership, and Supe
## Facts the build sits on (verified in code, 2026-09-22 research pass)
- **The app is already private-only go-live** — `YouTubeStreamService.CreateBroadcast` hardcodes
`privacyStatus="private"` + `enableAutoStart/Stop` + `low latency`, no monitor stream
(`enableMonitorStream=false`), and the Go Live dialog is locked to Private. "Test" is therefore a
**session variant over the real pipeline**, not a new broadcast mode.
- **Test mode is always Private** — it remains a **session variant over the real pipeline**, not a
new broadcast mode. The creator clarified 2026-11-04 that normal Release Go Live offers a
visibility choice; development/test runs stay forced Private.
- The **liveChatId flow already exists**: `GetBroadcastLiveChatIdAsync` → `_youtubeChat.Start(liveChatId)`
in `PrepareAndStartLiveAsync` — the "chat endpoint activation" the ask describes.
- OAuth scope already includes `youtube` + `youtube.force-ssl` (`YouTubeAuthService.cs:18`) —
@@ -79,4 +78,4 @@ inject mock chat, with alert/event triggers for subscriber, membership, and Supe
## Follow-ups (NOT in this task)
- Real stinger/TTS alert widgets → TASK 3 items 16/17/20.
- Test-mode health-panel depth (per-broadcast status inside the drawer) if ever wanted.
- Test-mode health-panel depth (per-broadcast status inside the drawer) if ever wanted.
+10 -8
View File
@@ -13,17 +13,19 @@ prove it. Make the output formats a tested, locked contract instead of an assump
**Slices (one integration test each, in order):**
1. ☐ **What we actually emit** — enumerate the real encoding configurations (widescreen 1080p60/
1080p30/720p60/720p30 + vertical 9:16 1080p60) and pin them in one place (`FfmpegArgs`-adjacent),
1080p30/720p60/720p30 + vertical 9:16 1080p60/1080p30) and pin them in one place (`FfmpegArgs`-adjacent),
each with its own geometry contract test. This turns "formats exist" into "formats are defined".
2. ☐ **9:16 geometry** — vertical render must be true 1080×1920 (or the GUP-negotiated size) with
the composite laid out for a phone: viewer-safe top strip (TikTok/Shorts overlays live top-left
and bottom), caption/text clearance, and the webcam not cropped off-centre. Test: composite a
known layout, decode the output frame, assert dimensions + element placement vs the contract.
3. ☐ **Live-shorts check on a real stream** — private Test Stream at 9:16, then pull the thumbnail/
2. ✅ **9:16 output resolution (resolution-only acceptance, 2026-11-04)** — creator-supplied
`ty-20261104-0927-982-0000-2.mp4` reports H.264 1080×1920 at 60 fps. The creator accepted the
resolution check only; captions and visual safe-zone placement were not reviewed.
3. ☐ **9:16 safe-zone geometry** — confirm the composite is laid out for a phone: viewer-safe top
strip (TikTok/Shorts overlays live top-left and bottom), caption/text clearance, and webcam
placement. Test a known layout and assert element placement against the contract.
4. ☐ **Live-shorts check on a real stream** — private Test Stream at 9:16, then pull the thumbnail/
player quirk list from YouTube (Title visible, overlays); confirm nothing the streamer put on
screen sits under YouTube's own chrome. This is the "never tested" item the creator flagged —
test on a real vertical test stream and cite the observation.
4. ☐ **Recorded .mp4 matches output** — the saved vertical .mp4 must carry the same 9:16 frame the
5. ☐ **Recorded .mp4 matches output** — the saved vertical .mp4 must carry the same 9:16 frame the
stream showed, not a squeezed/wider master. Test: record vertical, decode first frames, assert.
**Design decisions:**
@@ -31,4 +33,4 @@ prove it. Make the output formats a tested, locked contract instead of an assump
- Geometry is a contract with tests, not a hope. Derived ratios (stream vs composite vs canvas)
get a derived-value test so one change can't silently wreck Shorts/TikTok output.
- Keep widescreen untouched — only add what vertical needs (the existing test suite stays green
for 16:9).
for 16:9).