Module clock33 

Generic 33-bit wrapping-clock helpers.

ISO/IEC 13818-1 §2.4.3.7 samples a 90 kHz clock into a 33-bit PTS/DTS field; ANSI/SCTE 35 §9.2 pts_time reuses the identical 2^33 modulus so a splice cue can be compared against the same clock. Both wrap roughly every 26.5 hours, and any long-lived consumer that needs an ever-growing timeline, or just needs to compare two nearby samples correctly across a wrap boundary, needs the same handful of primitives. Before this module existed, four crates (timed-metadata, transmux, media-doctor, compliance-probe) each hand-rolled their own copy; an overrun or wrap-direction fix in one reached none of the others. This module is now the single owner both algorithms live in.

transmux (a container-muxing hub) cannot take a dependency on timed-metadata (a DPI/timed-metadata signalling conversion crate several layers up the stack, pulling in scte35-splice/mp4-emsg) without an inverted, heavy dependency edge, and the primitive itself has no dependencies of its own — so it lives here, in the crate every one of the four already depends on, rather than promoting one sibling to depend on another.

Two independent operations live here, because they answer different questions and must not be collapsed into one:

• unwrap_delta — extend a running unwrapped (ever-growing, signed) accumulator by the next raw sample, correcting for exactly one wrap in either direction. Used to turn a repeating hardware counter into an absolute timeline (PTS/DTS unrolling across a capture, including B-frame reordering that dips slightly backward without crossing a wrap).
• wrapping_forward_distance — the modular forward distance from one already-comparable raw value to another, with no accumulator or history at all. Used to classify a single pair of values as “in order” vs “wrapped/out of order” when the caller already knows the two are supposed to be close in time (e.g. a decode-order monotonicity check, or a splice cue’s pts_time judged against a reference “now”).

Constants

WRAP_33BIT

The 33-bit modulus (2^33) shared by MPEG-2 Systems PTS/DTS (ISO/IEC 13818-1 §2.4.3.7) and SCTE-35 pts_time (ANSI/SCTE 35 §9.2) — both a 90 kHz clock sampled into a 33-bit field.

WRAP_33BIT_HALF

Half of WRAP_33BIT — the threshold distinguishing a genuine backward step from a legal wrap.

Functions

unwrap_delta

Extend a running unwrapped 33-bit clock by the delta to the next raw value, correcting for a single wrap in either direction.

wrapping_forward_distance

The modular forward distance from from to to on the 33-bit clock: (to - from) mod 2^33, always in [0, 2^33).