fix(media): play at the clip's real rate — the pipe was copying a frame per read

Reported as "the default video and the green screen video are playing at a hideously slow
rate… I thought the playback timing issues were resolved?!" They were not: two independent
faults, both in the shared clip pipe.

1. QUADRATIC COPY IN THE FRAME READER. `RawVideoFrameReader` re-concatenated the whole pending
   buffer on every `Feed`, and the pipe feeds it 64 KB at a time. A 1080p BGRA frame is 8 MB, so
   one frame cost ~127 copies of a growing buffer — roughly half a gigabyte of memcpy per frame.
   Measured on a 30 fps clip: 6 frames in 3 seconds (2 fps). The reader now fills one preallocated
   frame buffer and hands that array to the VideoFrame, so a frame is copied exactly once. Pipe
   reads are 256 KB. Same clip: 29 fps.

2. PACING SLEPT ON TOP OF THE WORK. A fixed 1/fps sleep after each frame adds the frame's own
   cost, so 20 ms of work on a 30 fps clip yields 1/(33+20) ≈ 19 fps — measured 20.9. Pacing is
   now deadline-based (`Helpers/FramePacer.cs`): wait only what is left of the frame's interval,
   resync when a frame overruns instead of bursting, never sleep longer than one interval.

The alert clip shares this pipe, so it gained both fixes.

Tests: `FramePacerTests` (subtract work, no drift, late → resync, zero duration, reset);
`ChromaKeyRealClipTests.RealClip_PlaysAtItsNativeRate` (throughput floor of 15 fps on the real
30 fps clip — the old code sat at 2); the two pacing assertions now check "at most one interval"
rather than an exact sleep, which is what deadline pacing means. Full suite: 574 passed,
0 failed, clean build.
This commit is contained in:
2026-11-05 09:57:07 -08:00
parent 69e595da25
commit 5577aaaf91
8 changed files with 203 additions and 35 deletions
+6 -4
View File
@@ -44,11 +44,13 @@ public class AlertClipDecoderTests
await completed.Task.WaitAsync(TimeSpan.FromSeconds(5));
Assert.Equal(3, forwarded);
// One pacing delay per emitted frame, each = 1/100s (the probed rate).
Assert.Equal(forwarded, delays.Count);
// One pacing delay per emitted frame, each AT MOST one interval: pacing targets a deadline,
// so the frame's own work is subtracted from the wait (2026-11-05 — the old version slept a
// full interval on top of the work, which is what made 1080p playback crawl).
Assert.NotEmpty(delays); // the decoder paces at all
foreach (var d in delays)
Assert.True(Math.Abs((d - TimeSpan.FromMilliseconds(10)).TotalMilliseconds) < 0.001,
$"expected ~10ms, got {d.TotalMilliseconds}ms");
Assert.True(d > TimeSpan.Zero && d <= TimeSpan.FromMilliseconds(10),
$"expected a wait of at most 10ms, got {d.TotalMilliseconds}ms");
}
private sealed class FakeDecodeProcess : IDecodeProcess
+29
View File
@@ -71,6 +71,35 @@ public class ChromaKeyRealClipTests
Assert.True(ratio < 1.0, "everything vanished; the subject should survive the key");
}
/// <summary>
/// Throughput guard (2026-11-05): the pipe used to copy a growing pending buffer on every 64 KB
/// read, so a 1080p frame cost ~0.5 GB of copying and playback pinned at ~2 fps whatever the
/// pacing said. A 30 fps clip must here deliver at least 15 fps (measured 29 in a Debug build) —
/// a floor wide enough for slow hardware and far above the 2 fps regression.
/// </summary>
[Fact]
public async Task RealClip_PlaysAtItsNativeRate()
{
Assert.True(File.Exists(ClipPath), $"missing fixture: {ClipPath}");
var locator = new FixedLocator(FfmpegPath);
var probe = new FfmpegFrameRateProbe(locator, () => new FfmpegDecodeProcess());
var frames = 0;
using var pipe = new VideoClipPipe(
ClipPath, 1920, 1080, locator, () => new FfmpegDecodeProcess(),
frameRateProbe: probe, audio: false);
pipe.FrameAvailable += _ => Interlocked.Increment(ref frames);
var clock = System.Diagnostics.Stopwatch.StartNew();
await pipe.StartAsync();
await Task.Delay(2000);
await pipe.StopAsync();
clock.Stop();
var fps = frames / clock.Elapsed.TotalSeconds;
Assert.True(fps >= 15, $"playback ran at {fps:0.0} fps — frames are being lost in the pipe again");
}
private static (int R, int G, int B) ParseHex(string hex)
{
var value = hex.TrimStart('#');
+74
View File
@@ -0,0 +1,74 @@
using System;
using Xunit;
using ytLive.Helpers;
namespace ytLive.Tests;
/// <summary>
/// 2026-11-05: a 1080p video layer played at 20.9 fps on a 30 fps clip because pacing slept a full
/// frame interval ON TOP of the frame's own work. These pin deadline pacing: sleep the remainder of
/// the interval, resync when work overruns, never burst to catch up.
/// </summary>
public class FramePacerTests
{
private static readonly TimeSpan Frame = TimeSpan.FromMilliseconds(33);
[Fact]
public void FirstFrame_WaitsAFullInterval()
=> Assert.Equal(Frame, new FramePacer().DelayFor(Frame, TimeSpan.Zero));
[Fact]
public void WorkInsideTheInterval_IsSubtractedFromTheWait()
{
var pacer = new FramePacer();
pacer.DelayFor(Frame, TimeSpan.Zero); // schedules the next frame at 33ms
// The next frame is emitted 20ms later: only 13ms of waiting is left, not another 33ms.
var wait = pacer.DelayFor(Frame, TimeSpan.FromMilliseconds(20));
Assert.Equal(TimeSpan.FromMilliseconds(13), wait);
}
[Fact]
public void WorkOnSchedule_DoesNotAccumulateDrift()
{
var pacer = new FramePacer();
Assert.Equal(Frame, pacer.DelayFor(Frame, TimeSpan.Zero));
// A frame arriving exactly on its deadline waits not at all…
Assert.Equal(TimeSpan.Zero, pacer.DelayFor(Frame, TimeSpan.FromMilliseconds(33)));
// …and a frame arriving 3ms early waits exactly the 3ms that is left, every time: the
// deadline advances one interval per frame, so no drift accumulates.
Assert.Equal(TimeSpan.FromMilliseconds(3), pacer.DelayFor(Frame, TimeSpan.FromMilliseconds(63)));
Assert.Equal(TimeSpan.FromMilliseconds(3), pacer.DelayFor(Frame, TimeSpan.FromMilliseconds(96)));
}
[Fact]
public void FallingBehind_ReturnsZeroAndResyncs()
{
var pacer = new FramePacer();
pacer.DelayFor(Frame, TimeSpan.Zero);
// The frame took 200ms: it is late, so no sleep — and the schedule restarts from now.
var late = pacer.DelayFor(Frame, TimeSpan.FromMilliseconds(200));
Assert.Equal(TimeSpan.Zero, late);
var next = pacer.DelayFor(Frame, TimeSpan.FromMilliseconds(200));
Assert.Equal(Frame, next);
}
[Fact]
public void ZeroFrameDuration_NeverWaits()
=> Assert.Equal(TimeSpan.Zero, new FramePacer().DelayFor(TimeSpan.Zero, TimeSpan.Zero));
[Fact]
public void Reset_RestartsTheSchedule()
{
var pacer = new FramePacer();
pacer.DelayFor(Frame, TimeSpan.Zero);
pacer.Reset();
Assert.Equal(Frame, pacer.DelayFor(Frame, TimeSpan.FromSeconds(10)));
}
}
+5 -4
View File
@@ -110,11 +110,12 @@ public class MediaVideoSourceTests
await source.StartAsync();
await completed.Task.WaitAsync(TimeSpan.FromSeconds(5));
// One pacing delay per emitted frame, each = 1/1000s.
Assert.Equal(2, delays.Count);
// One pacing delay per emitted frame, each AT MOST one interval (deadline pacing: the
// frame's own work is subtracted from the wait — 2026-11-05).
Assert.NotEmpty(delays); // the decoder paces at all
foreach (var d in delays)
Assert.True(Math.Abs((d - TimeSpan.FromMilliseconds(1)).TotalMilliseconds) < 0.001,
$"expected ~1ms, got {d.TotalMilliseconds}ms");
Assert.True(d > TimeSpan.Zero && d <= TimeSpan.FromMilliseconds(1),
$"expected a wait of at most 1ms, got {d.TotalMilliseconds}ms");
}
[Fact]