ReviewOS

also looking at this

home-lang/home

feat(video): add checked elementary packet and PTS outputs

#919
Merged chris wants to merge feat/packet-output-streams into main
4 files +148 -0
packages/video/docs/packet-output.mdadded+34-0
Changes to packages/video/docs/packet-output.md
@@ -0,0 +1,34 @@
1# Checked elementary packet and PTS output
2
3`src/core/packet_output.zig` is a standalone, allocation-free boundary for
4reusable streaming sinks. The broader sink graph includes decoded-frame and
5accumulating packet collections; this module neither retains borrowed packets
6nor imports that graph.
7
8`annexB(input, output)` converts four-byte big-endian length-prefixed AVC/HEVC
9NAL units to four-byte Annex B start codes. It checks every length before writing
10any destination bytes, rejects empty/truncated/zero-length input, and checks
11output capacity. Input/output must not overlap. Parameter sets can be converted
12separately and prepended at the first key of a newly attached output.
13
14`formatPts(timestamp_us, output)` formats integer microsecond PTS as milliseconds
15with exactly three decimal digits and LF. Zero and all u64 timestamps are exact;
16no floating-point rounding or locale formatting is used. Too-small buffers remain
17unchanged. A 32-byte destination covers the complete u64 range.
18
19`PtsWriter` wraps an explicit synchronous `Sink{context,write}`. Sink callbacks
20must completely accept their borrowed data or return an error. Rejected
21non-increasing timestamps do not touch the sink. A sink failure poisons the
22writer; create a fresh writer for a new clip/epoch. The module does not own files,
23threads or packet storage and does not depend on FFmpeg/Libav.
24
25Focused tests on Zig 0.15.2 and the Home development toolchain:
26
27```sh
28zig test packages/video/src/core/packet_output.zig
29```
30
31Tests cover multi-NAL conversion, malformed/truncated input, exact maximum PTS,
32small-buffer state preservation, monotonicity and sink-failure poisoning.
33zig-camera uses the helpers at its native callback output boundary, with
34independent video decoding and media/PTS timeline checks in its integration suite.