ReviewOS

also looking at this

home-lang/home

feat(media): add bounded PCM capture, owned snapshots and A/V streaming

#917
Merged chris wants to merge feat/pcm-av-streaming into main
11 files +683 -0
packages/video/src/core/pcm_timeline.zigadded+262-0
Changes to packages/video/src/core/pcm_timeline.zig
@@ -0,0 +1,262 @@
1//! Bounded PCM ownership and sample-accurate clipping on a common nanosecond clock.
2//! Single serialized owner; returned data expires on the next push/mutation.
3const std = @import("std");
4pub fn at(origin: u64, frames: u64, rate: u32) !u64 {
5 if (rate < 8000 or rate > 192000) return error.InvalidRate;
6 const value = @as(u128, origin) + @as(u128, frames) * 1_000_000_000 / rate;
7 if (value > std.math.maxInt(u64)) return error.TimestampOverflow;
8 return @intCast(value);
9}
10pub fn before(origin: u64, cut: u64, rate: u32, limit: usize) usize {
11 if (cut <= origin) return 0;
12 return @intCast(@min(limit, (@as(u128, cut - origin) * rate + 999_999_999) / 1_000_000_000));
13}
14const Entry = struct { offset: usize, frames: usize, consumed: usize = 0, timestamp: u64 };
15pub const Chunk = struct { data: []const u8, timestamp: u64, frames: usize, end_ns: u64 };
16pub const Cursor = struct { block: usize = 0, frame: usize = 0 };
17pub const Queue = struct {
18 allocator: std.mem.Allocator,
19 data: []u8,
20 entries: []Entry,
21 rate: u32,
22 channels: u32,
23 capacity: usize,
24 head: usize = 0,
25 count: usize = 0,
26 used: usize = 0,
27 write_pos: usize = 0,
28 last_end: ?u64 = null,
29 trimmed: u64 = 0,
30 retention_floor: ?u64 = null,
31 pub fn init(a: std.mem.Allocator, rate: u32, channels: u32, frames: usize, blocks: usize) !Queue {
32 if (rate < 8000 or rate > 192000 or channels < 1 or channels > 2 or frames == 0 or frames > rate * 10 or blocks == 0 or blocks > 4096) return error.InvalidConfiguration;
33 const data = try a.alloc(u8, frames * channels * 2);
34 errdefer a.free(data);
35 const entries = try a.alloc(Entry, blocks);
36 return .{ .allocator = a, .data = data, .entries = entries, .rate = rate, .channels = channels, .capacity = frames };
37 }
38 pub fn deinit(s: *Queue) void {
39 s.allocator.free(s.data);
40 s.allocator.free(s.entries);
41 }
42 pub fn push(s: *Queue, data: []const u8, timestamp: u64) !void {
43 const stride = s.channels * 2;
44 if (data.len == 0 or data.len % stride != 0) return error.InvalidPcm;
45 const frames = data.len / stride;
46 if (frames > s.capacity - s.used or s.count == s.entries.len) return error.BufferFull;
47 const ts = timestamp;
48 if (s.last_end) |end| if (ts < end) return error.InvalidTimestamp;
49 const end = try at(ts, frames, s.rate);
50 const first = @min(frames, s.capacity - s.write_pos);
51 @memcpy(s.data[s.write_pos * stride ..][0 .. first * stride], data[0 .. first * stride]);
52 @memcpy(s.data[0 .. (frames - first) * stride], data[first * stride ..]);
53 s.entries[(s.head + s.count) % s.entries.len] = .{ .offset = s.write_pos, .frames = frames, .timestamp = ts };
54 s.write_pos = (s.write_pos + frames) % s.capacity;
55 s.count += 1;
56 s.used += frames;
57 s.last_end = end;
58 }
59 fn consume(s: *Queue, e: *Entry, n: usize) void {
60 e.consumed += n;
61 s.used -= n;
62 if (e.consumed == e.frames) {
63 s.head = (s.head + 1) % s.entries.len;
64 s.count -= 1;
65 }
66 }
67 /// Circular ownership: reject invalid input before eviction, then discard
68 /// whole oldest blocks until the new block fits. No allocation after init.
69 pub fn pushRolling(s: *Queue, data: []const u8, timestamp: u64) !void {
70 const stride = s.channels * 2;
71 if (data.len == 0 or data.len % stride != 0) return error.InvalidPcm;
72 const frames = data.len / stride;
73 if (frames > s.capacity) return error.BufferFull;
74 if (s.last_end) |end| if (timestamp < end) return error.InvalidTimestamp;
75 _ = try at(timestamp, frames, s.rate);
76 while (frames > s.capacity - s.used or s.count == s.entries.len) {
77 const e = &s.entries[s.head];
78 const n = e.frames - e.consumed;
79 s.retention_floor = try at(e.timestamp, e.frames, s.rate);
80 s.trimmed += n;
81 s.consume(e, n);
82 }
83 try s.push(data, timestamp);
84 }
85 /// Non-consuming sample window. Cursor and returned slices expire on any
86 /// mutation. Separate cursors can replay the same history independently.
87 pub fn window(s: *const Queue, minimum: u64, cut: u64, cursor: *Cursor) !?Chunk {
88 while (cursor.block < s.count) {
89 const e = s.entries[(s.head + cursor.block) % s.entries.len];
90 const begin = @max(@max(e.consumed, cursor.frame), before(e.timestamp, minimum, s.rate, e.frames));
91 const end = before(e.timestamp, cut, s.rate, e.frames);
92 if (begin >= end) {
93 if (end < e.frames) return null;
94 cursor.block += 1;
95 cursor.frame = 0;
96 continue;
97 }
98 const offset = (e.offset + begin) % s.capacity;
99 const n = @min(end - begin, s.capacity - offset);
100 cursor.frame = begin + n;
101 return .{ .data = s.data[offset * s.channels * 2 ..][0 .. n * s.channels * 2], .timestamp = try at(e.timestamp, begin, s.rate), .frames = n, .end_ns = try at(e.timestamp, begin + n, s.rate) };
102 }
103 return null;
104 }
105 /// Freeze a selected sample window into independent, minimally sized storage.
106 /// Caller serializes source mutation; destination may then move to a worker.
107 pub fn cloneWindow(s: *const Queue, a: std.mem.Allocator, minimum: u64, cut: u64) !Queue {
108 var cursor: Cursor = .{};
109 var frames: usize = 0;
110 var blocks: usize = 0;
111 while (try s.window(minimum, cut, &cursor)) |chunk| {
112 frames += chunk.frames;
113 blocks += 1;
114 }
115 // One wrapped source block can become two contiguous descriptors.
116 // A full source therefore needs at most entries.len + 1 descriptors.
117 const data = try a.alloc(u8, @max(frames, 1) * s.channels * 2);
118 errdefer a.free(data);
119 const entries = try a.alloc(Entry, @max(blocks, 1));
120 errdefer a.free(entries);
121 var result = Queue{ .allocator = a, .data = data, .entries = entries, .rate = s.rate, .channels = s.channels, .capacity = @max(frames, 1) };
122 cursor = .{};
123 while (try s.window(minimum, cut, &cursor)) |chunk| try result.push(chunk.data, chunk.timestamp);
124 return result;
125 }
126 /// Emit samples with time >= minimum and < cut. Wrap is returned as separate
127 /// contiguous chunks; never duplicate a sample at a segment boundary.
128 pub fn take(s: *Queue, minimum: u64, cut: u64) !?Chunk {
129 while (s.count != 0) {
130 const e = &s.entries[s.head];
131 const end = before(e.timestamp, cut, s.rate, e.frames);
132 const begin = @max(e.consumed, @min(end, before(e.timestamp, minimum, s.rate, e.frames)));
133 if (begin > e.consumed) {
134 const n = begin - e.consumed;
135 s.trimmed += n;
136 s.consume(e, n);
137 if (s.count == 0 or begin == e.frames) continue;
138 }
139 if (end <= e.consumed) return null;
140 const offset = (e.offset + e.consumed) % s.capacity;
141 const n = @min(end - e.consumed, s.capacity - offset);
142 const result = Chunk{ .data = s.data[offset * s.channels * 2 ..][0 .. n * s.channels * 2], .timestamp = try at(e.timestamp, e.consumed, s.rate), .frames = n, .end_ns = try at(e.timestamp, e.consumed + n, s.rate) };
143 s.consume(e, n);
144 return result;
145 }
146 return null;
147 }
148};
149test "PCM splits across samples and arena wrap without loss or duplicate frames" {
150 var q = try Queue.init(std.testing.allocator, 48000, 1, 8, 4);
151 defer q.deinit();
152 try q.push(&.{ 1, 0, 2, 0, 3, 0, 4, 0, 5, 0, 6, 0 }, 1000000);
153 const first = (try q.take(1000000, 1062500)).?;
154 try std.testing.expectEqualSlices(u8, &.{ 1, 0, 2, 0, 3, 0 }, first.data);
155 try std.testing.expect((try q.take(1000000, 1062500)) == null);
156 const next = (try q.take(1062500, 1125000)).?;
157 try std.testing.expectEqualSlices(u8, &.{ 4, 0, 5, 0, 6, 0 }, next.data);
158 try q.push(&.{ 7, 0, 8, 0, 9, 0, 10, 0 }, 1125000);
159 const wrap = (try q.take(1125000, 2000000)).?;
160 try std.testing.expectEqualSlices(u8, &.{ 7, 0, 8, 0 }, wrap.data);
161 try std.testing.expectEqualSlices(u8, &.{ 9, 0, 10, 0 }, (try q.take(1125000, 2000000)).?.data);
162 try std.testing.expectEqual(@as(usize, 0), q.used);
163}
164test "PCM rejects full queues, invalid inputs and overflow before modifying history" {
165 var q = try Queue.init(std.testing.allocator, 48000, 1, 4, 2);
166 defer q.deinit();
167 try q.push(&.{ 1, 0, 2, 0, 3, 0, 4, 0 }, 1000000);
168 try std.testing.expectError(error.BufferFull, q.push(&.{ 5, 0 }, 2000000));
169 _ = try q.take(1041667, 2000000);
170 try std.testing.expectEqual(@as(u64, 3), q.trimmed);
171 try std.testing.expectError(error.InvalidPcm, q.push(&.{1}, 2000000));
172 try std.testing.expectError(error.InvalidTimestamp, q.push(&.{ 1, 0 }, 1));
173 try std.testing.expectError(error.TimestampOverflow, at(std.math.maxInt(u64), 1, 48000));
174 const previous = q.last_end.?;
175 try std.testing.expectError(error.InvalidTimestamp, q.push(&.{ 1, 0 }, previous - 1));
176 try std.testing.expectEqual(previous, q.last_end.?);
177 try std.testing.expectEqual(@as(u64, 1_000_000_000), try at(0, 44100, 44100));
178}
179test "PCM partial allocation failure cleanup" {
180 const Check = struct {
181 fn run(a: std.mem.Allocator) !void {
182 var q = try Queue.init(a, 48000, 2, 1024, 32);
183 defer q.deinit();
184 }
185 };
186 try std.testing.checkAllAllocationFailures(std.testing.allocator, Check.run, .{});
187}
188
189test "rolling PCM snapshots are repeatable across wrap and exact sample boundaries" {
190 var q = try Queue.init(std.testing.allocator, 44100, 1, 8, 3);
191 defer q.deinit();
192 try q.pushRolling(&.{ 1, 0, 2, 0, 3, 0, 4, 0, 5, 0 }, 1000000);
193 try q.pushRolling(&.{ 6, 0, 7, 0, 8, 0, 9, 0 }, try at(1000000, 5, 44100));
194 try std.testing.expectEqual(@as(u64, 5), q.trimmed);
195 try std.testing.expectEqual(@as(usize, 4), q.used);
196 const start = try at(try at(1000000, 5, 44100), 1, 44100);
197 for (0..2) |_| {
198 var cursor: Cursor = .{};
199 const a = (try q.window(start, std.math.maxInt(u64), &cursor)).?;
200 try std.testing.expectEqualSlices(u8, &.{ 7, 0, 8, 0 }, a.data);
201 const b = (try q.window(start, std.math.maxInt(u64), &cursor)).?;
202 try std.testing.expectEqualSlices(u8, &.{ 9, 0 }, b.data);
203 try std.testing.expect((try q.window(start, std.math.maxInt(u64), &cursor)) == null);
204 try std.testing.expectEqual(@as(usize, 4), q.used);
205 }
206 const floor = q.retention_floor;
207 try std.testing.expectError(error.InvalidTimestamp, q.pushRolling(&.{ 1, 0 }, 0));
208 var oversized: [18]u8 = undefined;
209 @memset(&oversized, 0);
210 try std.testing.expectError(error.BufferFull, q.pushRolling(&oversized, q.last_end.?));
211 try std.testing.expectEqual(floor, q.retention_floor);
212 try std.testing.expectEqual(@as(usize, 4), q.used);
213}
214test "rolling PCM metadata limit and window clipping preserve gaps" {
215 var q = try Queue.init(std.testing.allocator, 8000, 2, 16, 2);
216 defer q.deinit();
217 const block = [_]u8{ 1, 0, 2, 0, 3, 0, 4, 0 };
218 try q.pushRolling(&block, 0);
219 try q.pushRolling(&block, 1000000);
220 try q.pushRolling(&block, 2000000);
221 try std.testing.expectEqual(@as(u64, 2), q.trimmed);
222 var cursor: Cursor = .{};
223 const chunk = (try q.window(1125000, 2000000, &cursor)).?;
224 try std.testing.expectEqual(@as(usize, 1), chunk.frames);
225 try std.testing.expectEqual(@as(u64, 1250000), chunk.end_ns);
226 try std.testing.expect((try q.window(1125000, 2000000, &cursor)) == null);
227}
228
229test "frozen PCM windows own wrapped clipped samples and clean up allocation failures" {
230 const Check = struct {
231 fn run(a: std.mem.Allocator) !void {
232 var q = try Queue.init(a, 44100, 1, 6, 3);
233 defer q.deinit();
234 try q.pushRolling(&.{ 1, 0, 2, 0, 3, 0, 4, 0 }, 1000);
235 try q.pushRolling(&.{ 5, 0, 6, 0, 7, 0, 8, 0 }, try at(1000, 4, 44100));
236 const begin = try at(try at(1000, 4, 44100), 1, 44100);
237 var frozen = try q.cloneWindow(a, begin, std.math.maxInt(u64));
238 defer frozen.deinit();
239 try q.pushRolling(&.{ 9, 0, 10, 0, 11, 0, 12, 0 }, q.last_end.?);
240 var cursor: Cursor = .{};
241 var frames: usize = 0;
242 var values: [6]u8 = undefined;
243 while (try frozen.window(0, std.math.maxInt(u64), &cursor)) |chunk| {
244 @memcpy(values[frames * 2 ..][0..chunk.data.len], chunk.data);
245 frames += chunk.frames;
246 }
247 try std.testing.expectEqualSlices(u8, &.{ 6, 0, 7, 0, 8, 0 }, &values);
248 }
249 };
250 try std.testing.checkAllAllocationFailures(std.testing.allocator, Check.run, .{});
251}
252
253test "freeze supports a full descriptor queue with a wrapped final block" {
254 var q = try Queue.init(std.testing.allocator, 48000, 1, 8193, 4096);
255 defer q.deinit();
256 for (0..4097) |i| try q.pushRolling(&.{ 1, 0, 2, 0 }, try at(0, i * 2, 48000));
257 var frozen = try q.cloneWindow(std.testing.allocator, 0, std.math.maxInt(u64));
258 defer frozen.deinit();
259 try std.testing.expectEqual(@as(usize, 4096), q.count);
260 try std.testing.expectEqual(@as(usize, 4097), frozen.count);
261 try std.testing.expectEqual(q.used, frozen.used);
262}