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