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/STREAMING_AV.mdadded+65-0
Changes to packages/video/STREAMING_AV.md
@@ -0,0 +1,65 @@
1# Bounded recording support
2
3`src/containers/av_stream.zig` streams Matroska video plus lossless S16LE PCM
4through a caller-owned synchronous sink. Supports MJPEG, AVC and HEVC; AVC/HEVC
5samples must be four-byte NAL-length prefixed and accompanied by avcC/hvcC
6CodecPrivate. Each packet is one cluster, using microsecond timecodes and one
7common epoch. Per-track timestamps must increase; cross-track ordering may differ.
8The writer keeps a fixed header buffer and no frame collection. A sink failure
9poisons further writes. Final duration, seek cues and audio compression are absent.
10
11`src/core/pcm_timeline.zig` owns a fixed PCM arena and descriptor queue. It rejects
12capacity exhaustion without mutation, checks time arithmetic, and clips at sample
13boundaries for initial trimming and segment splits. Borrowed output chunks expire
14at the next mutation; consume them synchronously. It does not resample or correct
15drift. Preserve the capture clock and gaps; never infer capture time from callbacks.
16
17`src/core/recording_policy.zig` checks soft elapsed-time and byte thresholds. The
18caller generates paths and requests a keyframe; it must not cut predicted frames.
19It suppresses duplicate requests while a split is pending and ignores empty output.
20
21`packages/audio/src/io/native_capture.{c,h,zig}` provides explicit Linux ALSA
22S16LE capture using checked system headers and an opaque handle. Compile the C
23source with the system compiler and link libasound. Rate 8–192kHz, mono/stereo,
24block size 1–4096; nonblocking reads have a bounded timeout. It anchors the sample
25clock from ALSA MONOTONIC timestamps, converts to Linux BOOTTIME, then advances
26by sample count. Reported clock error is measured against ALSA status; >100ms
27error, XRUN or device removal fails instead of silently dropping/recovering audio.
28This is a new opt-in input backend; the older recorder abstraction is unchanged.
29The existing simplified AAC implementations have not been adopted or represented
30as a standards-verified capture encoder.
31
32Call read and close serially. No queues, threads or implicit microphone access are
33created by the Home adapter. Consumers must bound their own input/output queues.
34Physical microphone latency, camera offset, suspend, drift and long recordings
35still require hardware validation. No FFmpeg or Libav dependency is used.
36
37Targeted Zig tests (0.15.2 and current Home toolchain):
38
39```sh
40zig test packages/video/src/core/pcm_timeline.zig
41zig test packages/video/src/core/recording_policy.zig
42zig test packages/video/src/containers/av_stream.zig
43```
44
45The Linux native smoke explicitly opens ALSA's `null` test device, never the
46user's default microphone. See `.github/workflows/streaming-av.yml`.
47
48`Queue.pushRolling` adds bounded circular PCM history. It validates the entire
49input before evicting whole oldest blocks to meet both sample and descriptor
50limits. `retention_floor` reports the end of the discarded prefix. Invalid or
51oversized blocks leave history untouched. `window(minimum, cut, cursor)` reads
52non-destructively with sample-exact clipping, including arena wrap. Each replay
53uses a fresh cursor; chunks and cursors expire on mutation. `Chunk.end_ns` uses
54the original block clock to avoid accumulating fractional sample rounding.
55Consumers can align an encoded keyframe ring to the PCM retention floor and
56replay separate snapshots without consuming live audio. If eviction passes a
57live consumer's watermark, report loss rather than silently producing a gap.
58No encoder, thread or file I/O is performed by these history methods.
59
60`Queue.cloneWindow(allocator, minimum, cut)` freezes just the selected sample
61window into independent storage. It preserves capture timestamps and sample phase,
62handles a wrapped source block even when all 4096 descriptors are occupied, and
63frees partial allocations on failure. The source is unchanged. Serialize cloning
64with source mutation; after return the copy may move to an independent worker and
65outlive the source. No audio encoder or worker runtime is imported by this module.