ytLlive/ai.md

ytLlive — AI Guide

Memory map entry point. Conventions live in schema.md; task status and YouTube API research in TASKS.md; directory maps in each folder's index.md. Reading order: this file → TASKS.md → <dir>/index.md → source.

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.

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.

Run

dotnet build   # Windows only — WPF requires Windows target
dotnet run

Note: EnableWindowsTargeting=true is set in ytLive.csproj, so the project can be restored/built from WSL, but running requires Windows.

Tests

No test framework set up yet. When added: dotnet test.

Architecture

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

Path	Role
Models/	Plain data types — Scene, Source, QualityOption, StreamConfig, StreamHealth, YouTubeChannel, ChatMessage
ViewModels/	MainViewModel — exposes collections + commands for the UI; GoLiveViewModel, ReuseImageViewModel
Services/	YouTube OAuth2, stream/broadcast management, live chat polling, LayoutStore (SQLite)
Helpers/	ViewModelBase (INotifyPropertyChanged), RelayCommand, ImageCache, AppLog (file logger), FocusPreservingListBox, OAuthCredentials, 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), left (scenes/sources), right (chat), bottom (health)

Key patterns

• ViewModelBase.SetProperty<T>() for property change notifications
• RelayCommand for all button actions; commands gate on state (e.g. Start only when Offline)
• ViewModels are constructed in XAML (<vm:MainViewModel/> as DataContext)
• 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)
• 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)
• Resolution tiers (bottom bar): 1080p60@8 → 1080p30@8 → 720p60@6 → 480p30@2.5 Mbps; default = first. A tooltip explains finding upload bandwidth — an in-app speed test was deliberately dropped (unreliable)
• 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)

Current limitations / TODOs

• Helpers/OAuthCredentials.cs now contains the real ClientId/ClientSecret — auth service is implemented, but tokens still don't persist (Windows DPAPI planned; account UI in the GoLive dialog is simulated)
• GoLiveViewModel.SignIn/ChangeAccount removed — Connect (OAuth) is the only entry to streaming
• Scene/source/asset layout does persist (SQLite); token persistence does not (yet)
• YouTubeStreamService uses hardcoded 1080p/60fps and per-broadcast streams — must switch to the v3 variable reusable stream
• No capture/encoding/RTMP yet
• StreamConfig defaults (TargetBitrate=6000, Resolution="1920x1080") are stale — the live dropdown drives StreamHealth.CurrentBitrate/FPS instead

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

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

Free forever: all streams unlimited, no time caps, no subscription, no per-feature paywalls. The one paid line is a one-time unlock (delivered via itch.io — they handle hosting, payment, and key delivery; we never own a server or a key shop):

• Free: a periodic full-frame branding flash — "made with ytLlive!" rendered big and centered at ~25% opacity for about one second (soft 250ms fade in/out), repeated every 300s, on the live output (and on v0.2 local recordings). Implemented as BrandFlashLayer in the preview compositor (MainWindow.xaml CanvasGrid) + BrandFlashTimer in MainViewModel — cadence 300s, first flash ~5s after go-live, only while live or recording. 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.
• Paid (one-time): branding flash removed (flips BrandFlashEnabled off) + Alerts (Super Chat / membership / subscribe pop-ins).

Deliberately 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 tiers, and donation-only (relies on the kindness of strangers). Resolution/quality ceilings are deferred — that decision belongs to the resolution & streaming-constraints conversation, not monetization.

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 button should never pressure the user ("sign in (optional)", not a modal wall), but "Go Live" only appears once connected.

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 = a Connect button that starts OAuth; going live is unreachable until the account is connected.

YouTube Live API — design constraints (do not violate)

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.
• Variable reusable stream — liveStreams.insert once per channel with cdn.resolution=variable, cdn.frameRate=variable, isReusable=true; cache the ingestion URL + stream name and reuse for every broadcast. Any quality tier works without recreating the stream, and auto step-down is done by us dropping bitrate on the fly (zero API calls).
• 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 — poll liveStreams.list; render nothing on good/ok, surface a banner only on configurationIssues[] with warning/error severity. Bottom strip = YouTube logo
  • green/red connection dot (clickable → opens the dialog).
• 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 — stop encoder → transition(complete), enableAutoStop as the safety net.
• 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).