feat: add mp2ts-loop for seamless looping of constant-rate transport streams

[tobbee]

Summary

Adds mp2ts-loop, a new tool that loops a single-program, constant-rate MPEG-2 transport stream seamlessly and forever, to a file and/or UDP. It also moves the module to Go 1.24 and mp4ff v0.58.0, and takes -version from Go's build information.

mp2ts-loop

SCAN → SELECT → PREPARE (in memory) → LOOP/SEND. -scan prints the analysis and the chosen loop as JSON, and -d caps the loop duration.

• Loop points.
  • IDR: used when the stream has them.
  • HEVC CRA: rewritten to BLA at the seam, so the leading RASL pictures are discarded instead of corrupting the first GOP.
  • MPEG-2: an I picture after a sequence header, closed GOP preferred. An open-GOP loop point gets broken_link.
  • Selection: a loop-point class with fewer than two points falls through to the next. The longest loop is preferred that is a whole number of nominal frame periods (an even frame count at 59.94 fps, a multiple of four at 23.976). A loop never spans a signalled discontinuity.
• Video: H.264, H.265, MPEG-2. Audio: AAC, MP2, AC-3.
  • Shift: audio is shifted per wrap by less than one audio frame, with no accumulated drift.
  • Splitting: frame-aligned multi-frame PES are split to one frame per PES (with data_alignment_indicator), so the loop can cut on any frame.
• Transport timing.
  • Slots: the segment keeps one slot per source packet, so every packet keeps its source timing.
  • Audio: audio multiplexed outside the loop's packets (it usually lags the video) is moved across the loop boundary to where it sits relative to the video.
  • PCR: regenerated linearly, exact across wraps. It can be on the video PID or its own PID, following the PMT's PCR_PID.
  • Seam: packets just before the seam move by the buffer-level difference between the two loop points.
  • UDP: paced at exactly the PCR rate, on the monotonic clock.
• SCTE-35.
  • Kept: a cue only when its whole break (CUE-OUT to CUE-IN, or CUE-OUT + duration) is inside the loop. A cue sent before the loop for such a break is moved to the loop start.
  • Each wrap: pts_adjustment advances by the loop duration and every event ID by the span of IDs used in the loop. The CRC is recomputed.
  • Dropped: everything else; the scan says why.
• Other PIDs such as SMPTE-2038 ANC are passed through and timestamp-shifted per wrap.
• Refused, with the reason:
  • variable-rate streams, detected from the PCR, with signalled discontinuities respected;
  • audio or video PES without a PTS;
  • streams without two loop points, e.g. GDR / intra-refresh.

Design notes and the remaining plan are in cmd/mp2ts-loop/PLAN.md.

Other changes

• Toolchain: requires Go 1.24 and mp4ff v0.58.0 (no code changes needed). CI tests Go 1.24 and 1.27, and the lint job sets up Go itself. The old Go 1.19 job would have failed on log/slog.
• Version: -version reports the version Go embeds from the git tag and commit (internal.Version(), debug.ReadBuildInfo).
  • internal/version.go and the Makefile -ldflags are removed.
  • The Makefile now builds packages, via a .PHONY pattern rule.
  • make build now includes mp2ts-pidfilter.
  • The shared -version handler names the right tool, not "ts-info".
• mp2ts-info: lists MP2, AC-3, and MPEG-2 video PIDs.

Testing

• Unit and golden tests:
  • Scan reports: golden reports for 7 fixtures. New fixtures are mpeg2_open_mp2.ts and avc_aac_cbr.ts (constant-rate); the older AVC/HEVC fixtures are variable-rate and now refused.
  • Video and seams: MPEG-2 parsing, CRA→BLA and broken_link.
  • SCTE-35: pairing rules, section reassembly, per-wrap rewrite, and an end-to-end loop with injected cues.
  • Audio and timing: audio slot placement, drift continuity with moved audio, loop selection (whole frame periods, discontinuities), PCR analysis across discontinuities, a separate PCR PID, and the UDP pacing schedule.
  • Toolchains: all pass on Go 1.24 and 1.27; golangci-lint is clean.
• Real streams (broadcast captures and ffmpeg encodes, 3 to 200 wraps):
  • Decode: ffmpeg decodes with no errors, and there are 0 continuity-counter errors.
  • PCR: within about 0.5 tick of a straight line over all wraps.
  • Video: exact PTS grids at 25, 29.97, 50, 59.94, and 23.976 fps.
  • Audio: the per-wrap shift stays under one audio frame in every wrap. Each audio PES arrives at the same time as in the source (median 0 ms change), except up to about 110 ms just before the seam, where those loops' buffer mismatch has to be absorbed.
  • UDP: the measured send rate against the stream's own PCR is −0.4 ppm (before the fix: +13.6 ppm).

Known limitations / follow-ups

• Variable-rate streams are refused; supporting them would mean keeping each packet's source PCR timing.
• Interlace: frame-coded interlace works (MPEG-2, AVC MBAFF). AVC PAFF, MPEG-2 field pictures, and HEVC field coding are planned in PLAN.md; HEVC is waiting for example files.
• GDR / intra-refresh streams cannot be looped.
• Non-PES-aligned audio (frames straddling PES) is copied whole, so the cut is PES-granular there.
• PCR on an audio PID is not handled.
• Open-GOP MPEG-2: the B-pictures leading each seam show a brief transient (broken_link is set).
• Bounded runs (-m): the first and last wraps lack the moved audio that would come from the neighbouring wrap.
• Buffer matching: loop points are not yet chosen for matching buffer levels, which would shrink the shift just before the seam.

🤖 Generated with Claude Code