From c0595a67f5a18f773d5ec1a8db6ca216762a6908 Mon Sep 17 00:00:00 2001 From: Scott Lamb Date: Wed, 26 Jan 2022 01:04:00 -0800 Subject: [PATCH] improve timestamp docs, take 2 In take 1, I put some of the most important information on private fields, so it wouldn't show up on public docs. Let's fix that now. --- src/client/timeline.rs | 2 +- src/lib.rs | 49 ++++++++++++++++++++++++++---------------- 2 files changed, 32 insertions(+), 19 deletions(-) diff --git a/src/client/timeline.rs b/src/client/timeline.rs index 50175f3..f164ac1 100644 --- a/src/client/timeline.rs +++ b/src/client/timeline.rs @@ -100,7 +100,7 @@ impl Timeline { .checked_add(i64::from(delta)) .ok_or_else(|| { // This probably won't happen even with a hostile server. It'd - // take ~2^31 packets (~ 2 billion) to advance the time this far + // take ~2^32 packets (~ 4 billion) to advance the time this far // forward or backward even with no limits on time jump per // packet. format!( diff --git a/src/lib.rs b/src/lib.rs index 05abf0c..2729f04 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -62,40 +62,53 @@ struct ReceivedMessage { msg: Message, } -/// An RTP timestamp, coupled with clock rate and stream start time for conversion to "NPT". +/// An annotated RTP timestamp. +/// +/// This couples together three pieces of information: +/// +/// * The timestamp as an `i64`. In client use, its top bits should be inferred from wraparounds +/// of 32-bit RTP timestamps. The Retina client's policy is that timestamps that differ by more +/// than `i32::MAX` from previous timestamps are treated as backwards jumps. +/// +/// * The codec-specific clock rate. +/// +/// * The stream's starting time. In client use, this is often as received in the RTSP +/// `RTP-Info` header but may be controlled via [`crate::client::InitialTimestampPolicy`]. +/// According to [RFC 3550 section 5.1](https://datatracker.ietf.org/doc/html/rfc3550#section-5.1), "the initial +/// value of the timestamp SHOULD be random". +/// +/// In combination, these allow conversion to "normal play time" (NPT): seconds since start of +/// the stream. /// /// According to [RFC 3550 section 5.1](https://datatracker.ietf.org/doc/html/rfc3550#section-5.1), /// RTP timestamps "MUST be derived from a clock that increments monotonically". In practice, -/// many RTP servers violate this. +/// many RTP servers violate this. The Retina client allows such violations unless +/// [`crate::client::PlayOptions::enforce_timestamps_with_max_jump_secs`] says otherwise. /// -/// The [Display] and [Debug] implementations display: +/// In client use, the top bits should be inferred from wraparounds of 32-bit RTP timestamps. +/// The Retina client's policy is that timestamps that differ by more than `i32::MAX` from +/// previous timestamps are treated as backwards jumps. It's allowed for a timestamp to +/// indicate a time *before* the stream's starting point. +/// +/// [`Timestamp`] can't represent timestamps which overflow/underflow `i64` can't be constructed or +/// elapsed times (`elapsed = timestamp - start`) which underflow `i64`. The client will return +/// error in these cases. This should rarely cause problems. It'd take ~2^32 packets (~4 billion) +/// to advance the time this far forward or backward even with a hostile server. +/// +/// The [`Display`] and [`Debug`] implementations currently display: /// * the bottom 32 bits, as seen in RTP packet headers. This advances at a /// codec-specified clock rate. /// * the full timestamp. -/// * a conversion to RTSP "normal play time" (NPT): zero-based and normalized to seconds. +/// * NPT #[derive(Copy, Clone, PartialEq, Eq)] pub struct Timestamp { /// A timestamp which must be compared to `start`. - /// - /// In client use, the top bits should be inferred from wraparounds of 32-bit RTP timestamps. - /// The Retina client's policy is that timestamps that differ by more than `i32::MAX` from - /// previous timestamps are treated as backwards jumps. It's allowed for a timestamp to - /// indicate a time *before* `start`, unless - /// [`crate::client::PlayOptions::enforce_timestamps_with_max_jump_secs`] says otherwise. - /// - /// `timestamp` itself is not allowed to overflow/underflow; similarly `timestamp - start` is - /// not allowed to underflow. This should rarely cause problems. It'd take ~2^31 packets (~2 - /// billion) to advance the time this far forward or backward even with a hostile server. timestamp: i64, /// The codec-specified clock rate, in Hz. Must be non-zero. clock_rate: NonZeroU32, /// The stream's starting time, as specified in the RTSP `RTP-Info` header. - /// - /// According to [RFC 3550 section - /// 5.1](https://datatracker.ietf.org/doc/html/rfc3550#section-5.1), "the initial value of the - /// timestamp SHOULD be random". start: u32, }