TASK 3 milestone 1: webcam capture (MediaCapture CPU-first, CameraManager refcount, picker, clip/mirror, schema v2, tests)

Services/CameraDeviceInfo.cs

@@ -0,0 +1,13 @@
+namespace ytLive.Services;
+
+public sealed class CameraDeviceInfo
+{
+    public string Id { get; }
+    public string DisplayName { get; }
+
+    public CameraDeviceInfo(string id, string displayName)
+    {
+        Id = id;
+        DisplayName = displayName;
+    }
+}

Services/CameraManager.cs

@@ -0,0 +1,218 @@
+using System;
+using System.Collections.Generic;
+using System.Threading.Tasks;
+using System.Windows;
+using System.Windows.Media;
+using System.Windows.Media.Imaging;
+using System.Windows.Threading;
+using ytLive.Helpers;
+
+namespace ytLive.Services;
+
+/// <summary>
+/// Owns webcam capture sessions app-wide, refcounted by DeviceId. One device =
+/// at most one capture, one shared WriteableBitmap; the last release stops and
+/// disposes the source. Frames arrive on a worker thread and are coalesced onto
+/// the UI dispatcher (at most one pending copy per session, using the latest
+/// frame) so a 60fps device doesn't drown the render thread.
+/// </summary>
+public sealed class CameraManager : IDisposable
+{
+    private sealed class CameraSession
+    {
+        public string DeviceId { get; }
+        public ICameraFrameSource Source { get; }
+        public Action<VideoFrame>? FrameHandler;
+        public int RefCount;
+        public bool Started;
+        public WriteableBitmap? PreviewBitmap;
+        public VideoFrame? LatestFrame;
+        public bool FramePending;
+
+        public CameraSession(string deviceId, ICameraFrameSource source)
+        {
+            DeviceId = deviceId;
+            Source = source;
+            RefCount = 1;
+        }
+    }
+
+    private readonly ICameraEnumerator _enumerator;
+    private readonly Func<string, ICameraFrameSource> _frameSourceFactory;
+    private readonly Dispatcher? _uiDispatcher;
+    private readonly Dictionary<string, CameraSession> _sessions = new();
+    private readonly object _gate = new();
+
+    /// <summary>Raised on the UI thread when a camera's shared preview bitmap is first created.</summary>
+    public event Action<string, WriteableBitmap>? PreviewBitmapChanged;
+
+    /// <summary>Raised when a capture fails to start (device in use, access denied, no preview source).</summary>
+    public event Action<string, string>? CameraFailed;
+
+    public CameraManager(ICameraEnumerator enumerator, Func<string, ICameraFrameSource> frameSourceFactory,
+        Dispatcher? uiDispatcher = null)
+    {
+        _enumerator = enumerator;
+        _frameSourceFactory = frameSourceFactory;
+        _uiDispatcher = uiDispatcher;
+    }
+
+    public ICameraEnumerator Enumerator => _enumerator;
+
+    /// <summary>Increments the refcount for a device, starting capture the first time.</summary>
+    public async Task<bool> AcquireAsync(string deviceId)
+    {
+        if (string.IsNullOrWhiteSpace(deviceId)) return false;
+
+        CameraSession session;
+        bool shouldStart;
+        lock (_gate)
+        {
+            if (_sessions.TryGetValue(deviceId, out var existing))
+            {
+                existing.RefCount++;
+                shouldStart = false;
+                session = existing;
+            }
+            else
+            {
+                session = new CameraSession(deviceId, _frameSourceFactory(deviceId));
+                session.FrameHandler = frame => OnFrameAvailable(session, frame);
+                session.Source.FrameAvailable += session.FrameHandler;
+                _sessions[deviceId] = session;
+                shouldStart = true;
+            }
+        }
+
+        if (!shouldStart) return session.Started;
+
+        try
+        {
+            await session.Source.StartAsync();
+            session.Started = true;
+            return true;
+        }
+        catch (Exception ex)
+        {
+            lock (_gate)
+                _sessions.Remove(deviceId);
+            session.Source.FrameAvailable -= session.FrameHandler;
+            AppLog.Write($"CameraManager: failed to start camera '{deviceId}': {ex.Message}");
+            CameraFailed?.Invoke(deviceId, ex.Message);
+            await SafeStopAsync(session.Source);
+            return false;
+        }
+    }
+
+    /// <summary>Decrements the refcount; stops and disposes the source at zero.</summary>
+    public async Task ReleaseAsync(string deviceId)
+    {
+        CameraSession? toStop = null;
+        lock (_gate)
+        {
+            if (!_sessions.TryGetValue(deviceId, out var session)) return;
+            if (--session.RefCount > 0) return;
+            _sessions.Remove(deviceId);
+            toStop = session;
+        }
+
+        if (toStop == null) return;
+        toStop.Source.FrameAvailable -= toStop.FrameHandler;
+        await SafeStopAsync(toStop.Source);
+        toStop.PreviewBitmap = null;
+    }
+
+    public VideoFrame? GetLatestFrame(string deviceId)
+    {
+        lock (_gate)
+            return _sessions.TryGetValue(deviceId, out var session) ? session.LatestFrame : null;
+    }
+
+    public void Dispose()
+    {
+        List<CameraSession> sessions;
+        lock (_gate)
+        {
+            sessions = new List<CameraSession>(_sessions.Values);
+            _sessions.Clear();
+        }
+
+        foreach (var session in sessions)
+        {
+            session.Source.FrameAvailable -= session.FrameHandler;
+            _ = SafeStopAsync(session.Source);
+        }
+    }
+
+    private static async Task SafeStopAsync(ICameraFrameSource source)
+    {
+        try
+        {
+            await source.StopAsync();
+        }
+        catch (Exception ex)
+        {
+            AppLog.Write($"CameraManager: stopping camera failed: {ex.Message}");
+        }
+    }
+
+    private bool TryGetActiveSession(CameraSession session)
+    {
+        lock (_gate)
+            return _sessions.TryGetValue(session.DeviceId, out var current) && ReferenceEquals(current, session);
+    }
+
+    private void OnFrameAvailable(CameraSession session, VideoFrame frame)
+    {
+        if (!TryGetActiveSession(session)) return;
+        session.LatestFrame = frame;
+
+        if (session.PreviewBitmap == null)
+        {
+            if (_uiDispatcher == null) return;
+            if (_uiDispatcher.CheckAccess())
+                EnsurePreviewBitmap(session);
+            else
+                _uiDispatcher.BeginInvoke(() =>
+                {
+                    if (TryGetActiveSession(session))
+                        EnsurePreviewBitmap(session);
+                }, DispatcherPriority.Render);
+            return;
+        }
+
+        if (_uiDispatcher == null || _uiDispatcher.CheckAccess())
+        {
+            CopyFrame(session);
+            return;
+        }
+
+        if (session.FramePending) return;
+        session.FramePending = true;
+        _uiDispatcher.BeginInvoke(() =>
+        {
+            session.FramePending = false;
+            if (TryGetActiveSession(session) && session.PreviewBitmap != null)
+                CopyFrame(session);
+        }, DispatcherPriority.Render);
+    }
+
+    private void EnsurePreviewBitmap(CameraSession session)
+    {
+        if (session.PreviewBitmap != null || session.LatestFrame == null) return;
+        var frame = session.LatestFrame;
+        var bitmap = new WriteableBitmap(frame.Width, frame.Height, 96, 96, PixelFormats.Bgra32, null);
+        bitmap.WritePixels(new Int32Rect(0, 0, frame.Width, frame.Height), frame.BgraPixels, frame.Stride, 0);
+        session.PreviewBitmap = bitmap;
+        PreviewBitmapChanged?.Invoke(session.DeviceId, bitmap);
+    }
+
+    private void CopyFrame(CameraSession session)
+    {
+        var bitmap = session.PreviewBitmap;
+        var frame = session.LatestFrame;
+        if (bitmap == null || frame == null) return;
+        if (frame.Width != bitmap.PixelWidth || frame.Height != bitmap.PixelHeight) return;
+        bitmap.WritePixels(new Int32Rect(0, 0, frame.Width, frame.Height), frame.BgraPixels, frame.Stride, 0);
+    }
+}

Services/ICameraEnumerator.cs

@@ -0,0 +1,10 @@
+namespace ytLive.Services;
+
+/// <summary>
+/// Enumerates physical capture devices. Seam so the picker and CameraManager
+/// never touch WinRT directly (tests inject fakes).
+/// </summary>
+public interface ICameraEnumerator
+{
+    Task<IReadOnlyList<CameraDeviceInfo>> GetCamerasAsync();
+}

Services/ICameraFrameSource.cs

@@ -0,0 +1,14 @@
+namespace ytLive.Services;
+
+/// <summary>
+/// A running capture source for one device. Raises normalized BGRA frames from
+/// a worker thread; callers must marshal to the UI thread. Seam so CameraManager
+/// is testable without WinRT.
+/// </summary>
+public interface ICameraFrameSource
+{
+    string DeviceId { get; }
+    event Action<VideoFrame>? FrameAvailable;
+    Task StartAsync();
+    Task StopAsync();
+}

Services/LayoutStore.cs

@@ -31,7 +31,7 @@ public class LayoutStore : IDisposable
     {
         string[] statements =
         {
-            "PRAGMA user_version = 1;",
+            "PRAGMA user_version = 2;",
             """
             CREATE TABLE IF NOT EXISTS Scene (
                 Id TEXT PRIMARY KEY,
@@ -65,6 +65,8 @@ public class LayoutStore : IDisposable
                 Opacity REAL NOT NULL DEFAULT 1,
                 MonitorIndex INTEGER,
                 DeviceId TEXT,
+                ClipShape TEXT NOT NULL DEFAULT 'Traditional',
+                IsMirrored INTEGER NOT NULL DEFAULT 0,
                 SortOrder INTEGER NOT NULL DEFAULT 0
             );
             """,
@@ -75,6 +77,36 @@ public class LayoutStore : IDisposable
             cmd.CommandText = sql;
             cmd.ExecuteNonQuery();
         }
+        MigrateSourceTable();
+    }
+
+    // v1 → v2: Source gains ClipShape + IsMirrored (webcam clip/mirror prefs).
+    // CREATE TABLE IF NOT EXISTS doesn't touch existing tables, so pre-v2 DBs
+    // get the columns here instead.
+    private void MigrateSourceTable()
+    {
+        var columns = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
+        using (var cmd = _connection.CreateCommand())
+        {
+            cmd.CommandText = "PRAGMA table_info(Source);";
+            using var reader = cmd.ExecuteReader();
+            while (reader.Read())
+                columns.Add(reader.GetString(1));
+        }
+
+        if (!columns.Contains("ClipShape"))
+        {
+            using var cmd = _connection.CreateCommand();
+            cmd.CommandText = "ALTER TABLE Source ADD COLUMN ClipShape TEXT NOT NULL DEFAULT 'Traditional';";
+            cmd.ExecuteNonQuery();
+        }
+
+        if (!columns.Contains("IsMirrored"))
+        {
+            using var cmd = _connection.CreateCommand();
+            cmd.CommandText = "ALTER TABLE Source ADD COLUMN IsMirrored INTEGER NOT NULL DEFAULT 0;";
+            cmd.ExecuteNonQuery();
+        }
     }
 
     public List<Scene> Load()
@@ -102,7 +134,7 @@ public class LayoutStore : IDisposable
         {
             cmd.CommandText = """
                 SELECT Id, SceneId, AssetId, Type, Name, IsEnabled,
-                       X, Y, Width, Height, Opacity, MonitorIndex, DeviceId
+                       X, Y, Width, Height, Opacity, MonitorIndex, DeviceId, ClipShape, IsMirrored
                 FROM Source ORDER BY SortOrder
                 """;
             using var reader = cmd.ExecuteReader();
@@ -123,6 +155,8 @@ public class LayoutStore : IDisposable
                     Opacity = reader.GetDouble(10),
                     MonitorIndex = reader.IsDBNull(11) ? null : reader.GetInt32(11),
                     DeviceId = reader.IsDBNull(12) ? null : reader.GetString(12),
+                    ClipShape = Enum.TryParse<ClipShape>(reader.GetString(13), out var clip) ? clip : ClipShape.Traditional,
+                    IsMirrored = reader.GetInt32(14) != 0,
                 };
                 if (!sourcesByScene.TryGetValue(sceneId, out var list))
                     sourcesByScene[sceneId] = list = new List<Source>();
@@ -185,9 +219,11 @@ public class LayoutStore : IDisposable
         {
             cmd.CommandText = """
                 INSERT INTO Source (Id, SceneId, AssetId, Type, Name, IsEnabled,
-                                    X, Y, Width, Height, Opacity, MonitorIndex, DeviceId, SortOrder)
+                                    X, Y, Width, Height, Opacity, MonitorIndex, DeviceId,
+                                    ClipShape, IsMirrored, SortOrder)
                 VALUES ($id, $sceneId, $assetId, $type, $name, $isEnabled,
-                        $x, $y, $w, $h, $opacity, $monitor, $device, $sort)
+                        $x, $y, $w, $h, $opacity, $monitor, $device,
+                        $clip, $mirrored, $sort)
                 """;
             cmd.Transaction = tx;
             var idP = cmd.Parameters.Add("$id", SqliteType.Text);
@@ -203,6 +239,8 @@ public class LayoutStore : IDisposable
             var opacityP = cmd.Parameters.Add("$opacity", SqliteType.Real);
             var monitorP = cmd.Parameters.Add("$monitor", SqliteType.Integer);
             var deviceP = cmd.Parameters.Add("$device", SqliteType.Text);
+            var clipP = cmd.Parameters.Add("$clip", SqliteType.Text);
+            var mirroredP = cmd.Parameters.Add("$mirrored", SqliteType.Integer);
             var sortP = cmd.Parameters.Add("$sort", SqliteType.Integer);
 
             foreach (var scene in scenes)
@@ -223,6 +261,8 @@ public class LayoutStore : IDisposable
                     opacityP.Value = source.Opacity;
                     monitorP.Value = (object?)source.MonitorIndex ?? DBNull.Value;
                     deviceP.Value = (object?)source.DeviceId ?? DBNull.Value;
+                    clipP.Value = source.ClipShape.ToString();
+                    mirroredP.Value = source.IsMirrored ? 1 : 0;
                     sortP.Value = sort++;
                     cmd.ExecuteNonQuery();
                 }

Services/MediaCaptureCameraEnumerator.cs

@@ -0,0 +1,15 @@
+using Windows.Devices.Enumeration;
+
+namespace ytLive.Services;
+
+public sealed class MediaCaptureCameraEnumerator : ICameraEnumerator
+{
+    public async Task<IReadOnlyList<CameraDeviceInfo>> GetCamerasAsync()
+    {
+        var devices = await DeviceInformation.FindAllAsync(DeviceClass.VideoCapture);
+        var result = new List<CameraDeviceInfo>(devices.Count);
+        foreach (var device in devices)
+            result.Add(new CameraDeviceInfo(device.Id, device.Name));
+        return result;
+    }
+}

Services/MediaCaptureFrameSource.cs

@@ -0,0 +1,128 @@
+using System;
+using System.Linq;
+using System.Runtime.InteropServices;
+using System.Runtime.InteropServices.WindowsRuntime;
+using System.Threading.Tasks;
+using Windows.Graphics.Imaging;
+using Windows.Media.Capture;
+using Windows.Media.Capture.Frames;
+using Windows.Media.MediaProperties;
+using ytLive.Helpers;
+
+namespace ytLive.Services;
+
+/// <summary>
+/// CPU-first MediaCapture source. Requests BGRA8 frames from the camera's video
+/// preview source; the capture pipeline does any format conversion, so every
+/// frame arrives as a normalized <see cref="VideoFrame"/>. Frames arrive on a
+/// worker thread — marshal before touching WPF.
+/// </summary>
+public sealed class MediaCaptureFrameSource : ICameraFrameSource
+{
+    private readonly string _deviceId;
+    private MediaCapture? _capture;
+    private MediaFrameReader? _frameReader;
+
+    public string DeviceId => _deviceId;
+
+    public event Action<VideoFrame>? FrameAvailable;
+
+    public MediaCaptureFrameSource(string deviceId)
+    {
+        _deviceId = deviceId;
+    }
+
+    public async Task StartAsync()
+    {
+        var capture = new MediaCapture();
+        MediaFrameReader? reader = null;
+        try
+        {
+            var settings = new MediaCaptureInitializationSettings
+            {
+                VideoDeviceId = _deviceId,
+                StreamingCaptureMode = StreamingCaptureMode.Video,
+                MemoryPreference = MediaCaptureMemoryPreference.Cpu,
+            };
+            await capture.InitializeAsync(settings);
+
+            var colorSource = capture.FrameSources
+                .FirstOrDefault(pair => pair.Value.Info.MediaStreamType == MediaStreamType.VideoPreview)
+                .Value;
+            if (colorSource == null)
+                throw new InvalidOperationException($"No video preview source on camera '{_deviceId}'.");
+
+            reader = await capture.CreateFrameReaderAsync(colorSource, MediaEncodingSubtypes.Bgra8);
+            reader.FrameArrived += OnFrameArrived;
+            await reader.StartAsync();
+
+            _capture = capture;
+            _frameReader = reader;
+        }
+        catch
+        {
+            if (reader != null)
+            {
+                reader.FrameArrived -= OnFrameArrived;
+                reader.Dispose();
+            }
+            capture.Dispose();
+            throw;
+        }
+    }
+
+    public async Task StopAsync()
+    {
+        var reader = _frameReader;
+        _frameReader = null;
+        if (reader != null)
+        {
+            reader.FrameArrived -= OnFrameArrived;
+            try
+            {
+                await reader.StopAsync();
+            }
+            catch (Exception ex)
+            {
+                AppLog.Write($"MediaCaptureFrameSource: stop frame reader failed: {ex.Message}");
+            }
+            reader.Dispose();
+        }
+
+        var capture = _capture;
+        _capture = null;
+        capture?.Dispose();
+    }
+
+    private void OnFrameArrived(MediaFrameReader sender, MediaFrameArrivedEventArgs args)
+    {
+        using var frame = sender.TryAcquireLatestFrame();
+        var videoFrame = frame?.VideoMediaFrame?.SoftwareBitmap;
+        if (videoFrame == null) return;
+
+        var bitmap = videoFrame.BitmapPixelFormat == BitmapPixelFormat.Bgra8
+            ? videoFrame
+            : SoftwareBitmap.Convert(videoFrame, BitmapPixelFormat.Bgra8);
+
+        try
+        {
+            using var buffer = bitmap.LockBuffer(BitmapBufferAccessMode.Read);
+            using var reference = buffer.CreateReference();
+            if (WindowsRuntimeMarshal.TryGetDataUnsafe(reference, out var pixelsPtr, out var capacity))
+            {
+                var pixels = new byte[capacity];
+                Marshal.Copy(pixelsPtr, pixels, 0, (int)capacity);
+                FrameAvailable?.Invoke(new VideoFrame(bitmap.PixelWidth, bitmap.PixelHeight, pixels));
+            }
+        }
+        catch (Exception ex)
+        {
+            AppLog.Write($"MediaCaptureFrameSource: frame copy failed: {ex.Message}");
+        }
+        finally
+        {
+            if (!ReferenceEquals(bitmap, videoFrame))
+                bitmap.Dispose();
+        }
+    }
+}

Services/VideoFrame.cs

@@ -0,0 +1,22 @@
+namespace ytLive.Services;
+
+/// <summary>
+/// A normalized CPU frame (32bpp BGRA, tightly packed). The capture path hands
+/// these to the UI thread, which copies them into the shared WriteableBitmap.
+/// Deliberately the only pixel type the rest of the app knows about — every
+/// future capture source (screen, background-removed webcam) feeds the same seam.
+/// </summary>
+public sealed class VideoFrame
+{
+    public int Width { get; }
+    public int Height { get; }
+    public byte[] BgraPixels { get; }
+    public int Stride => Width * 4;
+
+    public VideoFrame(int width, int height, byte[] bgraPixels)
+    {
+        Width = width;
+        Height = height;
+        BgraPixels = bgraPixels;
+    }
+}

Services/index.md

@@ -8,7 +8,14 @@ External-facing logic: YouTube API, persistence. See
 | `YouTubeAuthService.cs` | OAuth2 via Google: loopback callback (`http://localhost:8765/oauth2/callback`), token exchange, refresh, channel fetch. Constructor takes optional `HttpClient` + `sessionChanged` callback (test seam + save hook); session persists via `Helpers/TokenStore` (DPAPI); `ClearSession()` signs out (called by `MainViewModel.StopStream` on End Livestream) |
 | `YouTubeStreamService.cs` | Broadcast/stream management via the v3 API (`enableAutoStart/Stop`). **Not yet switched to the `variable` reusable stream** |
 | `YouTubeChatService.cs` | Polls `liveChat/messages`, raises `MessageReceived`; `IDisposable` |
-| `LayoutStore.cs` | SQLite persistence (`Microsoft.Data.Sqlite`) at `%APPDATA%\ytLlive\ytLlive.db`; assets stored as BLOBs keyed by SHA-256 content hash; save/open layout files |
+| `LayoutStore.cs` | SQLite persistence (`Microsoft.Data.Sqlite`) at `%APPDATA%\ytLlive\ytLlive.db`; assets stored as BLOBs keyed by SHA-256 content hash; save/open layout files; schema `user_version` 2 (`Source.ClipShape`/`IsMirrored` — added by `ALTER TABLE` for pre-v2 DBs) |
+| `VideoFrame.cs` | Normalized CPU frame seam (`Width`/`Height`/tightly-packed BGRA `byte[]`) — the only pixel type the rest of the app knows about; future capture sources (screen, background-removed webcam) feed the same seam |
+| `CameraDeviceInfo.cs` | `(Id, DisplayName)` for a physical capture device |
+| `ICameraEnumerator.cs` | `GetCamerasAsync()` — seam so the picker/`CameraManager` never touch WinRT (tests inject fakes) |
+| `ICameraFrameSource.cs` | `StartAsync`/`StopAsync`/`FrameAvailable(VideoFrame)` — seam for a running capture source |
+| `MediaCaptureCameraEnumerator.cs` | WinRT enumeration via `DeviceInformation.FindAllAsync(DeviceClass.VideoCapture)` |
+| `MediaCaptureFrameSource.cs` | CPU-first MediaCapture source (`MemoryPreference = Cpu`, BGRA8 via `CreateFrameReaderAsync`); frames arrive on a worker thread |
+| `CameraManager.cs` | Webcam capture ownership: refcounted by `DeviceId`, one shared `WriteableBitmap` per camera, dispatcher-coalesced ~render-rate UI updates (latest-frame drop); `PreviewBitmapChanged`/`CameraFailed` events |
 
 Related: constructed in [`ViewModels/MainViewModel.cs`](../ViewModels/MainViewModel.cs)
 (no DI container yet). Models in [`Models/index.md`](../Models/index.md).