LlamaCasty/ai.md

ytLlive — AI Guide

Memory map entry point. Conventions live in schema.md; task status and YouTube API research in TASKS.md; brand/marketing palette and launch strategy in MARCOM.md (gitignored — read it before any branding or marketing work); directory maps in each folder's index.md. Reading order: this file → TASKS.md → MARCOM.md → <dir>/index.md → source.

Subsystem detail is split out: large blocks of this file now live under docs/ai/ and this file keeps a short invariant stub + link where each was removed. Open docs/ai/index.md to find the right one, or ignore it entirely until your task touches a moved subsystem.

Response style

No default "Plans & Pitfalls" / planning boilerplate. Respond directly and concisely: do the queued work, then report what changed and what's next. Skip feature pitch, step-by-step implementation plans, pros/cons tables, and "potential pitfalls" sections unless the user explicitly asks for a plan first. A short diff-style summary beats a proposal document every time.

Derivative work (spin guard mandated in AGENTS.md)

Nothing we build is novel — streaming/overlay/WebView2 problems were solved by OBS, CEV, and WPF ecosystems long before us. Two consequences:

1. Proactive: new features start with a quick external scan, not head-first design (citation goes in the commit message).
2. Objectively triggered spin guard: a second failed fix for the same symptom means STOP theorizing and research the established answer externally; there is no unique bug in this repo that the wider ecosystem hasn't hit. This project's hard lesson: the web-source bounding saga (2026-08) burned 9 commits rediscovering that a browser source is a fixed canvas — OBS keeps it at a stable page size, crops/hugs content via the box, and clips at the edge. The apparent "gap" that ended the saga was a widget's own CSS glow effect, not a bug.

Derived-solution rule (2026-08-29, driven by the image-shrink incident): when you work out any one-off, reusable solution (recipe / workaround / how-to), write it into MyMistakes.md → Recipes registry that same session, and grep it before ever re-deriving. A solution recorded once ends the loop; an un-recorded one guarantees the user hears it derived again (see AGENTS.md → Working rules → 🔬).

LAN infrastructure (192.168.50.x)

All LAN credentials live in CREDENTIALS.md (gitignored). Server IPs and roles:

Host	IP	Role
corsair	.132	Gaming/streaming primary — RTX 5070 Ti (this machine)
llamavault	.87	ODROID-HC4, 12TB RAID5, media storage (NFS). SSH: ssh mshallop@192.168.50.87. DHCP-bound — it moved off .86 after the 2026-10 power outage, so confirm with a ping before trusting any path. SMB is reached by the llamavault name, pinned in the Windows hosts file, never by literal IP: \\llamavault\llamaVault\...
pivault	.158	RPi5 8GB, 10.83TB RAID5 NAS
jarvis	.210	AMD Ryzen 5 5600X, RX 6600 XT — AI inference, SearXNG, Docker registry, Immich
ultron	.108	AMD Ryzen 7 7840HS — AI orchestrator, llama-server, Qdrant
gordito	.144	Home Assistant, Alarmo, Zigbee
officerfriendly	.26	Pi-hole DNS
octopi	.197	OctoPrint (Prusa MK4)
BigBlinkyRouter	.1	ASUS ROG GT-BE98 Pro, WiFi 7

Web infra (DO droplet): llamacasty.com + llamachile.tube at 143.244.176.131.

Pushing to the Gitea instance (llgit.llamachile.tube). The repo is gramps/LlamaCasty (renamed from gramps/ytLlive; the old path 301-redirects). Push over HTTPS, not SSH: origin = https://llgit.llamachile.tube/gramps/LlamaCasty.git, with the credential helper /home/gramps/bin/gitea-credential (registered as credential.https://llgit.llamachile.tube.helper) reading the account password from the gitignored CREDENTIALS.md on demand — nothing stored in plaintext, nothing in a command line. The Gitea account password IS the portal password in CREDENTIALS.md, and the same password authenticates the REST API (curl --config …/api/v1/user) — that API is the fastest way to ask the server questions (the repo's real name and clone URL, the account's SSH keys, a token). ⛔ The SSH endpoint on llgit:2214 is not a usable push path: the account's SSH keys ARE registered (key id 6 "Corsair VSC" = this machine's ~/.ssh/id_ed25519) yet the server refuses the publickey, and the port later refused connections outright. Do not spend a session on key archaeology — ask the API, then push over HTTPS.

No-Fluff Mode (on demand)

Invoke with "no-fluff mode" (or similar) when you want ruthless review instead of reassurance. In that mode:

• Strip all polite pleasantries, emojis, transitions, and conversational padding.
• Treat the user's input as a draft to be methodically deconstructed or strengthened — argue, correct, and sharpen rather than agree.
• Give unvarnished truth, not reassurance.

This is an occasional, explicitly-invoked mode — never the default. The default response style above stays in effect unless invoked.

Brand

Brand palette and official assets live in MARCOM.md (gitignored — read it for hex values, asset file names, and marketing copy). The brand red #e94560 is the primary accent used throughout the UI.

Product name vs repo/assembly branding (2026-09-14)

The product is llamacasty (llamacasty.com, llamachile.tube, llgit.llamachile.tube). The repo path, csproj AssemblyName/RootNamespace, DB/log paths (%APPDATA%\ytLlive\...), and most internal namings are the legacy ytLive/ytLlive — a re-brand that never renamed the internals. Treat the two as separate: external/user-facing language says "llamacasty", code/assembly/repo names stay ytLive. If a full internal re-brand is ever done, this note and the UI locator (Premium/wordmark) are the checklists; it is NOT a goal pre-1.0.

Say "LlamaCasty" when reporting to the creator — never "ytLive" in prose. ytLive is the internal repo/assembly/namespace name only. Exact current split:

surface	name	note
product / site / marketing	LlamaCasty	llamacasty.com, llamachile.tube
repo dir, csproj, RootNamespace	ytLive	230 files: namespace ytLive.*
AssemblyName → shipped exe	ytLive	ytLive.exe
app data dir	%APPDATA%\ytLlive	capital L, drifts from ytLive
Distribution.md tells customers	LlamaCasty.exe	⚠ mismatch vs the real ytLive.exe

Consequences, so nobody re-hunts them:

• Renaming <AssemblyName> to LlamaCasty is the cheap win (the customer-visible exe name matches what Distribution.md already promises; namespaces can stay ytLive.*). It is 4 lines, but it hard-breaks three pack URIs that spell the assembly name: MainWindow.xaml:14 (the window icon — taskbar/Alt-Tab), OverlayHost.xaml:96, RenameRecordingDialog.xaml:5. Miss those and you ship a broken icon. Queued in TASKS.md under the shipping task, not done.
• Renaming the %APPDATA%\ytLlive folder is breaking — it would orphan every existing user's layout DB, Assets and settings. Never do it casually; needs a migration.
• No code compares its own assembly name (no GetExecutingAssembly().GetName().Name checks), so the assembly name is otherwise free to change.

AI transparency

This project is built through AI-assisted pair-programming. All code is generated under the supervision of an experienced developer with decades of coding experience. Architecture decisions, product direction, and quality gates are human-owned; AI accelerates implementation. This is a testimonial to successful human-AI collaboration, not autonomous code generation.

Run

First time on a fresh clone (or if ffmpeg/ was deleted) — this is REQUIRED, not optional:

./scripts/fetch-ffmpeg.sh   # ~65 MB once; verifies SHA-256, extracts 9 files into ./ffmpeg

FFmpeg is bundled, never downloaded at runtime (Windows Store policy 10.2.2 — the old runtime download 404'd on 2026-09-01 and would fail certification). The binaries are gitignored because 135 MB of DLLs in git would tax every commit on this 9p tree; the pinned URL + SHA-256 in the script are the audit trail. ytLive.csproj's GuardBundledFfmpeg target fails the build with that exact instruction if the folder is missing. FFMPEG_ZIP=<path> reuses a pre-downloaded archive.

# From WSL, ALWAYS use the Windows dotnet host — never Linux `dotnet` for this project:
"/mnt/c/Program Files/dotnet/dotnet.exe" build "C:\Users\gramp\Documents\Code\projects\ytLive\ytLive.csproj"
"/mnt/c/Program Files/dotnet/dotnet.exe" run -c Release   # the launch command (creator, 2026-10-16): Release, not Debug — perf takes must read Release numbers

Run-mode convention (creator directive 2026-10-16): the creator launches with -c Release by DEFAULT. Debug runs happen ONLY when the AI explicitly names the Debug command for a specific reason — never implicitly, and never for reading performance numbers (Debug pixel paths are several × slower; every take in the 141ms saga read Debug numbers where Release is the real reading).

Pre-commit gate (write it down — I forgot once): ALWAYS run ./scripts/verify.sh "<file1>" "<file2>" ... (declared scope) before committing. It forces a clean build (0 warnings), the full test suite (passes only the 2 known pre-existing [FAIL]s), and the scope check in one shot. An incremental build can report 0 Warning(s) while skipping recompiles — that's how CS8601 slipped past on 2026-08-29. Never claim 0 warnings from anything but verify.sh's clean build.

EnableWindowsTargeting=true in ytLive.csproj lets a cold restore work from WSL, but a Linux dotnet run/build re-downloads 100M+ of windowsdesktop.app.* packs into the Linux NuGet cache (which lacks them) over the slow 9p /mnt/c bridge — twice, because the WPF _wpftmp generated project triggers a second restore (203s observed). The Windows cache has the SQLite packages and the packs resolve from C:\Program Files\dotnet\packs, so the Windows host never re-downloads. Never use --no-restore right after an interrupted restore — the stale project.assets.json produces misleading NETSDK1064 "package not found" errors. Running requires Windows anyway.

Tests

xUnit in ytLive.Tests (net8.0-windows10.0.19041.0, matches the app TFM). Run on Windows — WSL can't run net8.0-windows tests:

dotnet.exe vstest "C:\...\ytLive.Tests\bin\Debug\net8.0-windows10.0.19041.0\ytLive.Tests.dll"

Good Dog Rule: ONE integration test per change (no feature branches pre-1.0 — work lands on main, see AGENTS.md). Current: TokenStore DPAPI roundtrip/corrupt/missing/clear, OAuth exchange/refresh/ClearSession, CameraManager refcount + frame pump + failure handling (fakes for the WinRT seams), real-MainWindow round-clip interaction test, LayoutStore delete roundtrip, LayoutStore pre-round-rect-dims roundtrip, LayoutStore background roundtrip, LayoutStore HasBackground roundtrip + v5→v6 non-Live backfill, ScreenCaptureManager refcount + shared-bitmap + coalescing (fake IScreenCaptureSource + a real background-STA Dispatcher), BackgroundTests, SceneCatalogTests, the TASK 25 dirty-layout heal (BackgroundHealIntegrationTests), WebcamSafeguardTests, SceneCompositorTests (full-scene composite + vertical tier), StretchMathTests, FfmpegLocatorTests, FfmpegEncoderTests, FramePumpTests, the TASK 8/11/12 audio chain (AudioPipelineTests + MasterLimiter), the Socials fediverse-heal roundtrip, AboutHubTests, NotificationAreaIntegrationTests (TASK 24), GlobalHotkeyTests + HotkeyConfigTests (TASK 20), WebcamMenuGateTests (TASK 26), ChatLayerGateTests (TASK 27), BroadcastPullOutTests (TASK 29), DefaultRecordFolder fallback (TASK 30), WebView2ManagerTests (TASK 17), RecordingFileTests + OnAirSignTests (TASK 18), SessionTeardownTests + WebcamOutputKeyTests + GameMeterHonestyTests (2026-09-01 recording-verification fixes) — ZERO known failures as of 2026-09-01. AudioPipelineTests 25/25 green in 26ms — the "known failing" Mix_HonorsProviderGains… and the class's notorious STANDALONE HANG shared one root cause: TASK 22's _delayedMix (nullable, never initialized) was dereferenced (delayed.Length on null) every live-mix tick — a swallowed NRE starved the pipe the tests read and flooded startup.log. Test was right, code drifted from the map's own contract (loopbackGain = GameAudioVolume — now honored; the "unity because loopback scales with the endpoint" assumption was disproven by the creator's 20%-volume meter observation). The former RoundClip "known failure" (stale-test layers: namescoped FindName + VisualTreeHelper.HitTest where UIElement.InputHitTest models input — see MyMistakes) was fixed the same day. Per-class runs through the Windows dotnet.exe host execute the RealApp/MainWindow suites fine; only the FULL-suite run still hangs (WASAPI teardown, pre-existing) — and the whole-suite "247 total" era count is stale; trust per-class results.

Reward-event capture (monetization awareness, see the Monetization section) will add its integration tests here when it ships: one real chat-poll payload containing all seven reward event types → assert the persisted canonical RewardEvent rows (type + amount/currency/tier/memberLevel/participant ids) round-trip into SQLite.

Launch POSITION is derived, never restored (2026-10-04)

Creator ruling: the window must open in the upper-left of its screen with ~75px padding, because the restore path was putting it below the fold. MainWindow.RestoreWindowGeometry now ignores the saved position entirely and calls the pure TopLeftPlacement(workArea, w, h, padding), which takes the work-area origin plus LaunchPadding = 75 and clamps so the window is never pushed off-screen: a window that fits stays wholly visible, one too big to fit falls back to the work-area origin. LaunchPadding is in device-independent units, so it scales with DPI instead of being a fixed physical pixel count.

Size and maximized state are still persisted and restored — only position was dropped. The clamp still applies to size: saved values are Math.Clamped to [MinWidth, work.Width], which is why a saved 800×500 comes back as 1366×768 (the XAML MinWidth/MinHeight). Reverting this is reverting the one block in MainWindow.xaml.cs; the saved values are still written, so nothing is lost.

Why the old clamp was wrong (do not "fix" it back): it tolerated Left as low as work.Left - width + 120 and Top up to work.Bottom - 80 — ranges wide enough to leave the window almost entirely off-screen while still looking like a successful clamp. A clamp that permits the window to be ~unreachable is worse than no clamp, because it reads as a guarantee it does not keep.

BroadcastPullOutTests.Metadata_Persists_Window_Launches_TopLeft_And_UpdatePatchesRemote (renamed from ..._WindowRestores_Clamped_...) is the integration guard — it asserts the constructor applies the derived placement for both an on-screen and a wildly off-screen (-99999) saved position. Placement math itself is covered by WindowPlacementTests (pure function, no HWND needed).

Real-MainWindow tests MUST be hermetic (DB pollution bug)

The integration test boots a real MainWindow → MainViewModel → real LayoutStore (%APPDATA%\ytLlive\ytLlive.db). Shutdown() on close saves the layout (full rewrite: DELETE all scenes/sources, re-insert), so any source a test adds would be persisted over the user's real ones — this happened and wiped the real webcam source (DeviceId replaced by the test's fake test-camera). Rule: a test that constructs MainWindow MUST first set MainViewModel.LayoutPathOverride to a temp DB path and reset it (plus SqliteConnection.ClearAllPools() + delete) in finally. The seam is internal static string? LayoutPathOverride (line ~529 in MainViewModel.cs), ytLive.csproj has InternalsVisibleTo("ytLive.Tests").

The layout DB is a full rewrite per save (delete all, re-insert from memory), so save/load round trips are exact: an element removed in the UI (RemoveElement → scene.Elements.Remove → OnElementsChanged → debounced ScheduleSave, plus Shutdown on close) does not come back after reload (LayoutStorePersistenceTests guards this).

Architecture

C# / WPF (.NET 8) following MVVM:

Path	Role
Models/	Plain data types — Scene, Source (incl. ClipShape, IsMirrored, VideoImageSource), QualityOption, StreamConfig, StreamHealth, YouTubeChannel, ChatMessage, Socials (SocialService enum + SocialEntry/SocialsConfig + SocialServiceIcons) — the social bar
ViewModels/	MainViewModel — public partial class, one file per functional area (Scenes, Background, Webcam, Audio, Trax, Socials, Streaming, Chat, Overlays, Account, License, Recording — split complete, see ViewModels/index.md); Chat.cs is a thin delegating facade over Services/ChatOverlayLayer.cs (Commit G, first true decomposition), and now also over Services/AlertOverlayLayer.cs (TASK 43 — the native alert box, same true-component pattern); GoLiveViewModel, ReuseImageViewModel, CameraPickerViewModel, SocialsDialogViewModel
Services/	YouTube OAuth2, stream/broadcast management, live chat polling, LayoutStore (SQLite), SocialValidator (ISocialValidator seam + HttpSocialValidator default), webcam: VideoFrame seam + CameraDeviceInfo/ICameraEnumerator/ICameraFrameSource interfaces + MediaCaptureCameraEnumerator/MediaCaptureFrameSource (WinRT) + CameraManager, screen capture: IFullScreenDetector/Win32FullScreenDetector + IScreenCaptureSource/ScreenCaptureFrameSource (WinRT GraphicsCapture) + ScreenCaptureManager + ScreenCaptureSourceFactory + Direct3D11Helper/CaptureInterop (COM bridges), media source: IMediaFrameSource + MediaVideoSource (spawns ffmpeg rawvideo BGRA decode) + MediaVideoSourceManager (refcount-by-path session owner) + pure RawVideoFrameReader + IDecodeProcess/FfmpegDecodeProcess process seam (binary-stdout mirror of IEncoderProcess; see "Media source"), compositor: SceneCompositor + CompositorOptions + pure StretchMath + StaticPixelCache (see docs/ai/frame-pipeline.md → "Scene compositor"), alerts: ChatOverlayLayer + AlertOverlayLayer/AlertRenderer (the native celebration-zone overlay, TASK 43 — see "Native events & alerts"), audio: IAudioSource seam + WasapiLoopbackAudioSource/WasapiMicAudioSource (NAudio WASAPI) + AudioMixer + pure AudioLevelMeter/WaveToFloat/VoiceFilterChain/LowShelfFilter/HighShelfFilter/NoiseGate/Compressor/AutoDucker/AudioRingBuffer/TinyResampler/AudioSyncDelay + MusicPlayer + ITraxPlayer (TRAX toggle seam — FakePlayer in tests; the dot is green/red/gray and the error scrolls terse in the desktop-audio bar; MusicVolume fixed 0.5) + IAudioPipeWriter/NamedPipeAudioWriter (see "Live audio capture"), encoder: IFfmpegEncoder/FfmpegEncoder + IEncoderProcess/FfmpegEncoderProcess + IFfmpegLocator/FfmpegLocator + pure FfmpegArgs/FfmpegProgressParser/FfmpegEncoderPicker + the FramePump frame producer (see "Live encoder" + docs/ai/frame-pipeline.md → "Live frame pipeline"), notifications: INotificationService seam (AppNotificationSeverity Info/Success/Warning/Error) + NotificationService (Notification.Wpf toasts, see "Toast notifications")
Helpers/	ViewModelBase (INotifyPropertyChanged), RelayCommand, ImageCache, AppLog (file logger), FocusPreservingListBox, OAuthCredentials, TokenStore (DPAPI session persistence), BuildStamp (wordmark release counter #N, +1 per commit, generated by GenerateBuildStamp in ytLive.csproj via git rev-list; the per-build GUID now logs to startup.log only — 2026-09-04), visibility converters
Themes/	Controls.xaml — the single dark-theme source, merged once in App.xaml (see Themes/index.md)
MainWindow.xaml	Dark theme; layout: top bar (controls), center (preview + live controls below), left (scenes/sources), right (chat), bottom (gear + stream stats + resolution)

Key patterns

• ViewModelBase.SetProperty<T>() for property change notifications
• RelayCommand for all button actions; commands gate on state (e.g. Start only when Offline). Typed CommandParameters — no stringly-typed command tokens: menu items that pick a source type pass the enum value itself (CommandParameter="{x:Static models:SourceType.DisplayCapture}"), so a typo breaks the build instead of silently adding an Image; AddSource still falls back to Enum.TryParse<SourceType>(..., true) for safety. The webcam item is its own AddWebcamCommand (it greys out via CanAddWebcamToActiveScene and isn't a SourceType — webcams are WebcamSceneConfig, not Source rows)
• Audio is KISS by rule — the whole of audio is one knob: desktop/game audio is automatic (WASAPI loopback from the default output at unity, zero UI — "it just is"); the mic is the creator's only audio control — sound meter + mute button + volume slider (MicVolume, defaults to 0.8) all sit together on the second line of the preview bottom row, BELOW the Socials+TRAX row, CENTERED beneath the preview panel. The TRAX button + Desktop Audio meter sit on the first line of that same row. Meter: 288px, muted slate track (#3a3b52) with ruler graduations and muted yellow/red zone tints at 60%/80%; fill = green → yellow → red via MeterFillWidth/MeterBrush; the meter is a READ-ONLY realtime level display — it shows the live input level scaled by the volume (raising the volume moves ambient noise up the bar), NOT the volume setting: the fill is Math.Min(1, AudioLevelMeter.ToDisplay(AudioLevel) * MicVolume) — ToDisplay maps the raw linear RMS onto a −60..0 dBFS display scale, because real speech sits around −40..−20 dBFS (0.01..0.1 linear) which would leave a flat scale dead (AudioLevel is fed by the audio mixer once capture lands, 0 with no input) and 0 while muted. While the volume slider is being dragged the bar previews the slider position (SetVolumeAdjusting, from PreviewMouseLeftButtonDown/Up + LostMouseCapture handlers) so the creator sees where they're setting it; on release it returns to the live level — with no input it bounces back to 0, exactly as it does today. Clicking the meter does nothing; clicking the MIC label opens the mic picker (OpenMicPickerCommand), and the picked voice source name (MicSourceName) is shown left-justified INSIDE the meter bar (FontSize 10, ellipsized to the bar) — the fill runs at 75% opacity so the text and the ruler markings stay visible through it. Mute (ToggleMicMuteCommand/MicMuted) is a plain clickable speaker icon (MicSpeaker_MouseLeftButtonUp code-behind handler — not a Button, Stretch="Uniform" so the glyph is never clipped) that swaps to a red do-not-symbol (slashed speaker) when muted. The slider and the speaker can never disagree: MicMuted is read-only, derived from MicVolume == 0 — sliding the volume off flips the speaker to muted (storing the prior level in _volumeBeforeMute), sliding it up from 0 clears the mute indicator (and the stored level); the speaker button just runs the volume to 0 or restores it (default 0.8 if unknown). Muting zeroes the meter; unmuting flashes the meter to the restored position for ~300ms (BeginVolumeFlash/EndVolumeFlash on a DispatcherTimer, cancelled if the slider is grabbed) before it returns to the live level. Line 2 of the footer holds everything else: stream stats (bitrate/fps/dropped/duration/health) on the left, quality dropdown + gear on the right. The slider is a slim dimensional style in Themes/Controls.xaml (gradient track, beveled green fill on a 5px pill, gloss-sphere thumb with drop shadow — deliberately NOT flat). No device pickers (never show device names — no "install a device you didn't know existed"), no filter stacks, no monitoring, no routing — OBS's confusion (dynamic mixer, unintuitive names, four required filters) is deliberately absent. A production-ready mic chain (high-pass → noise gate → compressor) will be applied invisibly in the mixer, unconfigurable. Capture runs only while live (privacy indicator stays off otherwise). Capture pipeline = IAudioSource seam + NAudio WasapiCapture/WasapiLoopbackCapture + AudioMixer (pending — the UI is in place now). Mic mute icon (2026-08-13): a second 16px clickable glyph — a microphone, red + slash when muted — sits between the meter and the speaker (both mutes adjacent, spacing between the icons) and reuses the same MicSpeaker_MouseLeftButtonUp → ToggleMicMuteCommand handler. REC / ON-AIR pills + signs (TASK 18, 2026-08-29): the top-center area is now two sliding pill toggles (intent) next to two status signs (reality). REC pill (RecordPillOn) is the local-recording intent — works signed-out; ON-AIR pill (OnAirPillOn) is the streaming intent — greyed/disabled until IsConnected. The REC sign (RecDotBrush/RecTextBrush/RecDotOpacity) is dark-gray + dim offline and green-tinged, pulsing only while actually recording (IsRecording), not merely pill-on. The ON-AIR sign (OnAirBrush = #555 offline, #22c55e live) is green while actually streaming (IsLive); the PRIVATE badge (IsLivePrivate) still shows when the broadcast is private. Both sign labels share the StatusSignText style (Themes/Controls.xaml) so REC and ON-AIR can't drift apart — status color lives on the dot only, never the label. The elapsed timer shows while IsLive || IsRecording. The connected account's avatar/name shows in the top bar next to the primary button (AccountAvatarUrl/AccountDisplayName via SyncConnectedAccount), so the creator always sees WHICH account will go live.
• ViewModels are constructed in XAML (<vm:MainViewModel/> as DataContext)
• True decomposition beats partial-shuffling (2026-08-31, Commit G): MainViewModel is a ~4100-line god-object split into 17 partials — but partials are a myth of decomposition: every partial shares the same class, same SetProperty state, same collaborators via Scenes/StagedScene/IsLive/Source.VideoImageSource, so an AI fetching one partial still reconstructs the whole class. The only thing that actually improves retrieval is a boundary where a feature owns its own state + collaborators. Services/ChatOverlayLayer.cs is the model (extracted from MainViewModel.Chat.cs 194→44): the layer owns the message buffer, ChatBoxRenderer, fade/mock timers, preview renders, and the live RenderFrame; the VM keeps only the binding surface (ChatMessages delegates to _chatLayer.Messages so XAML + LeftPanel CollectionChanged hold; the two computed gate props stay on the VM because their OnPropertyChanged is raised from VM setters). Services/AlertOverlayLayer.cs (TASK 43, 2026-09-24) is a second true component built fresh on the same contract — it owns the event queue, the 33ms playback ticker, the per-source preview renders and the live RenderFrame, with Advance(double) exposed as the deterministic test clock; the VM again keeps only the facade (RenderAlertBox, UpdateAlertBoxPreview, CanAddAlerts). Two COMPONENT layers, one facade partial. Diagnostic — glue vs. component: before extracting, count OnPropertyChanged/SetProperty touches (glue) and bound-property reads per partial. Zero/low-glue + a cohesive state blob (renderer/timers/buffer) = extract (chat). High glue over an already-extracted service (Audio, Webcam, Background, Scenes — AudioMixer/CameraManager/ScreenCaptureManager/ChatBoxRenderer already exist) = leave as VM glue; forcing it adds coupling, doesn't remove it. Don't manufacture seams to hit a line count — the line count is a guideline for context, not a design goal.
• SceneGraph component + baked-crust compositor (TASK 31): Services/SceneGraph.cs owns the scene collection (Scenes — the ViewModel's Scenes property delegates to it) and the element mutation surface (AddElement/InsertElement/RemoveElement/MoveElement, each invalidating the bake cache) plus queries that were scattered LINQ (GetBackground/GetWebcam/GetChatBoxes/GetSplitPoint/IsStatic). Elements expose ElementKind Kind (Static = images/background art, Dynamic = webcam/live capture/chat/web). The split point is the index of the first dynamic element; SceneGraph.GetBakedBase bakes/caches all static layers below it (keyed by scene id + static element identities), and SceneCompositor.BakeStaticBase/CompositeLayers/the Render(.., staticBase, split) overload composite the dynamic/above-split layers per frame. FramePump.RenderScene uses the optimized path when a SceneGraph is wired in (falls back to full render without one). Invariant: dynamic-only pixel changes never invalidate; static layout/opacity/visibility/asset changes do (via InvalidateBake from the VM's element-property and background-heal paths). Defensive deviation from the TASK 31 spec: ChatOverlayLayer keeps taking IEnumerable<Scene> instead of depending on GetChatBoxes() — it is deliberately decoupled from the graph (its doc comment says "without owning the scene graph"); and the static background helpers (EnsureBackground/NormalizeBackgrounds) stay on the ViewModel because BackgroundTests.cs unit-tests MainViewModel.EnsureBackground directly. Queries + invalidation moved; helpers stayed.
• Services are currently instantiated in MainViewModel's constructor — no DI container yet
• Layout persists to SQLite (Microsoft.Data.Sqlite); scenes/sources/asset bytes stored in the DB, asset identity is a SHA-256 content hash (1:M reuse, no file paths — assets are always available). Loaded sources always derive IsBackground from Type (OR'd with the persisted column, so legacy DisplayCapture backdrops keep their flag) — pre-derivation rows with IsBackground=0 heal on load
• Element z-order is a unified space, not per-table (2026-09-20): Source and WebcamSceneConfig live in different tables, and a webcam can be interleaved between sources in a scene. Both tables' SortOrder is stamped from the SAME counter — the element's index within scene.Elements — and Load merges the two tables' rows per scene by that shared z (tie-break sources-first, so legacy per-table rows read back stacked the way they were saved). Never re-introduce per-type sort counters + "append all Sources then all configs", or a webcam slotted mid-stack reverts on reload (creator-reproduced bug).
• Five-scene catalog (Models/SceneCatalog.cs): the product is exactly Starting/Live/BRB/Chat/Ending — work with less, never more (the escape hatch for "more" is OBS). Scenes are matched by name (SceneCatalog.Is, case-insensitive trim). Empty DBs seed all five; the scenes-header "+" (ShowAddScene/MissingScenes on MainViewModel) only appears while ≥1 canonical scene is missing and its menu lists only the missing ones, re-adding them by name (AddSceneCommand). Renaming a canonical scene makes it missing again; AddScene rejects non-canonical names.
• Theming: all custom styles live in Themes/Controls.xaml, merged in App.xaml — never duplicate styles per-window (dialog duplicates were consolidated into this dictionary). Every control in the app carries a theme style (TASK 58, 2026-10-21): an unstyled ComboBox/CheckBox falls back to the light WPF system template (grey border, system arrow, white popup list) and sticks out of the dark panels — the properties panel's drop-downs had been hand-painted with a Background/Foreground instead of a style (the chat Font drop-down was a copy of that), and every check box was default. The rule now: ComboBox → YtComboBox, CheckBox → YtCheckBox, the dense properties fields → YtTextBoxCompact (BasedOn YtTextBox: 11px, padding 4,2) — no hand-painted Background/BorderBrush on a themed control. ytLive.Tests/PropertiesStyleTests.cs is the guard: it fails if an unstyled drop-down, check box or properties field comes back — but that guard sees only those three control types, so a picker built as something else (a Button + a code-built ContextMenu) slipped through it and the creator had to ask twice (TASK 63)
• The properties panel is a HIERARCHY (TASK 59, 2026-10-21): a title owns its content, and the content is indented one level (10px) under it — the creator's ruling: "the 'drag to move' help text needs to be indented under 'Mirror Rect' to show parentage … same with Geometry, Border Color, Border Thickness … Remove should be indented under Background as should Blur … Strength should be indented under Blur." So the webcam's block reads Shape (the mirror switch + the shape choice) → Geometry → Border Color → Border Thickness → Background (Remove, Blur, and Strength one level deeper under Blur), each title SemiBold at 11px #a0a0b0 like the existing ones. The shape is a CHOICE, not a toggle button: IsRectShape/IsRoundShape on SceneElement are two settable bools and the panel shows them as two SegmentToggle options (Rect | Circle) with Rect selected by default (an element that never picked a shape is a rect) — the old single button showed the next action ("Round"), which is why the creator could not tell what the camera was. The mutual exclusion lives in the MODEL (each setter flips through ToggleClipShape() and both props are re-raised), not in a WPF RadioButton group — a RadioButton group unchecks its siblings by setting IsChecked in code, which silently kills the binding (stackoverflow 7376373). Each setter always re-raises, so a refused write (the vertical Chat layout is rect-only) makes the UI snap back. Guard: ytLive.Tests/PropertiesHierarchyTests.cs
• One list for the offered colours (TASK 60): the border-colour drop-down builds its menu from Models/BorderColorPalette.cs (NamedColor(Hex, Name) + NameOf(hex) — empty for a colour outside the palette, "no name" being the honest answer), NOT from a list inside the click handler — the creator asked for a colour NAME next to each hex (#e94560 Crimson), and a hard-coded string[] cannot carry one. A palette the creator may want to extend belongs in a testable catalogue, with the UI as a consumer. TASK 62: the field that shows the current colour shows the name beside it too (SceneElement.BorderColorName), and the hex field keeps a fixed width so the name stays next to the hex instead of drifting to the row's far edge
• A picker IS the app's drop-down (TASK 63, 2026-10-21): the border colour is now a YtComboBox — the same widget the Display and Font pickers wear — not a ... button that built a ContextMenu in code. The creator's complaint ("one of the first things we did was define branding. We established look-and-feel standards. And yet you keep ignoring these") had a precise cause: the TASK 58 sweep looked for ComboBox/CheckBox/TextBox types, and the border picker was neither — it was a hand-rolled Button + code-built menu, so it was never in scope, and the guard could not see it. Lesson: a style sweep must ask "is this the app's widget?", not "is this control type themed?" — anything hand-rolled that looks like a picker (a button that opens a menu) is invisible to a type-based guard. The hex field stays (a custom colour can still be typed); the drop-down carries the swatch and the colour's NAME, the rows carry swatch + hex + name. Guard: ytLive.Tests/BorderColorPickerTests.cs
• A ComboBox's CLOSED box and its ROWS can differ — only through a template selector (TASK 63): WPF copies ItemTemplate into SelectionBoxItemTemplate, and that property is read-only in C# ("Property or indexer 'ComboBox.SelectionBoxItemTemplate' cannot be assigned"), so a plain ItemTemplate renders the SAME content in the closed box and in every row. The one mechanism that tells the two apart is an ItemTemplateSelector: WPF calls it with the ContentPresenter's templated parent — the ComboBox when the closed box renders, the ComboBoxItem when a row renders. Helpers/ClosedBoxTemplateSelector.cs does exactly that (ClosedTemplate for the ComboBox, RowTemplate for the ComboBoxItem). A ComboBoxItem.ContentTemplate set through an ItemContainerStyle does not work: WPF overwrites the container's ContentTemplate with the ComboBox's ItemTemplate (null) — so use the selector.
• The theme's drop-down popup sizes to its CONTENT, not to the ComboBox (measured 2026-10-21): the YtComboBox popup carries no width binding, so the pop-up is as wide as its widest row (measured 142.7px for the border-colour rows against a 100px ComboBox) — a row is never clipped, and the popup may be wider than the closed box. Measure (RenderTargetBitmap/ActualWidth in a throwaway test), don't guess. And a Popup's visual root (PopupRoot) has a null visual parent (VisualTreeHelper.GetParent(popupRoot) == null) even though PopupRoot IS a Visual: its only link back to the Popup and the owning ComboBox is LogicalTreeHelper.GetParent. Any ancestor walk used by a window-level click-outside guard (LeftPanel.IsDescendantOf) MUST fall back to LogicalTreeHelper.GetParent(child) when VisualTreeHelper.GetParent(child) returns null, or clicking a ComboBoxItem inside PART_Popup looks like an outside click and deselects SelectedElement before the item click registers (fixed 2026-10-22).
• A field in a dense panel carries a FIXED width (TASK 61): a WPF element sizes itself to its content, and in a DockPanel the last child fills the row — so a row of same-kind fields looks broken unless every field has an explicit Width AND the row sets LastChildFill="False". The geometry fields are 44px: the measured width of -1920 in the app's font at 11px (via WPF's FormattedText — measure, don't guess) plus the field's padding and border. Guard: ytLive.Tests/GeometryFieldWidthTests.cs
• Resolution tiers: 1080p60@8 (default) → 1080p30@8 → 720p60@6 → 720p30@6 → Vertical 1080p60@8 (9:16, 1080×1920). The composition master frame is always 1920×1080 — a tier is an output rect + target resolution over that master, so source geometry is never rewritten (no rounding drift). 16:9 tiers use the full frame; the vertical tier uses a centered 607×1080 window and the preview dims the cropped side strips at 55% black with an accent outline (semi-crop — the cut area stays visible). A resolution badge in the preview corner shows the active tier. Bottom bar: gear icon far left, stream stats (bitrate/FPS/dropped/duration) centered under preview, resolution dropdown far right. A tooltip explains finding upload bandwidth — an in-app speed test was deliberately dropped (unreliable). The future encoder crops the master to the rect and scales to the tier's Width×Height
• Crash diagnosis: AppLog writes startup checkpoints to %APPDATA%\ytLlive\startup.log; App.xaml.cs logs DispatcherUnhandledException/AppDomain.UnhandledException. When WPF won't run from WSL, this log is how you find the failure (it caught the MenuItemRole.Separator XAML crash and the ComboBox SelectionBoxItem bug). The log is SIZE-CAPPED (TASK 55, 2026-10-22): at 5 MB startup.log rolls to startup.1.log (one rolled copy kept) — the policy lives in Helpers/LogRotation.cs as a pure function over a path, so AppLog's 156-call-site surface never changes and the rule is testable on its own. Guard: ytLive.Tests/AppLogRotationTests.cs

⚠️ Known issue: screens/layers settings audit — RETIRED INTO THE GOLD PASS (2026-08-22, dispositioned 2026-09-01)

The AI hallucinated through multiple commits that night on background/scene property placement, repeatedly misreading the spec and introducing bugs. Specifically: moved properties to the wrong superclass level, used new instead of override breaking WPF bindings, removed working code, and added UI elements that weren't spec'd. The audit was never run since. The creator ruled (2026-09-01): it is a going-gold requirement, not session debt — the fine-tooth-comb pass (every screen's Background layer properties, pill toggle persistence, context menu visibility, "Add Layer"/"(+)" menu items) is a named checklist item under TASK 36 (gold pass) and this landmine is closed here.

Current limitations / TODOs

• Helpers/OAuthCredentials.cs contains the real ClientId/ClientSecret. Auth is complete and the session persists via Windows DPAPI (Helpers/TokenStore.cs → %APPDATA%\ytLlive\ytLlive.auth, CurrentUser scope), reloaded best-effort at startup with a proactive refresh of a near-expiry access token. Sign-in/Change Account lives inside the Start Stream dialog (two-state flow — no separate Connect button). Sign-out is explicit only, and that means Logout — NOT Change Account: StopStream() does NOT clear the session — TASK 18's 2026-08-29 reversal ("stopping a recording leaves the creator signed in") — the older "graceful End signs out" line here was stale and is corrected against the code (2026-09-01). YouTubeAuthService takes an optional HttpClient + sessionChanged + openBrowser callback (test seams + save hook; services are still constructed in MainViewModel). Change Account must never sign out first (fixed 2026-09-27): it used to await SignOutYouTubeAsync(); await SignInAsync();, and since SignOutYouTubeAsync → TokenStore.Clear() deletes ytLlive.auth, cancelling in the Google chooser left the creator logged out of a working account. It is now just await SignInAsync() — success overwrites the token via the sessionChanged hook, cancel/failure leaves the session untouched. The OAuth flow also releases its loopback callback port on retry: abandoning the browser leaves the attempt holding localhost:8765 for its 5-minute timeout, so a new AuthenticateAsync cancels and awaits the abandoned attempt before binding, serialised by a SemaphoreSlim (_authGate) — without that gate, two overlapping calls both see a free port and race to bind it (the exact failure the takeover prevents)
• Google Cloud project ownership (recorded 2026-09-27, do not re-hunt): OAuth ClientId is 198374416003-s8tm3rb5csh91quvlg6mnec6srmrr6md.apps.googleusercontent.com, so the Cloud project number is 198374416003. That project is owned by the llamachile.shop@gmail.com ("gramps") Google account. ⛔ This is NOT the same account as the YouTube channel a creator signs into the app with — console access and channel identity are separate logins, and assuming they are the same was the trap that stalled the search. Direct link that resolves it in one hop: https://console.cloud.google.com/apis/credentials?project=198374416003. If the picker shows no match, it defaults to the "Recent" tab — switch to "All" before concluding the project is missing.
• Scene/source/asset layout + the social bar persist (SQLite, schema v8); the OAuth session persists (DPAPI); the paid-unlock state persists (LayoutStore Settings table — LicenseKey/LicenseValidatedAt/IsPremium, 14-day offline grace)
• YouTubeStreamService manages the variable reusable stream (shipped 2026-08-16): GetOrCreateReusableStreamAsync lists liveStreams?mine=true and reuses the existing cdn.isReusable stream, creating it only on first use (resolution=variable, frameRate=variable); the stream is cached via LayoutStore (SaveReusableStream/LoadReusableStream, Settings table) and bound at broadcast insert (boundStreamId). Health (shipped 2026-08-16): GetStreamHealthAsync(streamId) polls liveStreams?part=status for healthStatus + configurationIssues[] → StreamHealth; the real API nests them under status.healthStatus = {status, lastUpdateTimeSeconds, configurationIssues[]} — the parse accepts that object shape and the legacy flat-string shape (fix 2026-09-22: the object shape crashed every poll with requires an element of type 'String'); banner decision in pure StreamHealthReporter
• Webcam capture is shipped (milestone 1); the live desktop/game backdrop is shipped (ship task #1); the output compositor (TASK 4 ship step 1) is SHIPPED, the FFmpeg locator (TASK 4 ship step 2) is SHIPPED, the encoder + RTMP push (TASK 4 ship step 3) is SHIPPED, WASAPI audio capture (TASK 4 ship step 4) is SHIPPED, frame-pipeline wiring (TASK 4 ship step 5) is SHIPPED, health stats (TASK 4 ship step 6) is SHIPPED, one-click go-live + private-only enforcement (TASK 4 ship step 7) is SHIPPED — TASK 4 (RTMP Ingest) is fully done; full plan in TASKS.md
• StreamConfig defaults (TargetBitrate=6000, Resolution="1920x1080") are stale — the live dropdown drives StreamHealth.CurrentBitrate/FPS instead
• v1 task queue (2026-08-19): tasks 19-23 added for v1 feature completeness; TASK 3.18 (chat box) shipped; TASK 16 (infinity display) shipped; TASK 10 (Polar billing) shipped — steps 1-7 (Velopack bootstrap, PolarLicenseService, license entry UI, LayoutStore entitlement, BrandFlash toggle, startup re-validation, PremiumUrl wired); Velopack update URL pending:
  • TASK 10: Polar billing — license key entry, offline entitlement, brand flash gating, Velopack auto-updates
  • TASK 19/23 merged: Control Surface UX — director's control room, transitions (Cut/Fade/Move), thumbnails above central monitor, edit mode offline only, right panel eliminated
  • TASK 20: Hotkeys (global keyboard shortcuts) — the single biggest UX gap
  • Broadcast metadata pull-out + launch geometry — shipped 2026-08-24 ("Text" tab on the Live screen, see its section below)
  • TASK 21: Media source (video file playback) — starting soon videos, BRB loops
  • TASK 22: Audio sync offset — lip-sync correction for USB mics/capture cards
  • These were identified through competitive analysis and are table-stakes for any streaming software in 2025-2026. Full details in TASKS.md.

Control Surface UX (TASK 19/23 — shipped 2026-08-24, verified by code survey)

The app is a director's control surface, not an editor. This replaces the OBS-style scene list with a TV-control-room metaphor.

Layout: Two-column. Left panel = one panel, two states. Center = thumbnails above central monitor.

• Left panel: When offline (edit mode) → LAYERS + PROPERTIES (same as current, minus SCREENS). When live/recording → YouTube Live Chat (entire panel replaced, never coexists with layers/properties). Mode is implicit (derived from StreamStatus), no toggle button.
• Thumbnails: Five scene previews above the central monitor, 16:9, drag-reorderable. Click = stage (offline) or transition (live). Active scene gets brand-red glow border.
• Central monitor: Shows staged scene (offline, editable in edit mode) or live output (live, read-only). During transitions: compositor-blended animation.
• Right panel: Eliminated. Chat moved to left panel (live mode).
• Edit gating: IsEditMode = StreamStatus == Offline && !IsRecording. When live/recording: all drag/resize, context menus, right-click property adjustments disabled. Gun safety — no accidental edits mid-stream.

Scene reference split: ActiveScene → StagedScene (central monitor target, editable offline) + LiveScene (encoder output). Go Live sets LiveScene = StagedScene. Thumbnail click sets StagedScene (offline) or fires transition (live).

Transitions: TransitionService (new file) — Cut/Fade/Move with configurable duration (default 300ms). SceneCompositor.RenderBlend() blends two scenes' frames. FramePump feeds LiveScene to encoder; during transitions, feeds blended frames. Go Live always = Cut (clean start).

Thumbnails: Scene.Snapshot property. SceneCompositor.Render() at 320×180 → WriteableBitmap. Only staged scene has live backdrop render; other 4 = static snapshots.

Thumbnails: Scene.Snapshot property. Fill = per-scene tile artwork first — each canonical scene's ThumbnailAssetId (an Asset-table image, the creator's CRT-styled renders seeded at heal into the internal DB), else background art; minis never render live captures. The scene currently staged shows the shared on-air image (OnAirImageAssetId setting → Asset row, seed path MainViewModel.OnAirSeedPath) in its tile and it follows the scene swap — "the on-air screen jumps around the top bar" (user ruling 2026-10-10). The Live screen's tile only shows the green placeholder when it is staged and no on-air art is stamped. The strip labels are FontSize 20 (user ruling 2026-10-10); border = #e94560 when staged, #22c55e when live. The preview's own live signal is the outer PreviewGlow red border — NOT the 6px green #22c55e rectangle that previously sat in the BackdropLayer (removed 2026-10-10).

Global hotkeys (TASK 20 — step 1 shipped 2026-08-24)

• Services/GlobalHotkeys.cs: HotkeyId enum (9 actions), IHotkeyRegistrar seam, Win32HotkeyRegistrar (RegisterHotKey, no modifiers), GlobalHotkeyManager. Fixed defaults: F1-F5 canonical scenes, F6 start/end stream, F7 mic mute, F8 desktop-audio mute, F9 TRAX play/pause.
• MainWindow.OnSourceInitialized creates the manager and forwards Activated → MainViewModel.HandleHotkey; window Closed detaches (unregister all).
• MainViewModel.HandleHotkey maps ids to TransitionToScene/start-end commands (honoring CanExecute)/mute toggles/TraxLeftClick.
• Tests: RegistrarOverride static seam mirrors LayoutPathOverride. Landmine: forcing a WPF window's handle with WindowInteropHelper.Handle does NOT raise SourceInitialized and returns Zero pre-show — use EnsureHandle() in tests; it both creates the HWND and fires the event.

Broadcast metadata pull-out + launch geometry (2026-08-24)

The "Text" tab (always visible, 2026-08-24 revision): a white 30px tab with rotated YouTube-red "Text" sits on the right edge of the preview, vertically centered — shown regardless of login/stream state (creator decision; original IsLive gating removed same day). Click toggles the drawer (ToggleDrawerCommand); any left-click outside the form also collapses it (Window_PreviewMouseLeftButtonDown checks TextPullOutHost ancestry), as does the ✕. The drawer is a 320px dark panel over the preview's right edge (200ms CubicEase on Width, BroadcastForm.IsDrawerOpen drives it). The Update button still greys until CurrentBroadcastId exists.

Fields — the always-editable snippet/status set (⚠️ creator premise inverted: contentDetails fields like latency/DVR/embed are editable ONLY in created/ready, NOT while live; they are deliberately absent):

• Title / Description / Tags (comma-separated string → snippet.tags[]) / Visibility ComboBox (private/unlisted/public) / Made-for-Kids CheckBox — all live-editable pre- and post-launch
• Scheduled Start is read-only ("set at Go Live")

Plumbing: Models/BroadcastMetadata POCO; Services/LiveBroadcastFormViewModel (owns field state, persists every edit to Settings keys Broadcast.* immediately via Func<LayoutStore> seam — survives layout re-pointing; owns drawer state; UpdateBroadcastCommand gated by CurrentBroadcastId != null && !IsUpdating). YouTubeStreamService.UpdateBroadcast PUTs liveBroadcasts?part=snippet,status and must echo scheduledStartTime — update replaces the whole snippet part, omitting it clears the schedule. Go Live prefills the dialog from the form (BroadcastForm.Title/Description) and calls CaptureGoLive(title, description, now) on confirm. MainViewModel.CurrentBroadcastId exposes the private _currentBroadcastId; notified on create/end.

The old Default Stream Title/Description (un-persisted, App Settings overlay) are DELETED — the form owns those fields end-to-end; Go Live prefill routes through it.

Launch geometry: default 1920×1040, MinWidth 1366, MinHeight 768, WindowStartupLocation=Manual. Window size/position persist on close via RestoreBounds (+ WindowState Normal/Maximized; Minimized treated as Normal) into Settings keys Window.*; restored in the MainWindow ctor BEFORE show, clamped to the minimums and the primary SystemParameters.WorkArea (a position saved on a since-disconnected secondary monitor falls back on-screen). Multi-monitor restore is not supported yet.

Test seam note: YouTubeAuthService.SetSession() is public — tests inject a channel with future TokenExpiry so EnsureToken() passes offline; pair with an HttpClient(new StubHandler()).

Screen backdrop capture (TASK 3 ship task #1) — model reworked by TASK 25

The Background is a locked per-screen layer (TASK 25): exactly one per canonical scene, always named "Background", pinned at index 0, never addable/removable/reorderable, absent from the (+) menu. Flavor is decided by scene: Live = DisplayCapture (the real-time desktop/game surface with Show Desktop / monitor switch / fullscreen-game detect, falling back to live-background.jpg); Starting/BRB/Chat/Ending = static Background art layers. MainViewModel.NormalizeBackgrounds(scenes) (internal static) heals any loaded layout to this model on every load: keeps the correctly-flavored row (or converts a survivor in place — note Source.Type's setter derives IsBackground, so conversions must re-assert the flag), drops duplicates/stale rows, seeds missing ones via CreateBackground(name), renames, moves to index 0; non-canonical scenes get HasBackground=false and lose any backgrounds. HealBackgrounds() (instance) runs Normalize + stamps default art (StampDefaultBackgroundAsset reads Assets/{scene}-background.jpg pack resources through AddAsset; custom Browse art wins). This replaces the old five-seeder cluster (Seed{Starting,Brb,Ending,Chat}Background, SeedLiveBackgroundAsset, EnsureDefaultBackground) and EnforceBackgroundPolicy.

• Model (schema v6): Source.IsBackground (persisted) marks the one Background per scene; Source.CaptureKey (persisted) names the target — monitor:<n>, window:<hwnd>, or picker:<displayname>. The Live row is a real Source of Type DisplayCapture, inserted first (MainViewModel.EnsureBackground(scene), internal static — also used by the StagedScene setter so a scene switch can never expose a missing Background), fixed at X=0/Y=0/1920×1080, and excluded from drag/hit-test/remove/reorder (remove is guarded in RemoveElement; the element template sets IsHitTestVisible=false for backgrounds; the row's remove button and "Remove Source" menu item are hidden). Scene.HasBackground (persisted) is true for all five canonical scenes (see SceneCatalog.HasBackground). Capture controls — "Change Capture…"/"Refresh Capture"/"Capture Display"/"Show Desktop" — exist only while the Live scene is staged (CanChangeBackground = staged scene is Live; the preview CanvasGrid menu binds it directly, the layer-row menu MultiBindings it with the row's own IsBackground via Helpers/AllTrueToVisibilityConverter). Non-Live screens keep the properties panel pill ("Use default background") + Browse for custom art.
• Settings hygiene: LayoutStore.Save purges orphaned BackgroundUseDefault_{id} / BackgroundPath_{id} Settings keys whose id is no longer a live Source row (TASK 25 heal drops duplicates; their keys must not accumulate).
• Layering invariant (regression lesson, 2026-08-23): ActiveBackgroundImage renders above BackgroundImage, so it is fed by static-art rows only (Type == Background). The capture-flavored Live row must never populate it or it permanently covers the desktop/game capture; Live's canvas shows DisplaySource (capture, falling back to its AssetId art). Flavor-blind IsBackground lookups are for persistence/heal/minis — not this overlay.
• Detection (event-driven): Win32FullScreenDetector hooks SetWinEventHook(EVENT_SYSTEM_FOREGROUND) — fires on the UI thread whenever the foreground window changes. The callback runs the same GetForegroundWindow + DwmGetWindowAttribute(DWMWA_EXTENDED_FRAME_BOUNDS) + MonitorFromWindow + GetMonitorInfo check; a window is full-screen when its frame covers all four monitor edges; own process is excluded; monitor index = EnumDisplayMonitors enumeration order (the same order ScreenCaptureSourceFactory uses to map index→HMONITOR via Win32FullScreenDetector.GetMonitorHandle). IFullScreenDetector also exposes GetDisplays() (DisplayInfo: index/name/resolution/bounds/IsPrimary, friendly name via EnumDisplayDevices) + PrimaryMonitorIndex() for the in-app "Capture Display" submenu + FullscreenMonitorChanged event + StartWatching()/StopWatching(). At launch ReacquireScreenCaptures heals backgrounds (HealBackgrounds()), then keys the Live background to the full-screen game's monitor; when no game is detected, ResolveAutoCaptureKey() returns null — stale CaptureKey values are cleared, no capture session is started, and Source.DisplaySource falls back to _imageSource (the static asset on the backdrop element). StartWatching() is called at the end of ReacquireScreenCaptures. OnFullscreenMonitorChanged auto-redesignates when a fullscreen game appears on a different monitor; null (no fullscreen / own window) is ignored — the existing capture keeps running so loading screens / transitions don't break the stream. RefreshBackdropAutoCapture (bound to "Refresh Capture" context menu + Activated handler) reads the current foreground directly as a manual fallback. Deduplication: _lastReportedMonitor prevents redundant redesignates from rapid foreground changes.
• Capture (WinRT GraphicsCapture): ScreenCaptureFrameSource creates a free-threaded Direct3D11CaptureFramePool (2 buffers, B8G8R8A8UIntNormalized) + GraphicsCaptureSession; frames → SoftwareBitmap.CreateCopyFromSurfaceAsync (alpha ignored) → VideoFrame (BGRA8), bytes read via WindowsRuntimeMarshal.TryGetDataUnsafe (the same CsWinRT-safe read the webcam path uses) — the IMemoryBufferByteAccess ComImport cast threw Invalid cast on every frame under CsWinRT, which flooded startup.log (~5 MB in a session) and burned CPU, so it is gone. Surfaces larger than the 1920×1080 master are downscaled to the master (DownscaleBgra, integer 8.8 fixed-point bilinear — slice 16: the same two-stage math as SceneCompositor.Bilinear; the previous double-per-pixel version was ~30-45ms quiet / ~150ms under 240Hz-HDR load and froze the desktop layer ~90% of a take). Conversions run as up to MaxConcurrentConversions (3) overlapping readbacks (slice 17: the OS readback, not the downscale, is the ~47ms wall — see Slice 17) with a monotonic LatestFrame publish gate (MonotonicGate: a slow OLDER completion can never overwrite a newer frame), and are spaced by a 10ms floor (MinConvertInterval): the monitor delivers at the 240Hz DWM cadence (~4.2ms), far too fast for the ~60/s the pump can use, so the extra arrivals are dropped (skip busy/skip cadence telemetry). Hand-out buffers come from a reuse-distance ring (FrameRingBuffer, depth 8, redLine 4): a buffer is only rewritten ≥4 rents after its last hand-out, else a fresh one is allocated — a frame a consumer still holds (session.LatestFrame survives conversions; the dispatcher preview copy lags) can never be read-while-overwritten (the 1742 tear). Rolling telemetry (frames/s, conv avg/max ms, drops, ring allocs) is logged to startup.log every 2s while converting. Per-frame conversion failures are logged at most once per 5 s (ErrorLogThrottle). DRM-protected content delivers black frames (OS limitation, documented). Frame pool pauses while the app is minimized — capture keeps running, the pool just stops delivering.
• Ownership: ScreenCaptureManager mirrors CameraManager — refcounted by target key, one shared WriteableBitmap per key, dispatcher-coalesced latest-frame copies, PreviewBitmapChanged/CaptureFailed events, ReleaseAllAsync on re-designation. ScreenCaptureSourceFactory.Resolve(key) parses the key into a source; PickAsync() shows the OS GraphicsCapturePicker ("Change Capture…", owner window set via the IInitializeWithWindow ComImport) and returns a transient picker: key — a reload falls back to auto-detection.
• "Capture Window…" — in-app window pin (TASK 38, 2026-09-21): the Live backdrop context menus (PreviewPane canvas + layer-row) offer a submenu listing visible top-level windows of other processes (Win32WindowEnumerator, an EnumWindows pass filtered like Win32FullScreenDetector: visible, non-cloaked via DWMWA_CLOAKED, non-empty rect, other-process, titled). Picking one runs RedesignateBackgroundAsync("window:0x{hwnd:X}") — the same full-bleed layer-0 capture path as the game/desktop, keyed straight into ScreenCaptureSourceFactory (window: already resolved there). Session-scoped, never persisted: window: (and picker:) keys are IsTransientCaptureKey — ReacquireScreenCaptures strips them before auto-detection on every load, because an HWND can be recycled to an unrelated window after restart (resurrecting a dead pin could capture the wrong window). Pin wins while alive: OnFullscreenMonitorChanged skips re-designation while IsAliveWindowPin(current.CaptureKey) is true — the auto game/desktop detector never steals an explicit pin. No dead ends: if the pinned window's capture session dies mid-session, OnScreenCaptureFailed (transient key only) re-runs ReacquireScreenCaptures → auto-fallback (fullscreen game → desktop → static art). Seam: IWindowEnumerator + WindowInfo (Label = "Title — Process"), WindowEnumeratorOverride static test seam mirrors CameraEnumeratorOverride.
• CsWinRT projection gaps hand-rolled: Windows.Graphics.Direct3D11.Direct3D11Helper is not projected, so Direct3D11Helper P/Invokes d3d11.dll!D3D11CreateDevice (hardware, BGRA_SUPPORT, explicit 11.1-first feature array) → QI IDXGIDevice → the WinRT interop export CreateDirect3D11DeviceFromDXGIDevice → MarshalInterface<IDirect3DDevice>.FromAbi (one shared device per process). Do not switch back to the QI-for-IDirect3DDxgiInterfaceAccess trick: the raw D3D11 device no longer exposes that interface on newer Windows (verified E_NOINTERFACE on build 26200, hardware and WARP alike) while CreateDirect3D11DeviceFromDXGIDevice keeps working. IInitializeWithWindow are ComImports in CaptureInterop.cs. All WinRT projections were verified by reflection against the built Microsoft.Windows.SDK.NET.dll before writing the interop.
• Known v1 limits: full-desktop captures are CPU-copied at native resolution (GPU downscale = encoder task); multi-monitor live re-targeting beyond the auto-detected game is behind the picker; picker- and window-pin captures don't survive reload (session-scoped by design — see the "Capture Window…" bullet).
• Focus-loss capture lag (known OS limit, NOT an in-app throttle — deferred): when the app window loses focus the preview visibly slows (mouse-movement lag). Nothing in the repo checks focus to slow capture — the only focus hooks (FullscreenMonitorChanged event + RefreshBackdropAutoCapture) re-target the backdrop, never pace it. The lag is inherited: Windows.Graphics.Capture is content-driven and DWM/OS-throttled while the app is in the background (worse under a full-screen game on 24H2/26100), GPU readback (CreateCopyFromSurfaceAsync) contends with the foreground game, the source's one-in-flight _framePending gate drops frames during stalls, and the manager's DispatcherPriority.Render copies only run as fast as WPF presents the window. Slice 16 shrank the per-conversion stall (fast downscale + 10ms cadence floor) but the OS-level delivery throttle under focus loss remains. Recorded 2026-08-13; no mitigation attempted yet (deferred by user decision).
• GPU posture: same as webcam — CPU frames, WPF hardware-presents; D3DImage GPU compositing deferred to the encoder task.
• Preview watermark: the "Preview" placeholder hides while a background capture renders — ShowPreviewPlaceholder also checks BackgroundImage (raised on change), so a scene with live capture shows the feed instead of the "nothing here" label.

Webcam capture (TASK 3 milestone 1)

• Seam-first: everything above the WinRT layer speaks only VideoFrame (normalized tightly-packed BGRA8) + CameraDeviceInfo/ICameraEnumerator/ICameraFrameSource interfaces. Tests inject fakes; screen capture and background removal later feed the same seam.
• CPU-first: MediaCaptureInitializationSettings { MemoryPreference = Cpu, StreamingCaptureMode = Video, SharingMode = SharedReadOnly }, frames pulled via CreateFrameReaderAsync(colorSource, MediaEncodingSubtypes.Bgra8) — the pipeline does any format conversion, so every FrameArrived yields a ready BGRA8 SoftwareBitmap (bytes read via WindowsRuntimeMarshal.TryGetDataUnsafe, not marshalled copies).
• Reader-output subtype ladder (2026-09-15 webcam-take fix): the reader is created per-candidate by ReaderSubtypeCandidates(activeSubtype) — Bgra8 for uncompressed cameras (fast path), NV12 then source-default for cameras sitting in MJPG. A camera another app left in MJPG mode cannot be read as Bgra8 by a MediaFrameReader (StartAsync → OutputFormatNotSupported; the MJPG pipeline exposes NV12, not BGRA) — exactly what a browser grabbing the webcam produces. When the app can't re-negotiate (our SetMediaStreamPropertiesAsync refuses with "file in use / CaptureMode is SharedReadOnly" under msedge + NVIDIA Broadcast contention), an MJPG-active reader otherwise aborts the whole acquisition. Each candidate is allocated AND started under its OWN catch — WinRT answers an unsupported subtype with a THROW (E_INVALIDARG), not a status; one rejected format must never abort the ladder. Failures degrade to the next candidate; rejections are logged + collected into the final error; only the outer catch nets device-level errors (see MyMistakes.md → WINRT RESOURCE-ALLOCATION RECIPE). Anything not Bgra8 is converted in OnFrameArrived, which already handled non-BGRA software bitmaps.
• Source pick, not first hit: the frame reader is bound to the first source that is VideoPreview (preferred) or VideoRecord, not blindly the first preview source. If a camera exposes neither, the failure names the device and the stream types it does expose. SharedReadOnly lets the capture coexist with other apps that share the camera.
• Known failure: NVIDIA Broadcast — it opens the physical webcam exclusively, so InitializeAsync fails with "camera in use" (or, if init slips through, the device exposes no preview source). Fix: quit Broadcast while streaming, or pick its virtual "NVIDIA Broadcast" device from the picker and the app captures the processed feed. This is a real-device finding (Logitech VID_046D&PID_082D). Correction (2026-10-05): Windows Studio Effects is NOT a second option of this kind — it runs inside the physical camera's own driver, so it never appears as a selectable device. Only tools that install a virtual camera (NVIDIA Broadcast, XSplit VCam) do. "Pick the vcam" is a user action in the camera picker, never an automatic substitution: creator ruling 2026-10-05 — the app must not bypass the user's explicit camera choice, so there is deliberately no fallback-camera setting.
• TFM: net8.0-windows10.0.19041.0 (app + tests) pulls the WinRT projection from the SDK reference packs — no NuGet package, no capability manifest (unpackaged desktop app works; the Windows privacy camera toggle still applies). EnableWindowsTargeting keeps WSL builds working.
• One webcam, many scenes (schema v3) — app-level default (2026-09-17): a singleton Webcam row holds the identity (Id/DeviceId/Name); each scene gets its own WebcamSceneConfig (position/size/clip/mirror/border/IsVisible). Scene.Elements holds images (Source) and, at most once, the webcam (WebcamSceneConfig); Scene.WebcamConfig is the accessor. CameraManager refcounts capture sessions by DeviceId (a session starts at RefCount = 1; repeat acquire bumps it; the last release stops + disposes). The webcam is an app-level resource — ONE selection (the app default), usable in every scene that can host it. "Add Webcam" places the existing default DIRECTLY (no picker); the Windows camera picker runs only for the initial selection (_webcam == null). Choosing a different camera in the picker swaps it app-wide via SwapWebcamIdentityAsync (same path "Change Webcam…" uses). Per-scene gate, not app-wide (TASK 26 superseded by creator directive 2026-09-17): CanAddWebcam = StagedScene is { WebcamConfig: null } && IsWebcamAttainable — a scene holding its own placement greys the row (one webcam per stream), but ANOTHER scene holding one does not, so Chat's camera never greys Live. Attainable means a live lock, not just a saved identity: IsWebcamAttainable = _webcam != null && CameraManager.IsRunning(_webcam.DeviceId) — an identity whose device was unplugged, or whose session can't start, leaves the row greyed with WebcamAddToolTip = "No webcam is currently available…" (identity alone no longer suffices). The max-1 reason gets the gentle "a second camera means you've graduated to OBS" line. Removing a scene's placement keeps the identity (it's the app default; _webcam is never nulled by removal) — Add stays offered for the same camera, because the app holds its own base lock (below).
• Startup resource lifecycle (2026-09-17): the webcam is a resource the app allocates and locks, validated at startup — this answers "why is the WebCam row greyed" from inside the app instead of a DB spelunk. MainViewModel.ValidateWebcamResourceStartupAsync (fired fire-and-forget right after LoadLayout, stored as WebcamStartupValidationTask so tests await it) enumerates the OS once and tri-states on the count: 0 → app runs on, layer inactive, no alarm; 1 → attempt CameraManager.AcquireAsync(device) as an app-wide lock — on failure a persistent red alert (WebcamLockAlert, bottom of the Layers panel with a Retry button) re-polls every 5 s (_webcamLockPollTimer) until a lock succeeds, and any first real frame also clears it; ≥2 → deliberately no auto-lock — selection belongs to the App Settings dialog (gear) queued — TASK 40 Unit A (App Settings round, plan saved 2026-09-22). The single-camera branch always acquires (it no longer skips when configs already hold the session): that acquire is the app's own BASE ref, so removing every scene's placement leaves RefCount = 1 and the session alive — the gate stays satisfied and the Web Cam row stays offered, i.e. the app default outlives the scenes that render it. Acquire on a running session just bumps the refcount. CameraManager.IsRunning(deviceId) = a session exists (started OR still starting — a mid-start session is not "locked yet", it's in flight), and a rolled-back (failed) session leaves the dictionary so the pass can retry. After a successful single-cam lock, the pass adopts the camera as the app default if no identity exists yet (fresh layout) — the Web Cam layer is then offered in Live/Chat immediately (CanAddWebcam true); an already-loaded identity is never overwritten. Test seams mirror LayoutPathOverride: CameraEnumeratorOverride/CameraFrameSourceFactoryOverride let WebcamStartupResourceTests drive the probe without real hardware (0-cam no-alarm, 1-cam locked → identity adopted, lock-fail → alert → clears on retry). Attribution correction: the "NVIDIA Broadcast opens the webcam exclusively" failure below is a suspect-list claim — CameraConflictProbe reads only running process names, no device handles; contention symptoms fit shared-mode/bandwidth just as well (see MyMistakes.md). The YouTube Chat layer follows the same one-per-layout rule (TASK 27): CanAddYouTubeChat greys out the (+) item while any scene carries a ChatBox source (raised on staging + elements change; AddSource refuses a second as defense in depth). Chat layers created before the "YouTube Chat" default still carried the legacy name "Chat" (commit 65641d8 era) — LoadLayout heals exactly that un-renamed default to "YouTube Chat"; creator renames are untouched.
• Round→rect restores the aspect (persisted, schema v4): SceneElement.ToggleClipShape() snapshots the rectangular Width/Height into public RectWidth/RectHeight before going Round and restores them when switching back — otherwise the Round resize lock (square) would leave a square behind. The rect dims are persisted (WebcamSceneConfig.RectWidth/RectHeight, nullable), so a reloaded Round webcam still restores its pre-Round aspect instead of staying square. A one-time HealLegacySquareRect (load only) widens a pre-v4 Traditional config that ended up square to 16:9 (keeps height; Round and explicit rect dims are untouched).
• Device swap / layout reload: ChangeWebcamAsync (picker) and ReacquireWebcam (after load) release the old device with ReleaseAllAsync — a forced full drop that zeroes the refcount and stops the source regardless of how many scenes held it (the per-config count isn't known once the scenes are replaced) — then AcquireAsync the new device once per config.
• Shared bitmap, coalesced updates: one WriteableBitmap per active camera, created on the UI thread at the device's frame size (first frame), forwarded to every WebcamSceneConfig.VideoImageSource via PreviewBitmapChanged. Frames arrive on a worker thread; CameraManager coalesces onto the dispatcher (at most one pending copy per session, at Render priority, always copying the latest frame) so a 60fps device never drowns the render thread.
• Webcam added mid-session must get the live frames: PreviewBitmapChanged fires once (the first frame creates the shared bitmap); later frames only mutate that bitmap in place, so a config that didn't exist at first-frame time would never receive it — the empty/transparent container you'd see adding a webcam to Chat while Live already had the camera. CameraManager.GetPreviewBitmap(deviceId) exposes the current shared bitmap; AddWebcamToActiveSceneAsync assigns it to the new config right before AcquireAsync, and ReacquireWebcam re-propagates it to every config after a reload.
• Clip/mirror/border: per-element ClipShape (Traditional rectangle / Round ellipse) + IsMirrored (ScaleX = -1) + the OSB-standard static border (BorderColor #RRGGBB or ""=none, BorderOpacity 0–1, BorderWidth 0–20, BorderAnimation None|Pulse|Chase|Rainbow|Shimmer|MarchingAnts|Glow| Electricity|Sparkles). Rendered in the preview DataTemplate; toggled from the element's right-click context menu (webcam menu: Change Webcam…, Border Effect submenu — all 9 items enabled, values persist, rendering stays static until the animation tier ships — Border Color, Opacity/Thickness sliders, Hide in this scene, Remove); persisted in the layout DB. The Add menu shows when no webcam exists; the empty preview canvas has its own Show Webcam entry.
  • The Round webcam is an Image Stretch="UniformToFill" with an EllipseGeometry clip (Center=0.5,0.5 RadiusX/Y=0.5), inside a Viewbox Stretch="Uniform" holding a 1x1 Grid, so it renders as a true circle (diameter = the shorter element dimension) instead of an oval stretched to the element rect — the traditional Image keeps UniformToFill over the full rect. The clip is geometry, not an ImageBrush: a brush re-rasterizes the frequently-updated WriteableBitmap per frame on the render thread, which is what made the live webcam crawl while round. The Round border is a centered Ellipse at Width/Height = RoundBorderSize.
  • Resizing locks to a square (_resizeAspect = 1) while ClipShape == Round.
  • Webcam size clamp: ClampWebcamToBounds(config, sceneName) (internal — test seam) enforces the max per dimension at resize + load and no less than 10% of the master (192×108). The cap is picked by canonical scene name: 50% per dimension (960×540) everywhere except the Chat scene, which may reach half the screen area (~1358×764 @16:9) so the viewer sees the creator better (MaxWebcamWidthFor/MaxWebcamHeightFor; a renamed Chat loses the bigger cap). RoundBorderSize follows the clamped height. WebcamSafeguardTests guards the clamp.
  • Hit-testing: a Grid without Background only hit-tests where its children draw, so clicks in the empty corners of a round clip fell through to Window_PreviewMouseLeftButtonDown and deselected the element — making the corner handle ungrabbable. The element Grid carries Background="Transparent" (whole rect draggable; the empty canvas Grid uses the same trick for right-click Show Webcam) and the SelectionOverlay (dashed border + corner dot) is IsHitTestVisible="False" so it never intercepts the click. Two things make the webcam menu work: (1) the ContextMenu pins its own DataContext to PlacementTarget.DataContext — a ContextMenu isn't in the visual tree, so without it the Click-handler DataContext: patterns (and the IsChecked/slider bindings) silently fail; (2) Themes/Controls.xaml ships a full dark MenuItem template — PART_Popup (submenu popups), a popup ItemsPresenter (the Border Opacity/Thickness sliders live in Items, so they render in a hover flyout), a ✓ checkmark column, and a › arrow driven by HasItems. An earlier bare Border + Header template dropped all three: submenus never opened, sliders never rendered, checkmarks never showed — the menu looked dead even though the Click handlers were fine.
• GPU posture: webcam frames are CPU (GPU-agnostic; WPF hardware-presents the preview anyway). Hardware encoders (NVENC/AMF/QSV) matter for the encoder task, not capture. D3DImage GPU compositing is deferred to the encoder task.
• Background removal — REVERSED, now IN for v1 (creator ruling 2026-10-08, TASK 51). The 2026-10-05 "permanently out" ruling stood on "an in-app model means a runtime, a GPU/driver matrix, and per-scene tuning". The delivery shape changed: a ~430 KB Apache-2.0 model embedded in the exe, run on the CPU by onnxruntime — no download, no GPU requirement, no driver matrix. NVIDIA's Video Effects SDK stays ruled out (RTX-only + ~1 GB user-side download). See "Webcam background effects" below and TASKS/task-51-webcam-bg-effects.md.

Webcam background effects (TASK 51 — built 2026-10-09; jitter fix 2026-10-09)

• Model: Google's MediaPipe Selfie Segmenter, landscape (Apache-2.0, model card 2021-05-06), official file storage.googleapis.com/mediapipe-models/image_segmenter/selfie_segmenter_landscape/ float16/latest/selfie_segmenter_landscape.tflite. Converted to ONNX by our own tools/selfie-seg/convert_tflite_to_onnx.py (the graph ends in MediaPipe's custom op Convolution2DTransposeBias, which tf2onnx/tflite2onnx can't convert — 11 op types, so a direct translation was smaller than any workaround). Verified against Google's own runtime: verify_against_mediapipe.py feeds the same frame to MediaPipe's ImageSegmenter (original .tflite) and onnxruntime (our .onnx): max |diff| 5e-5, 100% binary agreement on two images. ⛔ Do NOT swap in PINTO model-zoo #109 (it's ML Kit's model, extracted — not Apache provenance). obs-backgroundremoval is GPL-3.0 — license-compatible since LlamaCasty went GPL-3.0 (2026-10-09), but none of its code is used; if any is ever borrowed, it needs its copyright notice kept.
• Contract: input [1,144,256,3] RGB /255 NHWC → output [1,144,256,1] person probability. The whole frame is stretched (not cropped) to 256×144, so the mask maps back by normalized coordinates.
• Shipping: Assets/Models/selfie_segmenter_landscape.onnx is an EmbeddedResource (in git, inside the exe — nothing to lose next to it, nothing fetched at runtime). Runtime = Microsoft.ML.OnnxRuntime 1.31.0 (MIT), CPU execution provider, 2 intra-op threads. Note the native onnxruntime.dll is ~17 MB (win-x64); an RID-less build copies every RID's native folder — the MSIX publish (TASK 48) must pin the RID so only win-x64 ships.
• Code (Services/BackgroundEffects/): IPersonSegmenter seam (Segment(VideoFrame) → SegmentationMask?, tests inject fakes); OnnxPersonSegmenter (lazy session from the embedded resource; never throws — a load/run failure logs once and returns null forever after); BackgroundEffectProcessor.Apply(frame, BackgroundEffect) — None = same instance (true passthrough), Remove = copy with alpha = bilinear-upscaled mask × source alpha, RGB untouched, IsOpaque = false (the compositor's straight-alpha blend shows the layers below), strength = edge feather (mask band 0.5±(0.05+0.45·s) → alpha); Blur (slice 2) = background downscaled 4× by box average, 3 separable box-blur passes and bilinear-upsampled, blended by the mask — person pixels (mask = 1) are copied untouched, opacity preserved. Blur radius is quadratic (BlurRadius(strength): 1→6 small px, default 0.5 = 2 — the "blur heavy" fix 2026-10-09; the old LINEAR 1→12 small px ≈ 48 full px was far beyond what the established tools use: StreamFX defaults its Box blur Size to 5 and its author stops downscale-based blurs around 8 px). The mask is computed once per frame (TrySegment) and rendered per effect (Render), so several variants share one inference. No mask / segmenter exception → passthrough + one log line, never a dropped layer.
• Config (slice 3): per scene, on WebcamSceneConfig — BackgroundEffect + BackgroundStrength (0..1, default 0.5), persisted as two additive guarded columns on WebcamSceneConfig (BackgroundEffect TEXT DEFAULT 'None', BackgroundStrength REAL DEFAULT 0.5, no version bump — the TASK 47 convention). RemoveBackground/BlurBackground are the radio-pill bools the UI binds.
• Hookup (slice 4) — the ONE processing point is CameraManager. Effects are per scene but the camera session is shared, so the manager renders variants keyed by WebcamEffectKey(effect, strength rounded to 0.01). MainViewModel.SyncWebcamEffects() declares the union of every config's key (SetRequestedEffects; unused variants are dropped so their CPU stops) and points each config's VideoImageSource at its variant's bitmap; it re-runs on load, add, remove, device swap, and any BackgroundEffect/BackgroundStrength change (configs are watched via PropertyChanged, which also ScheduleSaves). Per raw frame a background worker (latest-frame-drop, one at a time) segments ONCE and renders every variant; each variant keeps its own latest frame (the resolver: GetLatestFrame(device, key)) and WriteableBitmap (EffectPreviewBitmapChanged on first creation). The raw path is untouched — a slow/failed model never stalls the plain webcam — and an effect variant shows nothing until its first processed frame (Remove never flashes the real room). The compositor needed no change: its sampler already honours source alpha.
• Temporal smoothing (2026-10-09, creator check: "removal is jittery"): the segmenter classifies every frame independently, so a verdict that wavers at an edge makes the cut-out flutter. Fix: MaskSmoother blends each raw mask with the previous smoothed one — 0.75 × new + 0.25 × previous (CurrentWeight, internal const). State is per CameraSession (one per-camera worker), NOT in the segmenter — the OnnxPersonSegmenter is shared app-wide and its bundled-model contract test pins the raw per-frame output. A null mask (model hiccup) resets history; the first frame and any size change pass through un-blended; the returned mask never aliases the caller's array and two buffers ping-pong (no per-frame allocation — a 256×144 mask is 147 KB, past the 85 KB LOH). Weights come from the established tools, not a guess: OBS's obs-backgroundremoval smoke-tests temporal_smooth_factor at its 0.85 default, Jitsi's webcam background filter (jitsi/jitsi-meet#17080) found 0.7/0.3 transformed best — a midpoint that still reacts to real movement; 0.5/0.5 leaves a smearing edge ghost. The blur "heavy" follow-up was fixed the same day: quadratic radius, 1→6 small px (see the Blur bullet above).
• Perf (synthetic 1280×720, Debug build): segment 1.6 ms, Remove 3.3 ms, Blur 17.5 ms per frame (Release is several × faster). Pixel loops are row-parallel, capped at min(4, cores/2); the bilinear upsampling is separable (horizontal rows precomputed per mask/small row, one vertical lerp per pixel) — the first naive per-pixel 2-D bilinear cost 46/80 ms. CameraManager logs the real average once per session after 120 processed frames (startup.log: "background effects avg …"). MainViewModel.PersonSegmenterOverride is the hermetic-test seam.
• UI (slice 5, creator spec 2026-10-09): the webcam's properties in the Layers panel (Controls/LeftPanel.xaml) gain a Background section — two PillToggle switches, Remove and Blur, bound to RemoveBackground/BlurBackground (radio-exclusive: one on turns the other off, turning the active one off = None) and a Strength slider (0..1, 5% snaps, visible only while an effect is on; Blur = amount, Remove = edge softness). Dragging the slider never blanks the webcam: a new strength variant inherits the dropped same-effect variant's last frame + bitmap (CameraManager.SyncVariants), and the VM keeps the shown bitmap until the new one renders.
• Tests: BackgroundEffectEngineTests — the Remove integration test (fake segmenter), and a model contract test that runs the BUNDLED model through the C# preprocessing on a fixture and matches the MediaPipe-produced reference mask (≥99.5% agreement; fixture = MediaPipe's public test image mozart_square.jpg, public-domain painting, in ytLive.Tests/Fixtures/). CameraManagerTests — the ONE integration test for the jitter fix (a SteppingMaskSegmenter whose two consecutive masks disagree at an edge; asserts the second frame keeps a partial alpha where the raw mask would have cut to 0: x=6 → 58 upstairs of the raw 0, person core 255, background 0). Blur_default_strength_is_gentle_and_full_strength_is_strong pins the quadratic radius mapping (BlurRadius(0.5) = 2, BlurRadius(1) = 6) and the behaviour at a step edge: default smears light ~9px into the dark half vs ~26px at full strength.

Vertical (9:16) tier camera placement (TASK 57 — "vv" Units 1+2, built 2026-10-21)

The problem. The vertical tier (1080×1920) is a centred band crop of the SAME 1920×1080 master: OutputRect* = x 656.25, y 0, w 607.5, h 1080. A camera placed for 16:9 (the default webcam sits at x≈1408) lands outside the cropped window entirely — in the vertical stream the creator is simply not in the picture.

The rule (creator's locked table, 2026-10-17). Each scene keeps its own vertical placement — position, size and shape — and switching back to 16:9 restores the desktop layout exactly:

mode	shape	size	position
16:9	as today	as today	as today
vv · Live	circle or rect (the creator's choice, per scene)	small tile	one of six spots: top/bottom × left/centre/right
vv · Chat	rect only (the circle option is not offered)	the small tile (normal), or enlarged to fill one 607×540 area	the same six spots; enlarged fills the top or the bottom area
Starting / BRB / Ending	unchanged	unchanged	unchanged

Design — geometry only, no render-path change. The preview and the compositor both read the element's OWN X/Y/Width/Height + ClipShape, so the tier switch swaps the live geometry instead of teaching the render path about tiers:

• WebcamSceneConfig carries the vertical placement (VerticalX/Y/Width/Height/VerticalClipShape
  • VerticalRectWidth/Height — seven additive DB columns, NULL = "this scene has no vertical placement yet") and the parked 16:9 layout (LandscapeX/…/LandscapeRectHeight, transient).
• BeginVerticalLayout(...) parks the live 16:9 layout and brings the vertical one in; EndVerticalLayout() commits the vertical placement back into the stored slot and restores the parked 16:9 layout. The live geometry IS the render input → the compositor and PreviewPane.xaml are untouched.
• The save keeps the X/Y/W/H/ClipShape columns as the 16:9 layout (while the vertical tier is live, the parked values are written there and the live ones into the Vertical* columns).
• SceneElement.X/Y/Width/Height became virtual so the webcam can CONSTRAIN every write (drag, resize handle, properties fields) into the band — one choke point instead of three writers re-implementing the rule. Outside the band = invisible in the vertical stream.

The band and the six spots (Models/VerticalCameraLayout.cs, pure math): the band is 656.25…1263.75 × 0…1080; it splits into two 607×540 areas (top/bottom), each with three columns (left/centre/right) → six spots. A tile snaps to the spot its centre falls in, inset 32 master px from the band's outer edge (the app's own placement margin) and never outside the band. The default tile is 270×152 master px (480×270 in the 1080×1920 output) in the bottom-right spot — the corner the 16:9 default webcam uses. The Live scene gets that tile automatically the first time the vertical tier is picked (otherwise the vertical stream has no camera at all); the other scenes keep their 16:9 placement until the creator drags them into the band.

The Chat scene's own rules (Unit 2). In the vertical tier the Chat camera is rect only: the circle is not offered (MainViewModel.CanToggleClipShape is false → the Shape button disappears) and the model refuses it too — WebcamSceneConfig.ClipShape is overridden, so a locked camera cannot become Round by ANY writer (the toggle, the button, the placement swap). The lock is WebcamSceneConfig.VerticalShapeLocked, set by the VM per scene and cleared before the 16:9 layout comes back, so the desktop shape is restored. Its size is discrete: the small tile (normal) or one whole 607×540 area (enlarged) — the resize handle snaps to the nearer of the two (VerticalCameraLayout.SizeFor), and an enlarged camera fills the area its centre is in (top or bottom). The Chat scene also gets its tile automatically the first time the vertical tier is picked (like Live) — otherwise the vertical chat stream has no camera at all.

Manual entry (creator rule): the webcam's Layers properties gained a Geometry section (X/Y/W/H) — it edits the LIVE placement, i.e. the one the current tier shows. The webcam's geometry setters clamp it into the band, so a typed value can never push the camera out of the cropped window.

Derivative work. OBS has no built-in way to store a scene's layout per aspect ratio — the maintainers' answer is "create a new empty scene and add the scene you want to send as source" (obsproject.com/forum/threads/…161307), and Streamyard's dual-aspect guide says the same ("no built-in way to store separate layouts per aspect ratio, so you rely on manual workarounds and plugins" — streamyard.com/blog/dual-aspect-ratio-streaming-tool). Our per-scene, per-tier stored placement, resolved on the tier change, is the step past that.

Tests. VerticalWebcamLayoutTests — the ONE integration test for Unit 1: the vertical tier is picked → the Live camera comes INTO the band as a small tile → dragged to the top-right it lands top-right inside the band → back to 16:9 the desktop layout is restored exactly → and both placements survive a save + reload. (The store writes the webcam rows only when the app has a webcam identity — the config rows hang off it — so the test supplies one.) VerticalChatCameraLayoutTests — the ONE integration test for Unit 2: the vertical tier is picked → the Chat camera comes into the band as a small RECT tile → the circle option is not offered and cannot be set even on the model → dragged up and enlarged it fills the top area exactly → back to 16:9 the desktop layout is restored exactly and the circle option is offered again.

Known trap (see MyMistakes.md): a second properties panel bound to SelectedElement.IsWebcam broke WebcamBackgroundPillTests — that test finds the webcam's panel by binding text, so a new panel must use a different binding (IsWebcamSelected) or the selector matches twice.

Rendering budget, measurement & the compositor — moved

Frame cadence, per-element composite timing, the scene dump, the render budget and the SceneCompositor design live in docs/ai/frame-pipeline.md — read it before changing the render loop, the compositor, or anything that moves per-frame cost.

Invariants that hold even if you never open that file:

• Every global overlay must be composited on EVERY render path (pump, preview/thumbnails, scene dump — SceneCompositor.Overlay is shared for all three). A feature wired into one path is silently absent from the output; that bug (flash + social bar "preview-only forever", 2026-09-26) is why the rule exists.
• VideoFrame.Epoch is not optional. A producer that recycles buffers MUST bump Epoch per frame, or FramePump's buffer-identity paste cache and the full-render signature serve stale pixels. BrandFlashPresenter reuses one 8MB master buffer and stamps Epoch per read for exactly this reason.
• StripPool owns four dedicated BelowNormal background threads for strip-parallel compositing; strips below 64 rows run inline. Never demote threads inside Parallel.For — it runs on thread-pool threads and starves the scheduler (that mistake once broke audio-mix timing).
• Read render numbers in Release only. Debug pixel paths are several× slower; a Release 1080p composite measures ~1.0–1.1ms against the 16.67ms budget, and only Release takes are evidence.

FFmpeg locator (TASK 4 ship step 2 — shipped 2026-08-10; rewritten to BUNDLED 2026-09-28, plan in TASKS.md)

The encoder's one external dependency is ffmpeg.exe. It is BUNDLED — never downloaded, never fetched at runtime. IFfmpegLocator resolves an absolute path on demand: the bundle first (<AppContext.BaseDirectory>\ffmpeg\ffmpeg.exe), then PATH as the escape hatch for someone who deliberately installed their own. The order is the opposite of the original ("the user's own install wins") on purpose: a PATH ffmpeg may be a different major version or a GPL build, and the bundle is the one that was pinned, license-vetted and tested. If neither hits, it throws a loud IOException naming the missing folder and the fetch script — the old "found something on disk" cache path is gone deliberately, because silently satisfying a missing bundle with a stale copy is exactly the silent drift a certification-gated dependency must not have.

The bundle is not in git (135 MB of incompressible DLLs would tax every commit on this 9p-bridged tree). scripts/fetch-ffmpeg.sh populates ./ffmpeg from a pinned month-end BtbN LGPL-shared win64 artifact, verifies SHA-256 before extracting, and is idempotent; set FFMPEG_ZIP=<path> to reuse a pre-downloaded archive. ytLive.csproj copies ffmpeg\** to the output (CopyToPublishDirectory="Always" for the MSIX package) and the GuardBundledFfmpeg target fails the build if the folder is absent, so a fresh clone finds out before the creator presses Record rather than during a take. ffmpeg.exe + ffprobe.exe + the libav*.dll family must stay in one folder — Windows resolves a shared build's DLLs from the executable's own directory. ffplay.exe (18 MB) is deliberately not shipped; nothing calls it.

BtbN LGPL-shared (not gyan.dev, not static): it drops GPL-only libx264/x265 while keeping NVENC/QSV/AMF + libopenh264 + native AAC, and dynamic linking means LGPL compliance is "license text + source offer" with no static-relink (§6) material — see the Licensing guardrails below. libopenh264 is compiled into avcodec-63.dll (verified 2026-09-28: the encoder is registered there, and there is no separate OpenH264 binary to ship), so Cisco's BSD terms + patent grant ride along inside item 1 of THIRD-PARTY-NOTICES.txt. Pin: autobuild-2026-08-31-13-27 (month-end on purpose — BtbN keeps ~14 dailies but month-end builds ~2 years; a daily pin is what 404'd, see below).

⛔ Why this was rewritten (2026-09-27 → shipped 2026-09-28). The pinned-download design was a defect, not a cold-start edge case. It failed in production on 2026-09-01 — the previous daily pin aged out of BtbN's 14-day retention and the download 404'd on the creator's first real recording attempt. Two facts made "the pin is a const, just bump it" wrong:

• Microsoft Store policy 10.2.2 forbids dynamic code inclusion. Downloading an executable from the internet and running it is the exact pattern the policy names. An MSIX submission is rejected over it.
• Bumping the pin is whack-a-mole against a retention window we do not control.

Bundling deletes the startup network dependency entirely. The LGPL-shared build choice is unaffected — dynamic linking was chosen for LGPL §6 compliance ("license text + source offer"), not to enable downloading. Analysis: TASKS/research-store-certification.md §4. Guardrail: FfmpegLocatorTests.TheLocatorCarriesNoNetworkCapability asserts the locator's source contains no HttpClient/URL/downloader at all, so the policy cannot rot back.

Every other third-party binary already ships via NuGet — ffmpeg was the only download-and-execute. Verified 2026-09-28: e_sqlite3.dll and WebView2Loader.dll land in runtimes\win-x64\native\ (SQLitePCLRaw + WebView2 packages) and NAudio/Notification.Wpf/Microsoft.Data.Sqlite/ProtectedData are managed. Two gaps remain and are not fixed by bundling: the WebView2 Evergreen runtime is a machine prerequisite (a manifest framework-dependency + graceful-failure path, TASK 48 item 2), and Velopack's updater downloads and executes — its teardown is a compliance action, not just cleanup.

Live encoder + RTMP push (TASK 4 ship step 3 — shipped 2026-08-12, plan in TASKS.md)

The encoder is a thin orchestrator over ffmpeg.exe — no H.264/AAC code in the app. It spawns the subprocess (path from IFfmpegLocator), feeds raw BGRA master frames into stdin, and parses -stats stderr lines into StreamHealth (bitrate/FPS/duration, dropped-from-frame-count). FfmpegEncoder (IFfmpegEncoder seam) holds: StartAsync (locate → probe -encoders → spawn → stderr loop → drain loop), SubmitFrameAsync (slice 10: bounded-queue ENQUEUE — never a pipe write; the drain task owns stdin writes), StopAsync (flush queue → stdin EOF → ffmpeg finalizes + exits by itself; a 10s watchdog kills it), Dispose (force-kill + wait), and the HealthUpdated/ProcessFailed events. Pattern: the encoder never touches Process — it drives the IEncoderProcess seam (FfmpegEncoderProcess wraps the real Process, redirected stdin/stdout/stderr

• exit control); a Func<IEncoderProcess> factory + the locator are constructor-injected, so the integration test fakes the whole subprocess (probe + encoder) with a Channel-backed TextReader whose Complete() is EOF (null), never a ChannelClosedException.

Decisions (locked): args are pure (FfmpegArgs.Build, no string building in the encoder): -f rawvideo -pix_fmt bgra -video_size WxH -framerate FPS -i pipe:0 (NO -re — the FramePump is the pacer since slice 9, 2026-09-10; -re added a second, fighting clock on the rawvideo demux)

• a real audio input — the mixer writes IEEE-float stereo to a Windows named pipe (-f f32le -ar 48000 -ac 2 -i \\.\pipe\ytllive_audio, name via EncoderOptions.AudioPipeName; replaced the old -f lavfi -i anullsrc silence in the TASK 8 audio milestone) + explicit -map 0:v -map 1:a + -c:v <enc> -b:v K -maxrate K -bufsize 2K + -g fps×4 -keyint_min fps×4 -sc_threshold 0 -bf 0 -pix_fmt yuv420p (≤4s keyframes, closed GOP, H.264 compliance) + -c:a aac -ar 48000 -ac 2 -f flv <rtmpUrl>. Record output (TASK 18): FfmpegArgs.Build emits one self-contained block per output, each its own -map 0:v -map 1:a + codec tags (AddVideoTags helper). Stream block = -f flv <rtmpUrl>; record block = -f mp4 <RecordPath>. EncoderOptions.StreamEnabled/RecordEnabled/RecordPath gate each block, so the engine runs record-only (no RTMP) or stream-only — stream+record simultaneously is OUT by creator ruling (2026-09-01): the VOD is already the copy, and dual-encoding drags mid-range chassis and degrades BOTH outputs ("we're not them"). The old "cheap on NVENC" claim was an unverified assumption; the UI constraint is landed (2026-09-20): the REC/ON-AIR pills are radio-exclusive — arming one clears the other — while the dual-block machinery stays generic. FfmpegEncoder.StartAsync throws unless at least one output is enabled. Encoder choice is probed from the binary's -encoders listing (FfmpegEncoderPicker, pure): NVENC → QSV → AMF → OpenH264 fallback, never libx264 (GPL; see Licensing). EncoderOptions.VideoEncoder forces one and skips the probe. EncoderOptions also carries W×H/FPS/bitrate from the quality tier and GopSize = FPS×4. Constructed by MainViewModel since ship step 5 (new FfmpegEncoder(new FfmpegLocator())), driven by the FramePump below.

Local recording (TASK 18 — shipped 2026-08-29, VM + top-bar UX; plan in TASKS.md)

Recording is independent from streaming and needs no YouTube sign-in. A single segmented REC|ON-AIR switch in the top bar picks the mode (redesigned 2026-09-22 from the old two pills): REC (local file, works signed-out) / ON-AIR (streaming; armable signed-out — intent may light while offline, 2026-09-20: a greyed pill was the dead end the guard shipped to forbid). The switch selection is intent; IsRecording/IsLive are reality — the reality line (dot + word + elapsed) only lights when a session is actually running.

• State model (MainViewModel): pills RecordPillOn/OnAirPillOn stay the routing model (radio-exclusive — arming one clears the other, record-OR-live 2026-09-01; the ON-AIR setter stays armable signed-out (2026-09-20: intent must be able to light while offline)). Top bar redesign (2026-09-22): the bar is ONE surface rendered by the FIRST decision — Record or Stream — and each world is the whole bar (ShowIdleWorld/ShowRecordAction/ShowStreamActions, wired by RaiseTopBarModes()). The old sign-lights + two pill toggles + status dot + PRIVATE/TEST chips are gone; the mode is one segmented REC|ON-AIR switch (SegmentToggle/SegmentLabel styles), and "going back" is one tap on the other segment. Idle worlds: Record = switch + "Start Recording" (PrimaryStartButtonLabel names the armed world); Stream = switch
  • "Go Live" + Test (Test is a child of Stream — visible only stream-armed AND signed-in) plus the account zone on the right. The account zone is WORLD-INDEPENDENT (2026-09-23): ShowSignInButton = signed-out and ShowAvatarButton = the signed-in avatar, in Record and Stream worlds alike — it's app-level identity, and keeping it put pins the bar height (it no longer pops in and out between worlds). Right-click the avatar = Change Account/Logout. Running retires the switch and worlds; one reality line ● word elapsed + End replace them (RunningVisible/RunningText/RunningDotBrush — TEST/LIVE/REC, gold/red/green). The account status dot is gone — the avatar/Sign In pair carries connectedness. ShowPrimaryStartButton remains the always-idle face. StopStream clears both pills (see "Stop ends everything; failures roll back" below).
• Filenames (pure Services/RecordingFile): auto-name ty-<yyyyMMdd>-<HHmm start>-<fff>-0000.mp4 at start; rename-on-stop to ty-…-<hh2mm2 actual length>.mp4 (FinalizeRecordingAsync after the pump stops & the file closes), numeric -2/-3 suffix on collision (UniquePath). Length comes from _liveElapsed, which the session timer walks while IsLive || IsRecording. The <fff> millisecond segment is load-bearing, not decoration (2026-09-27): both names derive from _recordStartTime, so it survives the rename, and without it two instances started in the same minute compute the same start path and both ffmpeg processes write one file — which is exactly the dev multi-instance case (Helpers/InstanceProfile, one instance recording the other).
• Private broadcasts end the same way (creator ruling 2026-10-09). After StopStream's transition(complete), OfferToKeepPrivateBroadcastAsync reads the broadcast's privacy from YouTube (GetBroadcastPrivacyAsync — visibility can change mid-stream, local state isn't trusted) and, only if it is private, shows KeepBroadcastDialog (repo root): Enter = Keep (IsDefault), Escape / Delete / the X = delete via DeleteFinishedBroadcastAsync — videos.delete?id=<broadcastId> (a live broadcast's id IS its video id; 204), falling back to liveBroadcasts.delete on 404. An unreadable status asks nothing and deletes nothing; a failed delete toasts that the video is still on YouTube. Decision logic = MainViewModel.ClosePrivateBroadcastAsync (internal static, tested in PrivateBroadcastCloseOutTests); KeepBroadcastPromptOverride is the dialog seam.
• Save dialog: Cancel DISCARDS (creator ruling 2026-09-26). The RenameRecordingDialog result is a two-outcome decision, and it lives in the extracted MainViewModel.CompleteRecordingSave(startPath, dir, autoStem, chosenStem, creatorSaved) (internal, so ytLive.Tests can drive it against real files without a frame pump — see ytLive.Tests/RecordingSaveDialogTests.cs):
  • creatorSaved == false (Cancel / Escape / the X) → DELETE the temp file. Nothing is moved, nothing is left in the videos folder. A failed delete returns DiscardFailed and the toast NAMES the file + folder, because a "discarded" recording still on disk is worse than no report.
  • creatorSaved == true (Save, or Enter on the pre-filled default) → File.Move to the final name. A blank/whitespace box still means "keep the auto name" — but only on an explicit Save.
  • The bug this fixed: the caller used to File.Move UNCONDITIONALLY and only overwrite stem when the dialog returned true, so ShowDialog() == false fell straight through into the save — Cancel silently kept the recording under the default name. The modal itself was always correct; the side effect was in the wrong place. Any modal whose result gates a side effect must have every branch handled explicitly — a falsy result must never fall through into the effect.
• Folder: default %APPDATA%\ytLlive\recordings\, user-overridable via ChooseRecordFolderCommand (OpenFolderDialog), persisted through LayoutStore.Load/SaveRecordFolder (RecordFolder key).
• Explicit sign-out only: StopStream no longer clears the session/token. Sign out via Logout only — Change Account re-authenticates in place and deliberately does not sign out first (2026-09-27; signing out first deleted ytLlive.auth before the browser even opened, so a cancelled switch lost a working session). Stopping a recording leaves the creator signed in.
• Stop ends everything; failures roll back (2026-09-01): StopStream also clears both intent pills (RecordPillOn/OnAirPillOn) — a lit pill with no session behind it is a lie. Every frame-pump death and every go-live prep failure now runs the full StopStream teardown instead of leaving a limbo (StreamStatus.Error with IsRecording=true over a dead encoder — the first-launch zombie recording). Toast copy distinguishes "Recording stopped" from "stream pipeline stopped"; AudioMixer.StopLive is idempotent-safe for rollbacks that never reached StartLive. Seams: OnFramePumpFailed + IsRecording setter made internal (test-only, InternalsVisibleTo). Test: SessionTeardownTests.
• EncoderOptions.StreamEnabled/RecordEnabled/RecordPath gate outputs; record+stream is one ffmpeg with two output blocks (the dual-block machinery is unreachable from the UI since the pills are radio-exclusive). Rest of the engine (FramePump/encoder) is unchanged — BuildEncoderOptions always returns an options (flags from the pills + _activeRecordPath), so record-only reaches the pump.

Live audio capture (TASK 4 ship step 4 — shipped 2026-08-12; game audio bar 2026-08-13; TASK 8 audio milestone: real stream audio + filters + duck + TRAX, shipped 2026-08-14, plan in TASKS.md)

Capture runs for the app's lifetime and is KISS by rule: desktop/game audio is automatic (WASAPI loopback), the mic is the creator's only audio control (meter/mute/volume already shipped). The whole layer sits behind an IAudioSource seam (Services/Audio/: Start/Stop/Started/SampleReady/ Failed, IDisposable) so the app never touches NAudio directly and tests inject hermetic fakes (no devices, no timers).

• Sources (NAudio 2.2.1 — NAudio.Wasapi + NAudio.WinMM (for WaveOutEvent), MIT — item 9 in THIRD-PARTY-NOTICES.txt): WasapiLoopbackAudioSource = WasapiLoopbackCapture on the default render device; WasapiMicAudioSource = WasapiCapture with the device resolved by FriendlyName matching MicSourceName (the app only persists the DisplayName), falling back to the default capture endpoint. Both run at the device's own mix format — NAudio 2.2.1 exposes no overridable GetDefaultMixFormat on WasapiCapture, so there is no forced 48 kHz path; the mixer's TinyResampler normalizes any rate/channel layout to 48 kHz stereo (this replaced the earlier "force IEEE-float 48k" plan — the resampler IS the design). Mic device resolution re-reads the name provider Func<string?> at each Start, so a mic picked mid-session takes effect immediately (the mixer restarts the mic on pick). Both sources raise Started once their capture loop actually begins — the mixer turns that into MicConnected.
• AudioMixer owns both sources; StartMicCaptureAsync starts the mixer once at startup and Shutdown disposes it — NOT go-live — so the meters preview live. Mic samples: downmix to mono → TinyResampler → VoiceFilterChain per sample (bass LowShelfFilter 120 Hz +4 dB → treble HighShelfFilter 8 kHz +3 dB → NoiseGate (threshold 0.005, hysteresis 0.5, attack 0.5, release 0.0005) → SpeechLeveler (2026-10-09: automatic gain steering speech RMS to −20 dBFS over a 0.3 s window, gain −6..+20 dB, rises ≤10 dB/s / falls ≤30 dB/s, learns only while the gate is open and above −54 dBFS so pauses/hum are never pumped) → Compressor (threshold 0.5, ratio 4:1); all pure DSP) → ring buffer → the post-filter AudioLevelMeter (RMS, 0.2 exponential smoothing) → MicLevelChanged → marshalled to the UI thread → AudioLevel. Loopback samples: resample → ring buffer → second meter → LoopbackLevelChanged → the game bar's GameAudioLevel. The raw linear level maps to the meter's display scale by AudioLevelMeter.ToDisplay (−60..0 dBFS → 0..1, honest — the +10 dB display boost was removed 2026-10-09; the mic meter is ToDisplay(AudioLevel × MicVolume), true dB math, no ×1.2). Why (2026-10-09): a creator's YouTube upload measured −28.5 LUFS / −8.9 dBFS peak against YouTube's −14 LUFS reference (YouTube only turns loud videos down, never quiet ones up) while the boosted meter looked "dialed in". Nothing in the chain added gain — the compressor folds only above −6 dBFS and the limiter only caps. Re-running that same audio through the new chain (mic volume 0.8): −17.9 LUFS, −0.7 dBFS peak. Recording and streaming share this one mix, so both were (and now are) the same. Measure with the bundled ffmpeg: ffmpeg -i file -af ebur128=peak=true:framelog=quiet -f null -. Mic connection state surfaces as events: MicConnected (source Started), MicFailed (source Failed), and RestartMic() re-resolves + restarts just the mic (loopback keeps running). Failures log via AppLog; a mic failure zeroes the meter, a loopback failure never kills the mic. Meter Push is unconditional (a ?. on the event would skip the meter update when nothing is subscribed yet).
• Go-live audio (TASK 8): BeginGoLive → StartLive(pipeName) (idempotent) creates the named pipe server (NamedPipeAudioWriter, behind the IAudioPipeWriter seam) and a live loop task; every mixInterval (default 10 ms) FillAndMix reads a chunk from each ring buffer (silence-fills underruns), computes the post-filter mic RMS → AutoDucker (threshold 0.02, duck ×0.25 / −12 dB, attack 0.05, release 0.005, always on), applies the honest gains via Func<double> seams (micGain = MicMuted ? 0 : MicVolume; loopbackGain = GameMuted ? 0 : GameAudioVolume, × duck), mixes mono mic + stereo loopback into interleaved stereo, runs the MasterLimiter (a −1 dBFS ceiling so the honest gains can never sum past 0 dBFS and clip the AAC encode — instant attack per frame, smoothed release toward unity), and writes the floats to the pipe. The gains are wired through AudioGainProvider (Services/Audio/AudioGainProvider.cs) — the VM hands its MicGain/LoopbackGain Funcs to the mixer at construction, read live each tick, so the volume sliders and mute buttons are stream-honest. (Before this wiring the seams defaulted to unity and the controls were decorative.) StopStream → StopLive() (closes the pipe → ffmpeg audio EOF) BEFORE stopping the frame pump (video EOF) — the reverse order stalls on pipe backpressure. FfmpegEncoder itself is untouched; the VM owns the pipe lifecycle.
• Audio sync offset (TASK 22): after the limiter, FillAndMix routes the whole interleaved stereo mix through a AudioSyncDelay (Services/Audio/AudioSyncDelay.cs) — a pure delay line whose offset comes from a Func<int> syncOffsetMs seam (the VM's global AudioSyncOffsetMs, −500..+500 ms, persisted as Audio.SyncOffsetMs). This is OBS's documented fix for lip-sync: positive delays audio when it runs ahead of video; negative advances audio when it runs behind by eating the first |N| ms of the live stream head (see AudioMixer.StartLive; the delay line stays clamped 0..500 internally — negative bypasses it entirely). The advance is armed once at StartLive (eating the head mid-stream is impossible); positive is live-reactive (re-read per tick). A slider on the mic bar ("AUDIO SYNC", locked while live/recording via IsEditMode) surfaces it (a one-time status dot next to it was removed 2026-09-23 per creator feedback — the slider + numeric tooltip carry the state). Changing the delay flushes the line (a live change clicks rather than smears).
• TRAX — free background music (TASK 8): MusicPlayer = NAudio MediaFoundationReader (mp3/wav/m4a) → VolumeWaveProvider16 at the hardcoded 0.20 bed (no slider) → WaveOutEvent on the default device, looping on any clean natural end (PlaybackStopped with e.Exception == null → rewind + replay; the earlier Position >= Length check was unreliable for MediaFoundationReader and let tracks play once then stop). The desktop/game bar's mute toggles LocalGain (0 or 1; UpdateTraxLocalGain runs on every GameMuted change and on TRAX load), so muting kills TRAX in the headphones — matching the stream, where it rides the loopback channel. The volume slider drives system volume (PushSystemVolume) — which scales the HEADPHONES; the loopback capture is pre-endpoint-volume (disproven-then-fixed 2026-09-01), so the STREAM follows the knob via AudioGainProvider.LoopbackGain = GameMuted ? 0 : GameAudioVolume, and the game meter multiplies its display by the same. One knob, three honest paths. No third mixer input. The footer TRAX button lives inside the game audio bar (in the preview overlay), left of the "Desktop Audio" label (the creator's pick — it rides the desktop channel, so the music control sits with the desktop audio controls): status dot (red no track / yellow loaded stopped / green playing) + "TRAX"; left-click toggles play/pause (opens the in-app picker via OpenFileDialog when no track is loaded); right-click always opens the picker (TraxButton_PreviewMouseRightButtonUp, e.Handled = true, code-behind pattern); tooltip shows the loaded/playing track name or "No track — right-click to choose background music". The picked track persists via schema v9 single-row Music (TrackPath/IsEnabled) in LayoutStore. Known wrinkle (out of scope, future feature): YouTube mutes VODs carrying copyrighted music — "music on live, off VOD" is tabled.
  • ⛔ The load is behind a bounded probe, because a share that is gone must never freeze startup (2026-10-04). LoadLayout → LoadTrax used to call MusicPlayer.Load synchronously on the UI thread, and new MediaFoundationReader(path) does not fail fast on a dead SMB session — it burns the whole ARP/TCP/SMB timeout (~40s, measured) and then throws 0x80070035. Measured: OnStartup 08:42:59 → MainWindow loaded 08:43:43, with 42 of those 44s inside LoadLayout on that one track. The rule now: a probe may time out; only a bind is allowed to be on the creator's path. IsTrackReachableAsync(path, budget, File.Exists) runs the probe on a thread-pool thread under a Task.WhenAny ceiling (TraxProbeBudget = 2s) and reports offline/missing/slow as a normal state, not an error. Only a probe that passed gets the real bind, and that bind stays on the UI thread with every other MusicPlayer mutation, so no new cross-thread race is introduced. The orphan probe thread stays parked until SMB gives up — deliberate: it is not the thread anyone waits on. Same principle covers the webcam: a device held by another app fails fast (sharing violation) but a virtual-camera driver can stall enumeration, so device probes belong off the startup path too, not behind a long timeout.
• Mic status dot (Models/MicStatus.cs) on the preview-bottom MIC button: green = MicConnected, yellow = MicFailed (in use/unplugged), red = no mic device at startup (the mixer is never started, so loopback and the game bar can't run either — no capture devices at all). The picked mic persists: LayoutStore's Settings key/value table stores MicSourceName (saved on pick via SaveMicSourceName), and the VM restores it at construction BEFORE the mixer's first Start — so a restart reconnects the same already-vetted device (green) or reports it missing (yellow), instead of silently falling back to the default endpoint.
• Game audio bar (desktop/game, always visible — TASK 4's IGameAudioDetector show/hide gating was removed 2026-08-15: the bar used to appear only while a full-screen game with sound was up, which kept hiding the creator's desktop meter; the detector stack is gone, desktop audio is just automatic WASAPI loopback): overlaid at the bottom of the preview window (bottom-center, dark translucent chip, a mirror of the mic bar: meter + mute + volume slider). It's monitoring UI in the preview grid — the meter is display-only (fill = ToDisplay(GameAudioLevel) × GameAudioVolume — the ×volume term was missing until 2026-09-01: loopback capture does NOT shrink with the endpoint, so an unscaled meter left it pegged at 20% volume; GameMeterHonestyTests guards it), but its volume slider drives system volume (PushSystemVolume — live headphones follow the knob; the capture side is scaled in the mix, see TRAX note above) and mute kills TRAX (MusicPlayer.LocalGain = 0). Relabelled "Desktop Audio" (TASK 8) since TRAX rides the same channel.
• WaveToFloat (pure, shared): WASAPI mix formats → interleaved float — IEEE float 32-bit direct, PCM 16-bit normalized to -1..1, WaveFormatExtensible with the IEEE-float subformat GUID (NAudio.Dmo.AudioMediaSubtypes.MEDIASUBTYPE_IEEE_FLOAT), trailing partial samples ignored.
• Build 0 warnings; 197 passing (DSP/ring-buffer/ducker/resampler/pipe + mixer/hysteresis/ game-detector/meter-scale unit tests + the TASK 8 integration test AudioPipelineTests.Mix_WithFiltersDuckAndGain_Lands_On_AudioPipe + the polish-batch integration test Mix_HonorsProviderGains_AndGameMute_KillsTheLoopback proving the provider gains reach the pipe and mute silences the loopback).

The live frame pipeline — moved

FramePump and the whole path from frame producer to encoder (pacing, pool/paste caches, slice history, teardown, health stats) live in docs/ai/frame-pipeline.md.

Invariants that hold even if you never open that file:

• rawvideo is stamped by ARRIVAL, never by a timestamp. ffmpeg assigns pts from frame order at the declared fps, so supply rate = output speed. The pump duplicates the previous frame on a missed deadline (correct duration) and never resets nextTick to wall-now — rebasing turns a hitch into a silent time-lapse (take-2 lesson, 2026-09-01).
• Submit never blocks. The encoder queue is bounded and a drain task owns the stdin write + flush; on overflow the newest frame is dropped and counted (DroppedFrames) — overload costs content, never a frozen or smeared session.
• Stop order: StopAsync stops the encoder first — flushing the pending queue to EOF so the file finalizes with no accepted frame lost — before awaiting the pump loop; the reverse order deadlocked on pipe backpressure.
• Judge output in Release, by the burned _outputIndex — the 6-digit counter burned into each frame is what lets a recorded file be audited for drops after the fact; stats alone are not proof.

Social bar (TASK 6 — shipped 2026-08-12, plan in TASKS.md; bar bug-fix branch 2026-08-13)

A global bar layer (never a Source, no sources-list row) that sits over the bottom or top of the output and carries the creator's social links — content-sized, centered, GREEN glow when ON, position is a click-toggle top ⇄ bottom (default BOTTOM, persisted SocialBarPosition). Models/Socials.cs: SocialService enum (YouTube/Twitch/X/Instagram/TikTok/Facebook/Discord/Kick/Threads/Bluesky/GitHub/LinkedIn/Pinterest/ Snapchat/Reddit/WhatsApp/Telegram/Link/Website/Fediverse), SocialEntry (Service/Handle/ProfileUrl/ FediverseSoftware), SocialsConfig (Entries + BarPosition + BarEnabled; BarJustify dropped, column back-compat). Configured in the "Social Media Site Promotion" dialog (SocialsDialog.xaml + ViewModels/SocialsDialogViewModel, WPF-free, injected ISocialValidator + sign-in/sign-out fakes): ON/OFF bar switch (schema v8), 6 fixed slots — row 1 always YouTube (signed-in → channel handle; signed-out → sign-in gate → OAuth; delete → confirm sign-out), row 2 free, rows 3–6 lock icons on freemium. Service detection (SocialServiceIcons.DetectService): URL domain / fediverse @user@domain → Fediverse / bare→Website. Validation (Services/SocialValidator.cs, ISocialValidator seam + HttpSocialValidator default): async GET of the canonical profile URL; 200/redirect = valid, 404/failure = rejected. Fediverse additionally does a best-effort nodeinfo lookup (/.well-known/nodeinfo → software.name, stored in SocialEntry.FediverseSoftware / the SocialEntry.Software column, column-presence migration, no version bump) so the entry shows the instance's real logo (LogoDataForFediverse: mastodon/peertube/pixelfed/misskey/lemmy/pleroma/firefish, generic fediverse honeycomb fallback — Simple Icons CC0 path data, initials badges gone); nodeinfo failure still validates (glyph falls back). If the identity domain's nodeinfo is blocked (YunoHost SSO gates /.well-known/nodeinfo behind the login page) but the bare root 302s to the real instance, the lookup follows the root redirect and asks the resolved host. Cancel is a hard stop: LookupAsync takes a CancellationToken (dialog VM owns a CTS; Cancel/X/Save abort in-flight lookups, canceled continuations never touch slot state).

Bar bug-fix branch (2026-08-13) — three changes:

1. Positioning is a click-toggle (KISS) — the original drag set a local Canvas.SetTop value that permanently overrides the {Binding SocialBarTop} (a binding can never win over a local value), so the bar stayed wherever it was dropped. The first drag-snap fix (SocialBarSnap.Decide + ClearValue on release) still failed for shaky hands — jitter around the ±6px deadzone snapped the bar up but wouldn't let it come back down. Superseded by the user's click-toggle: clicking the bar flips it top ⇄ bottom (MainViewModel.ToggleSocialBarPosition), the bar rides the binding alone, and SocialBarSnap is gone.
2. Fediverse software self-heal — the DB row @gramps@llamachile.tube had Software = NULL because nodeinfo was only ever asked of the identity domain (a landing page; the real instance is mastodon.llamachile.tube). HttpSocialValidator.ResolveFediverseSoftwareAsync now probes well-known subdomains (mastodon. → social. → … FediverseSubdomainCandidates) when the identity domain and its redirect both come up empty, under a ~15s linked-CTS budget. MainViewModel runs the static HealFediverseSoftwareAsync off the UI thread on layout load, applies matches via the dispatcher, and saves; SocialEntry.FediverseSoftware is settable and raises LogoData, so the icon updates in place.
3. The bar renders on the live output — Compositor/SocialBarRenderer.cs rasterizes the entries into a transparent straight-alpha BGRA strip (1920-wide, 40px content + 24px glow pad, the green glow baked in, Pbgra32→straight-alpha unpremultiply) and the compositor blits it above the flash (see "Live frame pipeline").

Toast notifications (TASK 24 — shipped 2026-08-23, plan in TASKS.md)

Non-blocking user-facing messages replace blocking MessageBoxes. Seam: INotificationService.Show(title, message, AppNotificationSeverity) (Services/INotificationService.cs) + Info/Success/Warning/Error extension methods; MainViewModel news up the real NotificationService at its field initializer (no DI container — the VM is built from XAML). Library: Notification.Wpf 11.0.0 (Platonenkov fork, MIT — notice #10 in THIRD-PARTY-NOTICES.txt). Facts that cost a hunt:

• The NotificationArea XAML control registers itself with the manager on Loaded; routing matches the area's Name against the request's AreaName — our host is x:Name="ToastArea" in MainWindow's root grid (last child = topmost z-order, Grid.RowSpan=4, bottom-right above the footer via Margin="0,0,12,96", outside the preview Viewbox). An unknown AreaName silently drops the toast.
• NeverExpires() sets ExpirationTime = TimeSpan.MaxValue (NOT null); NotificationColor.ToHex() returns #AARRGGBB (alpha prefix).
• Lifetimes: Info/Success ~4s, Warning ~8s auto-dismiss, Error sticky until dismissed (the pure mapping lives in NotificationService.BuildRequest + the Cards tint table: slate info #3a3b52, green success #1d5c38, amber warning #b8860b, dark-red error #8f1f1f — matching the health-banner language).
• Calls marshal to the captured Dispatcher (_dispatcher.Invoke) — encoder/pump events fire off-thread.

Migrated MessageBoxes: both webcam-acquire warnings, image-read warning, sign-in unsuccessful/failed. Promoted from log-only (each keeps its AppLog line): go-live prep failures ×3 (reusable stream, broadcast insert, prep exception), frame-pump death while live, mic-missing at startup, premium lapse, saved-session refresh failure (sign-out notice). Deliberately left log-only: offline license re-validation skip (would spam every launch). Still modal by design: SocialsDialog's slot-delete YesNo confirm.

Licensing — do not violate (GPL-3.0 open source since 2026-10-09; see LICENSE, ADDITIONAL-TERMS.md, THIRD-PARTY-NOTICES.txt)

LlamaCasty is free software under GPL-3.0-or-later (creator rulings 2026-10-09 — free forever, public repo, "GPL-3 with attribution"). Copyright (C) 2026 Gramps. ADDITIONAL-TERMS.md carries the three §7 terms: 7(b) every copy keeps "Based on LlamaCasty by Gramps — https://llamacasty.com" in its About screen; 7(c) modified versions are marked and renamed; 7(e) no trademark rights. The icon + logo files (Assets/llamacasty-icon.png/.ico, Assets/llamacasty-logo.jpg) are all rights reserved, outside the GPL — verbatim copies may carry them, forks must replace them (this is what keeps the merch brand protected). The scene backgrounds + default alert video are AI-generated placeholders (creator: made "with the intent of individual creators to immediately replace with their own images") — they go out under the GPL with the code, no reservation. LICENSE + ADDITIONAL-TERMS.md ship beside the exe (csproj None items); the About panel shows THIRD-PARTY-NOTICES.txt, whose header carries the LlamaCasty license notice (GPL §5(d) "Appropriate Legal Notices"). Source offer (§6): https://llgit.llamachile.tube/gramps/LlamaCasty (the Gitea repo; creator toggles it public — the old gramps/ytLlive path 301-redirects there), recorded in the notices header + README.

Every bundled component must stay GPL-3.0-compatible (MIT/BSD/Apache-2.0/LGPL/public domain all are; GPL-2.0-only and proprietary are not; Apache-2.0 is fine with GPL-3 but NOT with GPL-2). The rules below predate the GPL switch; where their reason was "proprietary product" it is noted, but the rule itself still stands for its other reasons. NEVER:

• Swap the FFmpeg pin casually — the BtbN lgpl-shared pin is the verified build. A GPL FFmpeg build would now be license-compatible (the old "GPL contaminates the paid product" reason is gone), but changing builds means re-verifying encoders, and libx264 carries no H.264 patent grant (Cisco's covers OpenH264). Keep lgpl-shared unless a task says otherwise.
• Distribute the static lgpl build — LGPLv2.1 §6 wants relinkable object files for static linking. The shared (dynamic-DLL) build sidesteps that: compliance is "license text + source offer + unmodified binaries". The pin is lgpl-shared; when the pin is refreshed, keep the shared variant.
• Use BtbN's nonfree variant — it adds fdk-aac (Fraunhofer code licensing). The native FFmpeg AAC encoder is fine (no Fraunhofer code) but grants no AAC patent license — accepted low-risk posture for RTMP→YouTube, since encoder vendors cover their implementations (Cisco OpenH264, NVIDIA NVENC, Intel QSV, AMD AMF).
• Link FFmpeg into the app — it stays a separate subprocess fed frames over a pipe; that separation keeps the app's own code out of LGPL reach.
• Drop THIRD-PARTY-NOTICES.txt from the shipped app or the About screen, or alter the FFmpeg copyright/LGPL notices inside the downloaded binaries. Automating the download counts as distribution — the obligations are not optional.
• Pin to a moving target — the latest BtbN release tag floats. Only immutable autobuild tags give a reproducible source offer. Record the tag + variant beside the URL (TASKS.md) every time the pin moves.
• Use non-CC0 icon art — the social bar's bundled SVG logo path data comes from Simple Icons (CC0 1.0, public domain — see THIRD-PARTY-NOTICES.txt). Replacing or adding logos must stay CC0 or another public-domain source; a logo asset under an incompatible or attribution-heavy license would complicate every redistribution. The app's icon + logo (Assets/llamacasty-icon.*, Assets/llamacasty-logo.jpg) are the creator's own art — all rights reserved, outside the GPL (ADDITIONAL-TERMS.md).
• Ship an ML model without clean provenance — the background-effects model (TASK 51) is Google's official MediaPipe Selfie Segmenter download (Apache-2.0, model card), converted by our own script. Model-zoo re-hosts (e.g. PINTO #109 = ML Kit's model, extracted) are off-limits. Apache-2.0 §4 obligations (license notice + "we converted it") live in THIRD-PARTY-NOTICES.txt.
• Forget the v1 license-texts gate — THIRD-PARTY-NOTICES.txt links the canonical license texts; at v1 (GA) the full texts of every license it names MUST ship alongside it (TASK 4 requirement 9 is the release blocker). Queued early is wrong; the release pass owns it.
• Break the in-app About requirement — since TASK 11 the About overlay is the app's in-app creator hub: the real logo, the creator links (YouTube channel, Mastodon, Buy me a coffee, and the greyed "Unlock Premium" seam whose billing URL is tabled), and a Licenses & legal sub-panel that loads THIRD-PARTY-NOTICES.txt from the executable directory and renders it in a scrolling panel — never the OS viewer, no Notepad, no browser tab. The premium/coffee link constants live in MainViewModel (PremiumUrl, CoffeeUrl, ChannelUrl, MastodonUrl); filling in the billing URL lights up the premium button. Do not reintroduce an "open the notices in Notepad" button.

Design Principle

This software is so intuitive that even the most right-brained person can easily intuit and use it.

Apply this to every UI decision:

• One-click go-live with working defaults
• Prefilled YouTube defaults (RTMP URL, bitrate, resolution, latency)
• Visual/drag-and-drop scene building over property panels
• Every action produces a visible outcome — no dead ends
• "We're not them" (2026-09-01): assume the creator's hardware is mediocre, because it is. Every feature spends the machine's budget once — never twice for the same result (record OR stream, not both; one reusable stream; one webcam; two mixer inputs). If a feature only sings on a high-end chassis, it doesn't ship — the OBS escape hatch is open by design.

Monetization (design decision — the branding flash is the sword)

⛔ Superseded 2026-10-08/09 — free forever, no branding on the stream. The credit is now OFF by default: MainViewModel.ShowBrandFlash (internal static, default false) is the master switch, and BrandFlashEnabled => ShowBrandFlash && !IsPremium feeds the presenter at construction and on every licence change. The code (BrandFlashPresenter, the FramePump brandFlash: seam, the preview layer) is kept, not deleted — creator ruling: "don't delete it, just make it conditionally displayed". BrandFlashOutputTests opt in by setting the switch before constructing a MainWindow; Credit_IsOffByDefault_EvenOnTheFreeTier guards the default. Everything below is the historical paid-tier design.

Full pricing and the Year 1 revenue forecast in MONETIZATION.md (gitignored). ⚠️ No Polar product, discount code, or license key exists any more — nothing bills today; Polar is dormant. Brand palette and assets in MARCOM.md (gitignored). This section covers the in-app model.

Free forever: all features unlocked for everyone — no feature lock, no paid tier, and since 2026-10-08 no watermark either (the credit is OFF by default; see the banner above). No creator will tolerate a watermark, and as a good-guy developer we give everyone complete access so no one can call us crooked. Money comes from gratuity/merch, not gating (TASK 54).

• Free: a periodic branding credit — "made with LlamaCasty!" in full-frame neon (white core, feathered red/blue halo with the channels split in opposite directions), at a random position inside the frame on every presentation (single pre-measured line, so it never wraps; travel range is 0 … 1920−textWidth), held 2s (500ms fade in, 1000ms full, 500ms fade out), first credit ~5s after go-live then every rand(30s)+30s (30–60s), on the live output and local recordings. An always-on watermark can be cropped or covered; an intermittent full-frame flash can't be cropped and is impractical to edit around on a live feed. The flash is also the free tier's billboard — every free stream advertises LlamaCasty to its own viewers; the free tier is distribution, not compromise. Implemented as Services/Compositor/BrandFlashPresenter.cs (raster + envelope + placement + licence gate), published to both the frame pump (FramePump(brandFlash:) → the compositor's per-frame flashFrame slot) and the preview (BrandFlashElement, bound to BrandFlashImageSource) from the same VideoFrame, so the preview cannot drift from the broadcast. Deliberately NOT the flashFrame parameter of SceneGraph.GetBakedBase — SceneRegion.Matches compares element ids only, so a credit folded into the cached bake would freeze there and never expire. Pre-GA posture — REVERSED 2026-09-26 (TASK 36 shipped). This used to render in the preview only, never on the broadcast, so test VODs stayed clean. The creator ruled that the free tier must be honest advertising: it now composites into the recording and the stream. Test VODs from an unlicensed instance carry the credit — use a license key or the paid build for clean captures. Escalation model (2026-09-01, creator decision): the cadence is obnoxiously self-promoting. License activation still flips exactly one bit: IsPremium → flash off. Nothing else changes between free and paid, ever. Cadence is APP-LIFETIME, not go-live (creator ruling 2026-09-26): the presenter is Start()ed once in the MainViewModel ctor, not from UpdateLiveVisuals(). It used to be gated on IsLive, which meant a recording made without ever going live carried no credit — the creator's ruling: "the made with llamacasty flash should appear in all scenes, not just live" and "should also appear in recordings". One start now covers every scene, the preview, the stream and the recording, because go-live and local recording are the same FramePump (Streaming.Operations.cs:68 and :199 both call StartAsync with the same brandFlash: delegate) — verified, not assumed; there is no second encoder path needing a "redirect". The licence gate needs no live branch: IsPremium's setter pushes Enabled from anywhere. Consequence of app-lifetime — the premium edge restarts the timer. Enabled = false stops the DispatcherTimer (cutting the advertisement mid-credit). Because Start() is no longer called per go-live, nothing would ever restart it, so a key entered mid-session would leave the credit dead until the process restarted. The setter therefore restarts it when re-enabling while _running (IsCadenceTimerEnabled is the test seam). Test-arithmetic trap, hit again 2026-09-26: Advance(5.1) in ONE call cannot observe a credit — Advance both opens the presentation and ages it by the same delta, so a single 5.1s step blows clean through the 2s window. Always step in 1/30s increments like the real timer (the Step helpers in BrandFlashOutputTests).
• Paid: branding flash removed. BrandFlashEnabled is now a derived, non-assignable !IsPremium and the presenter's own Enabled gate is re-checked on every frame, so the entitlement changing mid-credit cuts the advertisement on the next tick rather than letting it finish. That's it. No feature gating. Alerts, social bar slots, voice filters, TRAX, recording — everything is free. How IsPremium is obtained is a billing concern and has changed twice; what it gates has not.
• Pricing: ⛔ SUPERSEDED 2026-10-08 by the free-forever ruling (TASK 54). Retained as reasoning only: $10/mo subscription or $400 lifetime, no annual, ruled 2026-09-27 and overtaken ten days later. If a paid tier ever returns, these are the numbers to argue from. How IsPremium would be obtained is a billing concern; what it gates is not.
• Billing: ⏸ dormant — no paid tier exists (free-forever ruling 2026-10-08, TASK 54). The Store IAP plan of 2026-09-27 was never implemented (Windows.Services.Store appears nowhere in the repo) and was withdrawn with the Store route on 2026-10-22. If a paid tier ever returns, the provider is Polar — merchant of record for VAT/sales tax, 5% + $0.50 Starter, $50 already paid; Distribution.md §4.2/§4.5 holds the design. ⚠️ No Polar product, org ID, key prefix, or discount code exists (d105dfa1-…, c05fb364-…, LCYT-, LLAMAFOUNDER/ LLAMA50, the customer-portal validate endpoint, and the 14-day offline-grace machine are all gone).
• Support (creator's model, corrected 2026-09-01): support = email + GitHub issues — the once-planned in-app bug-reporter is out of product (TASKS.md → closed list). Most queries are how-tos / feature requests / manual-skimmers. Maintenance cadence = "when I get around to it" with emergency patches; not a 24/7 service promise. There is no licence chatter at all — the app is free, there are no keys, and no user sees licence UI. TASK 36 item 5 (expiry reminder) is struck.

Monetization awareness (built-in, ungated, free — 2026-09-01; v1 SCOPE per the complete-v1 ruling — build order: capture → report → journey → Alerts): the app is monetization-aware by design, for every creator, free and ungated (the only subscriber swap remains the branding-flash removal above). It has three layers, all free — this is the product's differentiator, not a paid tier:

• Reward-event capture (the data foundation). The live-chat poll (YouTubeChatService.Poll) receives every reward event over liveChat/messages and — since TASK 43 (2026-09-24) — decodes all six types, not two: superChatEvent, superStickerEvent, newSponsorEvent, membershipGiftingEvent, giftMembershipReceivedEvent, memberMilestoneChatEvent land as ChatMessage.Kind (ChatEventKind) with their payload fields (display string, sticker description, gift count, gifter name, milestone months); free subscriptions emit NO event (API fact — a sub mention is a plain text row). The remaining half of the original capture plan stays open (TASK 3 item 20): persist each event to the canonical SQLite RewardEvents table (broadcastId, type, timestamp, amountMicros, currency, tier...) + superChatEvents.list (30-day lookback) backfill — that persistence is what the session report and the journey tracker read. Alerts did not wait on it: the shipped alert path (TASK 43) renders directly from the in-memory ChatMessage feed.
• Session / broadcast report. A session is created at Go Live; the poll + End roll that session's reward totals (new members, Super Chat , stickers , gifts, milestones). This is the in-app replacement for the emailed external "stream activity report" — the incumbents (Streamlabs et al.) email near-useless post-stream summaries; we track the same data natively and maintain it.
• Journey tracker (TASK 39, slice 1 shipped 2026-09-22). A "YPP" tab below the Stream Settings pull-out (Live screen right edge) shows the connected creator's position toward each YPP tier threshold. Slice 1 = current-scope data only: channels.list?mine=true &part=statistics,contentDetails (subs/views/videos + uploads-playlist id) + playlistItems.list for 90-day public uploads. Every refresh appends a YppSnapshot to SQLite (schema v10) — the history a later slice needs for velocity/ETA. The auditDetails part is OUT (fixed 2026-09-23): readding it 403s the WHOLE request — that part alone requires the youtubepartner-channel-audit scope no app for normal creators should request (the standing flags sat unreadable since slice 1 shipped; the app's youtube + youtube.force-ssl scopes were never sufficient for them — the "no re-consent" slice-1 claim was wrong for that part). Channel standing now deep-links to the Earn page; API stats come from statistics,contentDetails only. YPP/API failures log the response body's error.reason. YPP thresholds are versioned, date-aware DATA, never constants — the Tier-2 bar doubles for new applicants on 2027-02-01 (long-form 4,000 → 8,000 qualified hrs / 365d; Shorts 10M → 20M / 90d), while the Tier-1 fan-funding bar (500 subs / 3,000 hrs / 3M Shorts) is unchanged. Hardcoding the pre-2027 numbers would ship the wrong ETA. Watch-hours / Shorts / velocity / ETA are slice 2: Analytics-API scopes (yt-analytics.readonly, additive yt-analytics-monetary.readonly) behind the IChannelStatsProvider seam (additive capability, requires an OAuth re-consent). Compliance items no API exposes (2FA, AdSense linkage) are in-app self-reported checkboxes with deep links; channel standing (exposed only via the partner-audit scope) deep-links to the Earn page. Slice 2's once-daily refresh gate + snapshot history were baked into slice 1.

What was rejected: always-on watermark (obscurable — replaced by the flash), hard stream-time cutoffs (the worst dead end — a stream dying mid-broadcast reads as broken, and YouTube streams routinely run 2-4 hours), soft-limit nagging, freemium feature tiers, and donation-only (relies on the kindness of strangers). Resolution/quality ceilings stay rejected (fixed 2026-09-01, no longer "deferred"): the free tier never loses quality — auto step-down (TASK 33) is a protect the stream feature, never a monetization penalty.

Auth gates Go Live, but not exploration

The app is fully usable without authentication: users can build scenes, add sources, compose previews, and audition the software with zero commitment. But going live requires authentication — it's the one capability gated behind YouTube sign-in. The sign-in should never pressure the user ("sign in (optional)", not a modal wall): the two-state top bar shows Start Stream (offline) / End Stream (live), and the Start Stream dialog hosts the account — a saved session appears as the default with "Change Account"; with none saved, a "Sign in to YouTube" button starts OAuth and the Start button stays disabled until signed in.

Account assumption (do not build an account setup flow)

Connecting uses Google OAuth ("Sign in with Google") to link an existing YouTube creator account. ytLlive never creates or sets up accounts — that is YouTube's job. If the creator has no YouTube channel, they go to YouTube first. This assumption is explicit and must never be silently replaced by an in-app account-creation step. Zero state = the Start Stream dialog's "Sign in to YouTube" button; going live is unreachable until an account is connected.

YouTube Live API — design constraints (do not violate)

✅ SOLVED 2026-10-04 — the broadcasts never went live because they were never BOUND.

The bug, in one line: contentDetails.boundStreamId on liveBroadcasts.insert does not bind the broadcast. Binding requires an explicit POST liveBroadcasts/bind?id=…&streamId=…&part=id.

How it was finally proven, after a week of misdiagnosis — the diagnostic line, once its own JSON-nesting bug was fixed (FirstItem), read:

lifeCycle=created  privacy=private  autoStart=true  bound=NONE  boundMatches=NO-BINDING
| streamStatus=active  activeChat=none  cdn=rtmp/variable@variable

Every field is real, and together they are conclusive:

• bound=NONE with autoStart=true. Both live in the same contentDetails object on the insert, so the request was well-formed and accepted — the API took one field and silently ignored the other. That asymmetry is the proof; a malformed request would have failed outright.
• lifeCycle=created, not ready. Google: created = "incomplete settings, so it is not ready to transition to a live or testing status". An unbound broadcast is precisely incomplete.
• streamStatus=active — the ingest half was never broken. YouTube had an active stream and a broadcast that was not attached to it.

The causal chain, complete: no binding → lifeCycleStatus stuck at created → enableAutoStart has no bound stream to fire from → never live → close-out 403s invalidTransition because created → complete is not a legal edge (only ready/live are).

Why it survived a week, and the lesson worth keeping: every observable pointed away from the binding. ffmpeg pushed ~99 MB cleanly, the reusable stream went active, close-out returned a transition error (which reads like a lifecycle-timing problem), and the insert returned a valid broadcast ID (which reads like success). A reusable stream accepts bytes for a broadcast that is not watching it, so a perfectly healthy RTMP session is exactly what an unbound broadcast looks like. Google says it outright in the migration guide: "a liveBroadcast must be bound to exactly one stream before the live broadcast can actually start. The broadcast is not bound to any streams at the time that it's created." That sentence was in the docs I read during the original design and was not applied. Read the failure modes in the docs, not just the happy path.

Shipped: YouTubeStreamService.BindBroadcastAsync, called from PrepareAndStartLiveAsync immediately after CreateBroadcast and before the pump starts. Failure is fatal to the session (an unbound broadcast can never go live, so a live-looking UI over it is a lie). boundStreamId was removed from the insert body and the streamId parameter removed from CreateBroadcast — a parameter that looks meaningful but cannot affect the outcome is what made the misdiagnosis possible. The old test CreateBroadcast_With_StreamId_Binds_Reusable_Stream_At_Insert, which asserted the disproven behaviour and therefore laundered a guess into a guarantee, is replaced by CreateBroadcast_Does_Not_Claim_To_Bind_And_Omits_BoundStreamId plus BindBroadcastAsync_Posts_To_Bind_Endpoint_With_Both_Ids_And_No_Body.

Bind failures are not all "sign in again." Google documents six reasons (insufficientLivePermissions, liveStreamingNotEnabled, liveBroadcastBindingNotAllowed, liveStreamNotFound, liveBroadcastNotFound, internalError, plus rate limiting) and only the first is an auth problem. BindFailureMessage maps each to its own text; liveBroadcastBindingNotAllowed matters most, because it means our ordering is wrong and a generic "check the sign-in" would hide a bug in our own code behind a plausible excuse.

These are the hard facts behind every decision. Full list in TASKS.md.

• One-click go-live — never call transition(live). Insert the broadcast with enableAutoStart=true, enableAutoStop=true, enableMonitorStream=false, selfDeclaredMadeForKids=false, latencyPreference=low. The encoder starting brings YouTube live. enableMonitorStream=false is what lets us skip the testing stage.
• ⛔ CORRECTION (2026-10-04): the push is provably healthy — stop investigating it. The long test run settles it: liveBroadcasts.insert at 14:17:04.577, ffmpeg Output #0, flv to rtmp://a.rtmp.youtube.com/live2/5f6z-… at 14:17:05.686, and at 14:18:56.473 ffmpeg's own muxing summary reads video:101229KiB audio:1419KiB, muxing overhead: 0.202949% — ~99 MB of real video plus audio over 112s, which is exactly what 8000+128 kb/s should produce. No socket error, no 4xx from ingest, no reconnect. The broadcast still never left ready, and close-out earned 403 invalidTransition again. An earlier 8s run behaved identically, so "YouTube needed longer" is disproven — 112s is longer. The break is between ingest accepted and broadcast told to start, nowhere in the RTMP path.
• The binding is the prime suspect, and the app was blind to it. contentDetails.boundStreamId ("the live stream bound to the broadcast") and enableAutoStart ("start automatically when you start streaming video on the bound live stream") are both valid on insert, with no documented restriction against a reusable stream. But YouTube's migration guide carries the danger: "a liveBroadcast must be bound to exactly one stream before the live broadcast can actually start. The broadcast is not bound to any streams at the time that it's created." And this failure mode is invisible from the RTMP side, because a reusable stream accepts bytes for an unbound broadcast — ingest succeeding proves nothing. ⇒ LogBroadcastDiagnosticsAsync rides the existing stream-health poll (no second timer) and writes one greppable line: lifeCycleStatus, privacyStatus, recordingStatus, boundStreamId compared against the stream id we are actually pushing (BoundMatches → yes/MISMATCH/NO-BINDING/unknown), boundStreamLastUpdateTimeMs, enableAutoStart/Stop, liveChatId presence, the stream's own status.streamStatus + activeLiveChatId, and the CDN settings we declared. It is self-limiting — _broadcastSeenLive latches on live/liveStarting, so the line shouts only while the broadcast is stuck and goes quiet once healthy. The next run reads this line; it is the whole experiment. Guarded by BroadcastBindingTests.BoundMatches_ComparesTheBroadcastAgainstTheStreamWePush, which pins unknown for a missing expectation so an absent stream id can never be misreported as a match.
  • ⚠️ The first version of this diagnostic LIED, and the first real run caught it (2026-10-04). liveBroadcasts.list returns a list wrapper, so the broadcast lives at items[0]. The original code descended into items for the stream but read the broadcast's response root, so every broadcast field came back ? — and BoundMatches then dutifully reported a confident boundMatches=NO-BINDING from a parse that had never happened. Three lines of fabricated alarm. Two fixes, both load-bearing: FirstItem() descends into items[0] for both halves (and returns default when there is genuinely no item), and the line now prints boundMatches=unread when the broadcast could not be read, so an absent parse can never be reported as a verdict. Guarded by BroadcastBindingTests.FirstItem_DescendsIntoTheListWrapper_AndReportsAbsenceHonestly. Generalisation: a diagnostic must degrade to "I don't know", never to a confident wrong answer — otherwise one level of JSON nesting manufactures a bug that isn't there.
  • What the one run that did work proved: the stream half was correct, and it shows streamStatus=ready → streamStatus=active about 30s into the push. So the ingest does register as active server-side, which is a genuine step forward — combined with the 99MB muxed in the earlier run, the stream half of the system is now verified healthy. The broadcast half is still unobserved pending a re-run.
• Visibility picker (TASK 9 item 6) — DELIBERATE TEST-PHASE LOCK, not drift (2026-09-01). The "always Private" enforcement in YouTubeStreamService.CreateBroadcast stays while the creator runs multi-month real-world testing: non-private test streams would clutter the channel with VODs highlighting where the product breaks. recordFromStart/DVR stay ON — Private VODs are invisible to subscribers and serve as post-mortem review tapes; bulk-delete pre-GA. The unlock is a deliberate final-pass item in TASK 36 (gold pass), wired with the dialog selection — never opportunistic. The PRIVATE badge keeps showing when the stream is actually private.
• ⛔⛔ STOP. The always-Private lock is a DECISION, not a bug, not drift, not an open question. (Creator ruling, restated 2026-10-04 after being asked about it AGAIN.) privacyStatus = "private" hardcoded in YouTubeStreamService.CreateBroadcast is exactly right as written. Do not change it, do not "unlock" it, and — this is the part I keep getting wrong — do not raise it as a question, an observation, a suggestion, or a "heads-up". The creator has now answered this more than once.
  • What it becomes: the hardcoded lock is replaced by a real, user-selectable visibility option in the Go-Live dialog — at v1, not before. Not at 1.0-candidate, not at GA prep, not opportunistically during any other unit.
  • Why it exists: pre-v1 test streams would otherwise publish VODs of a product still breaking, in public, to subscribers. Private keeps those tapes usable for post-mortem review while staying invisible to the channel's audience.
  • Do not let these look like symptoms of the one they resemble. All are working as designed: privacy=private in the broadcast diag line; the PRIVATE badge; recordFromStart/DVR ON; and the absence of any delete call in the codebase (there is no delete feature, by design at this stage — "can we delete the test VODs" is a retired question, answered 2026-10-04: videos.delete accepts youtube.force-ssl which we already hold, private is a visibility setting not a deletion lock, and anyway a broadcast that never reaches live never becomes a VOD at all).
  • UpdateBroadcast is NOT the unlock — and it is also currently DEAD CODE. (Fact corrected 2026-10-04: an earlier version of this note said CreateBroadcast:112 / UpdateBroadcastMetadataAsync, both wrong.) The method that can change a live broadcast's privacy is YouTubeStreamService.UpdateBroadcast(broadcastId, meta), which sends privacyStatus = meta.Visibility ?? "private". It has no production caller — the only caller in the repo is BroadcastPullOutTests.cs:120. So CreateBroadcast hardcoding private is not merely backed up by convention, it is the only thing enforcing it.
  • ⇒ Is a Go Live video private? YES — verified 2026-10-04, and this answers a standing creator doubt. Three independent hardcodes (CreateBroadcast → "private"; GoLiveViewModel.Visibility => "Private"; BeginTestStream → StreamVisibility = "Private") plus one unreachable method. There is no path by which a broadcast this app creates can become non-private today. The creator's actual concern — "do not populate my channel with videos showing the app at its worst" — is fully met.
  • ⛔ THE LANDMINE, and the reason the above matters: LiveBroadcastFormViewModel still exposes VisibilityOptions = {private, unlisted, public} and UpdateBroadcast would happily honour it. The v1 visibility option is the first thing that will ever wire UpdateBroadcast up — so v1 is exactly when this guarantee ends, by the creator's own choice. When that happens, private stops being guaranteed and becomes a default the user can change. That is intended at v1; it is a disaster before v1. Do not wire UpdateBroadcast into any production path before v1, and do not "fix" the dead-code smell by calling it.
• ⛔ The TEST button is HIDDEN at v1 — it exists only because of the lock above (creator ruling 2026-10-04). This was absent from the map entirely until that date, which is how the dry-run framing below came to be the only recorded one. Both are true, and the second is the load-bearing one:
  • Its real job is being the guaranteed-private path. BeginTestStream hard-sets StreamVisibility = "Private" (MainViewModel.Streaming.Operations.cs:105), so Test can never publish. That is why it exists for the whole pre-v1 phase — a dry run you cannot leak.
  • At v1 it is redundant and gets hidden, because once visibility is a real dialog option the user picks Private themselves and a separate "safe" button no longer earns its place. Hiding it is part of the v1 visibility work, not a separate cleanup.
  • The pre-existing "dry run" framing is now known to be incomplete (ShowTestButton's own comment calls it "a dry-run of the livestream"). Do not read that comment as the reason the button must persist, and do not re-derive the button's purpose from it. If a dry run is still wanted at v1 it must be re-justified on its own merits — that question is open, and is for v1, not now.
  • It is a computed predicate, not a setting — ShowTestButton => ShowStreamActions && IsConnected (MainViewModel.Streaming.cs:182), feeding both CanStartTest and the XAML visibility. So the v1 hide is a one-line predicate change, not a settings migration.
  • Not a v1 blocker: the Test route is the same pipeline as Go Live — BeginTestStream → StartStreamingSession(alsoRecord: false) → PrepareAndStartLiveAsync — so Test and Go Live create identical broadcasts (boundStreamId, enableAutoStart). Test differs only in never recording (alsoRecord: false) and forcing Private. This is why Test is the correct way to run any diagnostic stream, and why a Test result is evidence about Go Live.
• Full broadcast form (TASK 9 item 7) — RESCOPED 2026-09-01 — the core editable fields ship (since 2026-08-24) as the always-visible Text drawer: title, description, tags, visibility, made-for-kids, live-editable; scheduling ships as TASK 34 (drawer ☑ Scheduled + adoption at Start). The old Advanced tab is permanently out of product (the 10% margin — see TASKS.md → "Out of product"): latency locked low, DVR/record-from-start locked on, embed/projection/CC/region fixed at sane defaults, invisible — every exposed field is a support ticket. categoryId is removed from CreateBroadcast (not a liveBroadcast field, silently ignored). Monetization enablement (if ever needed) rides the reward-events chain via liveBroadcasts.update, not a form field. Go-live order (TASK 9, shipped 2026-08-16): BeginGoLive → PrepareAndStartLiveAsync — ensure the reusable stream (GetOrCreateReusableStreamAsync, cache it), create the broadcast bound to it (CreateBroadcast(..., stream.Id) → boundStreamId), THEN start the pump (the URL must exist before FramePump.StartAsync, which reads it once). Failure → StreamStatus.Error, never a crash; StopStream clears _currentBroadcastId.
• Variable reusable stream (shipped 2026-08-16) — GetOrCreateReusableStreamAsync lists liveStreams?mine=true and reuses the existing cdn.isReusable stream, inserting once per channel (cdn.resolution=variable, cdn.frameRate=variable, isReusable=true) only on first use; the ingestion URL is cached via LayoutStore Settings (SaveReusableStream/LoadReusableStream) and bound to each broadcast at insert (boundStreamId). Any quality tier works without recreating the stream, and auto step-down rides the same property — we drop bitrate/resolution on the fly, zero API calls — but the deciding governor is not built: the old present tense there was a map-lie, corrected 2026-09-01; step-down is TASK 33 (v1 scope).
• Quality is greyed out while live — resolution/frameRate/ingestionType are immutable after stream creation; editing title/description/privacy is fine at any time.
• Report-by-exception health (SHIPPED 2026-08-16, TASK 9 item 3) — YouTubeStreamService.GetStreamHealthAsync(streamId) polls liveStreams.list?part=status; render nothing on good/ok/noData, surface a banner only on configurationIssues[] with warning/error severity. The decision is the pure Services/StreamHealthReporter.BannerFor (null text = no banner; error beats warning). The VM polls every 30s while live (DispatcherTimer _healthPollTimer, first poll right after go-live) and clears on End via ResetHealth; poll failures log only. Parsing (fix 2026-09-22): the real API nests status.healthStatus = {status, lastUpdateTimeSeconds, configurationIssues[]} — reading it as a string crashed every poll (requires an element of type 'String', seen 2026-09-22 on both test sessions); the parse now reads the nested .status/configurationIssues and tolerates the old flat-string shape. UI = a full-width banner strip under the top bar, HealthIssueBanner text + HealthIssueBackground (amber #b8860b warning / dark red #8f1f1f error), hidden by NotNullToVis. The design's bottom-strip YouTube logo + green/red dot (clickable → dialog) is still queued.
• One dialog, three states — not connected / 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.
• End stream (SHIPPED 2026-09-01; pre-flight hardened 2026-09-22) — stop encoder → YouTubeStreamService.EndBroadcastAsync POSTs liveBroadcasts/transition?broadcastStatus=complete&id=…&part=status (AFTER RTMP EOF, so no frames post-date the end — VOD finalizes immediately instead of ~1min of frozen "stream offline"). 2026-09-22: every end logged 403 invalidTransition — a blind complete races enableAutoStop/YouTube's auto-complete (the old doc's "already fired" guess was wrong; it's a broadcast state race). The call now pre-flights liveBroadcasts.list→status.lifeCycleStatus and only transitions from live/testing, skipping silently otherwise (enableAutoStop finishes every skip — never throws, never toasts a finished session). Inconclusive pre-check still posts (old behavior, backstopped). Record-only stops make ZERO API calls (guard: wasLive && _currentBroadcastId != null).
• Encoder compliance — keyframes ≤ 4s (gopSizeLong), closed GOP, H.264, AAC/MP3 @ 44.1/48kHz, mono/stereo only. YouTube flags violations via health status.
• Broadcast ID == Video ID — one ID tracks status, health, and the auto-created VOD (recordFromStart + enableDvr default true).
• Test Stream mode (TASK 41, SHIPPED 2026-09-22) — every broadcast is private-only anyway (see the visibility lock above), so "Test" is a session variant over the real go-live pipeline, not a new mode: BeginTestStream → StartStreamingSession(alsoRecord:false) (the dialog path was extracted into this shared boot — no Go Live dialog for a Test, no BroadcastForm.CaptureGoLive "last live" stamp, no recording). IsTestStream flips the face: gold top bar + glow (#9c6f1c), a TEST badge, and the End button reads "End Test"; StopStream clears it in every path (including pump-failure rollback). Once the liveChatId resolves, TestSession.BeginTest(broadcastId, liveChatId) opens the TEST drawer (third right-rail pull-out, three-way one-open-at-a-time exclusivity wired in MainViewModel.Ypp.cs; any left-click outside the rail closes whichever drawer is open — TEST included (fixed 2026-09-25, TASK 46; the code-behind outside-click close in MainWindow had skipped TestSession, so only Stream Settings + YPP dismissed on an outside click). liveChatId resolution (fixed 2026-09-25, TASK 44; ⚠️ CORRECTED 2026-10-04): the id is snippet.liveChatId — contentDetails has NO liveChatId property — and GetBroadcastLiveChatIdAsync(broadcastId, maxAttempts=10, delayMs=2000) reads part=snippet and polls with a bounded retry, and PrepareAndStartLiveAsync starts the frame pump FIRST before resolving it. The old claim that "YouTube only populates it once the broadcast is LIVE" is WRONG, and it was inferred from a sample rather than from the API. The 2026-10-04 diagnostic caught liveChatId=present while lifeCycleStatus=created — not live, not even ready. The official GetLiveChatId.java sample tests broadcastStatus == active before returning the id, and that read as a statement about when YouTube populates the field; it is only a guard in the sample. Generalisation: a sample's defensive check is not a spec. Also note the old note said the missing id meant "the ready state" — the broadcasts were never ready at all, they were created and unbound (see the SOLVED box above), so the terminology was wrong too. The bounded retry is harmless and stays, but the id is available far earlier than assumed — worth revisiting only if chat startup latency is ever reported as slow. Drawer tooling: Mock Chat Input = a REAL liveChat/messages.insert (YouTubeStreamService.InsertChatMessageAsync) that round-trips through the real ~2s poll and renders through the live overlay path; simulated Subscriber / New Member / Super Chat = YouTubeChatService.InjectSimulatedMessage, which raises the poller's MessageReceived seam, marked ChatMessage.IsSimulated. API fact (researched + hard constraint): liveChat/messages.insert only creates textMessageEvents — SuperChats / memberships / sponsorships cannot be inserted via any API; simulated non-text events are local-only by design and never reach YouTube. Insert body shape (fixed 2026-09-25, TASK 45): the body MUST include snippet.type = "textMessageEvent" alongside liveChatId and textMessageDetails.messageText — omitting type returns 400 MISSING_REQUIRED_FIELD (found live on the next Test Stream; the TASK 41 test had asserted body presence but not type, so it stayed false-green). Scopes youtube + youtube.force-ssl already cover insert. Real stinger/TTS alert widgets are DONE (TASK 43, shipped 2026-09-24) as the native alert box — see the next section; Text source (TASK 3 item 16) and the RewardEvent persistence (item 20) remain open.

Native events & alerts (TASK 43, shipped 2026-09-24 — StreamElements replaced)

The creator asked to replace the external StreamElements feed with native YouTube events; the answer is native events + a native alert box, and the product decisions are published decisions (recorded in TASKS/task-43-native-alerts.md):

• No third party. The chat feed IS the event feed: liveChat/messages carries all six monetization events (superChat / superSticker / newSponsor / membershipGifting / giftMembershipReceived / memberMilestoneChat). streamList is the connection semantics of that same endpoint (pollingIntervalMillis-driven), not a separate call — the service re-arms its one-shot poll on the server's cadence (clamp 1000–6000ms), maxResults=2000. Cite: https://developers.google.com/youtube/v3/live/docs/liveChatMessages/streamList
• SourceType.AlertBox — one "Stream Alerts" celebration zone per layout, OBS alert-box style: a designated draggable canvas area, idle = transparent. Mirrors the chat gate (CanAddAlerts; AddSource refuses a second). Defaults 620×430 → 680×200.
• Six events → six unique animations (Services/AlertRenderer.cs): SuperChat slide-up
  • gold count-up + shine sweep (green), SuperSticker scale-pop on a tilted chip (purple), NewMember drop-in + flash band (violet), MemberGift slide-left + gift-chip ×N fan (amber), GiftReceived confetti scale-in (green→purple), MemberMilestone rise + tenure growth bar (orange). Phases enter/hold/exit (~4–5s); every card draws the brand line "made with LlamaCasty!" — each broadcasted event is free product placement.
• Services/AlertOverlayLayer.cs — the component: enqueues events one-at-a-time, advances on a 33ms dispatch ticker, serves the live frame through RenderFrame (same cache-first pattern as chat) and the preview through UpdatePreview; Advance(double) is the deterministic test clock (tests drive playback with no timer). Queue cap 10 (floods drop the tail, never stall). ChatEventKind.None rows (plain chat, sub mentions) never enqueue — per the creator ruling, a subscriber mention is sufficient; there is no free-sub alert (YouTube emits none) and no viewer count (vetoed — demotivating, weaponizable).
• Alert box VIDEO (TASK 47, 2026-09-26): since TASK 47 the box plays a clip on every alert instead of (only) an animation — Enqueue→BeginClip spawns a per-play IAlertClipDecoder (ffmpeg rawvideo bgra -vf scale=W:H frame pipe + f32le audio pipe, both real-time paced via RawVideoFrameReader; not the refcounted MediaVideoSourceManager — alerts are one-shot plays that must be disposed at drain). Custom clip wins per-source over the built-in ONLY when AlertUseDefaultVideo==false AND the file exists; the shipped Assets/alert-default.mp4 is stamped into the Asset table at startup (AlertDefaultVideoKey setting; the prune keeps it via UNION) and read-at-play; any decode failure falls back to the six AlertRenderer animations (deliberate, not an error). Fades in/out via FadeDurationSeconds = 0.30 (AlertOverlayLayer const): fade-in by elapsed on straight-alpha frame copies; EOF → freeze-frame → fade-out → drain (the clip branch of Advance clears _current before AdvanceToNext — the miss that the TASK 47 test caught). Audio forwards to the mixer sink scaled by volume × fade.
• Alert ticker (announcement strip): AlertTickerFrame (in the layer) composes "Author — Kind · amount" and hands it to Services/Compositor/AlertTickerRenderer.cs — a strip rasterized on the UI thread once per text (cached, unpremultiplied straight-alpha pill) then positioned by pure byte-math per call, so the pump calls it from its own thread with no locking. It is a dynamic overlay, NEVER baked (the social bar IS baked into BakeStaticBase): SceneCompositor.Render + CompositeLayers take a trailing tickerFrame threaded from FramePump._alertTicker (Func<VideoFrame?> ctor seam) through RenderScene/RenderFull and mixed into BuildFullRenderSignature so a scroll changes the cache key. Toggled by AlertShowTicker.
  • It draws INSIDE the Stream Alerts box (creator ruling 2026-09-26). Was a global 1920px bar pinned to the top edge: "the ticker should appear over the stream alerts video, not over the entire preview window". The strip is now rendered at the alert box's own size (AlertTickerRenderer.Render(..., width, height), defaults still 1920×48) and the box's origin rides on VideoFrame.Placement ((int X, int Y)?, with OriginX/OriginY = 0 when unset). Every blit site reads tickerFrame.OriginX/OriginY instead of a literal 0, 0 — SceneCompositor ×2 and FramePump's static-bake Overlay path. The preview binds the same numbers (AlertTickerLeft/Top/Width/Height → AlertTickerElement's Canvas.Left/Top + Width/Height), so preview and output cannot drift — the same guarantee as the branding credit. Product default box is 680×200 at (620, 430) (MainViewModel.Sources.cs); height is clamped to the natural 48px strip. No alert box in the scene ⇒ no ticker at all — there is no global position left.
  • Why the position travels on the frame, not in a full-canvas frame: a 1920×1080 overlay is 8.3MB of large-object-heap garbage per tick — ~2.5GB churned over one 10s alert at 30fps. A box-sized strip is ~370KB. The branding flash does render full-canvas, but it recycles one 8MB buffer and bumps Epoch, so it never allocates per frame; the ticker allocates per call, so it must stay small.
  • CopyStrip clips rows to the target height: the pill rasterises at its natural 48px, so a box shorter than 48px would otherwise write past the end of the buffer.
  • Three display methods (Source.AlertDisplayMethod, DB column, panel "Display" selector): TickerScroll (marquee), Flash (0.5s on / 0.5s off), Solid (centred, still). The marquee is paced in reads per alert — TickerReadsPerAlert = 3 passes inside the alert's own length, speed derived from that — never px/s; the old fixed 140px/s took ~17s per pass, so a 10s alert showed the message once. Same convention as the incumbent (Streamlabs: "Alert Duration" + "Text Delay", not a scroll-speed slider). Flash's off half returns null.
  • A ticker still needs its own preview element, not a Source. It is a frame-pump producer, so it never rides a per-element Image; AlertOverlayLayer takes a tickerPreviewSink and publishes from RefreshAlertPreviews() (UI thread only — the pump thread must never touch a WriteableBitmap); the VM writes it into one reused WriteableBitmap (AlertTickerImageSource/AlertTickerVisible) bound to AlertTickerElement in PreviewPane.xaml, mirroring SocialBarElement. The rect is re-raised on every published frame, not just on a bitmap resize, so a box moved or resized mid-alert tracks live.
  • Two measurement traps here: a seamless marquee never goes blank (a wrapped copy enters as the pill clears), so count a pass by the pill's leading edge resetting, not by an empty frame; and the run is phase-started half a frame in, or the first published frame is blank (the pill sits exactly off the right edge).
• Alert audio under the master limiter: AudioMixer.EnqueueAlertAudio writes a dedicated 8s stereo-48k ring (AlertBufferSeconds), drained in FillAndMix before the limiter and added at unity — never ducked (creator ruling: "don't lower my game audio for a tip"); StartLive clears it. Per-alert loudness = the Volume slider.

---

Windows packaging & distribution (⛔ REVERSED 2026-10-22 — direct + Steam; Store dropped)

The Microsoft Store route is dead. A brand name on the Store's publisher line requires a Company account, which requires a registered legal entity (an LLC — ~$85 New Mexico with a ~2-week SOS backlog, ~$143 Wyoming). Partner Center does not convert an Individual account to a Company account later, and an Individual account publishes under the verified legal name. The creator will not fund an entity for a nameplate, so the 2026-09-27 Store ruling was withdrawn on 2026-10-22. Store IAP was never implemented either — Windows.Services.Store appears nowhere in the repo.

The route now:

1. Direct download from llamacasty.com — the app is free forever (TASK 54), so there is nothing to bill in v1.
2. Steam when $100 exists — Steam Direct is $100 per product (recoupable after $1,000 AGR), accepted categories include Audio/Video Production / Player Tools (OBS Studio is the precedent), the developer/publisher name is self-chosen so the brand needs no entity, 5+ screenshots at 1920×1080 + capsule art, a build Valve runs, and a 2-week live page before release. Valve takes 30%.
3. Polar is dormant, not deleted-in-principle — chosen checkout/licence provider if a paid tier ever returns; $50 already paid. Distribution.md §4.2/§4.5 holds the design.
4. The Microsoft Store: not pursued. The MSIX package stays as a working artifact and is submitted nowhere. History: TASKS/research-store-certification.md, TASKS/task-48-distribution-msix.md.

Consequences that are architecture, not packaging detail:

• ⛔ The updater is now MISSING, not deleted-by-design. Velopack and its bootstrap were removed on 2026-10-22 (TASK 48 slice 3) because the Store was going to deliver updates — that premise is gone. An update path must come back, and ytLive.Tests/StorePackagingTests.cs (which asserts no updater returns) must be rewritten with the chosen updater rather than left to veto one.
• The MSIX package still builds via scripts/package-msix.sh (TASK 48 slice 2) — publish Release -r win-x64 --self-contained into artifacts/msix-stage, copy Packaging/Package.appxmanifest in as AppxManifest.xml + Packaging/Assets/, then makeappx pack → artifacts/LlamaCasty.msix (159 MB, gitignored; MSIX_PFX signs it for a local install). The manifest is a full-trust packagedClassicApp at mediumIL with runFullTrust + webcam + microphone. Square310x310Logo/Wide150x150Logo traps are in MyMistakes.md. Logos come from the app's own artwork via scripts/make-store-logos.py.
• ⛔ Bundle ffmpeg — no runtime downloads (was Store policy 10.2.2; still right for a direct download, and it fixes the 2026-09-01 404). See the FFmpeg locator section above.
• ⛔ 64-bit Windows only (creator ruling 2026-10-09). Both csproj files set <PlatformTarget>x64</PlatformTarget> (the test project too — an AnyCPU test project referencing an x64 app raises MSB3270 and breaks the 0-warning gate). Why: the bundled ffmpeg is the win64 build, ONNX Runtime 1.31 ships no win-x86 native (only win-x64/win-arm64), and a 32-bit address space can't hold the 1080p frame buffers. Windows 11 is 64-bit-only anyway. Public copy says "64-bit Windows 10 or 11".

What does NOT change: the monetization posture. The app is free forever with no watermark (TASK 54, 2026-10-08), so IsPremium gates nothing in v1 and the branding flash is OFF by default. Monetization above governs.

⛔ Durable invariant: full trust, or recording silently breaks

MSIX packages run at one of two trust levels. A packaged WPF app declaring rescap:Capability Name="runFullTrust" runs at mediumIL — the same permissions as a standard desktop app, NOT AppContainer — and may spawn child processes, which is why bundling ffmpeg is legal. Writes to user-profile locations (AppData, Downloads, MyVideos) pass through unvirtualized at mediumIL; the package install folder is read-only.

ViewModels/MainViewModel.Recording.cs writes recordings to %USERPROFILE%\Downloads / SpecialFolder.MyVideos (DefaultRecordFolder(), ChooseRecordFolder() via Microsoft.Win32.OpenFolderDialog), and the whole temp-write-then-move lifecycle stays in one directory. That works only because we are full trust. No broadFileSystemAccess capability is needed, and none should be added.

⚠️ If anyone flips the manifest to appContainer, Directory.CreateDirectory and File.Move start resolving to a per-package virtualized location and output vanishes with no error. A comment at DefaultRecordFolder() is owed when the manifest lands (TASK 48 item 6) — not before; a comment describing a manifest that doesn't exist is worse than none.

Signing — do not buy EV

Microsoft removed the SmartScreen instant-bypass for EV certificates in March 2024. An EV-signed file now accrues reputation exactly like an OV-signed one, so EV ($400+/yr) buys what OV (~$150–300/yr) buys. Signing is not instant regardless — a valid cert stops the malware warning immediately, but "unrecognized publisher" clears only as SmartScreen accrues reputation from real download volume. Cert validity is capped at 460 days (recurring line item) and private keys must live on an HSM or hardware token. The 2026-10-22 ruling is to ship unsigned and accept the "unrecognized publisher" warning until download reputation accrues — buying a certificate is deferred, not rejected. Distribution.md §4.3 was corrected 2026-09-27 (it previously recommended EV).

Distribution and licensing are independent — and the channel decision does not decide licensing

A Store-distributed app may still verify licences with Polar (Store policy 10.8.1 explicitly permits a secure third-party purchase API for non-game PC products), so "which channel?" never implied "which billing?" — route B was a real option. The 2026-10-22 reversal proves the point in the other direction: dropping the Store did not by itself restart Polar, because the 2026-10-08 free-forever ruling (TASK 54) had already removed the paid tier. Polar is therefore dormant, ready if a paid tier ever returns, and nothing in v1 depends on it. The lesson worth keeping: the licensing choice rides on a monetization decision, not on a distribution decision.

⛔ "Only when the user says so" is enforced by Windows, not by us

Camera/mic consent is layered: Store policy 10.6 forbids circumventing OS checks; the Windows desktop-app camera/microphone toggle (Settings → Privacy & security, since Win10 1903) is the gate; hardware lights and tray indicators are the OS's disclosure mechanism. So route everything through the standard MF/DShow/WASAPI paths and we never write that certification ourselves — the OS does it and gets neither our credit nor our blame.

⚠️ Untested: whether that toggle reliably gates a DShow webcam and a capture card. Microsoft's own support page admits desktop apps "might still be able to access your camera or microphone even when these settings are turned off." This is not a certification failure (we declare webcam honestly and use supported APIs) but it is a real user-trust issue — so no privacy-forward marketing copy until it is measured. Guard note added to MARCOM.md.

⛔ Durable invariant: chat is rendered, never stored

TASK 49's profanity filter is local, on-device, opt-in, non-persistent, with a user-supplied word list — never a hardcoded slur list baked into the binary (unpleasant artifact, false positives across dialects, extractable). It must never match the SuperChat amount or any reward field — those are financial data under policy 10.5.5.

The non-persistence half is not just hygiene: it is the load-bearing half of the 11.12 UGC certification answer (mirrored YouTube chat is moderated at industrial scale upstream; ~1.6B comments removed in Q1 2026 alone, child safety the #2 reason at 124.6M). No future feature — chat history, moderation logs, analytics, crash payloads — may quietly break that assumption. If one is ever proposed, the 11.12 position must be re-argued first.

Minors

The operator is 13+ by construction, not by promise: LlamaCasty requires a YouTube account to stream, and YouTube's ToS sets the account floor at 13 (regional variants reach 14; 13–17 need parent/guardian permission; under-13s are on supervised/YouTube Kids accounts). So a COPPA theory premised on collecting PI from under-13s has no purchase against the operator. The residual is viewers — still possible on supervised family accounts — and it is weak: live chat is restricted there, YouTube moderates before we see it, and we persist nothing. COPPA is very unlikely to bind (not child-directed), but note the enforcement trend (FTC Sept 2025 Apitor: operators are responsible for what third-party components collect) — so the answer is a documented inquiry, and ours is "no third-party analytics or ad SDKs, no persisted chat or reward payloads."