TASK 21 slice 1 step 3: IMediaFrameSource + MediaVideoSourceManager

Refactor MediaVideoSource onto IMediaFrameSource (Key/FrameAvailable/Completed/
StartAsync/StopAsync, renaming Start->StartAsync, FrameReady->FrameAvailable),
behavior preserved. Add MediaVideoSourceManager: app-wide decode-session owner
refcounted by MediaPath with Func<string,IMediaFrameSource?> factory seam,
Acquire/Release/ReleaseAll/GetLatestFrame, coalescing each file's frames onto
the UI dispatcher onto one shared WriteableBitmap; MediaFailed + PreviewBitmapChanged.

Mirrors ScreenCaptureManager (screen-capture session ownership + dispatcher
coalescing), per the codebase precedent and derivative-work rule.

Tests: MediaVideoSourceManagerTests (5 unit + 1 integration: single shared
bitmap, coalesce-to-latest); MediaVideoSourceTests updated for renames.
10/10 media tests pass, build 0 warnings. Docs (TASKS/HANDOFF/ai.md) updated.

Services/IMediaFrameSource.cs

@@ -0,0 +1,21 @@
+namespace ytLive.Services;
+
+/// <summary>
+/// TASK 21: a media file decoder exposed to <see cref="MediaVideoSourceManager"/>.
+/// Mirrors <c>IScreenCaptureSource</c>/<c>ICameraFrameSource</c> so the manager
+/// (and tests) treat a local video file like any other frame source: start/stop
+/// and a per-frame <see cref="FrameAvailable"/> event consumers coalesce.
+/// </summary>
+public interface IMediaFrameSource : IDisposable
+{
+    string Key { get; }
+
+    /// <summary>Raised (on a worker thread) for each decoded frame.</summary>
+    event Action<VideoFrame>? FrameAvailable;
+
+    /// <summary>Raised when the file finishes decoding (natural EOF).</summary>
+    event Action? Completed;
+
+    Task StartAsync(CancellationToken cancellationToken = default);
+    Task StopAsync();
+}

Services/MediaVideoSource.cs

@@ -6,19 +6,20 @@ namespace ytLive.Services;
 
 /// <summary>
 /// TASK 21: decodes a local media file (any format ffmpeg handles) into
-/// <see cref="VideoFrame"/>s for a MediaSource. Spawns ffmpeg with
-/// <c>-f rawvideo -pix_fmt bgra</c>, reads the raw BGRA pipe via
-/// <see cref="RawVideoFrameReader"/>, and raises <see cref="FrameReady"/> per
-/// frame. The decoder process is a seam (<see cref="IDecodeProcess"/>) so tests
-/// run without a real codec or audio device. Frames are emitted as fast as the
-/// pipe produces them; native-FPS pacing is wired by the caller via a probe in a
-/// later unit (TASK 21 step 5 pacing).
+/// <see cref="VideoFrame"/>s for a MediaSource. Implements
+/// <see cref="IMediaFrameSource"/>: raises <see cref="FrameAvailable"/> per
+/// frame and <see cref="IMediaFrameSource.Completed"/> on natural EOF. Spawns
+/// ffmpeg with <c>-f rawvideo -pix_fmt bgra</c> and drains the raw BGRA pipe via
+/// <see cref="RawVideoFrameReader"/>. The decoder process and emitters are seams
+/// so tests run without a real codec or audio device.
 /// </summary>
-public sealed class MediaVideoSource : IDisposable
+public sealed class MediaVideoSource : IMediaFrameSource
 {
-    public event Action<VideoFrame>? FrameReady;
+    public event Action<VideoFrame>? FrameAvailable;
     public event Action? Completed;
 
+    public string Key => _path;
+
     private readonly string _path;
     private readonly int _width;
     private readonly int _height;
@@ -41,17 +42,19 @@ public sealed class MediaVideoSource : IDisposable
         _process = process;
     }
 
-    public void Start()
+    public Task StartAsync(CancellationToken cancellationToken = default)
     {
-        if (_run != null) return;
+        if (_run != null) return Task.CompletedTask;
         _run = _cts.Token.Register(StopInternal);
-        _ = Task.Run(RunAsync);
+        _ = Task.Run(RunAsync, CancellationToken.None);
+        return Task.CompletedTask;
     }
 
-    public void Stop()
+    public Task StopAsync()
     {
         _cts.Cancel();
         _run = null;
+        return Task.CompletedTask;
     }
 
     public void Dispose()
@@ -85,14 +88,12 @@ public sealed class MediaVideoSource : IDisposable
             var reader = new RawVideoFrameReader(_width, _height);
             var buffer = new byte[65536];
             var stream = _process.StandardOutput;
-            byte[] readChunk;
             while (!_cts.IsCancellationRequested && !_process.HasExited)
             {
                 var read = await stream.ReadAsync(buffer, 0, buffer.Length, _cts.Token).ConfigureAwait(false);
                 if (read <= 0) break;
-                readChunk = buffer.AsSpan(0, read).ToArray();
-                foreach (var frame in reader.Feed(readChunk))
-                    FrameReady?.Invoke(frame);
+                foreach (var frame in reader.Feed(buffer.AsSpan(0, read).ToArray()))
+                    FrameAvailable?.Invoke(frame);
             }
         }
         catch (OperationCanceledException)

Services/MediaVideoSourceManager.cs

@@ -0,0 +1,256 @@
+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>
+/// TASK 21: owns media-file decode sessions app-wide, refcounted by file path.
+/// One file = at most one decoder, 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). Mirrors ScreenCaptureManager/CameraManager.
+/// </summary>
+public sealed class MediaVideoSourceManager : IDisposable
+{
+    private sealed class MediaSession
+    {
+        public string Key { get; }
+        public IMediaFrameSource Source { get; }
+        public Action<VideoFrame>? FrameHandler;
+        public int RefCount;
+        public bool Started;
+        public WriteableBitmap? PreviewBitmap;
+        public VideoFrame? LatestFrame;
+        public bool FramePending;
+
+        public MediaSession(string key, IMediaFrameSource source)
+        {
+            Key = key;
+            Source = source;
+            RefCount = 1;
+        }
+    }
+
+    private readonly Func<string, IMediaFrameSource?> _sourceFactory;
+    private readonly Dispatcher? _uiDispatcher;
+    private readonly Dictionary<string, MediaSession> _sessions = new();
+    private readonly object _gate = new();
+
+    /// <summary>Raised on the UI thread when a media file's shared preview bitmap is first created.</summary>
+    public event Action<string, WriteableBitmap>? PreviewBitmapChanged;
+
+    /// <summary>Raised when a media decoder cannot be created (bad path).</summary>
+    public event Action<string, string>? MediaFailed;
+
+    public MediaVideoSourceManager(Func<string, IMediaFrameSource?> sourceFactory, Dispatcher? uiDispatcher = null)
+    {
+        _sourceFactory = sourceFactory;
+        _uiDispatcher = uiDispatcher;
+    }
+
+    /// <summary>Increments the refcount for a file, starting the decoder the first time.</summary>
+    public async Task<bool> AcquireAsync(string key)
+    {
+        if (string.IsNullOrWhiteSpace(key)) return false;
+
+        MediaSession session;
+        bool shouldStart;
+        lock (_gate)
+        {
+            if (_sessions.TryGetValue(key, out var existing))
+            {
+                existing.RefCount++;
+                shouldStart = false;
+                session = existing;
+            }
+            else
+            {
+                IMediaFrameSource? source;
+                try
+                {
+                    source = _sourceFactory(key);
+                }
+                catch (Exception ex)
+                {
+                    AppLog.Write($"MediaSource: creating decoder '{key}' failed: {ex.Message}");
+                    MediaFailed?.Invoke(key, ex.Message);
+                    return false;
+                }
+                if (source == null)
+                {
+                    MediaFailed?.Invoke(key, "No decoder for this file");
+                    return false;
+                }
+                session = new MediaSession(key, source);
+                session.FrameHandler = frame => OnFrameAvailable(session, frame);
+                session.Source.FrameAvailable += session.FrameHandler;
+                _sessions[key] = 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(key);
+            session.Source.FrameAvailable -= session.FrameHandler;
+            AppLog.Write($"MediaSource: failed to start decoder '{key}': {ex.Message}");
+            MediaFailed?.Invoke(key, ex.Message);
+            await SafeStopAsync(session.Source);
+            return false;
+        }
+    }
+
+    public async Task ReleaseAsync(string key)
+    {
+        MediaSession? toStop = null;
+        lock (_gate)
+        {
+            if (!_sessions.TryGetValue(key, out var session)) return;
+            if (--session.RefCount > 0) return;
+            _sessions.Remove(key);
+            toStop = session;
+        }
+
+        if (toStop == null) return;
+        toStop.Source.FrameAvailable -= toStop.FrameHandler;
+        await SafeStopAsync(toStop.Source);
+        toStop.PreviewBitmap = null;
+    }
+
+    /// <summary>Releases a file unconditionally (every ref) — used on layout reloads.</summary>
+    public async Task ReleaseAllAsync(string key)
+    {
+        MediaSession? toStop = null;
+        lock (_gate)
+        {
+            if (!_sessions.TryGetValue(key, out var session)) return;
+            session.RefCount = 0;
+            _sessions.Remove(key);
+            toStop = session;
+        }
+
+        if (toStop == null) return;
+        toStop.Source.FrameAvailable -= toStop.FrameHandler;
+        await SafeStopAsync(toStop.Source);
+        toStop.PreviewBitmap = null;
+    }
+
+    /// <summary>The most recent decoded frame for a file, or null before the first
+    /// frame (or if the file has no session). The live compositor reads media from here.</summary>
+    public VideoFrame? GetLatestFrame(string key)
+    {
+        lock (_gate)
+            return _sessions.TryGetValue(key, out var session) ? session.LatestFrame : null;
+    }
+
+    /// <summary>The shared preview bitmap for a file (so a config created after the
+    /// first frame can adopt the running bitmap), or null.</summary>
+    public WriteableBitmap? GetPreviewBitmap(string key)
+    {
+        lock (_gate)
+            return _sessions.TryGetValue(key, out var session) ? session.PreviewBitmap : null;
+    }
+
+    public void Dispose()
+    {
+        List<MediaSession> sessions;
+        lock (_gate)
+        {
+            sessions = new List<MediaSession>(_sessions.Values);
+            _sessions.Clear();
+        }
+
+        foreach (var session in sessions)
+        {
+            session.Source.FrameAvailable -= session.FrameHandler;
+            _ = SafeStopAsync(session.Source);
+        }
+    }
+
+    private static async Task SafeStopAsync(IMediaFrameSource source)
+    {
+        try
+        {
+            await source.StopAsync();
+        }
+        catch (Exception ex)
+        {
+            AppLog.Write($"MediaSource: stopping decoder failed: {ex.Message}");
+        }
+    }
+
+    private bool TryGetActiveSession(MediaSession session)
+    {
+        lock (_gate)
+            return _sessions.TryGetValue(session.Key, out var current) && ReferenceEquals(current, session);
+    }
+
+    private void OnFrameAvailable(MediaSession 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(MediaSession 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.Key, bitmap);
+    }
+
+    private void CopyFrame(MediaSession 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);
+    }
+}