LlamaCasty/docs/ai/overlays.md

Output overlays: social bar, alerts, chat

Everything composited over the frame: the social bar, the native alert box (six event animations, alert video, ticker), and the chat box conventions. Read before touching any of them or anything that composites a global layer.

Invariant: every global overlay must be composited on every render path — pump, preview/thumbnails, scene dump (SceneCompositor.Overlay is shared by all three). A feature wired into one path is silently absent from the output. That bug ("preview-only forever", 2026-09-26) is why the rule exists.

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").

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.

• Ticker settings and alert feed: Models/Ticker.cs is shared by the AlertBox and standalone SourceType.Ticker layers. Each source owns a distinct settings instance (IsEnabled + DisplayMethod); the existing AlertShowTicker and AlertDisplayMethod columns persist those settings on their own Source row, so this is additive without a schema migration. The standalone ticker can be added once in each scene and shows the in-memory active event plus queued events. Completed events are not retained as history. The AlertBox ticker uses the same renderer/settings shape but shows only the active event.

• AlertBox ticker (announcement strip): AlertBoxTickerFrame 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<Scene, VideoFrame?> ctor seam) through RenderScene/RenderFull and mixed into BuildFullRenderSignature so a scroll changes the cache key. It reads the active scene's AlertBox settings.

  • 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.
  • AlertBox preview: tickerPreviewSink publishes from RefreshAlertPreviews() (UI thread only — the pump thread must never touch a WriteableBitmap); the VM writes the box-sized frame into the reused bitmap bound to AlertTickerElement in PreviewPane.xaml. The rect is re-raised on every published frame so a box moved or resized mid-alert tracks live.
  • Standalone ticker preview/output: it is an ordinary dynamic Source with a per-element frame. AlertOverlayLayer updates each scene ticker's reusable VideoImageSource on its UI timer for preview; the output resolver renders the same source with that source's Ticker settings. It is not the AlertBox global ticker callback, so each scene's layer and settings remain independent.
  • 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.

• Alert sound byte (2026-11-01, creator ruling): the alert layer can carry an audio file (AlertAudioPath) that plays with the clip, plus AlertAudioLoop to repeat it under the clip ("Loop the sound until the video ends"). The video is always one pass to completion. ⛔ Alert audio plays on the DEFAULT OUTPUT DEVICE, not into the mixer (Services/Audio/ AlertAudioOutput for the clip's own PCM, MediaPlayer for the sound byte). That is deliberate: only audio that reaches the speakers is captured by the WASAPI loopback, which is what makes it audible to the creator and visible in the desktop sound bar. The old EnqueueAlertAudio path produced sound that was in the stream but invisible in the meter and inaudible in the room. Failure to open a device is logged and swallowed — a silent alert still renders.