also looking at this
feat(media): add bounded PCM capture, owned snapshots and A/V streaming
#917
11 files
+683
-0
| @@ -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. | |
| 3 | const std = @import("std"); | |
| 4 | pub 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 | } | |
| 10 | pub 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 | } | |
| 14 | const Entry = struct { offset: usize, frames: usize, consumed: usize = 0, timestamp: u64 }; | |
| 15 | pub const Chunk = struct { data: []const u8, timestamp: u64, frames: usize, end_ns: u64 }; | |
| 16 | pub const Cursor = struct { block: usize = 0, frame: usize = 0 }; | |
| 17 | pub 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 | }; | |
| 149 | test "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 | } | |
| 164 | test "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 | } | |
| 179 | test "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 | ||
| 189 | test "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 | } | |
| 214 | test "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 | ||
| 229 | test "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 | ||
| 253 | test "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 | } | |