Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 7 additions & 4 deletions doc/bin/ts.md
Original file line number Diff line number Diff line change
Expand Up @@ -137,9 +137,12 @@ are refused rather than reframed. `--pcr-pid` paces on another PID's PCR.
Each frame is a run of packets that ends at the next PCR on the clock PID or at
the next group start, stamped with the PCR time of its first byte. A group
starts at a `random_access_indicator` on the video PID (or the clock PID with
no video), at a flagged PCR jump forward, after a second without either, or
where the next frame would take the group past the relay's cache bound. Any
step back ends the import.
no video), at a PCR clock break, after a second without either, or where the
next frame would take the group past the relay's cache bound. A flagged PCR
jump forward carries its step into the timestamps. A step back, flagged or
not, or an unflagged one more than 10 s forward, such as a switch between two
unlocked encoders, is spliced instead: the timestamps carry on from where the
clock was, and the bytes still go out unchanged, step and all.

`export ts --passthrough` writes each run `--delay` after its time on the
source clock, so two exporters emit the same bytes. It takes neither
Expand Down Expand Up @@ -245,7 +248,7 @@ details each grader and its negative controls.
| Byte identity from the first group; nothing before PMT and PCR; off-grid junk dropped | [`passthrough_test.rs`](https://github.com/moq-dev/moq/blob/main/rs/moq-mux/src/container/ts/passthrough_test.rs) `a_broadcast_capture_is_byte_identical_from_the_first_group`, `nothing_is_published_before_the_pmt_and_a_pcr`, `leading_junk_does_not_hide_the_grid` | PR |
| Scrambled input groups and paces like its clear twin | [`passthrough_test.rs`](https://github.com/moq-dev/moq/blob/main/rs/moq-mux/src/container/ts/passthrough_test.rs) `a_scrambled_twin_groups_and_paces_the_same` | PR |
| `randomAccess` false for several programs or video streams | [`passthrough_test.rs`](https://github.com/moq-dev/moq/blob/main/rs/moq-mux/src/container/ts/passthrough_test.rs) `two_programs_on_one_clock_publish_no_random_access`, `two_video_streams_in_one_program_publish_no_random_access` | PR |
| Clock: wrap, flagged jump, step back refused, 192/204-byte packets refused | [`passthrough_test.rs`](https://github.com/moq-dev/moq/blob/main/rs/moq-mux/src/container/ts/passthrough_test.rs) | PR |
| Clock: wrap, flagged jump, steps spliced, 192/204-byte packets refused | [`passthrough_test.rs`](https://github.com/moq-dev/moq/blob/main/rs/moq-mux/src/container/ts/passthrough_test.rs) | PR |
| Export releases each run byte-identical on its own PCR, whatever the delivery skew | [`release_test.rs`](https://github.com/moq-dev/moq/blob/main/rs/moq-mux/src/container/ts/release_test.rs) `a_capture_is_released_byte_identical_on_its_own_pcr`, `releases_fed_with_different_skew_write_the_same_bytes` | PR |

### Acquisition and loss
Expand Down
11 changes: 6 additions & 5 deletions drafts/draft-lcurley-moq-mpegts.md
Original file line number Diff line number Diff line change
Expand Up @@ -310,7 +310,7 @@ From the first group on, the frames of consecutive groups concatenate to the inp
A group starts at:

- a packet with `random_access_indicator` set on the video PID of the clock's program (the first PID its PMT declares with a video `stream_type`), or on the clock PID when that program has no video;
- a PCR on the clock PID with `discontinuity_indicator` set that steps forward ({{passthrough-timestamps}}), since a group MUST NOT contain a PCR discontinuity;
- a PCR on the clock PID that breaks the count ({{passthrough-timestamps}}), since a group MUST NOT contain a PCR discontinuity;
- otherwise, the first PCR at least one second of PCR time after the group's start;
- the frame that would take a group past a size bound the publisher chooses below what a relay caches of one group; frames are never split to meet it.

Expand All @@ -327,9 +327,10 @@ A PCR gives the time of the byte holding the last bit of its `program_clock_refe
A byte between two PCRs is placed at the rate between them; a byte past the last PCR of a timebase takes the rate of the interval before it, and one before the first PCR of a timebase takes the rate of the interval after it.

PCRs are unwrapped into a 64-bit count of 27 MHz ticks, and timestamps never decrease.
A step forward of at most half the 2^33 × 300 tick period adds to the count, across the wrap included, so a wrap is not a discontinuity.
A PCR with `discontinuity_indicator` set whose step is forward by that measure adds its step too, after the bytes before it are timed at the rate before it, and the group it starts MUST follow hang's discontinuity marker ({{hang}}).
A PCR that steps backwards MUST end the track with an error, flagged or not: a flagged one is a restart, which is new content, so a publisher that carries on publishes it as a new broadcast.
A step forward of at most half the 2^33 × 300 tick period adds to the count, across the wrap included, so a wrap is not a discontinuity, unless it exceeds 10 seconds without `discontinuity_indicator`.
A PCR with `discontinuity_indicator` set whose step is forward by that measure breaks the count and adds its step.
Any other step, backwards with or without the flag or that unflagged leap forward, breaks the count and is spliced: the count continues from the time the rate before the PCR gives its byte, raised to at least the last frame's.
At a break, the bytes before the PCR are timed at the rate before it, and the group it starts MUST follow hang's discontinuity marker ({{hang}}).

The timeline depends only on the bytes since the publisher's first PCR, so two publishers that start at the same packet of one input publish identical frames.

Expand Down Expand Up @@ -458,7 +459,7 @@ A broadcast demultiplexed from a DVB transport stream: video and audio described
- MPEG-1/2 video and LATM AAC are named among `pesPacket` streams, and the DSM-CC types 0x0A to 0x0D among section-framed `verbatim` ones. A rebuilt PAT lists the network entry when the NIT is carried.
- MPEG-1/2 video `pesPacket` frames group from one sequence header to the next, rather than one PES per group.
- A flagged PCR jump on a `passthrough` track follows hang's discontinuity marker rather than a skipped group sequence.
- A `passthrough` track unwraps PCRs from its history, clamps extrapolated object times at a forward discontinuity, and cuts a fallback group after one second. `randomAccess` covers every published group; `muxRate` follows the measured source rate.
- A `passthrough` track unwraps PCRs from its history, clamps extrapolated object times at a forward discontinuity, splices a PCR step back or an unflagged one over 10 seconds forward rather than ending, and cuts a fallback group after one second. `randomAccess` covers every published group; `muxRate` follows the measured source rate.
- A `tracks` entry is never changed in place: a stream the PMT revises continues under a new name, and one it drops leaves the section. `programDescriptors` follows the PMT; `program`'s `transportStreamId` and `programNumber` do not change.
- A consumer rebuilding a stream follows the catalog's revisions at the next PMT `version_number`, and carries a stream only while a PMT lists it.
- `pmtPid` follows a PAT that moves the PMT, and a consumer rebuilding a stream moves the PMT behind a PAT at the next `version_number`.
Expand Down
67 changes: 0 additions & 67 deletions quest/m2/ts-passthrough-splice.md

This file was deleted.

62 changes: 39 additions & 23 deletions rs/moq-mux/src/container/ts/passthrough.rs
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,13 @@ pub(super) const PCR_HZ: u64 = 27_000_000;
/// PCR ticks: one second.
const FALLBACK_TICKS: u64 = PCR_HZ;

/// PCR ticks in a microsecond, the unit of an object's timestamp.
const TICKS_PER_MICRO: u64 = PCR_HZ / 1_000_000;

/// The longest unflagged step forward taken as elapsed time, in PCR ticks: the media-aware
/// import's [`LEAP`](super::step::LEAP).
const LEAP_TICKS: u64 = super::step::LEAP.as_micros() as u64 * TICKS_PER_MICRO;

/// The most bytes a group holds before its next object starts another, so a source with sparse
/// random access points still gives a joiner a group it can take whole.
pub(super) const GROUP_BYTES_MAX: u64 = 16 * 1024 * 1024;
Expand Down Expand Up @@ -69,8 +76,8 @@ const VIDEO_STREAM_TYPES: &[u8] = &[
///
/// - a packet with `random_access_indicator` on the video PID, or on the clock PID when the
/// program has no video;
/// - a PCR with `discontinuity_indicator` that jumps forward, since no group may hold a PCR
/// discontinuity;
/// - a PCR that breaks the count (see Timestamps): one with `discontinuity_indicator`, or a
/// step not taken as elapsed time, since no group may hold a PCR discontinuity;
/// - the first PCR at least one second after the group's start, for a source that never marks
/// random access;
/// - the first object that would take the group past half of what `moq-net` caches of one group,
Expand Down Expand Up @@ -99,12 +106,14 @@ const VIDEO_STREAM_TYPES: &[u8] = &[
/// that object places the clock, and otherwise whatever lands it at now on a clock already in use.
///
/// PCRs are unwrapped into a 64-bit count of 27 MHz ticks that never goes back. A step forward of
/// at most half the 2^33 * 300 tick period adds to the count, across the wrap included. A PCR with
/// `discontinuity_indicator` whose step is forward by that measure adds the step too, after the
/// bytes before it are timed at the rate before it, and starts a group behind a break marker. Any
/// step back ends the import: [`PcrRewind`](crate::Error::PcrRewind) without the flag,
/// [`PcrRestart`](crate::Error::PcrRestart) with it, since a signalled restart is new content and
/// needs a new broadcast. The timeline therefore depends only on the bytes since the importer's
/// at most half the 2^33 * 300 tick period adds to the count, across the wrap included, unless it
/// is more than 10 s without `discontinuity_indicator`. A PCR with the flag whose step is forward
/// adds the step too. Every other step, back with or without the flag or that unflagged leap, is
/// another timeline, such as a switch between two encoders whose clocks were never locked, and is
/// spliced: the count carries on from the time the rate before the PCR gives it. Either way the
/// bytes before it are timed at the rate before it, and the next group starts behind a break
/// marker. The bytes still go out verbatim, so a decoder downstream sees the step as the source
/// sent it. The timeline therefore depends only on the bytes since the importer's
/// first PCR and its shift, and two importers of one feed started at the same packet each placing
/// its own catalog's clock publish identical objects.
///
Expand Down Expand Up @@ -245,7 +254,7 @@ enum Groups {
Writing(Group),
}

/// The PCRs since the importer's first, or since the last flagged jump.
/// The PCRs since the importer's first, or since the last break.
struct Timebase {
/// The last PCR, raw.
raw: u64,
Expand Down Expand Up @@ -488,7 +497,7 @@ impl<E: super::Catalog> Passthrough<E> {
}
if let Some(raw) = pcr(pkt) {
clock = true;
start = self.clock(pid, raw, at)?;
start = self.clock(raw, at)?;
discontinuity = start == Some(Start::Discontinuity);
}
}
Expand Down Expand Up @@ -530,7 +539,7 @@ impl<E: super::Catalog> Passthrough<E> {

/// A PCR at `at` on the clock PID: close the object it ends, time everything waiting on it,
/// and say whether its packet starts a group.
fn clock(&mut self, pid: u16, raw: u64, at: u64) -> crate::Result<Option<Start>> {
fn clock(&mut self, raw: u64, at: u64) -> crate::Result<Option<Start>> {
let at = at + PCR_OFFSET;
self.close_object();
let flagged = std::mem::take(&mut self.pending_break);
Expand All @@ -557,20 +566,16 @@ impl<E: super::Catalog> Passthrough<E> {
// A retransmitted break (the same flagged PCR again) declares nothing new.
let flagged = flagged && !(timebase.samples.len() == 1 && timebase.raw == raw);
let step = (raw + PCR_WRAP - timebase.raw) % PCR_WRAP;
if step > PCR_WRAP / 2 {
let from = timebase.raw;
return Err(match flagged {
true => crate::Error::PcrRestart { pid, from, to: raw },
false => crate::Error::PcrRewind { pid, from, to: raw },
});
}
let last = timebase.samples.back().expect("a timebase has a sample").ticks;
// A step back, or one forward too far to be elapsed time, is another timeline: the
// count carries on from where the rate before it puts this PCR, ignoring the step.
let spliced = (step > PCR_WRAP / 2 || (!flagged && step > LEAP_TICKS)).then(|| locate(at, &timebase.samples));

if flagged {
if flagged || spliced.is_some() {
// No PCR on the old side is coming: what waits on one is timed by the rate before it,
// and the new side carries on from there.
self.drain_queue()?;
let ticks = (last + step).max(self.written);
let ticks = spliced.unwrap_or(last + step).max(self.written);
// The object before was closed and the queue drained, so both start empty.
self.timing = Clock::Seen {
timebase: Timebase {
Expand Down Expand Up @@ -649,10 +654,21 @@ impl<E: super::Catalog> Passthrough<E> {
}

fn write(&mut self, object: Object, ticks: u64) -> crate::Result<()> {
// Extrapolating past the last PCR before a small flagged jump can overshoot the jump.
let ticks = ticks.max(self.written);
// Extrapolating past the last PCR before a break can overshoot where the count resumes.
let mut ticks = ticks.max(self.written);
if object.discontinuity
&& let Groups::Writing(group) = &self.groups
{
// The break's marker sits on the last object's microsecond, or the one past the newest
// group's start when that is later, and the group behind it has to start past the
// marker. A splice can resume on either, as after a PCR repeated or a one-PCR timebase,
// neither of which gives a rate.
let past_object = (self.written / TICKS_PER_MICRO + 1) * TICKS_PER_MICRO;
let past_group = (group.ticks / TICKS_PER_MICRO + 2) * TICKS_PER_MICRO;
ticks = ticks.max(past_object).max(past_group);
}
self.written = ticks;
let timestamp = moq_net::Timestamp::from_micros(ticks / (PCR_HZ / 1_000_000))?;
let timestamp = moq_net::Timestamp::from_micros(ticks / TICKS_PER_MICRO)?;
// The first object, which starts a group, anchors the shift and is live on arrival.
let timestamp = self.shift.shift(timestamp)?;
let size = object.payload.len() as u64;
Expand Down
Loading