From d0d8a98c7ad76771e405229fcc5e32b92ab871f9 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 27 Oct 2026 16:47:51 -0700 Subject: [PATCH 01/12] chore(quest): claim quest/m1/binding-timestamps.md Quest-Claim: b389fb9601f12d46 From 5971d4643074ecce526f41649c3d7f33d5300e2d Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 27 Oct 2026 16:53:43 -0700 Subject: [PATCH 02/12] feat(moq-ffi)!: exact MoqTimestamp records replace microsecond fields Co-Authored-By: Claude Opus 5.5 --- rs/moq-ffi/src/audio.rs | 44 +++--- rs/moq-ffi/src/bench.rs | 10 +- rs/moq-ffi/src/consumer.rs | 27 ++-- rs/moq-ffi/src/error.rs | 2 +- rs/moq-ffi/src/flate.rs | 17 +- rs/moq-ffi/src/json.rs | 49 +++--- rs/moq-ffi/src/media.rs | 100 +++++++----- rs/moq-ffi/src/producer.rs | 10 +- rs/moq-ffi/src/test.rs | 313 +++++++++++++++++++++++-------------- rs/moq-ffi/src/video.rs | 65 ++++---- 10 files changed, 363 insertions(+), 274 deletions(-) diff --git a/rs/moq-ffi/src/audio.rs b/rs/moq-ffi/src/audio.rs index dfa5dce5332..1718c37db37 100644 --- a/rs/moq-ffi/src/audio.rs +++ b/rs/moq-ffi/src/audio.rs @@ -14,6 +14,7 @@ use crate::consumer::MoqBroadcastConsumer; use crate::demand::MoqTrackDemand; use crate::error::MoqError; use crate::ffi::Task; +use crate::media::MoqTimestamp; /// Raw PCM sample format, mirroring WebCodecs `AudioData.format`. /// @@ -189,8 +190,8 @@ pub struct MoqAudioDecoderOutput { /// PCM in the configured `output_format`. #[derive(uniffi::Record)] pub struct MoqAudioFrame { - /// Presentation timestamp of the first sample, in microseconds. - pub timestamp_us: u64, + /// Presentation timestamp of the first sample. + pub timestamp: MoqTimestamp, /// The samples, in the configured PCM layout. pub data: Vec, } @@ -211,36 +212,31 @@ pub enum MoqAudioRead { /// or a packet's timestamp did not continue the previous one. What follows does not /// continue what came before. Gap { - /// The furthest presentation point already read, in microseconds. - timestamp_us: u64, + /// The furthest presentation point already read. + timestamp: MoqTimestamp, /// An upper bound on how long until the next frame resumes. duration: Duration, }, /// The publisher stopped its encoder: it paused, switched source, or finished. /// - /// Frames that follow and start before `end_us` are the stopped encoder's remaining + /// Frames that follow and start before `end` are the stopped encoder's remaining /// media; the first frame at or past it comes from a fresh encoder. End { - /// Where the stopped encoder's media stops, in microseconds. - end_us: u64, + /// Where the stopped encoder's media stops. + end: MoqTimestamp, }, } -impl TryFrom for MoqAudioRead { - type Error = MoqError; - - fn try_from(read: moq_audio::decode::Read) -> Result { - use crate::consumer::timestamp_us; - Ok(match read { +impl From for MoqAudioRead { + fn from(read: moq_audio::decode::Read) -> Self { + match read { moq_audio::decode::Read::Frame(frame) => Self::Frame { frame: frame.into() }, moq_audio::decode::Read::Gap { timestamp, duration } => Self::Gap { - timestamp_us: timestamp_us(timestamp)?, + timestamp: timestamp.into(), duration: crate::ffi::duration(duration.into()), }, - moq_audio::decode::Read::End { end } => Self::End { - end_us: timestamp_us(end)?, - }, - }) + moq_audio::decode::Read::End { end } => Self::End { end: end.into() }, + } } } @@ -358,11 +354,7 @@ impl MoqAudioEncoder { impl From for MoqAudioFrame { fn from(f: moq_audio::Frame) -> Self { Self { - // The binding surface carries plain microseconds, so flatten the - // scaled `Timestamp` here. Saturating rather than erroring: this is a - // frame we already decoded, and a u64 overflow needs a timestamp - // ~580,000 years out. - timestamp_us: u64::try_from(f.timestamp.as_micros()).unwrap_or(u64::MAX), + timestamp: f.timestamp.into(), data: f.data.to_vec(), } } @@ -374,7 +366,7 @@ impl TryFrom for moq_audio::Frame { fn try_from(f: MoqAudioFrame) -> Result { Ok(Self::new( f.data.into(), - moq_net::Timestamp::from_micros(f.timestamp_us)?, + f.timestamp.try_into()?, )) } } @@ -566,7 +558,7 @@ impl ConsumerInner { async fn next(&mut self) -> Result, MoqError> { let read = self.consumer.read().await; self.delay.store(nanos(self.consumer.delay()), Ordering::Relaxed); - read?.map(MoqAudioRead::try_from).transpose() + Ok(read?.map(MoqAudioRead::from)) } } @@ -784,7 +776,7 @@ mod tests { // A partial codec frame makes finish publish the final packet and lookahead. audio .write(MoqAudioFrame { - timestamp_us: 0, + timestamp: MoqTimestamp { value: 0, scale: 1 }, data: vec![0.1_f32; 860].into_iter().flat_map(f32::to_ne_bytes).collect(), }) .unwrap(); diff --git a/rs/moq-ffi/src/bench.rs b/rs/moq-ffi/src/bench.rs index 94e80899e37..acc51712718 100644 --- a/rs/moq-ffi/src/bench.rs +++ b/rs/moq-ffi/src/bench.rs @@ -5,7 +5,7 @@ //! runs the same rounds on moq-net, below moq-ffi's handles and runtime. use crate::consumer::MoqTrackConsumer; -use crate::media::MoqFrame; +use crate::media::{MoqFrame, MoqTimestamp}; use crate::origin::{MoqOriginConfig, MoqOriginProducer}; use crate::producer::{MoqBroadcastProducer, MoqTrackInfo, MoqTrackProducer}; @@ -165,7 +165,8 @@ async fn ffi_round( let mut read = Vec::with_capacity(frames); for _ in 0..frames { let frame = group.read_frame().await.unwrap().expect("group ended"); - read.push((frame.payload, frame.timestamp_us)); + let timestamp = frame.timestamp.map(|t| moq_net::Timestamp::try_from(t).unwrap().as_micros() as u64); + read.push((frame.payload, timestamp)); } read }) @@ -176,7 +177,10 @@ async fn ffi_round( for f in 0..case.frames() { let frame = MoqFrame { payload: payload.to_vec(), - timestamp_us: Some(n * case.frames() as u64 + f as u64), + timestamp: Some(MoqTimestamp { + value: n * case.frames() as u64 + f as u64, + scale: 1_000_000, + }), }; group.write_frame(frame).unwrap(); } diff --git a/rs/moq-ffi/src/consumer.rs b/rs/moq-ffi/src/consumer.rs index 574e0e6f02c..a7ffe990a2c 100644 --- a/rs/moq-ffi/src/consumer.rs +++ b/rs/moq-ffi/src/consumer.rs @@ -10,16 +10,11 @@ use crate::ffi::{Background, Guard, Task}; use crate::media::*; use crate::producer::MoqTrackInfo; -pub(crate) fn timestamp_us(timestamp: moq_net::Timestamp) -> Result { - timestamp.as_micros().try_into().map_err(|_| MoqError::TimeOverflow) -} - -fn raw_frame(frame: moq_net::frame::Frame) -> Result { - let timestamp_us = frame.timestamp.map(timestamp_us).transpose()?; - Ok(MoqFrame { +fn raw_frame(frame: moq_net::frame::Frame) -> MoqFrame { + MoqFrame { payload: frame.payload.to_vec(), - timestamp_us, - }) + timestamp: frame.timestamp.map(Into::into), + } } /// Subscriber-side delivery preferences, mirroring [`moq_net::track::Subscription`]. @@ -81,8 +76,8 @@ pub enum MoqAnchor { }, /// The group containing this presentation time. An untimed track refuses it. Time { - /// The presentation time in microseconds. - timestamp_us: u64, + /// The presentation time. + timestamp: MoqTimestamp, }, } @@ -103,9 +98,7 @@ impl TryFrom for moq_net::track::Anchor { Ok(match anchor { MoqAnchor::Absolute { group } => Self::Absolute(group), MoqAnchor::Relative { groups } => Self::Relative(groups), - MoqAnchor::Time { timestamp_us } => { - Self::Time(moq_net::Timestamp::from_micros(timestamp_us).map_err(|_| MoqError::TimeOverflow)?) - } + MoqAnchor::Time { timestamp } => Self::Time(timestamp.try_into()?), }) } } @@ -494,7 +487,7 @@ impl TrackInner { }; Poll::Ready(Ok(Some(MoqDatagram { sequence: datagram.sequence, - timestamp_us: datagram.timestamp.map(timestamp_us).transpose()?, + timestamp: datagram.timestamp.map(Into::into), payload: datagram.payload.to_vec(), }))) } @@ -540,7 +533,7 @@ impl TrackShared { return Ok(None); } if let Some(frame) = kio::wait(|waiter| self.poll(|inner| inner.poll_pending_frame(waiter))).await? { - return Ok(Some(raw_frame(frame)?)); + return Ok(Some(raw_frame(frame))); } } } @@ -742,7 +735,7 @@ struct GroupInner { impl GroupInner { async fn read_frame(&mut self) -> Result, MoqError> { - self.group.read_frame().await?.map(raw_frame).transpose() + Ok(self.group.read_frame().await?.map(raw_frame)) } } diff --git a/rs/moq-ffi/src/error.rs b/rs/moq-ffi/src/error.rs index 8ed2a21f9c1..bf34ede7a66 100644 --- a/rs/moq-ffi/src/error.rs +++ b/rs/moq-ffi/src/error.rs @@ -231,7 +231,7 @@ pub enum MoqError { reason: String, }, - /// A timestamp is outside the supported range. + /// A timestamp value or scale is outside the supported range, or the scale is zero. #[error("timestamp overflow")] TimeOverflow, diff --git a/rs/moq-ffi/src/flate.rs b/rs/moq-ffi/src/flate.rs index 2340e5805db..f0d74066722 100644 --- a/rs/moq-ffi/src/flate.rs +++ b/rs/moq-ffi/src/flate.rs @@ -11,6 +11,7 @@ use std::sync::Arc; use moq_mux::binary::Config; use crate::error::MoqError; +use crate::media::MoqTimestamp; use crate::producer::{Child, MoqBroadcastProducer, MoqTrackProducer}; /// Options for an opaque data track, in either mode (the mode is fixed by the constructor). @@ -86,14 +87,14 @@ impl MoqFlateSnapshotProducer { } /// Publish a new payload, superseding the last. - /// `timestamp_us` is on the broadcast clock; null publishes untimed. - #[uniffi::method(default(timestamp_us = None))] - pub fn update(&self, payload: Vec, timestamp_us: Option) -> Result<(), MoqError> { + /// `timestamp` is on the broadcast clock; null publishes untimed. + #[uniffi::method(default(timestamp = None))] + pub fn update(&self, payload: Vec, timestamp: Option) -> Result<(), MoqError> { let _guard = crate::ffi::enter(); let mut guard = self.inner.lock().unwrap(); guard.as_mut().ok_or(MoqError::Closed)?.update(moq_net::Timed { value: payload.into(), - at: timestamp_us.map(moq_net::Timestamp::from_micros).transpose()?, + at: timestamp.map(TryInto::try_into).transpose()?, })?; Ok(()) } @@ -158,14 +159,14 @@ impl MoqFlateStreamProducer { } /// Append one payload to the log. - /// `timestamp_us` is on the broadcast clock; null publishes untimed. - #[uniffi::method(default(timestamp_us = None))] - pub fn append(&self, payload: Vec, timestamp_us: Option) -> Result<(), MoqError> { + /// `timestamp` is on the broadcast clock; null publishes untimed. + #[uniffi::method(default(timestamp = None))] + pub fn append(&self, payload: Vec, timestamp: Option) -> Result<(), MoqError> { let _guard = crate::ffi::enter(); let mut guard = self.inner.lock().unwrap(); guard.as_mut().ok_or(MoqError::Closed)?.append(moq_net::Timed { value: payload.into(), - at: timestamp_us.map(moq_net::Timestamp::from_micros).transpose()?, + at: timestamp.map(TryInto::try_into).transpose()?, })?; Ok(()) } diff --git a/rs/moq-ffi/src/json.rs b/rs/moq-ffi/src/json.rs index 9e09f9bce76..cd0677379f7 100644 --- a/rs/moq-ffi/src/json.rs +++ b/rs/moq-ffi/src/json.rs @@ -11,10 +11,11 @@ use std::sync::Arc; use serde_json::Value; -use crate::consumer::{MoqTrackConsumer, timestamp_us}; +use crate::consumer::MoqTrackConsumer; use crate::demand::MoqTrackDemand; use crate::error::MoqError; use crate::ffi::Task; +use crate::media::MoqTimestamp; use crate::producer::{Child, MoqBroadcastProducer, MoqTrackProducer}; /// Options for a JSON snapshot track (lossy latest-value mode). @@ -244,16 +245,16 @@ impl MoqJsonSnapshotProducer { /// Publish a new value, encoded as a snapshot or delta automatically. `value` is a JSON /// document. A no-op if unchanged from the previous update. - /// `timestamp_us` is on the broadcast clock; null publishes untimed. - #[uniffi::method(default(timestamp_us = None))] - pub fn update(&self, value: String, timestamp_us: Option) -> Result<(), MoqError> { + /// `timestamp` is on the broadcast clock; null publishes untimed. + #[uniffi::method(default(timestamp = None))] + pub fn update(&self, value: String, timestamp: Option) -> Result<(), MoqError> { let _guard = crate::ffi::enter(); let value: Value = serde_json::from_str(&value)?; let mut guard = self.inner.lock().unwrap(); let producer = guard.as_mut().ok_or(MoqError::Closed)?; producer.update(moq_net::Timed { value: &value, - at: timestamp_us.map(moq_net::Timestamp::from_micros).transpose()?, + at: timestamp.map(TryInto::try_into).transpose()?, })?; Ok(()) } @@ -279,10 +280,8 @@ impl MoqJsonSnapshotProducer { pub struct MoqJsonValue { /// The JSON document. pub value: String, - /// The frame's timestamp on the broadcast clock in microseconds, or null when untimed. - /// Rounded down to a whole microsecond, so a tick on a track like 90 kHz may not survive a - /// read and republish exactly. - pub timestamp_us: Option, + /// The frame's timestamp on the broadcast clock, or null when untimed. + pub timestamp: Option, } impl MoqJsonValue { @@ -290,7 +289,7 @@ impl MoqJsonValue { let Some(timed) = timed else { return Ok(None) }; Ok(Some(Self { value: serde_json::to_string(&timed.value)?, - timestamp_us: timed.at.map(timestamp_us).transpose()?, + timestamp: timed.at.map(Into::into), })) } } @@ -402,16 +401,16 @@ impl MoqJsonStreamProducer { } /// Append one record to the log. `value` is a JSON document. - /// `timestamp_us` is on the broadcast clock; null publishes untimed. - #[uniffi::method(default(timestamp_us = None))] - pub fn append(&self, value: String, timestamp_us: Option) -> Result<(), MoqError> { + /// `timestamp` is on the broadcast clock; null publishes untimed. + #[uniffi::method(default(timestamp = None))] + pub fn append(&self, value: String, timestamp: Option) -> Result<(), MoqError> { let _guard = crate::ffi::enter(); let value: Value = serde_json::from_str(&value)?; let mut guard = self.inner.lock().unwrap(); let producer = guard.as_mut().ok_or(MoqError::Closed)?; producer.append(moq_net::Timed { value: &value, - at: timestamp_us.map(moq_net::Timestamp::from_micros).transpose()?, + at: timestamp.map(TryInto::try_into).transpose()?, })?; Ok(()) } @@ -572,19 +571,19 @@ impl MoqJsonWindowProducer { } /// Append one record to the back of the window. `value` is a JSON document. - /// `timestamp_us` is on the broadcast clock; null publishes untimed. - #[uniffi::method(default(timestamp_us = None))] - pub fn push(&self, value: String, timestamp_us: Option) -> Result<(), MoqError> { + /// `timestamp` is on the broadcast clock; null publishes untimed. + #[uniffi::method(default(timestamp = None))] + pub fn push(&self, value: String, timestamp: Option) -> Result<(), MoqError> { let value: Value = serde_json::from_str(&value)?; - let at = timestamp_us.map(moq_net::Timestamp::from_micros).transpose()?; + let at = timestamp.map(TryInto::try_into).transpose()?; self.edit(|producer| producer.push(moq_net::Timed { value: &value, at })) } /// Drop `count` records from the front of the window, clamped to what it holds. - /// `timestamp_us` is on the broadcast clock; null publishes untimed. - #[uniffi::method(default(timestamp_us = None))] - pub fn pop(&self, count: u64, timestamp_us: Option) -> Result<(), MoqError> { - let at = timestamp_us.map(moq_net::Timestamp::from_micros).transpose()?; + /// `timestamp` is on the broadcast clock; null publishes untimed. + #[uniffi::method(default(timestamp = None))] + pub fn pop(&self, count: u64, timestamp: Option) -> Result<(), MoqError> { + let at = timestamp.map(TryInto::try_into).transpose()?; self.edit(|producer| producer.pop(moq_net::Timed { value: count, at })) } @@ -647,10 +646,10 @@ pub enum MoqJsonWindowEvent { pub struct MoqJsonWindowTimed { /// The change to the window. pub event: MoqJsonWindowEvent, - /// The frame's timestamp on the broadcast clock in microseconds, or null when untimed. + /// The frame's timestamp on the broadcast clock, or null when untimed. /// A record first learned of from a group's restatement (after a join, or while behind) /// carries that frame's time, not its original push time. - pub timestamp_us: Option, + pub timestamp: Option, } impl MoqJsonWindowTimed { @@ -679,7 +678,7 @@ impl MoqJsonWindowTimed { }; Ok(Some(Self { event, - timestamp_us: timed.at.map(timestamp_us).transpose()?, + timestamp: timed.at.map(Into::into), })) } } diff --git a/rs/moq-ffi/src/media.rs b/rs/moq-ffi/src/media.rs index 4bb3ce1f75a..4cfff9c400f 100644 --- a/rs/moq-ffi/src/media.rs +++ b/rs/moq-ffi/src/media.rs @@ -7,7 +7,7 @@ use bytes::Buf; use moq_mux::catalog::hang::Extra; use crate::consumer::{ - MoqBroadcastConsumer, MoqFetchGroupOptions, MoqGroupConsumer, MoqSubscription, map_fetch_error, timestamp_us, + MoqBroadcastConsumer, MoqFetchGroupOptions, MoqGroupConsumer, MoqSubscription, map_fetch_error, }; use crate::demand::MoqTrackDemand; use crate::error::MoqError; @@ -184,6 +184,35 @@ pub struct MoqAudio { pub jitter: Option, } +/// An exact media timestamp, `value` units at `scale` units per second, mirroring [`moq_net::Timestamp`]. +/// +/// Reads carry the scale the publisher wrote, so a tick such as 90 kHz survives a read and +/// republish exactly. Writing one past the bounds below is refused with [`MoqError::TimeOverflow`]. +#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, uniffi::Record)] +pub struct MoqTimestamp { + /// The time in `scale` units, at most `2^61 - 1`. + pub value: u64, + /// Units per second, non-zero and at most `2^62 - 1`. + pub scale: u64, +} + +impl From for MoqTimestamp { + fn from(timestamp: moq_net::Timestamp) -> Self { + Self { + value: timestamp.value(), + scale: timestamp.scale().as_u64(), + } + } +} + +impl TryFrom for moq_net::Timestamp { + type Error = moq_net::TimeOverflow; + + fn try_from(timestamp: MoqTimestamp) -> Result { + Self::from_scale(timestamp.value, timestamp.scale) + } +} + /// A payload and the time it should be presented. /// /// The unit of both writing and raw reading: every producer write takes one of these, and a @@ -193,9 +222,9 @@ pub struct MoqAudio { pub struct MoqFrame { /// The frame payload. pub payload: Vec, - /// Presentation timestamp in microseconds, or null on an untimed track, on both publish and receive. + /// Presentation timestamp, or null on an untimed track, on both publish and receive. #[uniffi(default = None)] - pub timestamp_us: Option, + pub timestamp: Option, } /// A [`MoqFrame`] plus the codec metadata a media track carries. @@ -203,8 +232,8 @@ pub struct MoqFrame { pub struct MoqMediaFrame { /// The frame payload. pub payload: Vec, - /// Presentation timestamp in microseconds. - pub timestamp_us: u64, + /// Presentation timestamp. + pub timestamp: MoqTimestamp, /// Whether this frame opens a group or is a video keyframe; audio is true only at a group start. pub keyframe: bool, } @@ -218,9 +247,9 @@ pub struct MoqDatagram { /// Per-track sequence number, shared with groups. #[uniffi(default = 0)] pub sequence: u64, - /// Presentation timestamp in microseconds, or null on an untimed track, on both publish and receive. + /// Presentation timestamp, or null on an untimed track, on both publish and receive. #[uniffi(default = None)] - pub timestamp_us: Option, + pub timestamp: Option, /// Datagram payload, capped at 1200 bytes. pub payload: Vec, } @@ -1036,10 +1065,12 @@ impl MoqMediaTrackProducer { let mut guard = self.inner.lock().unwrap(); let media = guard.as_mut().ok_or(MoqError::Closed)?; - let timestamp = - hang::container::Timestamp::from_micros(frame.timestamp_us.ok_or_else(|| MoqError::Codec { + let timestamp = frame + .timestamp + .ok_or_else(|| MoqError::Codec { reason: "whole media frames require a timestamp".into(), - })?)?; + })? + .try_into()?; media .import .decode(&frame.payload, Some(timestamp)) @@ -1311,15 +1342,14 @@ pub struct MoqMediaGroupConfig { pub options: Option, } -fn media_frame(mut frame: moq_mux::container::Frame) -> Result { - let timestamp_us = timestamp_us(frame.timestamp)?; +fn media_frame(mut frame: moq_mux::container::Frame) -> MoqMediaFrame { let payload = frame.payload.copy_to_bytes(frame.payload.remaining()).to_vec(); - Ok(MoqMediaFrame { + MoqMediaFrame { payload, - timestamp_us, + timestamp: frame.timestamp.into(), keyframe: frame.keyframe, - }) + } } fn media_container( @@ -1364,37 +1394,32 @@ pub enum MoqMediaRead { }, /// Media after what was already read was lost; what follows does not continue it. Gap { - /// The furthest presentation point already read, in microseconds. - timestamp_us: u64, + /// The furthest presentation point already read. + timestamp: MoqTimestamp, /// An upper bound on how long until the next frame resumes. duration: std::time::Duration, }, /// The publisher stopped its encoder: it paused, switched source, or finished. - /// Frames starting before `end_us` are its remaining media; the first at or past it + /// Frames starting before `end` are its remaining media; the first at or past it /// comes from a fresh encoder. End { - /// Where the stopped encoder's media stops, in microseconds. - end_us: u64, + /// Where the stopped encoder's media stops. + end: MoqTimestamp, }, } -impl TryFrom for MoqMediaRead { - type Error = MoqError; - - fn try_from(read: moq_mux::container::Read) -> Result { - use crate::consumer::timestamp_us; - Ok(match read { +impl From for MoqMediaRead { + fn from(read: moq_mux::container::Read) -> Self { + match read { moq_mux::container::Read::Frame { frame, .. } => Self::Frame { - frame: media_frame(frame)?, + frame: media_frame(frame), }, moq_mux::container::Read::Gap { timestamp, duration } => Self::Gap { - timestamp_us: timestamp_us(timestamp)?, + timestamp: timestamp.into(), duration: crate::ffi::duration(duration.into()), }, - moq_mux::container::Read::End { end, .. } => Self::End { - end_us: timestamp_us(end)?, - }, - }) + moq_mux::container::Read::End { end, .. } => Self::End { end: end.into() }, + } } } @@ -1410,7 +1435,7 @@ struct Media { impl Media { async fn next(&mut self) -> Result, MoqError> { - self.inner.read().await?.map(MoqMediaRead::try_from).transpose() + Ok(self.inner.read().await?.map(MoqMediaRead::from)) } } @@ -1453,6 +1478,7 @@ mod read_tests { .await .unwrap(); let timestamp = |us| moq_net::Timestamp::from_micros(us).unwrap(); + let micros = |value| MoqTimestamp { value, scale: 1_000_000 }; let mut first = track.create_group(0u64.into()).unwrap(); format() .write( @@ -1470,7 +1496,7 @@ mod read_tests { panic!("expected frame") }; assert_eq!(frame.payload, b"encoded"); - assert_eq!(frame.timestamp_us, 10_000); + assert_eq!(frame.timestamp, micros(10_000)); assert!(frame.keyframe); let mut marker = track.create_group(2u64.into()).unwrap(); format() @@ -1486,11 +1512,11 @@ mod read_tests { .unwrap(); marker.finish().unwrap(); assert!( - matches!(reader.next().await.unwrap(), Some(MoqMediaRead::Gap { timestamp_us: 10_000, duration }) if duration == Duration::from_millis(10)) + matches!(reader.next().await.unwrap(), Some(MoqMediaRead::Gap { timestamp, duration }) if timestamp == micros(10_000) && duration == Duration::from_millis(10)) ); assert!(matches!( reader.next().await.unwrap(), - Some(MoqMediaRead::End { end_us: 20_000 }) + Some(MoqMediaRead::End { end }) if end == micros(20_000) )); let mut resumed = track.create_group(3u64.into()).unwrap(); format() @@ -1522,7 +1548,7 @@ struct MediaGroupInner { impl MediaGroupInner { async fn next(&mut self) -> Result, MoqError> { - self.inner.read().await?.map(media_frame).transpose() + Ok(self.inner.read().await?.map(media_frame)) } } diff --git a/rs/moq-ffi/src/producer.rs b/rs/moq-ffi/src/producer.rs index d622bdc1925..6b44852d3f5 100644 --- a/rs/moq-ffi/src/producer.rs +++ b/rs/moq-ffi/src/producer.rs @@ -800,12 +800,12 @@ impl MoqTrackProducer { /// Write `frame` as a single-frame group. /// - /// Custom timescales may round the timestamp during conversion. The frame must + /// A timestamp at another scale than the track's is converted to it, rounding down. The frame must /// match its track's timedness, otherwise it is refused with /// [`MoqProtocolKind::TimestampMismatch`](crate::error::MoqProtocolKind::TimestampMismatch). pub fn write_frame(&self, frame: MoqFrame) -> Result<(), MoqError> { let _guard = crate::ffi::enter(); - let timestamp = frame.timestamp_us.map(moq_net::Timestamp::from_micros).transpose()?; + let timestamp = frame.timestamp.map(TryInto::try_into).transpose()?; let mut guard = self.inner.lock().unwrap(); let track = guard.as_mut().ok_or(MoqError::Closed)?; track.write_frame(timestamp, frame.payload)?; @@ -819,7 +819,7 @@ impl MoqTrackProducer { /// its timestamp must match the track's timedness. pub fn append_datagram(&self, frame: MoqFrame) -> Result { let _guard = crate::ffi::enter(); - let timestamp = frame.timestamp_us.map(moq_net::Timestamp::from_micros).transpose()?; + let timestamp = frame.timestamp.map(TryInto::try_into).transpose()?; let mut guard = self.inner.lock().unwrap(); let track = guard.as_mut().ok_or(MoqError::Closed)?; Ok(track.append_datagram(timestamp, frame.payload)?) @@ -890,12 +890,12 @@ impl MoqGroupProducer { /// Write `frame` into this group. /// - /// Custom timescales may round the timestamp during conversion. The frame must + /// A timestamp at another scale than the track's is converted to it, rounding down. The frame must /// match its track's timedness, otherwise it is refused with /// [`MoqProtocolKind::TimestampMismatch`](crate::error::MoqProtocolKind::TimestampMismatch). pub fn write_frame(&self, frame: MoqFrame) -> Result<(), MoqError> { let _guard = crate::ffi::enter(); - let timestamp = frame.timestamp_us.map(moq_net::Timestamp::from_micros).transpose()?; + let timestamp = frame.timestamp.map(TryInto::try_into).transpose()?; let mut guard = self.inner.lock().unwrap(); let group = guard.as_mut().ok_or(MoqError::Closed)?; group.write_frame(timestamp, frame.payload)?; diff --git a/rs/moq-ffi/src/test.rs b/rs/moq-ffi/src/test.rs index a2a5974cbdf..b119930a8cc 100644 --- a/rs/moq-ffi/src/test.rs +++ b/rs/moq-ffi/src/test.rs @@ -24,6 +24,19 @@ use std::future::Future; use std::sync::Arc; use std::time::Duration; +/// `value` microseconds. +fn us(value: u64) -> MoqTimestamp { + MoqTimestamp { + value, + scale: 1_000_000, + } +} + +/// `timestamp` in whole microseconds, whatever scale it was read at. +fn micros(timestamp: MoqTimestamp) -> u64 { + moq_net::Timestamp::try_from(timestamp).unwrap().as_micros() as u64 +} + /// A millisecond track: the frames written here carry timestamps. fn timed() -> moq_net::track::Info { moq_net::track::Info::default().with_timescale(moq_net::Timescale::MILLI) @@ -603,7 +616,7 @@ async fn raw_audio_activity() { .unwrap(); audio .write(MoqAudioFrame { - timestamp_us: FIRST_TIMESTAMP_US, + timestamp: us(FIRST_TIMESTAMP_US), data: vec![0; FRAME_SAMPLES * std::mem::size_of::()], }) .unwrap(); @@ -612,7 +625,7 @@ async fn raw_audio_activity() { .expect("timed out waiting for raw audio frame") .unwrap() .expect("expected a raw audio frame"); - assert_eq!(first.timestamp_us, FIRST_TIMESTAMP_US); + assert_eq!(micros(first.timestamp), FIRST_TIMESTAMP_US); drop(subscription); tokio::time::timeout(TIMEOUT, audio.demand().unwrap().until_unwanted()) @@ -636,7 +649,7 @@ async fn raw_audio_activity() { audio.reanchor().unwrap(); audio .write(MoqAudioFrame { - timestamp_us: RESUMED_TIMESTAMP_US, + timestamp: us(RESUMED_TIMESTAMP_US), data: vec![0; FRAME_SAMPLES * std::mem::size_of::()], }) .unwrap(); @@ -645,14 +658,14 @@ async fn raw_audio_activity() { .expect("timed out waiting for resumed raw audio frame") .unwrap() .expect("expected a resumed raw audio frame"); - if resumed.timestamp_us == first.timestamp_us { + if resumed.timestamp == first.timestamp { resumed = tokio::time::timeout(TIMEOUT, next_encoded_frame(&subscription)) .await .expect("timed out waiting for re-anchored raw audio frame") .unwrap() .expect("expected a re-anchored raw audio frame"); } - assert_eq!(resumed.timestamp_us, RESUMED_TIMESTAMP_US); + assert_eq!(micros(resumed.timestamp), RESUMED_TIMESTAMP_US); audio.finish().unwrap(); broadcast.close().unwrap(); @@ -731,7 +744,7 @@ async fn audio_raw_publish_from_many_threads() { let producer = audio.clone(); std::thread::spawn(move || { producer.write(MoqAudioFrame { - timestamp_us: 250_000 + index * 20_000, + timestamp: us(250_000 + index * 20_000), data: audio_tone(index as usize * 960, 960, 2), }) }) @@ -745,13 +758,13 @@ async fn audio_raw_publish_from_many_threads() { while let Some(read) = tokio::time::timeout(TIMEOUT, decoder.next()).await.unwrap().unwrap() { let frame = match read { MoqAudioRead::Frame { frame } => frame, - MoqAudioRead::End { end_us } => { - assert_eq!(end_us, 250_000 + 8 * 20_000, "the finish ends after the last frame"); + MoqAudioRead::End { end } => { + assert_eq!(micros(end), 250_000 + 8 * 20_000, "the finish ends after the last frame"); continue; } MoqAudioRead::Gap { .. } => panic!("nothing was lost"), }; - assert_eq!(frame.timestamp_us, 250_000 + pcm.len() as u64 / 2 * 1_000_000 / 48_000); + assert_eq!(micros(frame.timestamp), 250_000 + pcm.len() as u64 / 2 * 1_000_000 / 48_000); pcm.extend(frame.data.as_chunks::<4>().0.iter().map(|s| f32::from_le_bytes(*s))); } assert_eq!(pcm.len(), 8 * 960 * 2, "finish must preserve the entire PCM duration"); @@ -764,7 +777,7 @@ async fn audio_raw_publish_from_many_threads() { } assert!(matches!( audio.write(MoqAudioFrame { - timestamp_us: 0, + timestamp: us(0), data: vec![0; 8] }), Err(MoqError::Closed) @@ -803,7 +816,7 @@ async fn audio_raw_publish_rejects_bad_frames() { assert!( audio .write(MoqAudioFrame { - timestamp_us: 0, + timestamp: us(0), data: vec![0; size] }) .is_err() @@ -880,7 +893,7 @@ async fn raw_audio_decode_delay() { for i in 0..2 { audio .write(MoqAudioFrame { - timestamp_us: i * FRAME_US, + timestamp: us(i * FRAME_US), data: audio_tone(i as usize * FRAME_SAMPLES, FRAME_SAMPLES, 1), }) .unwrap(); @@ -969,7 +982,7 @@ async fn raw_audio_decode_reports_encoder_ends() { } audio .write(MoqAudioFrame { - timestamp_us, + timestamp: us(timestamp_us), data: audio_tone(i * FRAME_SAMPLES, FRAME_SAMPLES, 1), }) .unwrap(); @@ -980,9 +993,9 @@ async fn raw_audio_decode_reports_encoder_ends() { let mut frames = Vec::new(); while let Some(read) = tokio::time::timeout(TIMEOUT, decoder.next()).await.unwrap().unwrap() { match read { - MoqAudioRead::Frame { frame } => frames.push((ends.len(), frame.timestamp_us)), + MoqAudioRead::Frame { frame } => frames.push((ends.len(), micros(frame.timestamp))), MoqAudioRead::Gap { .. } => panic!("nothing was lost"), - MoqAudioRead::End { end_us } => ends.push(end_us), + MoqAudioRead::End { end } => ends.push(micros(end)), } } // The reanchor drops whatever the first encoder's lookahead still held, while the @@ -1039,7 +1052,7 @@ async fn raw_audio_frame_durations() { // 2.5 ms of silence at 48 kHz, mono f32: exactly one encoded frame. audio .write(MoqAudioFrame { - timestamp_us: 0, + timestamp: us(0), data: vec![0; 120 * std::mem::size_of::()], }) .unwrap(); @@ -1156,7 +1169,7 @@ async fn raw_track_datagram_roundtrip() { let sequence = track .append_datagram(MoqFrame { payload: payload.clone(), - timestamp_us: Some(123_456), + timestamp: Some(us(123_456)), }) .unwrap(); let datagram = tokio::time::timeout(TIMEOUT, consumer.recv_datagram()) @@ -1166,7 +1179,7 @@ async fn raw_track_datagram_roundtrip() { .expect("expected a datagram"); assert_eq!(datagram.sequence, sequence); - assert_eq!(datagram.timestamp_us, Some(123_456)); + assert_eq!(datagram.timestamp.map(micros), Some(123_456)); assert_eq!(datagram.payload, payload); } @@ -1218,7 +1231,7 @@ async fn raw_track_update_does_not_wait_for_pending_read() { track .write_frame(MoqFrame { payload: payload.clone(), - timestamp_us: Some(20_000), + timestamp: Some(us(20_000)), }) .unwrap(); @@ -1229,7 +1242,7 @@ async fn raw_track_update_does_not_wait_for_pending_read() { .unwrap() .expect("expected a frame"); assert_eq!(frame.payload, payload); - assert_eq!(frame.timestamp_us, Some(20_000)); + assert_eq!(frame.timestamp.map(micros), Some(20_000)); } /// Subscribe to `name` on `broadcast` as a raw track, for a typed consumer to take over. @@ -1244,7 +1257,8 @@ async fn subscribe(broadcast: &MoqBroadcastProducer, name: &str) -> Arc { @@ -1309,15 +1323,15 @@ async fn data_writes_preserve_optional_timestamps() { }, ) .unwrap(); - producer.append(payload.to_vec(), timestamp_us).unwrap(); + producer.append(payload.to_vec(), timestamp).unwrap(); producer.finish().unwrap(); } _ => unreachable!(), } let frame = consumer.read_frame().await.unwrap().unwrap(); assert_eq!(frame.payload, payload, "{kind}"); - assert_eq!(frame.timestamp_us, timestamp_us, "{kind}"); - assert_eq!(consumer.info().timescale, timestamp_us.map(|_| 1_000_000)); + assert_eq!(frame.timestamp, timestamp, "{kind}"); + assert_eq!(consumer.info().timescale, timestamp.map(|timestamp| timestamp.scale)); broadcast.close().unwrap(); } } @@ -1335,14 +1349,14 @@ async fn whole_media_frames_require_the_callers_timestamp() { assert!(matches!( media.write_frame(MoqFrame { payload: b"opus frame".to_vec(), - timestamp_us: None + timestamp: None }), Err(MoqError::Codec { .. }) )); media .write_frame(MoqFrame { payload: b"opus frame".to_vec(), - timestamp_us: Some(0), + timestamp: Some(us(0)), }) .unwrap(); media.finish().unwrap(); @@ -1369,7 +1383,7 @@ async fn catalog_now_fixes_the_clock_for_later_media() { media .write_frame(MoqFrame { payload: b"opus frame".to_vec(), - timestamp_us: Some(1_000_000), + timestamp: Some(us(1_000_000)), }) .unwrap(); assert_eq!( @@ -1408,7 +1422,7 @@ async fn json_snapshot_roundtrip() { let consumer = MoqJsonSnapshotConsumer::new(&*subscribe(&broadcast, "meta").await, config).unwrap(); for n in 1..=4 { - producer.update(format!(r#"{{"a":{n}}}"#), Some(n * 1000)).unwrap(); + producer.update(format!(r#"{{"a":{n}}}"#), Some(us(n * 1000))).unwrap(); } let value = tokio::time::timeout(TIMEOUT, consumer.next()) @@ -1420,7 +1434,7 @@ async fn json_snapshot_roundtrip() { serde_json::from_str::(&value.value).unwrap(), serde_json::json!({ "a": 1 }) ); - assert_eq!(value.timestamp_us, Some(1000)); + assert_eq!(value.timestamp.map(micros), Some(1000)); let value = tokio::time::timeout(TIMEOUT, consumer.next()) .await @@ -1431,7 +1445,7 @@ async fn json_snapshot_roundtrip() { serde_json::from_str::(&value.value).unwrap(), serde_json::json!({ "a": 2 }) ); - assert_eq!(value.timestamp_us, Some(2000)); + assert_eq!(value.timestamp.map(micros), Some(2000)); // `latest` skips the buffered third state. let value = tokio::time::timeout(TIMEOUT, consumer.latest()) @@ -1443,11 +1457,11 @@ async fn json_snapshot_roundtrip() { serde_json::from_str::(&value.value).unwrap(), serde_json::json!({ "a": 4 }) ); - assert_eq!(value.timestamp_us, Some(4000)); + assert_eq!(value.timestamp.map(micros), Some(4000)); producer.finish().unwrap(); assert!(matches!( - producer.update(r#"{"a":5}"#.into(), Some(5000)), + producer.update(r#"{"a":5}"#.into(), Some(us(5000))), Err(MoqError::Closed) )); let end = tokio::time::timeout(TIMEOUT, consumer.next()) @@ -1595,9 +1609,9 @@ async fn json_window_roundtrip() { let consumer = MoqJsonWindowConsumer::new(&*subscribe(&broadcast, "log").await, config).unwrap(); for n in 0..3 { - producer.push(format!(r#"{{"n":{n}}}"#), Some(n * 1000)).unwrap(); + producer.push(format!(r#"{{"n":{n}}}"#), Some(us(n * 1000))).unwrap(); } - producer.pop(2, Some(3000)).unwrap(); + producer.pop(2, Some(us(3000))).unwrap(); for n in 0..3 { let event = next_window(&consumer).await.expect("expected a push"); @@ -1605,7 +1619,7 @@ async fn json_window_roundtrip() { event, MoqJsonWindowTimed { event: window_push(n, n), - timestamp_us: Some(n * 1000), + timestamp: Some(us(n * 1000)), } ); } @@ -1613,16 +1627,16 @@ async fn json_window_roundtrip() { next_window(&consumer).await, Some(MoqJsonWindowTimed { event: MoqJsonWindowEvent::Pop { start: 0, end: 2 }, - timestamp_us: Some(3000), + timestamp: Some(us(3000)), }) ); producer.finish().unwrap(); assert!(matches!( - producer.push(r#"{"n":3}"#.into(), Some(4000)), + producer.push(r#"{"n":3}"#.into(), Some(us(4000))), Err(MoqError::Closed) )); - assert!(matches!(producer.pop(1, Some(4000)), Err(MoqError::Closed))); + assert!(matches!(producer.pop(1, Some(us(4000))), Err(MoqError::Closed))); assert_eq!(next_window(&consumer).await, None); } @@ -1655,7 +1669,7 @@ async fn json_window_cut_restates_the_window() { next_window(&consumer).await, Some(MoqJsonWindowTimed { event, - timestamp_us: None, + timestamp: None, }) ); } @@ -1686,7 +1700,7 @@ async fn json_window_cut_restates_the_window() { next_window(&consumer).await, Some(MoqJsonWindowTimed { event: window_push(3, 3), - timestamp_us: None, + timestamp: None, }) ); @@ -1739,7 +1753,7 @@ async fn json_window_refreshes_a_bounded_checkpoint_for_a_joiner() { next_window(&consumer).await, Some(MoqJsonWindowTimed { event, - timestamp_us: None, + timestamp: None, }) ); } @@ -1851,7 +1865,7 @@ async fn json_stream_roundtrip() { serde_json::from_str::(&value.value).unwrap(), serde_json::json!({ "n": n }) ); - assert_eq!(value.timestamp_us, None, "an untimed track yields no timestamp"); + assert_eq!(value.timestamp, None, "an untimed track yields no timestamp"); } producer.finish().unwrap(); } @@ -1994,7 +2008,7 @@ async fn dynamic_track_request() { track .write_frame(MoqFrame { payload: payload.clone(), - timestamp_us: Some(0), + timestamp: Some(us(0)), }) .unwrap(); @@ -2011,7 +2025,7 @@ async fn dynamic_track_request() { .expect("expected a frame"); assert_eq!(frame.payload, payload); - assert_eq!(frame.timestamp_us, Some(0)); + assert_eq!(frame.timestamp.map(micros), Some(0)); track.finish().unwrap(); } @@ -2024,33 +2038,33 @@ async fn raw_untimed_frames_and_datagrams_roundtrip() { track .write_frame(MoqFrame { payload: b"frame".to_vec(), - timestamp_us: None, + timestamp: None, }) .unwrap(); let frame = consumer.read_frame().await.unwrap().unwrap(); assert_eq!(frame.payload, b"frame"); - assert_eq!(frame.timestamp_us, None); + assert_eq!(frame.timestamp, None); let group = track.append_group().unwrap(); let reader = group.consume().unwrap(); group .write_frame(MoqFrame { payload: b"group".to_vec(), - timestamp_us: None, + timestamp: None, }) .unwrap(); group.finish().unwrap(); let frame = reader.read_frame().await.unwrap().unwrap(); assert_eq!(frame.payload, b"group"); - assert_eq!(frame.timestamp_us, None); + assert_eq!(frame.timestamp, None); track .append_datagram(MoqFrame { payload: b"datagram".to_vec(), - timestamp_us: None, + timestamp: None, }) .unwrap(); let datagram = consumer.recv_datagram().await.unwrap().unwrap(); assert_eq!(datagram.payload, b"datagram"); - assert_eq!(datagram.timestamp_us, None); + assert_eq!(datagram.timestamp, None); track.finish().unwrap(); } @@ -2061,7 +2075,7 @@ fn raw_writes_need_a_timestamp() { let track = broadcast.publish_track("status".into(), Some(timed_info())).unwrap(); let untimed = || MoqFrame { payload: b"ready".to_vec(), - timestamp_us: None, + timestamp: None, }; let refused = |err: MoqError| { matches!( @@ -2090,7 +2104,7 @@ async fn raw_frame_timestamps() { track .write_frame(MoqFrame { payload: payload.clone(), - timestamp_us: Some(12_345), + timestamp: Some(us(12_345)), }) .unwrap(); @@ -2100,7 +2114,7 @@ async fn raw_frame_timestamps() { .unwrap() .expect("expected a frame"); assert_eq!(frame.payload, payload); - assert_eq!(frame.timestamp_us, Some(12_345)); + assert_eq!(frame.timestamp.map(micros), Some(12_345)); let group = track.append_group().unwrap(); let group_consumer = group.consume().unwrap(); @@ -2108,7 +2122,7 @@ async fn raw_frame_timestamps() { group .write_frame(MoqFrame { payload: payload.clone(), - timestamp_us: Some(23_456), + timestamp: Some(us(23_456)), }) .unwrap(); group.finish().unwrap(); @@ -2119,11 +2133,66 @@ async fn raw_frame_timestamps() { .unwrap() .expect("expected a frame"); assert_eq!(frame.payload, payload); - assert_eq!(frame.timestamp_us, Some(23_456)); + assert_eq!(frame.timestamp.map(micros), Some(23_456)); track.finish().unwrap(); } +#[tokio::test] +async fn timestamps_are_exact() { + let broadcast = MoqBroadcastProducer::new().unwrap(); + let info = MoqTrackInfo { + timescale: Some(90_000), + ..timed_info() + }; + let track = broadcast.publish_track("video".into(), Some(info)).unwrap(); + let consumer = track.consume(None).unwrap(); + + // A present zero stays present, and one 90 kHz tick reads back as itself rather than + // the 11 µs it floors to. + for value in [0, 1] { + let timestamp = MoqTimestamp { value, scale: 90_000 }; + track + .write_frame(MoqFrame { + payload: b"frame".to_vec(), + timestamp: Some(timestamp), + }) + .unwrap(); + let frame = tokio::time::timeout(TIMEOUT, consumer.read_frame()) + .await + .unwrap() + .unwrap() + .unwrap(); + assert_eq!(frame.timestamp, Some(timestamp)); + } + + for invalid in [ + MoqTimestamp { value: 0, scale: 0 }, + MoqTimestamp { + value: 0, + scale: 1 << 62, + }, + MoqTimestamp { + value: 1 << 61, + scale: 90_000, + }, + ] { + let frame = MoqFrame { + payload: b"frame".to_vec(), + timestamp: Some(invalid), + }; + assert!(matches!(track.write_frame(frame), Err(MoqError::TimeOverflow)), "{invalid:?}"); + let range = MoqRange { + start: MoqAnchor::Time { timestamp: invalid }, + end: None, + }; + assert!(matches!( + moq_net::track::Range::try_from(range), + Err(MoqError::TimeOverflow) + )); + } +} + #[test] fn raw_track_supports_sparse_groups_and_known_end() { let broadcast = MoqBroadcastProducer::new().unwrap(); @@ -2149,7 +2218,7 @@ async fn abort_after_finish_keeps_the_track_handle() { track .write_frame(MoqFrame { payload: b"late abort".to_vec(), - timestamp_us: Some(0), + timestamp: Some(us(0)), }) .unwrap(); track.finish().unwrap(); @@ -2167,7 +2236,7 @@ async fn abort_after_finish_reaches_group_consumer() { group .write_frame(MoqFrame { payload: b"late abort".to_vec(), - timestamp_us: Some(0), + timestamp: Some(us(0)), }) .unwrap(); group.finish().unwrap(); @@ -2223,13 +2292,13 @@ async fn fetches_cached_group_without_subscribing() { group .write_frame(MoqFrame { payload: b"first".to_vec(), - timestamp_us: Some(0), + timestamp: Some(us(0)), }) .unwrap(); group .write_frame(MoqFrame { payload: b"second".to_vec(), - timestamp_us: Some(20_000), + timestamp: Some(us(20_000)), }) .unwrap(); group.finish().unwrap(); @@ -2250,10 +2319,10 @@ async fn fetches_cached_group_without_subscribing() { assert_eq!(fetched.sequence(), 0); let frame = fetched.read_frame().await.unwrap().expect("expected first frame"); assert_eq!(frame.payload, b"first".to_vec()); - assert_eq!(frame.timestamp_us, Some(0)); + assert_eq!(frame.timestamp.map(micros), Some(0)); let frame = fetched.read_frame().await.unwrap().expect("expected second frame"); assert_eq!(frame.payload, b"second".to_vec()); - assert_eq!(frame.timestamp_us, Some(20_000)); + assert_eq!(frame.timestamp.map(micros), Some(20_000)); assert!(fetched.read_frame().await.unwrap().is_none()); } @@ -2302,11 +2371,11 @@ async fn fetches_cached_media_group_and_decodes_container() { assert_eq!(fetched.sequence(), 0); let frame = fetched.next().await.unwrap().expect("expected keyframe"); assert_eq!(frame.payload, b"keyframe"); - assert_eq!(frame.timestamp_us, 1_000_000); + assert_eq!(micros(frame.timestamp), 1_000_000); assert!(frame.keyframe); let frame = fetched.next().await.unwrap().expect("expected delta frame"); assert_eq!(frame.payload, b"delta"); - assert_eq!(frame.timestamp_us, 1_020_000); + assert_eq!(micros(frame.timestamp), 1_020_000); assert!(!frame.keyframe); assert!(fetched.next().await.unwrap().is_none()); } @@ -2384,7 +2453,7 @@ async fn fetch_media_group_decodes_multiple_cmaf_samples() { .unwrap() .expect("expected first sample"); assert_eq!(first.payload, b"keyframe"); - assert_eq!(first.timestamp_us, 2_000_000); + assert_eq!(micros(first.timestamp), 2_000_000); assert!(first.keyframe); let second = tokio::time::timeout(TIMEOUT, fetched.next()) .await @@ -2392,7 +2461,7 @@ async fn fetch_media_group_decodes_multiple_cmaf_samples() { .unwrap() .expect("expected second sample"); assert_eq!(second.payload, b"delta"); - assert_eq!(second.timestamp_us, 2_020_000); + assert_eq!(micros(second.timestamp), 2_020_000); assert!(!second.keyframe); assert!( tokio::time::timeout(TIMEOUT, fetched.next()) @@ -2469,7 +2538,7 @@ async fn media_group_decodes_arrival_order_groups() { assert_eq!(first_media.sequence(), 0); let frame = next_media(&first_media).await.unwrap().expect("expected a frame"); assert_eq!(frame.payload, b"a"); - assert_eq!(frame.timestamp_us, 1_000_000); + assert_eq!(micros(frame.timestamp), 1_000_000); assert!(frame.keyframe); // A newer group lands while the first is stalled mid-way. @@ -2479,7 +2548,7 @@ async fn media_group_decodes_arrival_order_groups() { assert_eq!(second_media.sequence(), 1); let frame = next_media(&second_media).await.unwrap().expect("expected a frame"); assert_eq!(frame.payload, b"c"); - assert_eq!(frame.timestamp_us, 1_040_000); + assert_eq!(micros(frame.timestamp), 1_040_000); // The stalled group resumes and is still delivered. write_legacy(&mut first, 3, 1_020_000, b"b"); @@ -2488,7 +2557,7 @@ async fn media_group_decodes_arrival_order_groups() { .unwrap() .expect("expected the stalled group's frame"); assert_eq!(frame.payload, b"b"); - assert_eq!(frame.timestamp_us, 1_020_000); + assert_eq!(micros(frame.timestamp), 1_020_000); assert!(!frame.keyframe); first.finish().unwrap(); @@ -2582,7 +2651,7 @@ async fn dynamic_track_serves_fetch_miss_and_priority() { group .write_frame(MoqFrame { payload: b"fetched".to_vec(), - timestamp_us: Some(100_000), + timestamp: Some(us(100_000)), }) .unwrap(); group.finish().unwrap(); @@ -2595,7 +2664,7 @@ async fn dynamic_track_serves_fetch_miss_and_priority() { assert_eq!(fetched.sequence(), 5); let frame = fetched.read_frame().await.unwrap().expect("expected fetched frame"); assert_eq!(frame.payload, b"fetched".to_vec()); - assert_eq!(frame.timestamp_us, Some(100_000)); + assert_eq!(frame.timestamp.map(micros), Some(100_000)); } #[tokio::test] @@ -2692,7 +2761,7 @@ async fn requested_track_dynamic_survives_accept() { group .write_frame(MoqFrame { payload: b"archive".to_vec(), - timestamp_us: Some(180_000), + timestamp: Some(us(180_000)), }) .unwrap(); group.finish().unwrap(); @@ -2704,7 +2773,7 @@ async fn requested_track_dynamic_survives_accept() { .unwrap(); let frame = fetched.read_frame().await.unwrap().expect("expected archive frame"); assert_eq!(frame.payload, b"archive".to_vec()); - assert_eq!(frame.timestamp_us, Some(180_000)); + assert_eq!(frame.timestamp.map(micros), Some(180_000)); } #[tokio::test] @@ -2883,7 +2952,7 @@ async fn dynamic_track_request_can_publish_media() { media .write_frame(MoqFrame { payload: payload.clone(), - timestamp_us: Some(20_000), + timestamp: Some(us(20_000)), }) .unwrap(); @@ -2893,7 +2962,7 @@ async fn dynamic_track_request_can_publish_media() { .unwrap() .expect("expected a frame"); assert_eq!(frame.payload, payload); - assert_eq!(frame.timestamp_us, 20_000); + assert_eq!(micros(frame.timestamp), 20_000); media.discontinuity().unwrap(); media.finish().unwrap(); @@ -3548,7 +3617,7 @@ async fn local_publish_consume_audio() { media .write_frame(MoqFrame { payload: payload.clone(), - timestamp_us: Some(1_000_000), + timestamp: Some(us(1_000_000)), }) .unwrap(); @@ -3559,7 +3628,7 @@ async fn local_publish_consume_audio() { .expect("expected a frame"); assert_eq!(frame.payload, payload); - assert_eq!(frame.timestamp_us, 1_000_000); + assert_eq!(micros(frame.timestamp), 1_000_000); broadcast.close().unwrap(); } @@ -3619,7 +3688,7 @@ async fn video_publish_consume() { media .write_frame(MoqFrame { payload: keyframe, - timestamp_us: Some(0), + timestamp: Some(us(0)), }) .unwrap(); @@ -3629,7 +3698,7 @@ async fn video_publish_consume() { .unwrap() .expect("expected frame"); - assert_eq!(frame.timestamp_us, 0); + assert_eq!(micros(frame.timestamp), 0); assert!(!frame.payload.is_empty(), "frame should have payload data"); broadcast.close().unwrap(); @@ -3692,7 +3761,7 @@ async fn video_raw_publish_consume() { for i in 0..5u64 { video .write(MoqVideoFrame { - timestamp_us: i * 1_001_000 / 30, + timestamp: us(i * 1_001_000 / 30), data: rgba.clone(), }) .unwrap(); @@ -3742,7 +3811,7 @@ async fn video_raw_publish_consume() { for i in 5..20u64 { video .write(MoqVideoFrame { - timestamp_us: i * 1_001_000 / 30, + timestamp: us(i * 1_001_000 / 30), data: rgba.clone(), }) .unwrap(); @@ -3804,7 +3873,7 @@ async fn video_decode_frame_ownership() { for i in 0..10u64 { video .write(MoqVideoFrame { - timestamp_us: i * 33_333, + timestamp: us(i * 33_333), data: rgba.clone(), }) .unwrap(); @@ -3852,7 +3921,7 @@ async fn video_decode_frame_ownership() { for i in 10..40u64 { video .write(MoqVideoFrame { - timestamp_us: i * 33_333, + timestamp: us(i * 33_333), data: rgba.clone(), }) .unwrap(); @@ -3966,7 +4035,7 @@ async fn video_raw_publish_from_many_threads() { } video .write(MoqVideoFrame { - timestamp_us: i * 33_333, + timestamp: us(i * 33_333), data: rgba.as_ref().clone(), }) .unwrap(); @@ -4065,7 +4134,7 @@ async fn video_raw_publish_rejects_bad_frames() { assert!( video .write(MoqVideoFrame { - timestamp_us: 0, + timestamp: us(0), data: vec![0x80u8; 640 * 480 * 4], }) .is_err() @@ -4074,7 +4143,7 @@ async fn video_raw_publish_rejects_bad_frames() { video.finish().unwrap(); assert!(matches!( video.write(MoqVideoFrame { - timestamp_us: 0, + timestamp: us(0), data: vec![0x80u8; 320 * 240 * 4], }), Err(MoqError::Closed) @@ -4127,7 +4196,7 @@ async fn multiple_frames_ordering() { media .write_frame(MoqFrame { payload: payload.into_bytes(), - timestamp_us: Some(ts), + timestamp: Some(us(ts)), }) .unwrap(); } @@ -4139,7 +4208,7 @@ async fn multiple_frames_ordering() { .unwrap() .unwrap_or_else(|| panic!("expected frame {i}")); - assert_eq!(frame.timestamp_us, expected_ts, "frame {i} has wrong timestamp"); + assert_eq!(micros(frame.timestamp), expected_ts, "frame {i} has wrong timestamp"); let expected = format!("frame-{i}"); assert_eq!(frame.payload, expected.as_bytes(), "frame {i} has wrong payload"); } @@ -4238,7 +4307,7 @@ async fn finish_serves_finished_tracks_until_close() { audio .write_frame(MoqFrame { payload: b"tail".to_vec(), - timestamp_us: Some(0), + timestamp: Some(us(0)), }) .unwrap(); audio.finish().unwrap(); @@ -4312,7 +4381,7 @@ async fn closing_a_broadcast_ends_its_open_tracks() { let frame = MoqFrame { payload: b"late".to_vec(), - timestamp_us: Some(0), + timestamp: Some(us(0)), }; assert!(matches!(raw.write_frame(frame.clone()), Err(MoqError::Closed))); assert!(matches!(raw.finish(), Err(MoqError::Closed))); @@ -4574,7 +4643,7 @@ async fn dynamic_broadcast_request() { track .write_frame(MoqFrame { payload: payload.clone(), - timestamp_us: Some(20_000), + timestamp: Some(us(20_000)), }) .unwrap(); @@ -4584,7 +4653,7 @@ async fn dynamic_broadcast_request() { .unwrap() .expect("expected a frame"); assert_eq!(frame.payload, payload); - assert_eq!(frame.timestamp_us, Some(20_000)); + assert_eq!(frame.timestamp.map(micros), Some(20_000)); track.finish().unwrap(); served.close().unwrap(); @@ -4703,7 +4772,7 @@ async fn raw_track_next_group_is_repeatable() { track .write_frame(MoqFrame { payload: payload.clone(), - timestamp_us: Some(0), + timestamp: Some(us(0)), }) .unwrap(); @@ -4741,7 +4810,7 @@ async fn raw_track_group_order_commits_on_first_read() { track .write_frame(MoqFrame { payload: b"one".to_vec(), - timestamp_us: Some(0), + timestamp: Some(us(0)), }) .unwrap(); @@ -4759,7 +4828,7 @@ async fn raw_track_group_order_commits_on_first_read() { track .write_frame(MoqFrame { payload: b"two".to_vec(), - timestamp_us: Some(0), + timestamp: Some(us(0)), }) .unwrap(); let group = tokio::time::timeout(TIMEOUT, consumer.recv_group()) @@ -4773,7 +4842,7 @@ async fn raw_track_group_order_commits_on_first_read() { let sequence = track .append_datagram(MoqFrame { payload: b"beep".to_vec(), - timestamp_us: Some(0), + timestamp: Some(us(0)), }) .unwrap(); let datagram = tokio::time::timeout(TIMEOUT, consumer.recv_datagram()) @@ -4799,14 +4868,14 @@ fn raw_track() -> ( fn datagram_frame(payload: &[u8]) -> MoqFrame { MoqFrame { payload: payload.to_vec(), - timestamp_us: Some(1), + timestamp: Some(us(1)), } } fn group_frame(payload: &[u8]) -> MoqFrame { MoqFrame { payload: payload.to_vec(), - timestamp_us: Some(0), + timestamp: Some(us(0)), } } @@ -5095,7 +5164,7 @@ async fn raw_read_frame_skips_empty_group_on_open_track() { track .write_frame(MoqFrame { payload: payload.clone(), - timestamp_us: Some(1_000), + timestamp: Some(us(1_000)), }) .unwrap(); @@ -5106,7 +5175,7 @@ async fn raw_read_frame_skips_empty_group_on_open_track() { .unwrap() .expect("expected a frame"); assert_eq!(frame.payload, payload); - assert_eq!(frame.timestamp_us, Some(1_000)); + assert_eq!(frame.timestamp.map(micros), Some(1_000)); } /// Empty groups already in the cursor are skipped, then the next populated @@ -5124,7 +5193,7 @@ async fn raw_read_frame_skips_empty_then_populated_groups() { track .write_frame(MoqFrame { payload: payload.clone(), - timestamp_us: Some(2_000), + timestamp: Some(us(2_000)), }) .unwrap(); @@ -5134,7 +5203,7 @@ async fn raw_read_frame_skips_empty_then_populated_groups() { .unwrap() .expect("expected the populated group's first frame"); assert_eq!(frame.payload, payload); - assert_eq!(frame.timestamp_us, Some(2_000)); + assert_eq!(frame.timestamp.map(micros), Some(2_000)); } /// A group a hop reset as expired is skipped like an empty one, as a locally expired @@ -5210,7 +5279,7 @@ async fn raw_read_frame_keeps_group_across_cancelled_call() { group .write_frame(MoqFrame { payload: payload.clone(), - timestamp_us: Some(3_000), + timestamp: Some(us(3_000)), }) .unwrap(); group.finish().unwrap(); @@ -5222,7 +5291,7 @@ async fn raw_read_frame_keeps_group_across_cancelled_call() { .unwrap() .expect("cancelled read_frame must not lose the group's first frame"); assert_eq!(frame.payload, payload); - assert_eq!(frame.timestamp_us, Some(3_000)); + assert_eq!(frame.timestamp.map(micros), Some(3_000)); assert!( tokio::time::timeout(TIMEOUT, consumer.read_frame()) @@ -5268,7 +5337,7 @@ async fn raw_read_frame_drops_aborted_pending_group() { track .write_frame(MoqFrame { payload: payload.clone(), - timestamp_us: Some(4_000), + timestamp: Some(us(4_000)), }) .unwrap(); let frame = tokio::time::timeout(TIMEOUT, consumer.read_frame()) @@ -5277,7 +5346,7 @@ async fn raw_read_frame_drops_aborted_pending_group() { .unwrap() .expect("an aborted pending group must not block later groups"); assert_eq!(frame.payload, payload); - assert_eq!(frame.timestamp_us, Some(4_000)); + assert_eq!(frame.timestamp.map(micros), Some(4_000)); } /// `next_group` and `read_frame` share one ordered cursor. A cancelled @@ -5294,7 +5363,7 @@ async fn raw_read_frame_and_next_group_share_the_cursor() { first .write_frame(MoqFrame { payload: b"first".to_vec(), - timestamp_us: Some(0), + timestamp: Some(us(0)), }) .unwrap(); first.finish().unwrap(); @@ -5314,7 +5383,7 @@ async fn raw_read_frame_and_next_group_share_the_cursor() { track .write_frame(MoqFrame { payload: b"second".to_vec(), - timestamp_us: Some(0), + timestamp: Some(us(0)), }) .unwrap(); let frame = tokio::time::timeout(TIMEOUT, consumer.read_frame()) @@ -5432,7 +5501,7 @@ fn without_runtime() { media .write_frame(MoqFrame { payload: b"hello".to_vec(), - timestamp_us: Some(1000), + timestamp: Some(us(1000)), }) .unwrap(); @@ -5558,7 +5627,7 @@ async fn server_client_roundtrip() { media .write_frame(MoqFrame { payload: payload.clone(), - timestamp_us: Some(1_000_000), + timestamp: Some(us(1_000_000)), }) .unwrap(); @@ -5568,7 +5637,7 @@ async fn server_client_roundtrip() { .unwrap() .expect("expected a frame"); assert_eq!(frame.payload, payload); - assert_eq!(frame.timestamp_us, 1_000_000); + assert_eq!(micros(frame.timestamp), 1_000_000); // Clean up. Exercise `shutdown()` on the client side and the underlying // `cancel(code)` on the server side, so both shutdown paths run. @@ -5609,7 +5678,7 @@ async fn roundtrip(media: &MoqMediaTrackProducer, track: &MoqMediaTrackConsumer, media .write_frame(MoqFrame { payload: payload.to_vec(), - timestamp_us: Some(timestamp_us), + timestamp: Some(us(timestamp_us)), }) .unwrap(); loop { @@ -7724,7 +7793,7 @@ async fn shutdown_without_waiter_survives_session_disposal() { let group = track.append_group().unwrap(); group .write_frame(MoqFrame { - timestamp_us: Some(1), + timestamp: Some(us(1)), payload: vec![42; 64 * 1024], }) .unwrap(); @@ -7808,7 +7877,7 @@ async fn shutdown_ready(track: &MoqTrackProducer, reader: &MoqTrackConsumer) { let group = track.append_group().unwrap(); group .write_frame(MoqFrame { - timestamp_us: Some(0), + timestamp: Some(us(0)), payload: b"ready".to_vec(), }) .unwrap(); @@ -7849,7 +7918,7 @@ async fn shutdown_delivers_the_finished_track() { crate::ffi::detached(async move { let group = track.append_group()?; group.write_frame(MoqFrame { - timestamp_us: Some(0), + timestamp: Some(us(0)), payload: b"last".to_vec(), })?; group.finish()?; @@ -7934,7 +8003,7 @@ async fn ascending_subscription_reads_a_cached_backlog_oldest_first() { group .write_frame(MoqFrame { payload: b"x".to_vec(), - timestamp_us: Some(timestamp_us), + timestamp: Some(us(timestamp_us)), }) .unwrap(); group.finish().unwrap(); @@ -8145,7 +8214,7 @@ async fn time_anchors_start_at_the_containing_group() { group .write_frame(MoqFrame { payload: b"x".to_vec(), - timestamp_us: Some(timestamp_us), + timestamp: Some(us(timestamp_us)), }) .unwrap(); group.finish().unwrap(); @@ -8155,7 +8224,9 @@ async fn time_anchors_start_at_the_containing_group() { priority: 0, max_delay: Some(Duration::from_secs(10)), ranges: Some(vec![MoqRange { - start: MoqAnchor::Time { timestamp_us }, + start: MoqAnchor::Time { + timestamp: us(timestamp_us), + }, end: None, }]), order: Some(MoqOrder::Ascending), diff --git a/rs/moq-ffi/src/video.rs b/rs/moq-ffi/src/video.rs index a50fe16113f..936547379fb 100644 --- a/rs/moq-ffi/src/video.rs +++ b/rs/moq-ffi/src/video.rs @@ -19,6 +19,7 @@ use crate::bandwidth::{MoqAllocator, MoqReservation}; use crate::consumer::MoqBroadcastConsumer; use crate::demand::MoqTrackDemand; use crate::error::MoqError; +use crate::media::MoqTimestamp; /// A CPU pixel layout: what [`MoqVideoProducer::write`] is fed, and what /// [`MoqVideoDecodedFrame::pixels`] converts to. @@ -188,8 +189,8 @@ impl From for moq_video::encode::Gop { /// that layout. #[derive(uniffi::Record)] pub struct MoqVideoFrame { - /// Presentation timestamp, in microseconds. - pub timestamp_us: u64, + /// Presentation timestamp. + pub timestamp: MoqTimestamp, /// The pixels, in the configured layout. pub data: Vec, } @@ -197,8 +198,8 @@ pub struct MoqVideoFrame { /// One access unit emitted by a codec-only video encoder. #[derive(uniffi::Record)] pub struct MoqVideoPacket { - /// Presentation timestamp in microseconds. - pub timestamp_us: u64, + /// Presentation timestamp. + pub timestamp: MoqTimestamp, /// Encoded access-unit payload. pub data: Vec, /// Whether the access unit starts from a keyframe. @@ -209,7 +210,7 @@ fn video_packets(packets: Vec) -> Vec moq_video::Surface::I420(moq_video::I420::new(self.size, frame.data)?), MoqVideoPixelFormat::Rgba => moq_video::Surface::rgba(&frame.data, self.size)?, }; - let frame = moq_video::Frame::new(surface, moq_net::Timestamp::from_micros(frame.timestamp_us)?); + let frame = moq_video::Frame::new(surface, frame.timestamp.try_into()?); let mut guard = self.inner.lock().map_err(|_| panic_error())?; Ok(video_packets(block_on( guard.as_mut().ok_or(MoqError::Closed)?.encode(frame), @@ -420,7 +421,7 @@ impl VideoProducer { let Some(encoder) = self.encoder.as_mut() else { return Ok(()); }; - let frame = moq_video::Frame::new(surface, moq_net::Timestamp::from_micros(frame.timestamp_us)?); + let frame = moq_video::Frame::new(surface, frame.timestamp.try_into()?); // A backend that pipelines hands back an earlier frame's output, so this is // zero or more access units rather than one per call. let encoded = block_on(encoder.encode(frame))?; @@ -1044,10 +1045,9 @@ pub struct MoqVideoDecodedFrame { #[uniffi::export] impl MoqVideoDecodedFrame { - /// Presentation timestamp, in microseconds. - pub fn timestamp_us(&self) -> u64 { - // A decoded Timestamp is bounded by a QUIC varint, so its microseconds fit. - self.frame.timestamp.as_micros() as u64 + /// Presentation timestamp. + pub fn timestamp(&self) -> MoqTimestamp { + self.frame.timestamp.into() } /// Frame width in pixels: what the stream decoded to, since `resize` is only @@ -1111,8 +1111,8 @@ pub enum MoqVideoRead { /// Every picture from before the loss precedes it, and what follows does not continue /// what came before. Gap { - /// The furthest presentation point already read, in microseconds. - timestamp_us: u64, + /// The furthest presentation point already read. + timestamp: MoqTimestamp, /// An upper bound on how long until the next picture resumes. duration: std::time::Duration, }, @@ -1121,28 +1121,23 @@ pub enum MoqVideoRead { /// The stopped encoder's last pictures precede it; what follows comes from a fresh /// encoder. End { - /// Where the stopped encoder's media stops, in microseconds. - end_us: u64, + /// Where the stopped encoder's media stops. + end: MoqTimestamp, }, } -impl TryFrom for MoqVideoRead { - type Error = MoqError; - - fn try_from(read: moq_video::decode::Read) -> Result { - use crate::consumer::timestamp_us; - Ok(match read { +impl From for MoqVideoRead { + fn from(read: moq_video::decode::Read) -> Self { + match read { moq_video::decode::Read::Frame(frame) => Self::Frame { frame: Arc::new(MoqVideoDecodedFrame { frame }), }, moq_video::decode::Read::Gap { timestamp, duration } => Self::Gap { - timestamp_us: timestamp_us(timestamp)?, + timestamp: timestamp.into(), duration: crate::ffi::duration(duration.into()), }, - moq_video::decode::Read::End { end } => Self::End { - end_us: timestamp_us(end)?, - }, - }) + moq_video::decode::Read::End { end } => Self::End { end: end.into() }, + } } } @@ -1152,7 +1147,7 @@ struct VideoConsumerInner { impl VideoConsumerInner { async fn next(&mut self) -> Result, MoqError> { - self.consumer.read().await?.map(MoqVideoRead::try_from).transpose() + Ok(self.consumer.read().await?.map(MoqVideoRead::from)) } } @@ -1391,8 +1386,13 @@ mod finish_tests { }, ) .unwrap(); + // NTSC frame times, which no microsecond count holds exactly. + let ntsc = |i: u64| MoqTimestamp { + value: i * 1001, + scale: 30_000, + }; let picture = |i: u64| MoqVideoFrame { - timestamp_us: i * 1_001_000 / 30, + timestamp: ntsc(i), data: vec![(i * 40) as u8; (width * height * 3 / 2) as usize], }; @@ -1406,9 +1406,9 @@ mod finish_tests { packets.extend(encoder.encode(picture(3)).unwrap()); packets.extend(encoder.finish().unwrap()); - let keyframes: Vec = packets.iter().filter(|p| p.keyframe).map(|p| p.timestamp_us).collect(); + let keyframes: Vec = packets.iter().filter(|p| p.keyframe).map(|p| p.timestamp).collect(); assert_eq!(packets.len(), 4, "one access unit per picture"); - assert_eq!(keyframes, [0, 3 * 1_001_000 / 30], "keyframes at the start and the cut"); + assert_eq!(keyframes, [ntsc(0), ntsc(3)], "keyframes at the start and the cut"); assert!(packets.iter().all(|p| !p.data.is_empty()), "an empty access unit"); assert!(matches!(encoder.encode(picture(4)), Err(MoqError::Closed))); } @@ -1633,7 +1633,10 @@ mod rung_tests { fn frame(i: u64) -> MoqVideoFrame { MoqVideoFrame { - timestamp_us: i * 33_333, + timestamp: MoqTimestamp { + value: i * 33_333, + scale: 1_000_000, + }, data: vec![(i * 40) as u8; 320 * 240 * 3 / 2], } } From afd78364d4cd050cab62808f28ef3edc10c37beb Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 27 Oct 2026 17:36:24 -0700 Subject: [PATCH 03/12] feat(bindings)!: carry exact timestamps in every binding Co-Authored-By: Claude Opus 5.5 --- c/moq/test/probe.c | 6 +- cpp/moq/bench/main.cpp | 5 +- cpp/moq/test/probe.cpp | 52 +- cpp/obs/src/moq-output.cpp | 19 +- cpp/obs/src/moq-source.cpp | 30 +- cpp/obs/test/moq-audio-encoder-test.cpp | 28 +- cpp/obs/test/moq-output-test.cpp | 7 +- cpp/obs/test/moq-source-test.cpp | 69 ++- dart/moq/README.md | 4 +- dart/moq/bench/ffi.dart | 7 +- dart/moq/lib/audio.dart | 20 +- dart/moq/lib/json.dart | 8 +- dart/moq/lib/media.dart | 18 - dart/moq/lib/moq.dart | 2 +- dart/moq/lib/src/aliases.dart | 3 + dart/moq/lib/src/durations.dart | 20 - dart/moq/lib/src/timestamp.dart | 38 ++ dart/moq/lib/video.dart | 24 - dart/moq/test/docs/prelude.dart | 2 +- dart/moq/test/moq_test.dart | 130 ++++- dart/moq_ffi/lib/src/moq.dart | 498 +++++++++++------- dart/moq_ffi/test/leak_test.dart | 7 +- dart/moq_ffi/test/smoke_test.dart | 5 +- demo/carla/sim/moq_carla_sim/bridge.py | 3 +- demo/carla/sim/tests/conftest.py | 1 + demo/carla/sim/tests/test_bridge.py | 10 +- doc/lib/c/index.md | 3 +- doc/lib/cpp/index.md | 7 +- doc/lib/dart/index.md | 12 +- doc/lib/go/index.md | 15 +- doc/lib/kt/index.md | 10 +- doc/lib/py/index.md | 7 +- doc/lib/swift/index.md | 13 +- go/wrapper/README.md | 4 +- go/wrapper/audio/audio.go | 31 +- go/wrapper/bridge.go | 1 - go/wrapper/data_timestamps_test.go | 166 +++--- go/wrapper/doc.go | 2 +- go/wrapper/errors.go | 2 +- go/wrapper/example_test.go | 4 +- go/wrapper/flate/flate.go | 18 +- go/wrapper/internal/bridge/handles.go | 24 - go/wrapper/json/json.go | 54 +- go/wrapper/json/json_test.go | 9 +- go/wrapper/media/media.go | 41 +- go/wrapper/media/read_test.go | 17 +- go/wrapper/moq_test.go | 47 +- go/wrapper/publish.go | 18 +- go/wrapper/records.go | 67 +-- go/wrapper/records_internal_test.go | 46 +- go/wrapper/runtime_bench_test.go | 4 +- go/wrapper/subscribe.go | 15 +- go/wrapper/types.go | 6 +- go/wrapper/video/video.go | 54 +- kt/README.md | 6 +- .../kotlin/dev/moq/Aliases.kt | 4 +- .../kotlin/dev/moq/Durations.kt | 30 -- .../kotlin/dev/moq/Timestamp.kt | 34 ++ .../kotlin/dev/moq/audio/Audio.kt | 2 +- .../kotlin/dev/moq/json/Tracks.kt | 37 +- .../kotlin/dev/moq/media/Media.kt | 14 - .../kotlin/dev/moq/SmokeTest.kt | 86 ++- .../kotlin/dev/moq/docs/Prelude.kt | 2 +- kt/moq/src/jvmTest/kotlin/dev/moq/FfiBench.kt | 4 +- py/moq-ffi/tests/exit_inside_callback.py | 6 +- py/moq-rs/README.md | 18 +- py/moq-rs/benches/ffi.py | 5 +- py/moq-rs/docs/index.md | 3 +- py/moq-rs/examples/clock.py | 6 +- py/moq-rs/examples/serve_clock.py | 6 +- py/moq-rs/moq/__init__.py | 2 + py/moq-rs/moq/_read.py | 16 +- py/moq-rs/moq/_records.py | 68 ++- py/moq-rs/moq/audio.py | 12 +- py/moq-rs/moq/flate.py | 12 +- py/moq-rs/moq/json.py | 29 +- py/moq-rs/moq/media.py | 17 +- py/moq-rs/moq/publish.py | 7 +- py/moq-rs/moq/types.py | 2 + py/moq-rs/moq/video.py | 14 +- py/moq-rs/tests/test_data_timestamps.py | 53 +- py/moq-rs/tests/test_local.py | 112 ++-- py/moq-rs/tests/test_media_reads.py | 22 +- py/moq-rs/tests/test_server.py | 4 +- rs/moq-c/README.md | 17 +- rs/moq-c/c-tests/audio-decode-output.c | 5 +- rs/moq-c/c-tests/decode-output.c | 2 +- rs/moq-c/c-tests/timestamps.c | 154 ++++++ rs/moq-c/src/api.rs | 132 +++-- rs/moq-c/src/audio.rs | 33 +- rs/moq-c/src/consume.rs | 129 ++--- rs/moq-c/src/decode.rs | 42 +- rs/moq-c/src/ffi.rs | 10 + rs/moq-c/src/publish.rs | 26 +- rs/moq-c/src/test.rs | 422 +++++++++------ rs/moq-c/src/video.rs | 36 +- rs/moq-ffi/src/media.rs | 13 +- swift/README.md | 2 +- swift/Sources/Moq/Aliases.swift | 4 +- swift/Sources/Moq/Flate.swift | 8 +- swift/Sources/Moq/Json.swift | 30 +- swift/Sources/Moq/Media.swift | 10 +- swift/Sources/Moq/Timestamp.swift | 52 ++ swift/Sources/Moq/Track.swift | 18 +- swift/Tests/MoqTests/Docs/Prelude.swift | 2 +- swift/Tests/MoqTests/FfiBench.swift | 4 +- swift/Tests/MoqTests/SmokeTests.swift | 124 +++-- test/interop/clients/c/subscribe.c | 7 +- test/interop/clients/cpp/main.cpp | 14 +- test/interop/clients/go/main.go | 7 +- test/interop/clients/python/interop.py | 4 +- test/wasm/baseline/consumer.ts | 4 +- test/wasm/baseline/uniffi.ts | 2 +- test/wasm/uniffi/cases.ts | 30 +- 114 files changed, 2158 insertions(+), 1531 deletions(-) delete mode 100644 dart/moq/lib/src/durations.dart create mode 100644 dart/moq/lib/src/timestamp.dart delete mode 100644 kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Durations.kt create mode 100644 kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Timestamp.kt create mode 100644 rs/moq-c/c-tests/timestamps.c create mode 100644 swift/Sources/Moq/Timestamp.swift diff --git a/c/moq/test/probe.c b/c/moq/test/probe.c index 154f2a4e7d9..fd191093a0c 100644 --- a/c/moq/test/probe.c +++ b/c/moq/test/probe.c @@ -336,8 +336,8 @@ int main(void) { moq_frame frame = moq_frame_default(); frame.payload.data = hello; frame.payload.len = sizeof(hello); - frame.timestamp_us.has_value = true; - frame.timestamp_us.value = 1000; + moq_timestamp timestamp = {1000, 1000000}; + frame.timestamp = ×tamp; ok(moq_track_producer_write_frame(track, &frame), "write_frame"); moq_frame *received = await(&reading, "read_frame"); moq_task_free(task); @@ -345,7 +345,7 @@ int main(void) { CHECK(received->payload.len == sizeof(hello)); CHECK(memcmp(received->payload.data, hello, sizeof(hello)) == 0); /* The default moq-lite-06 session drops received timestamps, so the track arrives untimed. */ - CHECK(!received->timestamp_us.has_value); + CHECK(!received->timestamp); moq_frame_free(received); CHECK(!cancelled.done); diff --git a/cpp/moq/bench/main.cpp b/cpp/moq/bench/main.cpp index 66111b834ed..b89d6732897 100644 --- a/cpp/moq/bench/main.cpp +++ b/cpp/moq/bench/main.cpp @@ -84,7 +84,8 @@ Reader read(Case c, std::shared_ptr consumer, require(group != nullptr); for (int f = 0; f < c.frames(); ++f) { auto frame = ok(co_await group->read_frame()); - require(frame && frame->payload == payload && frame->timestamp_us == n * c.frames() + f); + require(frame && frame->payload == payload && frame->timestamp && + frame->timestamp->value == n * c.frames() + f); } } @@ -112,7 +113,7 @@ void throughput(Case c, double budget, std::vector &results) { for (auto &track : tracks) { auto group = ok(track->append_group()); for (int f = 0; f < c.frames(); ++f) - ok(group->write_frame({payload, n * c.frames() + f})); + ok(group->write_frame({payload, moq::Timestamp{n * c.frames() + f, 1000000}})); ok(group->finish()); } for (auto &reader : readers) { diff --git a/cpp/moq/test/probe.cpp b/cpp/moq/test/probe.cpp index fb119acc372..ea67ba68269 100644 --- a/cpp/moq/test/probe.cpp +++ b/cpp/moq/test/probe.cpp @@ -98,6 +98,41 @@ Coroutine read_one(std::shared_ptr consumer, std::optionalpublish_track("timed", timed), "publish timed track"); + auto consumer = ok(track->consume(std::nullopt), "consume timed track"); + for (uint64_t value : {0, 1}) { + ok(track->write_frame({bytes("tick"), moq::Timestamp{value, 90000}}), "write tick"); + auto frame = ok(consumer->read_frame().get(), "read tick"); + CHECK(frame && frame->timestamp); + CHECK(frame->timestamp->value == value && frame->timestamp->scale == 90000); + } + for (const moq::Timestamp &invalid : + {moq::Timestamp{0, 0}, moq::Timestamp{0, uint64_t(1) << 62}, moq::Timestamp{uint64_t(1) << 61, 90000}}) { + auto refused = track->write_frame({bytes("tick"), invalid}); + CHECK(!refused); + CHECK(std::holds_alternative(refused.error().get_variant())); + } + + auto untimed = ok(broadcast->publish_track("untimed", std::nullopt), "publish untimed track"); + auto untimed_consumer = ok(untimed->consume(std::nullopt), "consume untimed track"); + ok(untimed->write_frame({bytes("untimed"), std::nullopt}), "write untimed"); + auto frame = ok(untimed_consumer->read_frame().get(), "read untimed"); + CHECK(frame && !frame->timestamp); + ok(broadcast->close(), "close timestamp broadcast"); +} + // Exercise the installed audio publisher and consumer rather than only generated signatures. void audio_roundtrip() { auto broadcast = ok(moq::BroadcastProducer::init(), "audio broadcast"); @@ -126,7 +161,7 @@ void audio_roundtrip() { std::memcpy(data.data() + (sample * 2 + channel) * sizeof(float), &value, sizeof(value)); } } - ok(audio->write({250000 + packet * 20000, data}), "write audio"); + ok(audio->write({{250000 + packet * 20000, 1000000}, data}), "write audio"); } ok(audio->finish(), "finish audio"); size_t frames = 0; @@ -137,7 +172,7 @@ void audio_roundtrip() { CHECK(!std::holds_alternative(read->get_variant())); // The finish ends the encoder where its eight 20 ms frames stop. if (const auto *end = std::get_if(&read->get_variant())) { - CHECK(end->end_us == 250000 + 8 * 20000); + CHECK(same_time(end->end, {250000 + 8 * 20000, 1000000})); continue; } const auto *variant = std::get_if(&read->get_variant()); @@ -145,7 +180,7 @@ void audio_roundtrip() { const auto *next = &variant->frame; - CHECK(next->timestamp_us == 250000 + frames * 1000000 / 48000); + CHECK(same_time(next->timestamp, {250 * 48000 + frames * 1000, 48000000})); CHECK(next->data.size() % (2 * sizeof(float)) == 0); for (size_t sample = 0; sample < next->data.size() / (2 * sizeof(float)); sample++) { for (size_t channel = 0; channel < 2; channel++) { @@ -165,13 +200,14 @@ void audio_roundtrip() { auto power = [&](size_t tone) { return real[channel][tone] * real[channel][tone] + imag[channel][tone] * imag[channel][tone]; }; CHECK(power(channel) > power(1 - channel)); } - CHECK(!audio->write({0, std::vector(8)})); + CHECK(!audio->write({{0, 1000000}, std::vector(8)})); ok(broadcast->close(), "close audio broadcast"); } } // namespace int main() { + timestamp_roundtrip(); audio_roundtrip(); auto timebase_owner = ok(moq::BroadcastProducer::init(), "timebase owner"); auto timebase_other = ok(moq::BroadcastProducer::init(), "timebase other"); @@ -256,14 +292,14 @@ int main() { // The consumer survives the cancelled read and delivers the next frame. auto reading = consumer->read_frame(); - ok(track->write_frame({bytes("hello"), 1000}), "write_frame"); + ok(track->write_frame({bytes("hello"), moq::Timestamp{1000, 1000000}}), "write_frame"); auto frame = ok(reading.get(), "read_frame"); // get() consumed the state. CHECK(!reading.valid()); CHECK(frame.has_value()); CHECK(frame->payload == bytes("hello")); // The default moq-lite-06 session drops received timestamps, so the track arrives untimed. - CHECK(!frame->timestamp_us.has_value()); + CHECK(!frame->timestamp); // A continuation receives the next frame on the executor. { @@ -276,7 +312,7 @@ int main() { }); // then() took the future's state. CHECK(!reading_next.valid()); - ok(track->write_frame({bytes("then"), 2000}), "write_frame"); + ok(track->write_frame({bytes("then"), moq::Timestamp{2000, 1000000}}), "write_frame"); CHECK(done.wait_for(5s)); CHECK(received && received->payload == bytes("then")); } @@ -296,7 +332,7 @@ int main() { Latch done; std::optional received; auto reader = read_one(consumer, received, done); - ok(track->write_frame({bytes("co_await"), 3000}), "write_frame"); + ok(track->write_frame({bytes("co_await"), moq::Timestamp{3000, 1000000}}), "write_frame"); CHECK(done.wait_for(5s)); CHECK(received && received->payload == bytes("co_await")); (void)reader; diff --git a/cpp/obs/src/moq-output.cpp b/cpp/obs/src/moq-output.cpp index 752ea8c3775..d0cd3de0910 100644 --- a/cpp/obs/src/moq-output.cpp +++ b/cpp/obs/src/moq-output.cpp @@ -7,7 +7,6 @@ #include "moq-settings.h" #include "moq-url.h" #include "logger.h" -#include "util/util_uint64.h" #include #include @@ -604,20 +603,20 @@ void MoQOutput::Data(struct encoder_packet *packet) } // The packet's timestamp on the broadcast clock, or nothing when it falls before zero. -static std::optional PacketTimestamp(const struct encoder_packet *packet) +static std::optional PacketTimestamp(const struct encoder_packet *packet) { - // Add ~1 second offset to handle negative PTS from audio priming frames, and - // the same to video for A/V sync. - // TODO: This is slightly wrong when den is not evenly divisible by num, but close enough. - int64_t pts = packet->pts + packet->timebase_den / packet->timebase_num; - if (pts < 0) + // A tick is num/den seconds, so den units per second hold it exactly, 1001/30000 included. + // Offset by one second to cover the negative PTS of audio priming frames, and video by + // the same for A/V sync. + const int64_t value = packet->pts * packet->timebase_num + packet->timebase_den; + if (value < 0) return std::nullopt; - return util_mul_div64(pts, 1000000ULL * packet->timebase_num, packet->timebase_den); + return moq::Timestamp{static_cast(value), static_cast(packet->timebase_den)}; } -static moq::Frame PacketFrame(const struct encoder_packet *packet, uint64_t timestamp_us) +static moq::Frame PacketFrame(const struct encoder_packet *packet, const moq::Timestamp ×tamp) { - return moq::Frame{std::vector(packet->data, packet->data + packet->size), timestamp_us}; + return moq::Frame{std::vector(packet->data, packet->data + packet->size), timestamp}; } void MoQOutput::AudioData(struct encoder_packet *packet) diff --git a/cpp/obs/src/moq-source.cpp b/cpp/obs/src/moq-source.cpp index dfb5425162f..8d57cc38142 100644 --- a/cpp/obs/src/moq-source.cpp +++ b/cpp/obs/src/moq-source.cpp @@ -4,6 +4,7 @@ #include #include #include +#include #include @@ -75,6 +76,13 @@ namespace { struct moq_source; +// A track timestamp in the nanoseconds OBS stamps media with, floored when the scale does not +// divide a second evenly into nanoseconds. +static uint64_t moq_source_nanoseconds(const moq::Timestamp ×tamp) +{ + return util_mul_div64(timestamp.value, 1'000'000'000, timestamp.scale); +} + enum class Decoded { Pending, Ready, Failed }; // Full: the decoder refused the packet until its pending pictures are taken. enum class Sent { Accepted, Full, Failed }; @@ -86,7 +94,7 @@ struct VideoDecoder { SwsContext *sws_ctx = nullptr; bool got_keyframe = false; // End can precede the old encoder's final packets, whose timestamps are below it. - std::optional end_us; + std::optional end_ns; uint32_t frames_waiting_for_keyframe = 0; uint32_t consecutive_decode_errors = 0; obs_source_frame frame = {}; @@ -685,18 +693,18 @@ static void moq_source_on_frame(struct moq_source *ctx, const std::shared_ptrvideo_decoder; const auto &variant = (*result)->get_variant(); if (const auto *end = std::get_if(&variant)) { - decoder.end_us = end->end_us; + decoder.end_ns = moq_source_nanoseconds(end->end); moq_source_read_track(ctx, conn, track); return; } const auto *read = std::get_if(&variant); - if (!read || (decoder.end_us && read->frame.timestamp_us >= *decoder.end_us)) { + if (!read || (decoder.end_ns && moq_source_nanoseconds(read->frame.timestamp) >= *decoder.end_ns)) { // A gap loses references immediately. An end does so only at the fresh encoder, // after all old tail packets below its endpoint have entered the decoder. moq_source_drain_video(ctx, conn, track); avcodec_flush_buffers(decoder.codec_ctx); decoder.got_keyframe = false; - decoder.end_us.reset(); + decoder.end_ns.reset(); } if (!read) { moq_source_read_track(ctx, conn, track); @@ -771,7 +779,7 @@ static bool moq_source_on_audio_read(struct moq_source *ctx, const std::shared_p audio.format = AUDIO_FORMAT_FLOAT_PLANAR; audio.samples_per_sec = layout.sample_rate; // The same broadcast timeline video stamps, in the nanoseconds OBS expects. - audio.timestamp = frame.timestamp_us * 1000; + audio.timestamp = moq_source_nanoseconds(frame.timestamp); if (track == conn->pending_audio) conn->audio = std::move(conn->pending_audio); @@ -1062,9 +1070,9 @@ static std::unique_ptr moq_source_prepare_decoder(const moq::Video } } - // Packets carry the frame's microsecond timestamp, which the decoder hands back on the - // picture it belongs to. - decoder->codec_ctx->pkt_timebase = AVRational{1, 1'000'000}; + // Packets carry the frame's timestamp in OBS's nanoseconds, which the decoder hands back + // on the picture it belongs to. + decoder->codec_ctx->pkt_timebase = AVRational{1, 1'000'000'000}; // Open codec if (avcodec_open2(decoder->codec_ctx, codec, NULL) < 0) { @@ -1116,7 +1124,7 @@ static Sent moq_source_send_packet(VideoDecoder &decoder, const moq::MediaFrame packet->size = static_cast(frame_data.payload.size()); // The decoder hands this back on the picture it belongs to. Decode order has no // timestamp of its own here, so dts stays unset. - packet->pts = static_cast(frame_data.timestamp_us); + packet->pts = static_cast(moq_source_nanoseconds(frame_data.timestamp)); // Send packet to decoder int ret = avcodec_send_packet(decoder.codec_ctx, packet); @@ -1282,8 +1290,8 @@ static Decoded moq_source_receive_frame(VideoDecoder &decoder) return Decoded::Failed; } - // OBS expects nanoseconds; packets carry microseconds. - decoder.frame.timestamp = static_cast(frame->best_effort_timestamp) * 1000; + // Packets already carry the nanoseconds OBS expects. + decoder.frame.timestamp = static_cast(frame->best_effort_timestamp); decoder.frame.format = VIDEO_FORMAT_RGBA; av_frame_free(&frame); return Decoded::Ready; diff --git a/cpp/obs/test/moq-audio-encoder-test.cpp b/cpp/obs/test/moq-audio-encoder-test.cpp index ea229cea72b..7ebd63d8735 100644 --- a/cpp/obs/test/moq-audio-encoder-test.cpp +++ b/cpp/obs/test/moq-audio-encoder-test.cpp @@ -183,11 +183,11 @@ std::vector NoiseFrame(uint32_t &state, size_t samples) return pcm; } -// MoQOutput's conversion of an OBS packet's timestamp to the track's microseconds. -uint64_t PacketMicros(const encoder_packet &packet) +// MoQOutput's conversion of an OBS packet's timestamp to the track's. +moq::Timestamp PacketTimestamp(const encoder_packet &packet) { - const int64_t pts = packet.pts + packet.timebase_den / packet.timebase_num; - return static_cast(pts) * 1000000ULL * packet.timebase_num / packet.timebase_den; + const int64_t value = packet.pts * packet.timebase_num + packet.timebase_den; + return moq::Timestamp{static_cast(value), static_cast(packet.timebase_den)}; } // Publishes `count` tone packets from an encoder with `settings` the way MoQOutput @@ -241,8 +241,8 @@ void CheckSubscriberDecodes(const char *preset, size_t channels) const int count = 50; const int64_t start = 3 * RATE; // Where input sample `index` lands on the track: MoQOutput's one second offset on top. - auto micros = [&](int64_t index) { - return static_cast((start + RATE + index) * 1000000LL / RATE); + auto sample = [&](int64_t index) { + return static_cast(start + RATE + index); }; for (int i = 0; i < count; i++) { const int64_t pts = start + i * static_cast(encoder.frame_size); @@ -252,8 +252,8 @@ void CheckSubscriberDecodes(const char *preset, size_t channels) if (!packet) return; CHECK(packet->pts == pts && packet->dts == pts); - const uint64_t us = PacketMicros(*packet); - TestOk(track->write_frame({std::vector(packet->data, packet->data + packet->size), us}), + TestOk(track->write_frame({std::vector(packet->data, packet->data + packet->size), + PacketTimestamp(*packet)}), "write_frame"); TestOk(track->cut(), "cut"); } @@ -264,7 +264,7 @@ void CheckSubscriberDecodes(const char *preset, size_t channels) // with anything but its first input sample, shifts the phase and fails this. size_t decoded = 0; double error = 0, energy = 0; - std::optional first_decoded_us; + std::optional first_decoded; for (;;) { auto next = audio->next(); if (next.wait_for(std::chrono::seconds(10)) != std::future_status::ready) { @@ -280,11 +280,12 @@ void CheckSubscriberDecodes(const char *preset, size_t channels) if (!variant) break; const auto *frame = &variant->frame; - if (!first_decoded_us) - first_decoded_us = frame->timestamp_us; + if (!first_decoded) + first_decoded = frame->timestamp; const auto *samples = reinterpret_cast(frame->data.data()); const size_t frames = frame->data.size() / sizeof(float) / channels; - const int64_t offset = static_cast(frame->timestamp_us * RATE / 1000000ULL) - (start + RATE); + const int64_t offset = + static_cast(frame->timestamp.value * RATE / frame->timestamp.scale) - (start + RATE); for (size_t i = 0; i < frames; i++) { const double expected = Tone(offset + static_cast(i)); for (size_t c = 0; c < channels; c++) { @@ -298,7 +299,8 @@ void CheckSubscriberDecodes(const char *preset, size_t channels) // OBS never drains an audio encoder, so the decoder trims the 312-sample pre-skip // and nothing pads the tail: every input sample but that lookahead comes back. - CHECK(first_decoded_us == micros(0)); + // Compared as fractions of a second, since the track reads back at its own scale. + CHECK(first_decoded && first_decoded->value * RATE == sample(0) * first_decoded->scale); CHECK(decoded == count * encoder.frame_size - 312); CHECK(energy > 0 && error / energy < 0.05); printf(" %s, %zu channels: %zu samples, error %.4f\n", preset, channels, decoded, diff --git a/cpp/obs/test/moq-output-test.cpp b/cpp/obs/test/moq-output-test.cpp index 002164e8895..0c998599443 100644 --- a/cpp/obs/test/moq-output-test.cpp +++ b/cpp/obs/test/moq-output-test.cpp @@ -684,7 +684,8 @@ int main() // Everything up to the last frame, then the end of the track. bool ended = false; - uint64_t last_timestamp = first_frame ? first_frame->frame.timestamp_us : 0; + // Reads come back at the track's one scale, so values compare directly. + uint64_t last_timestamp = first_frame ? first_frame->frame.timestamp.value : 0; for (;;) { next = media->next(); if (next.wait_for(std::chrono::seconds(10)) != std::future_status::ready) @@ -698,10 +699,10 @@ int main() } CHECK(!std::holds_alternative((*result)->get_variant())); if (const auto *frame = std::get_if(&(*result)->get_variant())) - last_timestamp = frame->frame.timestamp_us; + last_timestamp = frame->frame.timestamp.value; } CHECK(ended); - CHECK(first_frame && last_timestamp > first_frame->frame.timestamp_us); + CHECK(first_frame && last_timestamp > first_frame->frame.timestamp.value); } } printf("stop drains the session: ok\n"); diff --git a/cpp/obs/test/moq-source-test.cpp b/cpp/obs/test/moq-source-test.cpp index 264ac02dcc6..0132a35799c 100644 --- a/cpp/obs/test/moq-source-test.cpp +++ b/cpp/obs/test/moq-source-test.cpp @@ -299,7 +299,8 @@ int g_decoded_width = 320; int g_decoded_height = 240; std::atomic g_last_decoder_extradata{-1}; std::atomic g_decoder_opens{0}; -// Only packets from the replacement use this timestamp; the old stream keeps decoding. +// Only packets from the replacement use this timestamp, in the nanoseconds packets carry; the +// old stream keeps decoding. std::atomic g_candidate_decode{0}; // 2: receive error, 3: needs more input std::atomic g_candidate_attempts{0}; // Holds packets' timestamps for reordering: each packet past the delay releases the @@ -375,7 +376,7 @@ int avcodec_send_packet(AVCodecContext *ctx, const AVPacket *packet) if (state.ready.size() >= g_decoder_capacity) return AVERROR(EAGAIN); state.last_pts = packet->pts; - if (state.last_pts == 1'000'000'000) + if (state.last_pts == 1'000'000'000'000) g_candidate_attempts++; state.held.push_back(packet->pts); if (state.held.size() > g_reorder_delay) { @@ -389,7 +390,7 @@ int avcodec_send_packet(AVCodecContext *ctx, const AVPacket *packet) int avcodec_receive_frame(AVCodecContext *ctx, AVFrame *frame) { auto &state = *static_cast(ctx->opaque); - if (state.last_pts == 1'000'000'000) { + if (state.last_pts == 1'000'000'000'000) { if (g_candidate_decode == 2) return AVERROR_INVALIDDATA; if (g_candidate_decode == 3) @@ -570,6 +571,12 @@ void report(const char *name) g_reported = g_failures; } +// A timestamp in microseconds, the scale most scenarios write at. +moq::Timestamp Micros(uint64_t us) +{ + return moq::Timestamp{us, 1'000'000}; +} + // A broadcast published on the relay, the way the MoQ output would publish it. class Publisher { public: @@ -605,9 +612,9 @@ class Publisher { { timestamp_us += 20'000; if (video) - TestOk(video->write_frame(moq::Frame{TestH264Keyframe(), timestamp_us}), "write video"); + TestOk(video->write_frame(moq::Frame{TestH264Keyframe(), Micros(timestamp_us)}), "write video"); if (audio) { - TestOk(audio->write_frame(moq::Frame{{0xfc, 0xff, 0xfe}, timestamp_us}), "write audio"); + TestOk(audio->write_frame(moq::Frame{{0xfc, 0xff, 0xfe}, Micros(timestamp_us)}), "write audio"); TestOk(audio->cut(), "cut audio"); } } @@ -762,33 +769,41 @@ int main() const auto *state = static_cast(held->video_decoder->codec_ctx->opaque); const auto pending = state->held.size(); CHECK(pending > 0); - const uint64_t end = static_cast(state->last_pts) + 1'000'000; + // The end and tail sit on a 90 kHz grid, which packets carry floored to nanoseconds. + const uint64_t end = static_cast(state->last_pts) * 9 / 100'000 + 90'000; + const auto ticks = [](uint64_t value) { + return moq::Timestamp{value, 90'000}; + }; + const auto nanos = [](uint64_t value) { + return value * 100'000 / 9; + }; auto inject = [&](moq::MediaRead read) { moq_source_on_frame(ctx, conn, held, std::optional{std::move(read)}); }; if (gap) { - inject(moq::MediaRead{moq::MediaRead::kGap{123456, std::chrono::microseconds(78901)}}); + inject(moq::MediaRead{ + moq::MediaRead::kGap{Micros(123456), std::chrono::microseconds(78901)}}); CHECK(g_output_frames == frames + static_cast(pending)); CHECK(!held->video_decoder->got_keyframe); } else { - inject(moq::MediaRead{moq::MediaRead::kEnd{end}}); + inject(moq::MediaRead{moq::MediaRead::kEnd{ticks(end)}}); CHECK(held->video_decoder->got_keyframe); // Non-key tail packets below the endpoint still depend on the old references. - inject(moq::MediaRead{ - moq::MediaRead::kFrame{moq::MediaFrame{TestH264Keyframe(), end - 1, false}}}); - CHECK(state->last_pts == static_cast(end - 1)); + inject(moq::MediaRead{moq::MediaRead::kFrame{ + moq::MediaFrame{TestH264Keyframe(), ticks(end - 1), false}}}); + CHECK(state->last_pts == static_cast(nanos(end - 1))); if (eof) { moq_source_on_frame(ctx, conn, held, std::optional{}); } else { inject(moq::MediaRead{moq::MediaRead::kFrame{ - moq::MediaFrame{TestH264Keyframe(), end, true}}}); - CHECK(state->last_pts == static_cast(end)); + moq::MediaFrame{TestH264Keyframe(), ticks(end), true}}}); + CHECK(state->last_pts == static_cast(nanos(end))); CHECK(state->held.size() == 1); } CHECK(g_output_frames == frames + static_cast(pending) + 1); std::lock_guard output_lock(g_video_mutex); CHECK(std::count(g_video_timestamps.begin(), g_video_timestamps.end(), - (end - 1) * 1000) == 1); + nanos(end - 1)) == 1); } CHECK(conn->video == held); } @@ -826,7 +841,8 @@ int main() }; for (int picture : decode_order) { const auto payload = picture == 0 ? TestH264Keyframe() : delta; - TestOk(publisher.video->write_frame(moq::Frame{payload, timestamp_us(picture)}), "write video"); + TestOk(publisher.video->write_frame(moq::Frame{payload, Micros(timestamp_us(picture))}), + "write video"); } TestOk(publisher.video->finish(), "finish video"); @@ -849,7 +865,7 @@ int main() const auto timestamp_us = [](int picture) { return 2'000'000 + uint64_t(picture) * 20'000; }; - g_unconverted_pts = int64_t(timestamp_us(2)); + g_unconverted_pts = int64_t(timestamp_us(2) * 1000); Publisher publisher(relay, "obs/test", true, false); void *source = createSource(); auto *ctx = static_cast(source); @@ -863,7 +879,8 @@ int main() std::vector expected; for (int picture = 0; picture < 6; picture++) { const auto payload = picture == 0 ? TestH264Keyframe() : delta; - TestOk(publisher.video->write_frame(moq::Frame{payload, timestamp_us(picture)}), "write video"); + TestOk(publisher.video->write_frame(moq::Frame{payload, Micros(timestamp_us(picture))}), + "write video"); expected.push_back(timestamp_us(picture) * 1000); } // Left unfinished: nothing is held back, and a finish appends an empty end-of-group frame. @@ -899,7 +916,8 @@ int main() }; CHECK(publisher.WriteUntil(pending)); // One picture, which the decoder holds until a drain. - TestOk(replacement->write_frame(moq::Frame{TestH264Keyframe(), 1'000'000'000}), "replacement frame"); + TestOk(replacement->write_frame(moq::Frame{TestH264Keyframe(), Micros(1'000'000'000)}), + "replacement frame"); TestOk(replacement->finish(), "finish replacement"); CHECK(publisher.WriteUntil([&] { return !pending(); })); const int frames = g_output_frames; @@ -926,7 +944,7 @@ int main() uint64_t samples = 0; CHECK(WaitFor([&] { for (const auto &frame : AAC_FRAMES) { - TestOk(aac->write_frame(moq::Frame{frame, 1'000'000 + samples * 1'000'000 / 44'100}), + TestOk(aac->write_frame(moq::Frame{frame, moq::Timestamp{44'100 + samples, 44'100}}), "write aac"); samples += 1024; } @@ -1078,7 +1096,7 @@ int main() const int frames = g_output_frames; CHECK(publisher.WriteUntil([&] { return g_output_frames >= frames + 10; })); CHECK(publisher.WriteUntil([&] { - TestOk(replacement->write_frame(moq::Frame{TestH264Keyframe(), 2'000'000}), + TestOk(replacement->write_frame(moq::Frame{TestH264Keyframe(), Micros(2'000'000)}), "replacement frame"); return g_last_timestamp == 2'000'000'000; })); @@ -1102,7 +1120,7 @@ int main() moq::MediaTarget::kNamed{std::string("!replacement")}, init), "replacement video"); auto write = [&] { - TestOk(replacement->write_frame(moq::Frame{TestH264Keyframe(), 1'000'000'000}), + TestOk(replacement->write_frame(moq::Frame{TestH264Keyframe(), Micros(1'000'000'000)}), "replacement frame"); }; CHECK(publisher.WriteUntil([&] { @@ -1165,7 +1183,8 @@ int main() return true; })); CHECK(publisher.WriteUntil([&] { - TestOk(replacement->write_frame(moq::Frame{BAD_OPUS, 1'000'000'000}), "replacement frame"); + TestOk(replacement->write_frame(moq::Frame{BAD_OPUS, Micros(1'000'000'000)}), + "replacement frame"); TestOk(replacement->cut(), "replacement audio cut"); std::lock_guard lock(g_candidate_mutex); return g_candidate.failed && candidate.expired(); @@ -1204,7 +1223,7 @@ int main() pending = ctx->connection->pending_audio; return pending && pending->audio_consumer; })); - TestOk(publisher.audio->write_frame(moq::Frame{BAD_OPUS, 900'000'000}), "malformed frame"); + TestOk(publisher.audio->write_frame(moq::Frame{BAD_OPUS, Micros(900'000'000)}), "malformed frame"); TestOk(publisher.audio->cut(), "malformed cut"); CHECK(WaitFor([&] { std::lock_guard lock(ctx->mutex); @@ -1217,7 +1236,7 @@ int main() pending.reset(); uint64_t timestamp_us = 1'000'000'000; CHECK(WaitFor([&] { - TestOk(replacement->write_frame(moq::Frame{{0xfc, 0xff, 0xfe}, timestamp_us}), + TestOk(replacement->write_frame(moq::Frame{{0xfc, 0xff, 0xfe}, Micros(timestamp_us)}), "replacement frame"); TestOk(replacement->cut(), "replacement audio cut"); timestamp_us += 20'000; @@ -1244,7 +1263,7 @@ int main() CHECK(active != nullptr); obs_source_audio audio = {}; moq::expected> misaligned( - moq::AudioRead::kFrame{moq::AudioFrame{1, {0, 0, 0}}}); + moq::AudioRead::kFrame{moq::AudioFrame{Micros(1), {0, 0, 0}}}); CHECK(!moq_source_on_audio_read(ctx, conn, active, misaligned, audio)); CHECK(!conn->audio); } diff --git a/dart/moq/README.md b/dart/moq/README.md index e812a8905ca..8d32100cdab 100644 --- a/dart/moq/README.md +++ b/dart/moq/README.md @@ -43,8 +43,8 @@ await for (final request in server.requests()) { The package uses `Future` for asynchronous operations and `Stream` for announcements, and `connect` / `listen` take an options struct like Rust does. Types are spelled without the `Moq` prefix (`Session`, `BroadcastProducer`, -`Backoff`), and microsecond fields read back as a `Duration` (`stats.rtt`, -`frame.timestamp`). The lower-level generated API +`Backoff`). Spans cross as a `Duration` (`stats.rtt`), and media times as an +exact `Timestamp` with `toDuration()`. The lower-level generated API remains available through the re-exported `moq_ffi` package. Flutter Web is not supported. Browser applications should use the TypeScript diff --git a/dart/moq/bench/ffi.dart b/dart/moq/bench/ffi.dart index 79a37ff4f54..1ab19d69615 100644 --- a/dart/moq/bench/ffi.dart +++ b/dart/moq/bench/ffi.dart @@ -60,7 +60,7 @@ Future throughput( final frame = await group.readFrame(); require( frame != null && - frame.timestampUs == n * c.frames + f && + frame.timestamp?.value == n * c.frames + f && frame.payload.length == payload.length && memcmp(frame.payload.address, payload.address, payload.length) == 0, @@ -78,7 +78,10 @@ Future throughput( try { for (var f = 0; f < c.frames; f++) { group.writeFrame( - frame: Frame(payload: payload, timestampUs: n * c.frames + f), + frame: Frame( + payload: payload, + timestamp: Timestamp(value: n * c.frames + f, scale: 1000000), + ), ); } group.finish(); diff --git a/dart/moq/lib/audio.dart b/dart/moq/lib/audio.dart index da95989bec5..61d75cea7de 100644 --- a/dart/moq/lib/audio.dart +++ b/dart/moq/lib/audio.dart @@ -28,7 +28,7 @@ typedef ReadFrame = FrameMoqAudioRead; /// Media after what was already read was lost; what follows does not continue it. typedef ReadGap = GapMoqAudioRead; -/// The publisher stopped its encoder; frames starting before `endUs` are its remaining media. +/// The publisher stopped its encoder; frames starting before `end` are its remaining media. typedef ReadEnd = EndMoqAudioRead; /// The PCM layout written to a [Producer]. @@ -55,23 +55,5 @@ typedef Codec = MoqAudioCodec; /// A raw PCM sample layout. typedef SampleFormat = MoqAudioSampleFormat; -/// Duration view over a PCM frame's timestamp. -extension AudioFrameDuration on MoqAudioFrame { - /// Presentation timestamp of the first sample. - Duration get timestamp => Duration(microseconds: timestampUs); -} - -/// Duration view over a gap. -extension AudioReadGapDuration on GapMoqAudioRead { - /// The furthest presentation point already read. - Duration get timestamp => Duration(microseconds: timestampUs); -} - -/// Duration view over an encoder end. -extension AudioReadEndDuration on EndMoqAudioRead { - /// Where the stopped encoder's media stops. - Duration get end => Duration(microseconds: endUs); -} - /// Input, codec settings, and publication ownership for a producer. typedef ProducerOptions = MoqAudioProducerOptions; diff --git a/dart/moq/lib/json.dart b/dart/moq/lib/json.dart index 73b62c37347..e26e0970c1c 100644 --- a/dart/moq/lib/json.dart +++ b/dart/moq/lib/json.dart @@ -39,9 +39,7 @@ typedef StreamConsumer = MoqJsonStreamConsumer; typedef StreamConfig = MoqJsonStreamConfig; /// A JSON string read from a track, with the timestamp of the frame that -/// carried it in microseconds, or null when untimed. Rounded down to a whole -/// microsecond, so a tick on a track like 90 kHz may not survive a read and -/// republish exactly. +/// carried it, or null when untimed. typedef Value = MoqJsonValue; /// Publishes a sliding window of JSON records on a track it takes over, pushed @@ -68,6 +66,6 @@ typedef WindowEventPop = PopMoqJsonWindowEvent; /// The records in `[start, end)` will never be delivered to this reader. typedef WindowEventSkip = SkipMoqJsonWindowEvent; -/// A [WindowEvent] and the timestamp of the frame that carried it, in -/// microseconds, or null when untimed. +/// A [WindowEvent] and the timestamp of the frame that carried it, or null +/// when untimed. typedef WindowTimed = MoqJsonWindowTimed; diff --git a/dart/moq/lib/media.dart b/dart/moq/lib/media.dart index b06a612436d..62a55e8ecad 100644 --- a/dart/moq/lib/media.dart +++ b/dart/moq/lib/media.dart @@ -104,21 +104,3 @@ typedef GroupConfig = MoqMediaGroupConfig; /// The packaging advertised for a media track. typedef Container = MoqContainer; - -/// Duration view over a media frame's presentation time. -extension MediaFrameDuration on MoqMediaFrame { - /// Presentation timestamp. - Duration get timestamp => Duration(microseconds: timestampUs); -} - -/// Duration view over a gap. -extension MediaReadGapDuration on GapMoqMediaRead { - /// The furthest presentation point already read. - Duration get timestamp => Duration(microseconds: timestampUs); -} - -/// Duration view over an encoder end. -extension MediaReadEndDuration on EndMoqMediaRead { - /// Where the stopped encoder's media stops. - Duration get end => Duration(microseconds: endUs); -} diff --git a/dart/moq/lib/moq.dart b/dart/moq/lib/moq.dart index 7bdaaaf25da..25bbc4f11f9 100644 --- a/dart/moq/lib/moq.dart +++ b/dart/moq/lib/moq.dart @@ -5,6 +5,6 @@ export 'package:moq_ffi/moq_ffi.dart'; export 'src/aliases.dart'; export 'src/client.dart'; -export 'src/durations.dart'; export 'src/epoch.dart'; export 'src/server.dart'; +export 'src/timestamp.dart'; diff --git a/dart/moq/lib/src/aliases.dart b/dart/moq/lib/src/aliases.dart index b4b13ca5e50..d3c0d831a92 100644 --- a/dart/moq/lib/src/aliases.dart +++ b/dart/moq/lib/src/aliases.dart @@ -123,6 +123,9 @@ typedef Datagram = MoqDatagram; /// A payload plus the timestamp it should be presented at. typedef Frame = MoqFrame; +/// An exact media time: `value` units at `scale` units per second. +typedef Timestamp = MoqTimestamp; + /// Tunes how a track subscription is delivered: priority, latency budget, ranges, and group ordering. typedef Subscription = MoqSubscription; diff --git a/dart/moq/lib/src/durations.dart b/dart/moq/lib/src/durations.dart deleted file mode 100644 index 386dd2ca476..00000000000 --- a/dart/moq/lib/src/durations.dart +++ /dev/null @@ -1,20 +0,0 @@ -import 'package:moq_ffi/moq_ffi.dart'; - -// The FFI surface carries media timestamps as microsecond integers; durations -// already cross as Dart's Duration. Read the timestamps back as a Duration. -// These are extensions, so the `*Us` fields stay available for anyone building -// a record to send back across the boundary. - -/// Duration view over a raw frame's presentation time. -extension FrameDuration on MoqFrame { - /// Presentation timestamp, or null for an untimed frame. - Duration? get timestamp => - timestampUs == null ? null : Duration(microseconds: timestampUs!); -} - -/// Duration view over a datagram's presentation time. -extension DatagramDuration on MoqDatagram { - /// Presentation timestamp, or null for an untimed datagram. - Duration? get timestamp => - timestampUs == null ? null : Duration(microseconds: timestampUs!); -} diff --git a/dart/moq/lib/src/timestamp.dart b/dart/moq/lib/src/timestamp.dart new file mode 100644 index 00000000000..14a10361bb9 --- /dev/null +++ b/dart/moq/lib/src/timestamp.dart @@ -0,0 +1,38 @@ +import 'package:moq_ffi/moq_ffi.dart'; + +final _microsPerSecond = BigInt.from(Duration.microsecondsPerSecond); + +/// Converts a [MoqTimestamp] to Dart's [Duration]. +extension TimestampDuration on MoqTimestamp { + /// This timestamp as a [Duration], rounded to the nearest microsecond. + /// + /// The timestamp itself is exact; keep it, not the duration, to republish a + /// tick such as 90 kHz. Throws a [RangeError] when the result does not fit + /// in a [Duration]. + Duration toDuration() { + // value * 10^6 can exceed 64 bits at the allowed bounds. + final units = BigInt.from(scale); + final micros = + (BigInt.from(value) * _microsPerSecond + units ~/ BigInt.two) ~/ units; + if (!micros.isValidInt) { + throw RangeError('timestamp $value/$scale s does not fit in a Duration'); + } + return Duration(microseconds: micros.toInt()); + } +} + +/// Converts a [Duration] to an exact [MoqTimestamp]. +extension DurationTimestamp on Duration { + /// This duration as an exact timestamp at microsecond scale. + /// + /// Throws an [ArgumentError] when negative. + MoqTimestamp toTimestamp() { + if (isNegative) { + throw ArgumentError.value(this, 'duration', 'must not be negative'); + } + return MoqTimestamp( + value: inMicroseconds, + scale: Duration.microsecondsPerSecond, + ); + } +} diff --git a/dart/moq/lib/video.dart b/dart/moq/lib/video.dart index b7171c06451..0c791b03a4d 100644 --- a/dart/moq/lib/video.dart +++ b/dart/moq/lib/video.dart @@ -82,30 +82,6 @@ typedef SoftwareEncoder = SoftwareMoqVideoEncoderKind; /// A specific backend by name, such as `videotoolbox`, `mediafoundation`, or `openh264`. typedef NamedEncoder = NamedMoqVideoEncoderKind; -/// Duration view over a raw picture's timestamp. -extension VideoFrameDuration on MoqVideoFrame { - /// Presentation timestamp. - Duration get timestamp => Duration(microseconds: timestampUs); -} - -/// Duration view over a decoded picture's timestamp. -extension VideoDecodedFrameDuration on MoqVideoDecodedFrame { - /// Presentation timestamp. - Duration get timestamp => Duration(microseconds: timestampUs()); -} - -/// Duration view over a gap. -extension VideoReadGapDuration on GapMoqVideoRead { - /// The furthest presentation point already read. - Duration get timestamp => Duration(microseconds: timestampUs); -} - -/// Duration view over an encoder end. -extension VideoReadEndDuration on EndMoqVideoRead { - /// Where the stopped encoder's media stops. - Duration get end => Duration(microseconds: endUs); -} - /// Input, codec settings, and publication ownership for a producer. typedef ProducerOptions = MoqVideoProducerOptions; diff --git a/dart/moq/test/docs/prelude.dart b/dart/moq/test/docs/prelude.dart index 02c1f7b750b..a76e2c48b14 100644 --- a/dart/moq/test/docs/prelude.dart +++ b/dart/moq/test/docs/prelude.dart @@ -6,4 +6,4 @@ import 'package:moq/moq.dart'; Moq get moq => throw UnimplementedError(); Uint8List get bytes => throw UnimplementedError(); Uint8List get rgba => throw UnimplementedError(); -int get pts => throw UnimplementedError(); +Timestamp get pts => throw UnimplementedError(); diff --git a/dart/moq/test/moq_test.dart b/dart/moq/test/moq_test.dart index f9b085bcbf1..b240de889f8 100644 --- a/dart/moq/test/moq_test.dart +++ b/dart/moq/test/moq_test.dart @@ -56,11 +56,14 @@ void main() { expect(() => catalog.now(), throwsA(isA())); }); - for (final timestamp in [null, 123456]) { + for (final timestamp in [ + null, + Timestamp(value: 123457, scale: 90000), + ]) { for (final mode in ['snapshot', 'stream']) { - test('flate $mode preserves timestamp $timestamp', () async { + test('flate $mode preserves timestamp ${timestamp?.value}', () async { final broadcast = BroadcastProducer(); - final info = timestamp == null ? null : TrackInfo(timescale: 1000000); + final info = timestamp == null ? null : TrackInfo(timescale: 90000); final track = broadcast.publishTrack(name: 'data', info: info); final consumer = track.consume(subscription: null); final payload = utf8.encode('payload'); @@ -70,7 +73,7 @@ void main() { track: track, config: moq_flate.Config(), ); - producer.update(payload: payload, timestampUs: timestamp); + producer.update(payload: payload, timestamp: timestamp); producer.finish(); } else { final producer = moq_flate.StreamProducer( @@ -78,12 +81,13 @@ void main() { track: track, config: moq_flate.Config(), ); - producer.append(payload: payload, timestampUs: timestamp); + producer.append(payload: payload, timestamp: timestamp); producer.finish(); } final frame = await consumer.readFrame().timeout(timeout); expect(frame?.payload, payload); - expect(frame?.timestampUs, timestamp); + expect(frame?.timestamp?.value, timestamp?.value); + expect(frame?.timestamp?.scale, timestamp?.scale); broadcast.close(); }); } @@ -95,7 +99,7 @@ void main() { final consumer = track.consume(subscription: null); track.writeFrame(frame: Frame(payload: utf8.encode('payload'))); final frame = await consumer.readFrame().timeout(timeout); - expect(frame?.timestampUs, isNull); + expect(frame?.timestamp, isNull); expect(consumer.info().timescale, isNull); track.finish(); broadcast.close(); @@ -124,7 +128,10 @@ void main() { for (var ms = 0; ms < 3; ms++) { final group = track.appendGroup(); group.writeFrame( - frame: Frame(payload: utf8.encode('x'), timestampUs: ms * 1000), + frame: Frame( + payload: utf8.encode('x'), + timestamp: Duration(milliseconds: ms).toTimestamp(), + ), ); group.finish(); } @@ -267,7 +274,10 @@ void main() { final producer = track.appendGroup(); producer.writeFrame( - frame: MoqFrame(payload: utf8.encode('dart round trip'), timestampUs: 0), + frame: MoqFrame( + payload: utf8.encode('dart round trip'), + timestamp: Duration.zero.toTimestamp(), + ), ); producer.finish(); @@ -416,14 +426,59 @@ void main() { expect(() => catalog.finish(), throwsA(isA())); }); - test('microsecond timestamps read back as Durations', () { + test('timestamps round-trip exactly at the track scale', () async { + final broadcast = BroadcastProducer(); + final track = broadcast.publishTrack( + name: 'video', + info: TrackInfo(timescale: 90000), + ); + final consumer = track.consume(subscription: null); + // A present zero stays present, and one 90 kHz tick reads back as itself + // rather than the 11 us a microsecond field floors it to. + for (final value in [0, 1]) { + track.writeFrame( + frame: Frame( + payload: utf8.encode('frame'), + timestamp: Timestamp(value: value, scale: 90000), + ), + ); + final frame = await consumer.readFrame().timeout(timeout); + expect(frame?.timestamp?.value, value); + expect(frame?.timestamp?.scale, 90000); + } + + for (final invalid in [ + Timestamp(value: 0, scale: 0), + Timestamp(value: 0, scale: 1 << 62), + Timestamp(value: 1 << 61, scale: 90000), + ]) { + expect( + () => track.writeFrame( + frame: Frame(payload: utf8.encode('frame'), timestamp: invalid), + ), + throwsA(isA()), + ); + } + track.finish(); + broadcast.close(); + }); + + test('timestamps convert to and from Durations', () { + final exact = const Duration(milliseconds: 20).toTimestamp(); + expect([exact.value, exact.scale], [20000, 1000000]); + expect(exact.toDuration(), const Duration(milliseconds: 20)); + // 5 ticks at 90 kHz is 55.6 us: rounded to nearest, not floored. expect( - Frame(payload: Uint8List(0), timestampUs: 20000).timestamp, - const Duration(milliseconds: 20), + Timestamp(value: 5, scale: 90000).toDuration(), + const Duration(microseconds: 56), ); expect( - moq_video.Frame(timestampUs: 33333, data: Uint8List(0)).timestamp, - const Duration(microseconds: 33333), + () => Timestamp(value: (1 << 61) - 1, scale: 1).toDuration(), + throwsRangeError, + ); + expect( + () => const Duration(microseconds: -1).toTimestamp(), + throwsArgumentError, ); }); @@ -528,18 +583,21 @@ void main() { ); for (var n = 1; n <= 4; n++) { - producer.update(value: jsonEncode({'n': n}), timestampUs: n * 1000); + producer.update( + value: jsonEncode({'n': n}), + timestamp: Duration(milliseconds: n).toTimestamp(), + ); } // next() yields every state in order; latest() skips the buffered third. moq_json.Value? value = await consumer.next().timeout(timeout); expect(jsonDecode(value!.value), {'n': 1}); - expect(value.timestampUs, 1000); + expect(value.timestamp?.toDuration(), const Duration(milliseconds: 1)); value = await consumer.next().timeout(timeout); expect(jsonDecode(value!.value), {'n': 2}); value = await consumer.latest().timeout(timeout); expect(jsonDecode(value!.value), {'n': 4}); - expect(value.timestampUs, 4000); + expect(value.timestamp?.toDuration(), const Duration(milliseconds: 4)); consumer.cancel(); producer.finish(); @@ -565,29 +623,38 @@ void main() { ); for (var n = 0; n < 3; n++) { - producer.push(value: jsonEncode({'n': n}), timestampUs: n * 1000); + producer.push( + value: jsonEncode({'n': n}), + timestamp: Duration(milliseconds: n).toTimestamp(), + ); } - producer.pop(count: 2, timestampUs: 3000); + producer.pop( + count: 2, + timestamp: const Duration(milliseconds: 3).toTimestamp(), + ); for (var n = 0; n < 3; n++) { final timed = await consumer.next().timeout(timeout); final push = timed!.event as moq_json.WindowEventPush; expect(push.index, n); expect(jsonDecode(push.value), {'n': n}); - expect(timed.timestampUs, n * 1000); + expect(timed.timestamp?.toDuration(), Duration(milliseconds: n)); } final timed = await consumer.next().timeout(timeout); final pop = timed!.event as moq_json.WindowEventPop; expect([pop.start, pop.end], [0, 2]); - expect(timed.timestampUs, 3000); + expect(timed.timestamp?.toDuration(), const Duration(milliseconds: 3)); // The cut's new group restates record 2, which this reader already has. producer.cut(); - producer.push(value: jsonEncode({'n': 3}), timestampUs: 4000); + producer.push( + value: jsonEncode({'n': 3}), + timestamp: const Duration(milliseconds: 4).toTimestamp(), + ); final pushed = await consumer.next().timeout(timeout); final push = pushed!.event as moq_json.WindowEventPush; expect(push.index, 3); - expect(pushed.timestampUs, 4000); + expect(pushed.timestamp?.toDuration(), const Duration(milliseconds: 4)); producer.finish(); expect(await consumer.next().timeout(timeout), isNull); @@ -619,7 +686,10 @@ void main() { video.cut(); for (var i = 0; i < 10; i++) { video.write( - frame: moq_video.Frame(timestampUs: i * 33333, data: rgba), + frame: moq_video.Frame( + timestamp: Timestamp(value: i * 3003, scale: 90000), + data: rgba, + ), ); } @@ -638,7 +708,10 @@ void main() { // Keep the encoder fed so the decoder sees frames after it joined. for (var i = 10; i < 40; i++) { video.write( - frame: moq_video.Frame(timestampUs: i * 33333, data: rgba), + frame: moq_video.Frame( + timestamp: Timestamp(value: i * 3003, scale: 90000), + data: rgba, + ), ); } @@ -709,7 +782,7 @@ void main() { for (var i = 0; i < 2; i++) { audio.write( frame: moq_audio.Frame( - timestampUs: i * 20000, + timestamp: Duration(milliseconds: i * 20).toTimestamp(), data: Uint8List(960 * 4), ), ); @@ -745,7 +818,10 @@ void main() { ), ); producer.write( - frame: moq_audio.Frame(timestampUs: 0, data: Uint8List(960 * 4)), + frame: moq_audio.Frame( + timestamp: Duration.zero.toTimestamp(), + data: Uint8List(960 * 4), + ), ); expect(producer.demand().name(), 'mic'); producer.finish(); diff --git a/dart/moq_ffi/lib/src/moq.dart b/dart/moq_ffi/lib/src/moq.dart index 1729c8a4564..769d0588685 100644 --- a/dart/moq_ffi/lib/src/moq.dart +++ b/dart/moq_ffi/lib/src/moq.dart @@ -8,7 +8,9 @@ import "dart:ffi"; import "dart:io" show Platform, File, Directory; import "dart:isolate"; import "dart:typed_data"; + import "package:ffi/ffi.dart"; + import "uniffi_runtime.dart"; export "uniffi_runtime.dart"; @@ -368,9 +370,9 @@ class FfiConverterMoqAudioEncoderOutput { } class MoqAudioFrame { - final int timestampUs; + final MoqTimestamp timestamp; final Uint8List data; - MoqAudioFrame({required this.timestampUs, required this.data}); + MoqAudioFrame({required this.timestamp, required this.data}); } class FfiConverterMoqAudioFrame { @@ -380,25 +382,25 @@ class FfiConverterMoqAudioFrame { static LiftRetVal read(Uint8List buf) { int new_offset = buf.offsetInBytes; - final timestampUs_lifted = FfiConverterUInt64.read( + final timestamp_lifted = FfiConverterMoqTimestamp.read( Uint8List.view(buf.buffer, new_offset), ); - final timestampUs = timestampUs_lifted.value; - new_offset += timestampUs_lifted.bytesRead; + final timestamp = timestamp_lifted.value; + new_offset += timestamp_lifted.bytesRead; final data_lifted = FfiConverterUint8List.read( Uint8List.view(buf.buffer, new_offset), ); final data = data_lifted.value; new_offset += data_lifted.bytesRead; return LiftRetVal( - MoqAudioFrame(timestampUs: timestampUs, data: data), + MoqAudioFrame(timestamp: timestamp, data: data), new_offset - buf.offsetInBytes, ); } static RustBuffer lower(MoqAudioFrame value) { final total_length = - FfiConverterUInt64.allocationSize(value.timestampUs) + + FfiConverterMoqTimestamp.allocationSize(value.timestamp) + FfiConverterUint8List.allocationSize(value.data) + 0; final buf = Uint8List(total_length); @@ -408,8 +410,8 @@ class FfiConverterMoqAudioFrame { static int write(MoqAudioFrame value, Uint8List buf) { int new_offset = buf.offsetInBytes; - new_offset += FfiConverterUInt64.write( - value.timestampUs, + new_offset += FfiConverterMoqTimestamp.write( + value.timestamp, Uint8List.view(buf.buffer, new_offset), ); new_offset += FfiConverterUint8List.write( @@ -420,7 +422,7 @@ class FfiConverterMoqAudioFrame { } static int allocationSize(MoqAudioFrame value) { - return FfiConverterUInt64.allocationSize(value.timestampUs) + + return FfiConverterMoqTimestamp.allocationSize(value.timestamp) + FfiConverterUint8List.allocationSize(value.data) + 0; } @@ -1102,8 +1104,8 @@ class FfiConverterMoqJsonStreamConfig { class MoqJsonValue { final String value; - final int? timestampUs; - MoqJsonValue({required this.value, this.timestampUs}); + final MoqTimestamp? timestamp; + MoqJsonValue({required this.value, this.timestamp}); } class FfiConverterMoqJsonValue { @@ -1118,13 +1120,13 @@ class FfiConverterMoqJsonValue { ); final value = value_lifted.value; new_offset += value_lifted.bytesRead; - final timestampUs_lifted = FfiConverterOptionalUInt64.read( + final timestamp_lifted = FfiConverterOptionalMoqTimestamp.read( Uint8List.view(buf.buffer, new_offset), ); - final timestampUs = timestampUs_lifted.value; - new_offset += timestampUs_lifted.bytesRead; + final timestamp = timestamp_lifted.value; + new_offset += timestamp_lifted.bytesRead; return LiftRetVal( - MoqJsonValue(value: value, timestampUs: timestampUs), + MoqJsonValue(value: value, timestamp: timestamp), new_offset - buf.offsetInBytes, ); } @@ -1132,7 +1134,7 @@ class FfiConverterMoqJsonValue { static RustBuffer lower(MoqJsonValue value) { final total_length = FfiConverterString.allocationSize(value.value) + - FfiConverterOptionalUInt64.allocationSize(value.timestampUs) + + FfiConverterOptionalMoqTimestamp.allocationSize(value.timestamp) + 0; final buf = Uint8List(total_length); write(value, buf); @@ -1145,8 +1147,8 @@ class FfiConverterMoqJsonValue { value.value, Uint8List.view(buf.buffer, new_offset), ); - new_offset += FfiConverterOptionalUInt64.write( - value.timestampUs, + new_offset += FfiConverterOptionalMoqTimestamp.write( + value.timestamp, Uint8List.view(buf.buffer, new_offset), ); return new_offset - buf.offsetInBytes; @@ -1154,7 +1156,7 @@ class FfiConverterMoqJsonValue { static int allocationSize(MoqJsonValue value) { return FfiConverterString.allocationSize(value.value) + - FfiConverterOptionalUInt64.allocationSize(value.timestampUs) + + FfiConverterOptionalMoqTimestamp.allocationSize(value.timestamp) + 0; } } @@ -1226,8 +1228,8 @@ class FfiConverterMoqJsonWindowConfig { class MoqJsonWindowTimed { final MoqJsonWindowEvent event; - final int? timestampUs; - MoqJsonWindowTimed({required this.event, this.timestampUs}); + final MoqTimestamp? timestamp; + MoqJsonWindowTimed({required this.event, this.timestamp}); } class FfiConverterMoqJsonWindowTimed { @@ -1242,13 +1244,13 @@ class FfiConverterMoqJsonWindowTimed { ); final event = event_lifted.value; new_offset += event_lifted.bytesRead; - final timestampUs_lifted = FfiConverterOptionalUInt64.read( + final timestamp_lifted = FfiConverterOptionalMoqTimestamp.read( Uint8List.view(buf.buffer, new_offset), ); - final timestampUs = timestampUs_lifted.value; - new_offset += timestampUs_lifted.bytesRead; + final timestamp = timestamp_lifted.value; + new_offset += timestamp_lifted.bytesRead; return LiftRetVal( - MoqJsonWindowTimed(event: event, timestampUs: timestampUs), + MoqJsonWindowTimed(event: event, timestamp: timestamp), new_offset - buf.offsetInBytes, ); } @@ -1256,7 +1258,7 @@ class FfiConverterMoqJsonWindowTimed { static RustBuffer lower(MoqJsonWindowTimed value) { final total_length = FfiConverterMoqJsonWindowEvent.allocationSize(value.event) + - FfiConverterOptionalUInt64.allocationSize(value.timestampUs) + + FfiConverterOptionalMoqTimestamp.allocationSize(value.timestamp) + 0; final buf = Uint8List(total_length); write(value, buf); @@ -1269,8 +1271,8 @@ class FfiConverterMoqJsonWindowTimed { value.event, Uint8List.view(buf.buffer, new_offset), ); - new_offset += FfiConverterOptionalUInt64.write( - value.timestampUs, + new_offset += FfiConverterOptionalMoqTimestamp.write( + value.timestamp, Uint8List.view(buf.buffer, new_offset), ); return new_offset - buf.offsetInBytes; @@ -1278,7 +1280,7 @@ class FfiConverterMoqJsonWindowTimed { static int allocationSize(MoqJsonWindowTimed value) { return FfiConverterMoqJsonWindowEvent.allocationSize(value.event) + - FfiConverterOptionalUInt64.allocationSize(value.timestampUs) + + FfiConverterOptionalMoqTimestamp.allocationSize(value.timestamp) + 0; } } @@ -1757,11 +1759,11 @@ class FfiConverterMoqContainerInit { class MoqDatagram { final int sequence; - final int? timestampUs; + final MoqTimestamp? timestamp; final Uint8List payload; MoqDatagram({ this.sequence = 0, - this.timestampUs = null, + this.timestamp = null, required this.payload, }); } @@ -1778,22 +1780,18 @@ class FfiConverterMoqDatagram { ); final sequence = sequence_lifted.value; new_offset += sequence_lifted.bytesRead; - final timestampUs_lifted = FfiConverterOptionalUInt64.read( + final timestamp_lifted = FfiConverterOptionalMoqTimestamp.read( Uint8List.view(buf.buffer, new_offset), ); - final timestampUs = timestampUs_lifted.value; - new_offset += timestampUs_lifted.bytesRead; + final timestamp = timestamp_lifted.value; + new_offset += timestamp_lifted.bytesRead; final payload_lifted = FfiConverterUint8List.read( Uint8List.view(buf.buffer, new_offset), ); final payload = payload_lifted.value; new_offset += payload_lifted.bytesRead; return LiftRetVal( - MoqDatagram( - sequence: sequence, - timestampUs: timestampUs, - payload: payload, - ), + MoqDatagram(sequence: sequence, timestamp: timestamp, payload: payload), new_offset - buf.offsetInBytes, ); } @@ -1801,7 +1799,7 @@ class FfiConverterMoqDatagram { static RustBuffer lower(MoqDatagram value) { final total_length = FfiConverterUInt64.allocationSize(value.sequence) + - FfiConverterOptionalUInt64.allocationSize(value.timestampUs) + + FfiConverterOptionalMoqTimestamp.allocationSize(value.timestamp) + FfiConverterUint8List.allocationSize(value.payload) + 0; final buf = Uint8List(total_length); @@ -1815,8 +1813,8 @@ class FfiConverterMoqDatagram { value.sequence, Uint8List.view(buf.buffer, new_offset), ); - new_offset += FfiConverterOptionalUInt64.write( - value.timestampUs, + new_offset += FfiConverterOptionalMoqTimestamp.write( + value.timestamp, Uint8List.view(buf.buffer, new_offset), ); new_offset += FfiConverterUint8List.write( @@ -1828,7 +1826,7 @@ class FfiConverterMoqDatagram { static int allocationSize(MoqDatagram value) { return FfiConverterUInt64.allocationSize(value.sequence) + - FfiConverterOptionalUInt64.allocationSize(value.timestampUs) + + FfiConverterOptionalMoqTimestamp.allocationSize(value.timestamp) + FfiConverterUint8List.allocationSize(value.payload) + 0; } @@ -1895,8 +1893,8 @@ class FfiConverterMoqDimensions { class MoqFrame { final Uint8List payload; - final int? timestampUs; - MoqFrame({required this.payload, this.timestampUs = null}); + final MoqTimestamp? timestamp; + MoqFrame({required this.payload, this.timestamp = null}); } class FfiConverterMoqFrame { @@ -1911,13 +1909,13 @@ class FfiConverterMoqFrame { ); final payload = payload_lifted.value; new_offset += payload_lifted.bytesRead; - final timestampUs_lifted = FfiConverterOptionalUInt64.read( + final timestamp_lifted = FfiConverterOptionalMoqTimestamp.read( Uint8List.view(buf.buffer, new_offset), ); - final timestampUs = timestampUs_lifted.value; - new_offset += timestampUs_lifted.bytesRead; + final timestamp = timestamp_lifted.value; + new_offset += timestamp_lifted.bytesRead; return LiftRetVal( - MoqFrame(payload: payload, timestampUs: timestampUs), + MoqFrame(payload: payload, timestamp: timestamp), new_offset - buf.offsetInBytes, ); } @@ -1925,7 +1923,7 @@ class FfiConverterMoqFrame { static RustBuffer lower(MoqFrame value) { final total_length = FfiConverterUint8List.allocationSize(value.payload) + - FfiConverterOptionalUInt64.allocationSize(value.timestampUs) + + FfiConverterOptionalMoqTimestamp.allocationSize(value.timestamp) + 0; final buf = Uint8List(total_length); write(value, buf); @@ -1938,8 +1936,8 @@ class FfiConverterMoqFrame { value.payload, Uint8List.view(buf.buffer, new_offset), ); - new_offset += FfiConverterOptionalUInt64.write( - value.timestampUs, + new_offset += FfiConverterOptionalMoqTimestamp.write( + value.timestamp, Uint8List.view(buf.buffer, new_offset), ); return new_offset - buf.offsetInBytes; @@ -1947,18 +1945,18 @@ class FfiConverterMoqFrame { static int allocationSize(MoqFrame value) { return FfiConverterUint8List.allocationSize(value.payload) + - FfiConverterOptionalUInt64.allocationSize(value.timestampUs) + + FfiConverterOptionalMoqTimestamp.allocationSize(value.timestamp) + 0; } } class MoqMediaFrame { final Uint8List payload; - final int timestampUs; + final MoqTimestamp timestamp; final bool keyframe; MoqMediaFrame({ required this.payload, - required this.timestampUs, + required this.timestamp, required this.keyframe, }); } @@ -1975,22 +1973,18 @@ class FfiConverterMoqMediaFrame { ); final payload = payload_lifted.value; new_offset += payload_lifted.bytesRead; - final timestampUs_lifted = FfiConverterUInt64.read( + final timestamp_lifted = FfiConverterMoqTimestamp.read( Uint8List.view(buf.buffer, new_offset), ); - final timestampUs = timestampUs_lifted.value; - new_offset += timestampUs_lifted.bytesRead; + final timestamp = timestamp_lifted.value; + new_offset += timestamp_lifted.bytesRead; final keyframe_lifted = FfiConverterBool.read( Uint8List.view(buf.buffer, new_offset), ); final keyframe = keyframe_lifted.value; new_offset += keyframe_lifted.bytesRead; return LiftRetVal( - MoqMediaFrame( - payload: payload, - timestampUs: timestampUs, - keyframe: keyframe, - ), + MoqMediaFrame(payload: payload, timestamp: timestamp, keyframe: keyframe), new_offset - buf.offsetInBytes, ); } @@ -1998,7 +1992,7 @@ class FfiConverterMoqMediaFrame { static RustBuffer lower(MoqMediaFrame value) { final total_length = FfiConverterUint8List.allocationSize(value.payload) + - FfiConverterUInt64.allocationSize(value.timestampUs) + + FfiConverterMoqTimestamp.allocationSize(value.timestamp) + FfiConverterBool.allocationSize(value.keyframe) + 0; final buf = Uint8List(total_length); @@ -2012,8 +2006,8 @@ class FfiConverterMoqMediaFrame { value.payload, Uint8List.view(buf.buffer, new_offset), ); - new_offset += FfiConverterUInt64.write( - value.timestampUs, + new_offset += FfiConverterMoqTimestamp.write( + value.timestamp, Uint8List.view(buf.buffer, new_offset), ); new_offset += FfiConverterBool.write( @@ -2025,7 +2019,7 @@ class FfiConverterMoqMediaFrame { static int allocationSize(MoqMediaFrame value) { return FfiConverterUint8List.allocationSize(value.payload) + - FfiConverterUInt64.allocationSize(value.timestampUs) + + FfiConverterMoqTimestamp.allocationSize(value.timestamp) + FfiConverterBool.allocationSize(value.keyframe) + 0; } @@ -2169,6 +2163,65 @@ class FfiConverterMoqMediaTrackConfig { } } +class MoqTimestamp { + final int value; + final int scale; + MoqTimestamp({required this.value, required this.scale}); +} + +class FfiConverterMoqTimestamp { + static MoqTimestamp lift(RustBuffer buf) { + return FfiConverterMoqTimestamp.read(buf.asUint8List()).value; + } + + static LiftRetVal read(Uint8List buf) { + int new_offset = buf.offsetInBytes; + final value_lifted = FfiConverterUInt64.read( + Uint8List.view(buf.buffer, new_offset), + ); + final value = value_lifted.value; + new_offset += value_lifted.bytesRead; + final scale_lifted = FfiConverterUInt64.read( + Uint8List.view(buf.buffer, new_offset), + ); + final scale = scale_lifted.value; + new_offset += scale_lifted.bytesRead; + return LiftRetVal( + MoqTimestamp(value: value, scale: scale), + new_offset - buf.offsetInBytes, + ); + } + + static RustBuffer lower(MoqTimestamp value) { + final total_length = + FfiConverterUInt64.allocationSize(value.value) + + FfiConverterUInt64.allocationSize(value.scale) + + 0; + final buf = Uint8List(total_length); + write(value, buf); + return toRustBuffer(buf); + } + + static int write(MoqTimestamp value, Uint8List buf) { + int new_offset = buf.offsetInBytes; + new_offset += FfiConverterUInt64.write( + value.value, + Uint8List.view(buf.buffer, new_offset), + ); + new_offset += FfiConverterUInt64.write( + value.scale, + Uint8List.view(buf.buffer, new_offset), + ); + return new_offset - buf.offsetInBytes; + } + + static int allocationSize(MoqTimestamp value) { + return FfiConverterUInt64.allocationSize(value.value) + + FfiConverterUInt64.allocationSize(value.scale) + + 0; + } +} + class MoqVideo { final String? label; final String? broadcast; @@ -4524,9 +4577,9 @@ class FfiConverterMoqVideoEncoderOutput { } class MoqVideoFrame { - final int timestampUs; + final MoqTimestamp timestamp; final Uint8List data; - MoqVideoFrame({required this.timestampUs, required this.data}); + MoqVideoFrame({required this.timestamp, required this.data}); } class FfiConverterMoqVideoFrame { @@ -4536,25 +4589,25 @@ class FfiConverterMoqVideoFrame { static LiftRetVal read(Uint8List buf) { int new_offset = buf.offsetInBytes; - final timestampUs_lifted = FfiConverterUInt64.read( + final timestamp_lifted = FfiConverterMoqTimestamp.read( Uint8List.view(buf.buffer, new_offset), ); - final timestampUs = timestampUs_lifted.value; - new_offset += timestampUs_lifted.bytesRead; + final timestamp = timestamp_lifted.value; + new_offset += timestamp_lifted.bytesRead; final data_lifted = FfiConverterUint8List.read( Uint8List.view(buf.buffer, new_offset), ); final data = data_lifted.value; new_offset += data_lifted.bytesRead; return LiftRetVal( - MoqVideoFrame(timestampUs: timestampUs, data: data), + MoqVideoFrame(timestamp: timestamp, data: data), new_offset - buf.offsetInBytes, ); } static RustBuffer lower(MoqVideoFrame value) { final total_length = - FfiConverterUInt64.allocationSize(value.timestampUs) + + FfiConverterMoqTimestamp.allocationSize(value.timestamp) + FfiConverterUint8List.allocationSize(value.data) + 0; final buf = Uint8List(total_length); @@ -4564,8 +4617,8 @@ class FfiConverterMoqVideoFrame { static int write(MoqVideoFrame value, Uint8List buf) { int new_offset = buf.offsetInBytes; - new_offset += FfiConverterUInt64.write( - value.timestampUs, + new_offset += FfiConverterMoqTimestamp.write( + value.timestamp, Uint8List.view(buf.buffer, new_offset), ); new_offset += FfiConverterUint8List.write( @@ -4576,7 +4629,7 @@ class FfiConverterMoqVideoFrame { } static int allocationSize(MoqVideoFrame value) { - return FfiConverterUInt64.allocationSize(value.timestampUs) + + return FfiConverterMoqTimestamp.allocationSize(value.timestamp) + FfiConverterUint8List.allocationSize(value.data) + 0; } @@ -4642,11 +4695,11 @@ class FfiConverterMoqVideoFrameRate { } class MoqVideoPacket { - final int timestampUs; + final MoqTimestamp timestamp; final Uint8List data; final bool keyframe; MoqVideoPacket({ - required this.timestampUs, + required this.timestamp, required this.data, required this.keyframe, }); @@ -4659,11 +4712,11 @@ class FfiConverterMoqVideoPacket { static LiftRetVal read(Uint8List buf) { int new_offset = buf.offsetInBytes; - final timestampUs_lifted = FfiConverterUInt64.read( + final timestamp_lifted = FfiConverterMoqTimestamp.read( Uint8List.view(buf.buffer, new_offset), ); - final timestampUs = timestampUs_lifted.value; - new_offset += timestampUs_lifted.bytesRead; + final timestamp = timestamp_lifted.value; + new_offset += timestamp_lifted.bytesRead; final data_lifted = FfiConverterUint8List.read( Uint8List.view(buf.buffer, new_offset), ); @@ -4675,14 +4728,14 @@ class FfiConverterMoqVideoPacket { final keyframe = keyframe_lifted.value; new_offset += keyframe_lifted.bytesRead; return LiftRetVal( - MoqVideoPacket(timestampUs: timestampUs, data: data, keyframe: keyframe), + MoqVideoPacket(timestamp: timestamp, data: data, keyframe: keyframe), new_offset - buf.offsetInBytes, ); } static RustBuffer lower(MoqVideoPacket value) { final total_length = - FfiConverterUInt64.allocationSize(value.timestampUs) + + FfiConverterMoqTimestamp.allocationSize(value.timestamp) + FfiConverterUint8List.allocationSize(value.data) + FfiConverterBool.allocationSize(value.keyframe) + 0; @@ -4693,8 +4746,8 @@ class FfiConverterMoqVideoPacket { static int write(MoqVideoPacket value, Uint8List buf) { int new_offset = buf.offsetInBytes; - new_offset += FfiConverterUInt64.write( - value.timestampUs, + new_offset += FfiConverterMoqTimestamp.write( + value.timestamp, Uint8List.view(buf.buffer, new_offset), ); new_offset += FfiConverterUint8List.write( @@ -4709,7 +4762,7 @@ class FfiConverterMoqVideoPacket { } static int allocationSize(MoqVideoPacket value) { - return FfiConverterUInt64.allocationSize(value.timestampUs) + + return FfiConverterMoqTimestamp.allocationSize(value.timestamp) + FfiConverterUint8List.allocationSize(value.data) + FfiConverterBool.allocationSize(value.keyframe) + 0; @@ -4916,26 +4969,26 @@ class FrameMoqAudioRead extends MoqAudioRead { } class GapMoqAudioRead extends MoqAudioRead { - final int timestampUs; + final MoqTimestamp timestamp; final Duration duration; GapMoqAudioRead({ - required int this.timestampUs, + required MoqTimestamp this.timestamp, required Duration this.duration, }); - GapMoqAudioRead._(int this.timestampUs, Duration this.duration); + GapMoqAudioRead._(MoqTimestamp this.timestamp, Duration this.duration); static LiftRetVal read(Uint8List buf) { int new_offset = buf.offsetInBytes; - final timestampUs_lifted = FfiConverterUInt64.read( + final timestamp_lifted = FfiConverterMoqTimestamp.read( Uint8List.view(buf.buffer, new_offset), ); - final timestampUs = timestampUs_lifted.value; - new_offset += timestampUs_lifted.bytesRead; + final timestamp = timestamp_lifted.value; + new_offset += timestamp_lifted.bytesRead; final duration_lifted = FfiConverterDuration.read( Uint8List.view(buf.buffer, new_offset), ); final duration = duration_lifted.value; new_offset += duration_lifted.bytesRead; - return LiftRetVal(GapMoqAudioRead._(timestampUs, duration), new_offset); + return LiftRetVal(GapMoqAudioRead._(timestamp, duration), new_offset); } @override @@ -4947,7 +5000,7 @@ class GapMoqAudioRead extends MoqAudioRead { @override int allocationSize() { - return FfiConverterUInt64.allocationSize(timestampUs) + + return FfiConverterMoqTimestamp.allocationSize(timestamp) + FfiConverterDuration.allocationSize(duration) + 4; } @@ -4956,8 +5009,8 @@ class GapMoqAudioRead extends MoqAudioRead { int write(Uint8List buf) { buf.buffer.asByteData(buf.offsetInBytes).setInt32(0, 2); int new_offset = buf.offsetInBytes + 4; - new_offset += FfiConverterUInt64.write( - timestampUs, + new_offset += FfiConverterMoqTimestamp.write( + timestamp, Uint8List.view(buf.buffer, new_offset), ); new_offset += FfiConverterDuration.write( @@ -4969,17 +5022,17 @@ class GapMoqAudioRead extends MoqAudioRead { } class EndMoqAudioRead extends MoqAudioRead { - final int endUs; - EndMoqAudioRead(int this.endUs); - EndMoqAudioRead._(int this.endUs); + final MoqTimestamp end; + EndMoqAudioRead(MoqTimestamp this.end); + EndMoqAudioRead._(MoqTimestamp this.end); static LiftRetVal read(Uint8List buf) { int new_offset = buf.offsetInBytes; - final endUs_lifted = FfiConverterUInt64.read( + final end_lifted = FfiConverterMoqTimestamp.read( Uint8List.view(buf.buffer, new_offset), ); - final endUs = endUs_lifted.value; - new_offset += endUs_lifted.bytesRead; - return LiftRetVal(EndMoqAudioRead._(endUs), new_offset); + final end = end_lifted.value; + new_offset += end_lifted.bytesRead; + return LiftRetVal(EndMoqAudioRead._(end), new_offset); } @override @@ -4991,15 +5044,15 @@ class EndMoqAudioRead extends MoqAudioRead { @override int allocationSize() { - return FfiConverterUInt64.allocationSize(endUs) + 4; + return FfiConverterMoqTimestamp.allocationSize(end) + 4; } @override int write(Uint8List buf) { buf.buffer.asByteData(buf.offsetInBytes).setInt32(0, 3); int new_offset = buf.offsetInBytes + 4; - new_offset += FfiConverterUInt64.write( - endUs, + new_offset += FfiConverterMoqTimestamp.write( + end, Uint8List.view(buf.buffer, new_offset), ); return new_offset; @@ -5194,17 +5247,17 @@ class RelativeMoqAnchor extends MoqAnchor { } class TimeMoqAnchor extends MoqAnchor { - final int timestampUs; - TimeMoqAnchor(int this.timestampUs); - TimeMoqAnchor._(int this.timestampUs); + final MoqTimestamp timestamp; + TimeMoqAnchor(MoqTimestamp this.timestamp); + TimeMoqAnchor._(MoqTimestamp this.timestamp); static LiftRetVal read(Uint8List buf) { int new_offset = buf.offsetInBytes; - final timestampUs_lifted = FfiConverterUInt64.read( + final timestamp_lifted = FfiConverterMoqTimestamp.read( Uint8List.view(buf.buffer, new_offset), ); - final timestampUs = timestampUs_lifted.value; - new_offset += timestampUs_lifted.bytesRead; - return LiftRetVal(TimeMoqAnchor._(timestampUs), new_offset); + final timestamp = timestamp_lifted.value; + new_offset += timestamp_lifted.bytesRead; + return LiftRetVal(TimeMoqAnchor._(timestamp), new_offset); } @override @@ -5216,15 +5269,15 @@ class TimeMoqAnchor extends MoqAnchor { @override int allocationSize() { - return FfiConverterUInt64.allocationSize(timestampUs) + 4; + return FfiConverterMoqTimestamp.allocationSize(timestamp) + 4; } @override int write(Uint8List buf) { buf.buffer.asByteData(buf.offsetInBytes).setInt32(0, 3); int new_offset = buf.offsetInBytes + 4; - new_offset += FfiConverterUInt64.write( - timestampUs, + new_offset += FfiConverterMoqTimestamp.write( + timestamp, Uint8List.view(buf.buffer, new_offset), ); return new_offset; @@ -7331,26 +7384,26 @@ class FrameMoqMediaRead extends MoqMediaRead { } class GapMoqMediaRead extends MoqMediaRead { - final int timestampUs; + final MoqTimestamp timestamp; final Duration duration; GapMoqMediaRead({ - required int this.timestampUs, + required MoqTimestamp this.timestamp, required Duration this.duration, }); - GapMoqMediaRead._(int this.timestampUs, Duration this.duration); + GapMoqMediaRead._(MoqTimestamp this.timestamp, Duration this.duration); static LiftRetVal read(Uint8List buf) { int new_offset = buf.offsetInBytes; - final timestampUs_lifted = FfiConverterUInt64.read( + final timestamp_lifted = FfiConverterMoqTimestamp.read( Uint8List.view(buf.buffer, new_offset), ); - final timestampUs = timestampUs_lifted.value; - new_offset += timestampUs_lifted.bytesRead; + final timestamp = timestamp_lifted.value; + new_offset += timestamp_lifted.bytesRead; final duration_lifted = FfiConverterDuration.read( Uint8List.view(buf.buffer, new_offset), ); final duration = duration_lifted.value; new_offset += duration_lifted.bytesRead; - return LiftRetVal(GapMoqMediaRead._(timestampUs, duration), new_offset); + return LiftRetVal(GapMoqMediaRead._(timestamp, duration), new_offset); } @override @@ -7362,7 +7415,7 @@ class GapMoqMediaRead extends MoqMediaRead { @override int allocationSize() { - return FfiConverterUInt64.allocationSize(timestampUs) + + return FfiConverterMoqTimestamp.allocationSize(timestamp) + FfiConverterDuration.allocationSize(duration) + 4; } @@ -7371,8 +7424,8 @@ class GapMoqMediaRead extends MoqMediaRead { int write(Uint8List buf) { buf.buffer.asByteData(buf.offsetInBytes).setInt32(0, 2); int new_offset = buf.offsetInBytes + 4; - new_offset += FfiConverterUInt64.write( - timestampUs, + new_offset += FfiConverterMoqTimestamp.write( + timestamp, Uint8List.view(buf.buffer, new_offset), ); new_offset += FfiConverterDuration.write( @@ -7384,17 +7437,17 @@ class GapMoqMediaRead extends MoqMediaRead { } class EndMoqMediaRead extends MoqMediaRead { - final int endUs; - EndMoqMediaRead(int this.endUs); - EndMoqMediaRead._(int this.endUs); + final MoqTimestamp end; + EndMoqMediaRead(MoqTimestamp this.end); + EndMoqMediaRead._(MoqTimestamp this.end); static LiftRetVal read(Uint8List buf) { int new_offset = buf.offsetInBytes; - final endUs_lifted = FfiConverterUInt64.read( + final end_lifted = FfiConverterMoqTimestamp.read( Uint8List.view(buf.buffer, new_offset), ); - final endUs = endUs_lifted.value; - new_offset += endUs_lifted.bytesRead; - return LiftRetVal(EndMoqMediaRead._(endUs), new_offset); + final end = end_lifted.value; + new_offset += end_lifted.bytesRead; + return LiftRetVal(EndMoqMediaRead._(end), new_offset); } @override @@ -7406,15 +7459,15 @@ class EndMoqMediaRead extends MoqMediaRead { @override int allocationSize() { - return FfiConverterUInt64.allocationSize(endUs) + 4; + return FfiConverterMoqTimestamp.allocationSize(end) + 4; } @override int write(Uint8List buf) { buf.buffer.asByteData(buf.offsetInBytes).setInt32(0, 3); int new_offset = buf.offsetInBytes + 4; - new_offset += FfiConverterUInt64.write( - endUs, + new_offset += FfiConverterMoqTimestamp.write( + end, Uint8List.view(buf.buffer, new_offset), ); return new_offset; @@ -8508,26 +8561,26 @@ class FrameMoqVideoRead extends MoqVideoRead { } class GapMoqVideoRead extends MoqVideoRead { - final int timestampUs; + final MoqTimestamp timestamp; final Duration duration; GapMoqVideoRead({ - required int this.timestampUs, + required MoqTimestamp this.timestamp, required Duration this.duration, }); - GapMoqVideoRead._(int this.timestampUs, Duration this.duration); + GapMoqVideoRead._(MoqTimestamp this.timestamp, Duration this.duration); static LiftRetVal read(Uint8List buf) { int new_offset = buf.offsetInBytes; - final timestampUs_lifted = FfiConverterUInt64.read( + final timestamp_lifted = FfiConverterMoqTimestamp.read( Uint8List.view(buf.buffer, new_offset), ); - final timestampUs = timestampUs_lifted.value; - new_offset += timestampUs_lifted.bytesRead; + final timestamp = timestamp_lifted.value; + new_offset += timestamp_lifted.bytesRead; final duration_lifted = FfiConverterDuration.read( Uint8List.view(buf.buffer, new_offset), ); final duration = duration_lifted.value; new_offset += duration_lifted.bytesRead; - return LiftRetVal(GapMoqVideoRead._(timestampUs, duration), new_offset); + return LiftRetVal(GapMoqVideoRead._(timestamp, duration), new_offset); } @override @@ -8539,7 +8592,7 @@ class GapMoqVideoRead extends MoqVideoRead { @override int allocationSize() { - return FfiConverterUInt64.allocationSize(timestampUs) + + return FfiConverterMoqTimestamp.allocationSize(timestamp) + FfiConverterDuration.allocationSize(duration) + 4; } @@ -8548,8 +8601,8 @@ class GapMoqVideoRead extends MoqVideoRead { int write(Uint8List buf) { buf.buffer.asByteData(buf.offsetInBytes).setInt32(0, 2); int new_offset = buf.offsetInBytes + 4; - new_offset += FfiConverterUInt64.write( - timestampUs, + new_offset += FfiConverterMoqTimestamp.write( + timestamp, Uint8List.view(buf.buffer, new_offset), ); new_offset += FfiConverterDuration.write( @@ -8561,17 +8614,17 @@ class GapMoqVideoRead extends MoqVideoRead { } class EndMoqVideoRead extends MoqVideoRead { - final int endUs; - EndMoqVideoRead(int this.endUs); - EndMoqVideoRead._(int this.endUs); + final MoqTimestamp end; + EndMoqVideoRead(MoqTimestamp this.end); + EndMoqVideoRead._(MoqTimestamp this.end); static LiftRetVal read(Uint8List buf) { int new_offset = buf.offsetInBytes; - final endUs_lifted = FfiConverterUInt64.read( + final end_lifted = FfiConverterMoqTimestamp.read( Uint8List.view(buf.buffer, new_offset), ); - final endUs = endUs_lifted.value; - new_offset += endUs_lifted.bytesRead; - return LiftRetVal(EndMoqVideoRead._(endUs), new_offset); + final end = end_lifted.value; + new_offset += end_lifted.bytesRead; + return LiftRetVal(EndMoqVideoRead._(end), new_offset); } @override @@ -8583,15 +8636,15 @@ class EndMoqVideoRead extends MoqVideoRead { @override int allocationSize() { - return FfiConverterUInt64.allocationSize(endUs) + 4; + return FfiConverterMoqTimestamp.allocationSize(end) + 4; } @override int write(Uint8List buf) { buf.buffer.asByteData(buf.offsetInBytes).setInt32(0, 3); int new_offset = buf.offsetInBytes + 4; - new_offset += FfiConverterUInt64.write( - endUs, + new_offset += FfiConverterMoqTimestamp.write( + end, Uint8List.view(buf.buffer, new_offset), ); return new_offset; @@ -9985,7 +10038,7 @@ class FfiConverterMoqTrackDemand { abstract class MoqFlateSnapshotProducerInterface { void finish(); - void update({required Uint8List payload, int? timestampUs = null}); + void update({required Uint8List payload, MoqTimestamp? timestamp = null}); } final _MoqFlateSnapshotProducerFinalizer = Finalizer>((ptr) { @@ -10048,12 +10101,12 @@ class MoqFlateSnapshotProducer implements MoqFlateSnapshotProducerInterface { }, moqExceptionErrorHandler); } - void update({required Uint8List payload, int? timestampUs = null}) { + void update({required Uint8List payload, MoqTimestamp? timestamp = null}) { return rustCall((status) { uniffi_moq_ffi_fn_method_moqflatesnapshotproducer_update( uniffiClonePointer(), FfiConverterUint8List.lower(payload), - FfiConverterOptionalUInt64.lower(timestampUs), + FfiConverterOptionalMoqTimestamp.lower(timestamp), status, ); }, moqExceptionErrorHandler); @@ -10087,7 +10140,7 @@ class FfiConverterMoqFlateSnapshotProducer { } abstract class MoqFlateStreamProducerInterface { - void append({required Uint8List payload, int? timestampUs = null}); + void append({required Uint8List payload, MoqTimestamp? timestamp = null}); void finish(); } @@ -10141,12 +10194,12 @@ class MoqFlateStreamProducer implements MoqFlateStreamProducerInterface { ); } - void append({required Uint8List payload, int? timestampUs = null}) { + void append({required Uint8List payload, MoqTimestamp? timestamp = null}) { return rustCall((status) { uniffi_moq_ffi_fn_method_moqflatestreamproducer_append( uniffiClonePointer(), FfiConverterUint8List.lower(payload), - FfiConverterOptionalUInt64.lower(timestampUs), + FfiConverterOptionalMoqTimestamp.lower(timestamp), status, ); }, moqExceptionErrorHandler); @@ -10309,7 +10362,7 @@ class FfiConverterMoqJsonSnapshotConsumer { abstract class MoqJsonSnapshotProducerInterface { MoqTrackDemand demand(); void finish(); - void update({required String value, int? timestampUs = null}); + void update({required String value, MoqTimestamp? timestamp = null}); } final _MoqJsonSnapshotProducerFinalizer = Finalizer>((ptr) { @@ -10382,12 +10435,12 @@ class MoqJsonSnapshotProducer implements MoqJsonSnapshotProducerInterface { }, moqExceptionErrorHandler); } - void update({required String value, int? timestampUs = null}) { + void update({required String value, MoqTimestamp? timestamp = null}) { return rustCall((status) { uniffi_moq_ffi_fn_method_moqjsonsnapshotproducer_update( uniffiClonePointer(), FfiConverterString.lower(value), - FfiConverterOptionalUInt64.lower(timestampUs), + FfiConverterOptionalMoqTimestamp.lower(timestamp), status, ); }, moqExceptionErrorHandler); @@ -10524,7 +10577,7 @@ class FfiConverterMoqJsonStreamConsumer { } abstract class MoqJsonStreamProducerInterface { - void append({required String value, int? timestampUs = null}); + void append({required String value, MoqTimestamp? timestamp = null}); MoqTrackDemand demand(); void finish(); } @@ -10579,12 +10632,12 @@ class MoqJsonStreamProducer implements MoqJsonStreamProducerInterface { ); } - void append({required String value, int? timestampUs = null}) { + void append({required String value, MoqTimestamp? timestamp = null}) { return rustCall((status) { uniffi_moq_ffi_fn_method_moqjsonstreamproducer_append( uniffiClonePointer(), FfiConverterString.lower(value), - FfiConverterOptionalUInt64.lower(timestampUs), + FfiConverterOptionalMoqTimestamp.lower(timestamp), status, ); }, moqExceptionErrorHandler); @@ -10744,8 +10797,8 @@ abstract class MoqJsonWindowProducerInterface { void cut(); MoqTrackDemand demand(); void finish(); - void pop({required int count, int? timestampUs = null}); - void push({required String value, int? timestampUs = null}); + void pop({required int count, MoqTimestamp? timestamp = null}); + void push({required String value, MoqTimestamp? timestamp = null}); } final _MoqJsonWindowProducerFinalizer = Finalizer>((ptr) { @@ -10825,23 +10878,23 @@ class MoqJsonWindowProducer implements MoqJsonWindowProducerInterface { }, moqExceptionErrorHandler); } - void pop({required int count, int? timestampUs = null}) { + void pop({required int count, MoqTimestamp? timestamp = null}) { return rustCall((status) { uniffi_moq_ffi_fn_method_moqjsonwindowproducer_pop( uniffiClonePointer(), FfiConverterUInt64.lower(count), - FfiConverterOptionalUInt64.lower(timestampUs), + FfiConverterOptionalMoqTimestamp.lower(timestamp), status, ); }, moqExceptionErrorHandler); } - void push({required String value, int? timestampUs = null}) { + void push({required String value, MoqTimestamp? timestamp = null}) { return rustCall((status) { uniffi_moq_ffi_fn_method_moqjsonwindowproducer_push( uniffiClonePointer(), FfiConverterString.lower(value), - FfiConverterOptionalUInt64.lower(timestampUs), + FfiConverterOptionalMoqTimestamp.lower(timestamp), status, ); }, moqExceptionErrorHandler); @@ -14239,7 +14292,7 @@ abstract class MoqVideoDecodedFrameInterface { int height(); Uint8List pixels({required MoqVideoPixelFormat format}); MoqVideoSurface? surface(); - int timestampUs(); + MoqTimestamp timestamp(); int width(); } @@ -14312,13 +14365,13 @@ class MoqVideoDecodedFrame implements MoqVideoDecodedFrameInterface { ); } - int timestampUs() { + MoqTimestamp timestamp() { return rustCallWithLifter( - (status) => uniffi_moq_ffi_fn_method_moqvideodecodedframe_timestamp_us( + (status) => uniffi_moq_ffi_fn_method_moqvideodecodedframe_timestamp( uniffiClonePointer(), status, ), - FfiConverterUInt64.lift, + FfiConverterMoqTimestamp.lift, null, ); } @@ -16206,6 +16259,53 @@ class FfiConverterOptionalMoqSubscription { } } +class FfiConverterOptionalMoqTimestamp { + static MoqTimestamp? lift(RustBuffer buf) { + return FfiConverterOptionalMoqTimestamp.read(buf.asUint8List()).value; + } + + static LiftRetVal read(Uint8List buf) { + if (ByteData.view(buf.buffer, buf.offsetInBytes).getInt8(0) == 0) { + return LiftRetVal(null, 1); + } + final result = FfiConverterMoqTimestamp.read( + Uint8List.view(buf.buffer, buf.offsetInBytes + 1), + ); + return LiftRetVal(result.value, result.bytesRead + 1); + } + + static int allocationSize([MoqTimestamp? value]) { + if (value == null) { + return 1; + } + return FfiConverterMoqTimestamp.allocationSize(value) + 1; + } + + static RustBuffer lower(MoqTimestamp? value) { + if (value == null) { + return toRustBuffer(Uint8List.fromList([0])); + } + final buf = Uint8List( + FfiConverterOptionalMoqTimestamp.allocationSize(value), + ); + FfiConverterOptionalMoqTimestamp.write(value, buf); + return toRustBuffer(buf); + } + + static int write(MoqTimestamp? value, Uint8List buf) { + if (value == null) { + buf[0] = 0; + return 1; + } + buf[0] = 1; + return FfiConverterMoqTimestamp.write( + value, + Uint8List.view(buf.buffer, buf.offsetInBytes + 1), + ) + + 1; + } +} + class FfiConverterOptionalMoqTokens { static MoqTokens? lift(RustBuffer buf) { return FfiConverterOptionalMoqTokens.read(buf.asUint8List()).value; @@ -17784,7 +17884,7 @@ external void uniffi_moq_ffi_fn_method_moqflatesnapshotproducer_finish( external void uniffi_moq_ffi_fn_method_moqflatesnapshotproducer_update( Pointer ptr, RustBuffer payload, - RustBuffer timestamp_us, + RustBuffer timestamp, Pointer uniffiStatus, ); @@ -17825,7 +17925,7 @@ external Pointer uniffi_moq_ffi_fn_constructor_moqflatestreamproducer_new( external void uniffi_moq_ffi_fn_method_moqflatestreamproducer_append( Pointer ptr, RustBuffer payload, - RustBuffer timestamp_us, + RustBuffer timestamp, Pointer uniffiStatus, ); @@ -17935,7 +18035,7 @@ external void uniffi_moq_ffi_fn_method_moqjsonsnapshotproducer_finish( external void uniffi_moq_ffi_fn_method_moqjsonsnapshotproducer_update( Pointer ptr, RustBuffer value, - RustBuffer timestamp_us, + RustBuffer timestamp, Pointer uniffiStatus, ); @@ -18014,7 +18114,7 @@ external Pointer uniffi_moq_ffi_fn_constructor_moqjsonstreamproducer_new( external void uniffi_moq_ffi_fn_method_moqjsonstreamproducer_append( Pointer ptr, RustBuffer value, - RustBuffer timestamp_us, + RustBuffer timestamp, Pointer uniffiStatus, ); @@ -18127,7 +18227,7 @@ external void uniffi_moq_ffi_fn_method_moqjsonwindowproducer_finish( external void uniffi_moq_ffi_fn_method_moqjsonwindowproducer_pop( Pointer ptr, int count, - RustBuffer timestamp_us, + RustBuffer timestamp, Pointer uniffiStatus, ); @@ -18137,7 +18237,7 @@ external void uniffi_moq_ffi_fn_method_moqjsonwindowproducer_pop( external void uniffi_moq_ffi_fn_method_moqjsonwindowproducer_push( Pointer ptr, RustBuffer value, - RustBuffer timestamp_us, + RustBuffer timestamp, Pointer uniffiStatus, ); @@ -19699,10 +19799,10 @@ external RustBuffer uniffi_moq_ffi_fn_method_moqvideodecodedframe_surface( Pointer uniffiStatus, ); -@Native, Pointer)>( +@Native, Pointer)>( assetId: _uniffiAssetId, ) -external int uniffi_moq_ffi_fn_method_moqvideodecodedframe_timestamp_us( +external RustBuffer uniffi_moq_ffi_fn_method_moqvideodecodedframe_timestamp( Pointer ptr, Pointer uniffiStatus, ); @@ -20780,7 +20880,7 @@ external int uniffi_moq_ffi_checksum_method_moqvideodecodedframe_pixels(); external int uniffi_moq_ffi_checksum_method_moqvideodecodedframe_surface(); @Native(assetId: _uniffiAssetId) -external int uniffi_moq_ffi_checksum_method_moqvideodecodedframe_timestamp_us(); +external int uniffi_moq_ffi_checksum_method_moqvideodecodedframe_timestamp(); @Native(assetId: _uniffiAssetId) external int uniffi_moq_ffi_checksum_method_moqvideodecodedframe_width(); @@ -21064,10 +21164,10 @@ void _checkApiChecksums() { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } if (uniffi_moq_ffi_checksum_method_moqflatesnapshotproducer_update() != - 29136) { + 44060) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } - if (uniffi_moq_ffi_checksum_method_moqflatestreamproducer_append() != 45773) { + if (uniffi_moq_ffi_checksum_method_moqflatestreamproducer_append() != 30402) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } if (uniffi_moq_ffi_checksum_method_moqflatestreamproducer_finish() != 6982) { @@ -21093,7 +21193,7 @@ void _checkApiChecksums() { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } if (uniffi_moq_ffi_checksum_method_moqjsonsnapshotproducer_update() != - 17590) { + 41112) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } if (uniffi_moq_ffi_checksum_method_moqjsonstreamconsumer_cancel() != 29308) { @@ -21102,7 +21202,7 @@ void _checkApiChecksums() { if (uniffi_moq_ffi_checksum_method_moqjsonstreamconsumer_next() != 21257) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } - if (uniffi_moq_ffi_checksum_method_moqjsonstreamproducer_append() != 36078) { + if (uniffi_moq_ffi_checksum_method_moqjsonstreamproducer_append() != 57310) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } if (uniffi_moq_ffi_checksum_method_moqjsonstreamproducer_demand() != 52854) { @@ -21126,10 +21226,10 @@ void _checkApiChecksums() { if (uniffi_moq_ffi_checksum_method_moqjsonwindowproducer_finish() != 49018) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } - if (uniffi_moq_ffi_checksum_method_moqjsonwindowproducer_pop() != 62669) { + if (uniffi_moq_ffi_checksum_method_moqjsonwindowproducer_pop() != 58245) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } - if (uniffi_moq_ffi_checksum_method_moqjsonwindowproducer_push() != 19295) { + if (uniffi_moq_ffi_checksum_method_moqjsonwindowproducer_push() != 47237) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } if (uniffi_moq_ffi_checksum_method_moqmediacatalogconsumer_cancel() != @@ -21355,7 +21455,7 @@ void _checkApiChecksums() { if (uniffi_moq_ffi_checksum_method_moqgroupproducer_sequence() != 21067) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } - if (uniffi_moq_ffi_checksum_method_moqgroupproducer_write_frame() != 42053) { + if (uniffi_moq_ffi_checksum_method_moqgroupproducer_write_frame() != 38774) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } if (uniffi_moq_ffi_checksum_method_moqtrackproducer_abort() != 37537) { @@ -21386,7 +21486,7 @@ void _checkApiChecksums() { if (uniffi_moq_ffi_checksum_method_moqtrackproducer_requests() != 60252) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } - if (uniffi_moq_ffi_checksum_method_moqtrackproducer_write_frame() != 32196) { + if (uniffi_moq_ffi_checksum_method_moqtrackproducer_write_frame() != 46891) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } if (uniffi_moq_ffi_checksum_method_moqtrackrequest_abort() != 62713) { @@ -21511,8 +21611,8 @@ void _checkApiChecksums() { if (uniffi_moq_ffi_checksum_method_moqvideodecodedframe_surface() != 3872) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } - if (uniffi_moq_ffi_checksum_method_moqvideodecodedframe_timestamp_us() != - 18681) { + if (uniffi_moq_ffi_checksum_method_moqvideodecodedframe_timestamp() != + 47810) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } if (uniffi_moq_ffi_checksum_method_moqvideodecodedframe_width() != 30916) { diff --git a/dart/moq_ffi/test/leak_test.dart b/dart/moq_ffi/test/leak_test.dart index bbbb3ccd1d0..b415f69aa23 100644 --- a/dart/moq_ffi/test/leak_test.dart +++ b/dart/moq_ffi/test/leak_test.dart @@ -85,7 +85,12 @@ void main() { ); final consumer = track.consume(subscription: null); final producer = track.appendGroup(); - producer.writeFrame(frame: MoqFrame(payload: payload, timestampUs: 0)); + producer.writeFrame( + frame: MoqFrame( + payload: payload, + timestamp: MoqTimestamp(value: 0, scale: 1000000), + ), + ); producer.finish(); final group = await consumer.nextGroup(); final frame = await group!.readFrame(); diff --git a/dart/moq_ffi/test/smoke_test.dart b/dart/moq_ffi/test/smoke_test.dart index d7aec01bc79..ad52d65f94f 100644 --- a/dart/moq_ffi/test/smoke_test.dart +++ b/dart/moq_ffi/test/smoke_test.dart @@ -54,7 +54,10 @@ void main() { final producer = track.appendGroup(); producer.writeFrame( - frame: MoqFrame(payload: utf8.encode('dart'), timestampUs: 0), + frame: MoqFrame( + payload: utf8.encode('dart'), + timestamp: MoqTimestamp(value: 0, scale: 1000000), + ), ); producer.finish(); diff --git a/demo/carla/sim/moq_carla_sim/bridge.py b/demo/carla/sim/moq_carla_sim/bridge.py index 98b8aa5c7aa..b49411c490d 100644 --- a/demo/carla/sim/moq_carla_sim/bridge.py +++ b/demo/carla/sim/moq_carla_sim/bridge.py @@ -16,7 +16,6 @@ import logging import struct from dataclasses import dataclass -from datetime import timedelta from typing import Callable import moq @@ -371,7 +370,7 @@ def publish(self, frame: Frame) -> None: raise BridgeError(f"{self.name}: frame before config for rendition {frame.rendition}") if self._origin_us is None: self._origin_us = frame.timestamp_us - timestamp = timedelta(microseconds=max(0, frame.timestamp_us - self._origin_us)) + timestamp = moq.Timestamp(max(0, frame.timestamp_us - self._origin_us), 1_000_000) track.write_frame(frame.payload, timestamp) self.published[frame.rendition] += 1 diff --git a/demo/carla/sim/tests/conftest.py b/demo/carla/sim/tests/conftest.py index 2ba51aa858c..132dfff4b6d 100644 --- a/demo/carla/sim/tests/conftest.py +++ b/demo/carla/sim/tests/conftest.py @@ -68,6 +68,7 @@ def __aiter__(self): moq.AnnounceEventRestart = AnnounceEventRestart moq.AnnounceRoute = lambda **kwargs: SimpleNamespace(**kwargs) moq.mint_epoch = lambda: str(uuid.uuid4()) +moq.Timestamp = lambda value, scale: SimpleNamespace(value=value, scale=scale) moq_json = ModuleType("moq.json") moq_json.SnapshotProducer = SnapshotProducer diff --git a/demo/carla/sim/tests/test_bridge.py b/demo/carla/sim/tests/test_bridge.py index 628f307751a..1a60d4dd17c 100644 --- a/demo/carla/sim/tests/test_bridge.py +++ b/demo/carla/sim/tests/test_bridge.py @@ -1,6 +1,5 @@ import asyncio import struct -from datetime import timedelta from types import SimpleNamespace import moq @@ -117,10 +116,6 @@ async def wanted_changed(self) -> int | None: return self._wanted -def microseconds(timestamp: timedelta) -> int: - return timestamp // timedelta(microseconds=1) - - class FakeTrack: def __init__(self, init: bytes, name: str, hint) -> None: self.init = init @@ -133,8 +128,9 @@ def __init__(self, init: bytes, name: str, hint) -> None: def demand(self) -> FakeDemand: return self.demand_handle - def write_frame(self, payload: bytes, timestamp: timedelta) -> None: - self.frames.append((payload, microseconds(timestamp))) + def write_frame(self, payload: bytes, timestamp: SimpleNamespace) -> None: + assert timestamp.scale == 1_000_000 + self.frames.append((payload, timestamp.value)) def finish(self) -> None: self.finished = True diff --git a/doc/lib/c/index.md b/doc/lib/c/index.md index 8be91d05c6c..079c62a826a 100644 --- a/doc/lib/c/index.md +++ b/doc/lib/c/index.md @@ -80,7 +80,8 @@ inside. The header is the reference: each function carries a doc comment. - **Audio needs cuts.** Video groups at its keyframes, but audio forms a group only where you call `moq_publish_media_cut`: after every frame, or at a segment cadence to align with video. - **Ending cleanly.** When the input ends, finish every track, then call `moq_publish_catalog_finish()` to finish the catalog, which ends the content. The broadcast stays announced and keeps serving the finished tracks, so a subscriber still catching up can drain them, until `moq_publish_close()` takes it offline. How long to keep it up is yours to decide. A track still open at the close ends with `UNROUTABLE`, which readers take as the publisher leaving, and its handle is released. - **Timeline breaks.** On a seek or pause, call `moq_publish_media_discontinuity`, then keep timestamps moving forward and resume video on a keyframe. -- **JSON values.** `moq_consume_json_value` fills `moq_json_value` with the document and its frame's `timestamp_us`, rounded down to a whole microsecond; `timestamp_present` is false on an untimed track. A snapshot consumer's callback fires for each state in order, but a group superseded before it is read is skipped. +- **Timestamps.** A `moq_timestamp` is exact: `value` units at `scale` units per second, so a 90 kHz tick survives a read and republish. Frames, datagrams, and JSON values point `timestamp` at theirs, NULL on an untimed track and valid as long as the payload. Tracks moq-c creates are timed, so their writes need one. A zero scale or an out-of-range value fails with `MOQ_ERROR_TIMESTAMP_OVERFLOW`. +- **JSON values.** `moq_consume_json_value` fills `moq_json_value` with the document and its frame's timestamp. A snapshot consumer's callback fires for each state in order, but a group superseded before it is read is skipped. - **Decoded reads.** `moq_decode_audio` and `moq_decode_video` deliver read ids in order: a frame, a gap where media was lost, or an end where the publisher stopped its encoder. Check `kind` on what `moq_decode_audio_read` or `moq_decode_video_read` writes. Free each id with `moq_decode_audio_read_free` or `moq_decode_video_read_free` promptly: a held video frame holds a decoder buffer, and the decoder stalls. - **Stats.** `moq_session_stats()` fills `moq_connection_stats` with `rtt_us`, `estimated_send_rate_bps`, and the byte and packet counters (`bytes_sent`, `bytes_received`, `bytes_lost`, `packets_sent`, `packets_received`, `packets_lost`). Each has a `_valid` flag, false when the transport does not report it, which is not the same as zero. `moq_session_snapshot()` adds the negotiated `protocol`. A failed dial or dropped connection reaches the session's `on_state` with its `failure` code, and `moq_error()` gives the reason during that callback. Hold the handle returned by `moq_session_recv_bandwidth()` to request receive estimates. `moq_bandwidth_consumer_peek()` reads the estimate and `moq_bandwidth_consumer_changed()` waits for a change. `moq_bandwidth_consumer_close()` releases demand; the last consumer stops PROBE. Stats snapshots do not request it. - **Demand.** A watcher from `moq_publish_track_demand()` (or the media, video, and audio variants) calls back `MOQ_DEMAND_USED` or `MOQ_DEMAND_UNUSED`, again whenever the wanted group moves. `moq_publish_demand_wanted()` reads that group: start a new one once it passes your largest. Set `refresh` in `moq_track_info` to have a joining subscriber ask for a new group once the newest has grown past `refresh` times its first frame. diff --git a/doc/lib/cpp/index.md b/doc/lib/cpp/index.md index 4728f2ba9d1..f3385545380 100644 --- a/doc/lib/cpp/index.md +++ b/doc/lib/cpp/index.md @@ -119,6 +119,9 @@ use one source timeline; omitting it keeps an independent offset. A timebase bel its broadcast and does not keep it open. `MediaContainerProducer` takes chunks split anywhere, so a raw byte stream needs no other importer. `moq::ContainerFormat::kFmp4` splits each fragment into one frame per sample. +Media times are exact `moq::Timestamp{value, scale}` records, `value` units at `scale` units +per second, and read back at the track's timescale, so a 90 kHz tick republishes unchanged. +A raw `moq::Frame` with `std::nullopt` is untimed. ```cpp // Publish encoded frames, or raw pixels with the codec inside the binding. @@ -126,12 +129,12 @@ anywhere, so a raw byte stream needs no other importer. // encoder or capture source. auto broadcast = ok(session->publish()->create_broadcast("my-stream.hang")); auto audio = ok(moq::MediaTrackProducer::audio(broadcast, moq::MediaTarget::kNamed{}, {moq::AudioFormat::kOpus, opus_init})); -ok(audio->write_frame({packet, 20'000})); +ok(audio->write_frame({packet, moq::Timestamp{960, 48'000}})); // 20 ms moq::VideoEncoderOutput output{moq::VideoCodec::kH264, std::nullopt, std::nullopt, moq::VideoEncoderKind::kAuto{}}; auto catalog = ok(moq::MediaCatalogProducer::init(broadcast)); auto video = ok(moq::VideoProducer::init(catalog, {{moq::VideoPixelFormat::kRgba, 1280, 720, {30000, 1001}}, output, "camera", nullptr})); -ok(video->write({0, rgba})); +ok(video->write({{0, 30'000}, rgba})); moq::AnnounceRoute route; route.epoch = moq::mint_epoch(); // a fresh epoch per run ok(broadcast->announce(route)); diff --git a/doc/lib/dart/index.md b/doc/lib/dart/index.md index 0889e49c7cf..d0d1110ee6e 100644 --- a/doc/lib/dart/index.md +++ b/doc/lib/dart/index.md @@ -17,10 +17,12 @@ Import `package:moq/media.dart` with a prefix for catalogs, encoded-media import container consumers. `TrackProducer.audio` / `.video` take a broadcast, an init record, and a `Named` or `Requested` target. `CatalogProducer(broadcast: ...)` owns catalog properties and sections; it holds the broadcast weakly and fails after the broadcast closes. -`package:moq/flate.dart` exposes opaque `SnapshotProducer` / `StreamProducer` with an optional `timestampUs`. +`package:moq/flate.dart` exposes opaque `SnapshotProducer` / `StreamProducer` with an optional `timestamp`. A missing data timestamp stays untimed; the library never substitutes zero or now. -`package:moq/json.dart` consumers return `Value` (`value`, `timestampUs`) from `next()`; a snapshot consumer -yields each state in order, and `latest()` skips to the newest. Read timestamps are rounded down to a whole microsecond. +`package:moq/json.dart` consumers return `Value` (`value`, `timestamp`) from `next()`; a snapshot consumer +yields each state in order, and `latest()` skips to the newest. +Media times are exact `Timestamp` records, `value` units at `scale` units per second, so a 90 kHz tick survives a +read and republish. `Duration.toTimestamp()` converts exactly; `Timestamp.toDuration()` rounds to the nearest microsecond. Raw tracks with a `null` timescale are untimed on both publish and receive. `MoqTrackInfo.compress` on a raw track sends each group DEFLATE-compressed to opt-in `moq-lite-07-wip` peers; other peers, and every reader here, get the original frames. `@moq/net` cannot read a compressed track yet. Whole-frame media writes require caller time; container imports keep their own timeline handling. @@ -93,7 +95,7 @@ final encoder = video.Producer( track: 'camera', ), ); -encoder.write(frame: video.Frame(timestampUs: pts, data: rgba)); +encoder.write(frame: video.Frame(timestamp: pts, data: rgba)); camera.announce(route: AnnounceRoute(epoch: mintEpoch())); encoder.finish(); ``` @@ -123,7 +125,7 @@ if (read is video.ReadFrame) { final mine = moq.createBroadcast('live/camera'); final track = mine.publishTrack(name: 'video', info: null); final group = track.appendGroup(); -group.writeFrame(frame: Frame(payload: bytes, timestampUs: null)); +group.writeFrame(frame: Frame(payload: bytes, timestamp: null)); group.finish(); mine.announce(route: AnnounceRoute(epoch: mintEpoch())); // a fresh epoch per run track.finish(); diff --git a/doc/lib/go/index.md b/doc/lib/go/index.md index 38ab0f5f69b..416f8c5da8c 100644 --- a/doc/lib/go/index.md +++ b/doc/lib/go/index.md @@ -16,14 +16,16 @@ linux/amd64, linux/arm64, darwin/arm64 (macOS 12.3+), windows/amd64. `moq.dev/moq/media` owns catalogs, encoded imports, and container consumers. Construct `NewAudioTrackProducer` / `NewVideoTrackProducer` from a broadcast, an init record, and a `Named` or `Requested` target. `NewCatalogProducer` holds its broadcast weakly; -catalog writes fail with `ErrClosed` after the broadcast closes. Media timestamps use `time.Duration`. +catalog writes fail with `ErrClosed` after the broadcast closes. Media timestamps are exact +`moq.Timestamp` records (`Value` at `Scale` units per second), so a 90 kHz tick survives a read and republish; +`TimestampFromDuration` and `TimestampToDuration` convert. A missing data timestamp stays untimed; the library never substitutes zero or now. Raw tracks with a `nil` timescale are untimed on both publish and receive. `TrackInfo.Compress` on a raw track sends each group DEFLATE-compressed to opt-in `moq-lite-07-wip` peers; other peers, and every reader here, get the original frames. `@moq/net` cannot read a compressed track yet. `moq.dev/moq/flate` publishes opaque snapshot and stream payloads; its `Update` / `Append` -and the JSON producers take a final `*time.Duration` timestamp argument (`nil` for untimed). +and the JSON producers take a final `*moq.Timestamp` argument (`nil` for untimed). JSON consumers return a `*Timed` holding the value and that timestamp; `SnapshotConsumer.Latest` -skips to the newest state where `Next` yields each one. Read timestamps are rounded down to a whole microsecond. +skips to the newest state where `Next` yields each one. A read timestamp is at the track's timescale. Whole-frame media writes require caller time; container imports keep their own timeline handling. Timed raw/data tracks require caller-supplied timestamps. Use `CatalogProducer.Now()` to stamp a locally created event on the broadcast clock; reading it fixes that clock for later media producers. @@ -90,15 +92,14 @@ for event, err := range announced.All(ctx) { ```go import ( - "time" moqvideo "moq.dev/moq/video" ) // Publish encoded frames, or raw pixels with the codec inside the binding. -// opusInit, packet, pts, and rgba come from your encoder or capture source. +// opusInit, packet, pts (90 kHz ticks), and rgba come from your encoder or capture source. broadcast, _ := client.CreateBroadcast("my-stream.hang") audio, _ := moqmedia.NewAudioTrackProducer(broadcast, moqmedia.Named{}, moqmedia.AudioInit{Format: moqmedia.AudioFormatOpus, Data: opusInit}) -timestamp := 20 * time.Millisecond +timestamp := moq.Timestamp{Value: 960, Scale: 48_000} // 20 ms on the Opus sample clock _ = audio.WriteFrame(moq.Frame{Payload: packet, Timestamp: ×tamp}) _ = audio.Cut() // audio has no keyframes, so this is what gives it groups @@ -109,7 +110,7 @@ video, _ := moqvideo.NewProducer(catalogProducer, moqvideo.ProducerOptions{ Output: moqvideo.EncoderOutput{Codec: moq.VideoCodecH264, Kind: moq.AutoEncoder()}, Track: &track, }) -_ = video.Write(moqvideo.Frame{Timestamp: time.Duration(pts) * time.Microsecond, Data: rgba}) +_ = video.Write(moqvideo.Frame{Timestamp: moq.Timestamp{Value: pts, Scale: 90_000}, Data: rgba}) epoch := moq.MintEpoch() // a fresh epoch per run _ = broadcast.Announce(moq.AnnounceRoute{Epoch: &epoch}) _ = audio.Finish() diff --git a/doc/lib/kt/index.md b/doc/lib/kt/index.md index 8b399b92fe1..44760db836d 100644 --- a/doc/lib/kt/index.md +++ b/doc/lib/kt/index.md @@ -16,10 +16,12 @@ x86\_64) and desktop JVM (Linux x86\_64/aarch64, macOS arm64, Windows x64). `dev.moq.media` owns catalogs, encoded imports, and container consumers. `TrackProducer.audio` / `.video` take a broadcast, a `Named` or `Requested` target, and an init record. `CatalogProducer(broadcast)` holds its broadcast weakly and fails with `Closed` after it closes. -`dev.moq.flate.SnapshotProducer` / `StreamProducer` publish opaque bytes with an optional `timestampUs`. +`dev.moq.flate.SnapshotProducer` / `StreamProducer` publish opaque bytes with an optional `timestamp`. A missing data timestamp stays untimed; the library never substitutes zero or now. `dev.moq.json` consumers' `values()` emits `Value` (`value`, `timestamp`) and `valuesAs()` emits `Timed`; -a snapshot consumer yields each state in order, and `latest()` skips to the newest. Read timestamps are rounded down to a whole microsecond. +a snapshot consumer yields each state in order, and `latest()` skips to the newest. +A `Timestamp(value, scale)` is exact and reads back at the track's timescale, so a 90 kHz tick republishes unchanged. +`Duration.toTimestamp()` is exact at nanosecond scale; `Timestamp.toDuration()` rounds to the nearest nanosecond. Raw tracks with a `null` timescale are untimed on both publish and receive. `MoqTrackInfo.compress` on a raw track sends each group DEFLATE-compressed to opt-in `moq-lite-07-wip` peers; other peers, and every reader here, get the original frames. `@moq/net` cannot read a compressed track yet. Whole-frame media writes require caller time; container imports keep their own timeline handling. @@ -71,7 +73,7 @@ Moq.connect("https://relay.example.com", ClientConfig(tls = ClientTls(roots = li Moq.connect("https://relay.example.com").use { moq -> val broadcast = moq.createBroadcast("my-stream.hang") val audio = dev.moq.media.TrackProducer.audio(broadcast, Named(null), AudioInit(format = AudioFormat.OPUS, data = opusInit)) - audio.writeFrame(Frame(payload = packet, timestampUs = 20_000u)) + audio.writeFrame(Frame(payload = packet, timestamp = Timestamp(960u, 48_000u))) audio.cut() // audio has no keyframes, so this is what gives it groups val video = dev.moq.video.Producer( @@ -79,7 +81,7 @@ Moq.connect("https://relay.example.com").use { moq -> dev.moq.video.ProducerOptions(input = VideoEncoderInput(format = VideoPixelFormat.RGBA, width = 1280u, height = 720u, framerate = dev.moq.video.FrameRate(30000u, 1001u)), output = VideoEncoderOutput(codec = VideoCodec.H264, bitrate = null, gop = null, kind = autoEncoder), track = "camera"), ) - video.write(VideoFrame(timestampUs = pts, data = rgba)) + video.write(VideoFrame(timestamp = pts, data = rgba)) broadcast.announce(AnnounceRoute(epoch = mintEpoch())) // a fresh epoch per run audio.finish() video.finish() diff --git a/doc/lib/py/index.md b/doc/lib/py/index.md index 5cf642d5fe2..516e077aa26 100644 --- a/doc/lib/py/index.md +++ b/doc/lib/py/index.md @@ -22,14 +22,15 @@ source timeline; omitting it keeps an independent offset. A timebase belongs to broadcast and does not keep it open. `ContainerProducer` takes chunks split anywhere, so a raw byte stream needs no other importer. `ContainerFormat.FMP4` splits each fragment into one frame per sample. -`MediaFrame.timestamp`, media writes, and `flush` use `datetime.timedelta`. +Media timestamps are exact `moq.Timestamp(value, scale)` records, so a 90 kHz tick survives a read and republish. +`Timestamp.from_timedelta` is exact; `.to_timedelta()` rounds to the nearest microsecond. A missing data timestamp stays untimed; the library never substitutes zero or now. JSON consumers yield `moq.json.Timed(value, timestamp)`; a snapshot consumer yields each state in order, -and `await consumer.latest()` skips to the newest. A window consumer's value is a `WindowPush`, `WindowPop`, or `WindowSkip`. Read timestamps are rounded down to a whole microsecond. +and `await consumer.latest()` skips to the newest. A window consumer's value is a `WindowPush`, `WindowPop`, or `WindowSkip`. Raw tracks with a `None` timescale are untimed on both publish and receive. `TrackInfo(compress=True)` on a raw track sends each group DEFLATE-compressed to opt-in `moq-lite-07-wip` peers; other peers, and every reader here, get the original frames. `@moq/net` cannot read a compressed track yet. `moq.flate.SnapshotProducer` / `StreamProducer` publish opaque payloads; their `update` / `append` -and the JSON producers accept `timestamp=timedelta(...)` (`None` for untimed). +and the JSON producers accept `timestamp=moq.Timestamp(...)` (`None` for untimed). Whole-frame media writes require caller time; container imports keep their own timeline handling. Timed raw/data tracks require caller-supplied timestamps. Use `CatalogProducer.now()` to stamp a locally created event on the broadcast clock; reading it fixes that clock for later media producers. diff --git a/doc/lib/swift/index.md b/doc/lib/swift/index.md index 6743997dbba..e12cfc43120 100644 --- a/doc/lib/swift/index.md +++ b/doc/lib/swift/index.md @@ -17,10 +17,13 @@ slices for iOS 16+, the iOS Simulator, and macOS 12.3+. `.named(name:)` or `.requested(request)` target. `Media.CatalogProducer(broadcast:)` updates catalog properties and sections without keeping the broadcast open. Its writes fail after closing or releasing the broadcast. -`Flate.SnapshotProducer` / `StreamProducer` publish opaque bytes with an optional `timestampUs`. +Media timestamps are exact `Timestamp` records, `value` units at `scale` units per second, carried at the track's timescale +(a write at another scale rounds down to it). On macOS 13+ and iOS, `try Timestamp(duration)` converts a `Duration` exactly, +and `try timestamp.duration` rounds back to the nearest attosecond. +`Flate.SnapshotProducer` / `StreamProducer` publish opaque bytes with an optional `timestamp`. A missing data timestamp stays untimed; the library never substitutes zero or now. -`Json` consumers yield `Json.Timed` (`value`, `timestampUs`); a snapshot consumer yields each state in order, -and `latest()` skips to the newest. Read timestamps are rounded down to a whole microsecond. +`Json` consumers yield `Json.Timed` (`value`, `timestamp`); a snapshot consumer yields each state in order, +and `latest()` skips to the newest. Raw tracks with a `nil` timescale are untimed on both publish and receive. `MoqTrackInfo.compress` on a raw track sends each group DEFLATE-compressed to opt-in `moq-lite-07-wip` peers; other peers, and every reader here, get the original frames. `@moq/net` cannot read a compressed track yet. Whole-frame media writes require caller time; container imports keep their own timeline handling. @@ -71,7 +74,7 @@ for try await event in try session.consume.announced(prefix: "live/", filter: "* // opusInit, packet, pts, and rgba come from your encoder or capture source. let broadcast = try session.publish.createBroadcast(path: "my-stream.hang") let audio = try Media.TrackProducer.audio(broadcast: broadcast, initData: Media.AudioInit(format: .opus, data: opusInit)) -try audio.writeFrame(packet, timestampUs: 20_000) +try audio.writeFrame(packet, timestamp: Timestamp(value: 20, scale: 1_000)) try audio.cut() // audio has no keyframes, so this is what gives it groups let video = try Video.Producer( @@ -80,7 +83,7 @@ let video = try Video.Producer( output: VideoEncoderOutput(codec: .h264, kind: .auto), track: "camera" ) -try video.write(VideoFrame(timestampUs: pts, data: rgba)) +try video.write(VideoFrame(timestamp: pts, data: rgba)) try broadcast.announce(route: AnnounceRoute(epoch: mintEpoch())) // a fresh epoch per run try audio.finish() try video.finish() diff --git a/go/wrapper/README.md b/go/wrapper/README.md index 034eea4ddf4..7b4f675458f 100644 --- a/go/wrapper/README.md +++ b/go/wrapper/README.md @@ -97,7 +97,7 @@ catalog snapshots, live media, and one fetched media group. The last two take a (`VideoRendition` or `AudioRendition`: a catalog ID and its config) and follow its broadcast and track themselves. `NewGroupConsumer` decodes a raw group, such as one from `moq.TrackConsumer.RecvGroup` for arrival-order reads. -Frames and `Flush` use `time.Duration`; `Demand()` owns track names and subscriber waits. +Frames carry exact `moq.Timestamp` records; `Demand()` owns track names and subscriber waits. `BroadcastProducer.Requests()` accepts subscriber-requested tracks. Call `TrackRequest.Accept()` for raw tracks, or pass the request as `media.Requested` @@ -112,7 +112,7 @@ carry every record in order. `NewWindowProducer` / `NewWindowConsumer` carry a s of records a reader can join at any point; the catalog has no window mode, so the producer takes only the track. Producers accept any `encoding/json` value; consumers return `json.RawMessage` so callers choose their own decoded type. -`Update` / `Append` / `Push` / `Pop` take a final `*time.Duration` on the broadcast clock; nil publishes untimed. +`Update` / `Append` / `Push` / `Pop` take a final `*moq.Timestamp` on the broadcast clock; nil publishes untimed. Raw tracks with a nil timescale are untimed; timed tracks require matching timestamps. `media.CatalogProducer.Now()` samples and fixes the catalog clock for explicit local-event stamps. `moq.dev/moq/flate` provides the matching snapshot and stream producers for opaque bytes. diff --git a/go/wrapper/audio/audio.go b/go/wrapper/audio/audio.go index 6387fb7d133..e6b6e204f63 100644 --- a/go/wrapper/audio/audio.go +++ b/go/wrapper/audio/audio.go @@ -65,19 +65,7 @@ func (o DecoderOutput) ffi() (ffi.MoqAudioDecoderOutput, error) { } // Frame is interleaved PCM with its presentation timestamp. -type Frame struct { - Timestamp time.Duration - Data []byte -} - -func (f Frame) ffi() (ffi.MoqAudioFrame, error) { - us, err := bridge.Duration(f.Timestamp, "audio timestamp") - return ffi.MoqAudioFrame{TimestampUs: us, Data: f.Data}, err -} - -func frame(raw ffi.MoqAudioFrame) Frame { - return Frame{Timestamp: time.Duration(raw.TimestampUs) * time.Microsecond, Data: raw.Data} -} +type Frame = ffi.MoqAudioFrame // Read is one item a Consumer reads, in delivery order: a ReadFrame, ReadGap, or ReadEnd. type Read interface{ read() } @@ -90,7 +78,7 @@ type ReadFrame struct { // ReadGap is media lost after what was already read: what follows does not continue it. type ReadGap struct { // Timestamp is the furthest presentation point already read. - Timestamp time.Duration + Timestamp moq.Timestamp // Duration is an upper bound on how long until the next frame resumes. Duration time.Duration } @@ -100,7 +88,7 @@ type ReadGap struct { // comes from a fresh encoder. type ReadEnd struct { // End is where the stopped encoder's media stops. - End time.Duration + End moq.Timestamp } func (ReadFrame) read() {} @@ -110,11 +98,11 @@ func (ReadEnd) read() {} func audioRead(raw ffi.MoqAudioRead) (Read, error) { switch read := raw.(type) { case ffi.MoqAudioReadFrame: - return ReadFrame{Frame: frame(read.Frame)}, nil + return ReadFrame{Frame: read.Frame}, nil case ffi.MoqAudioReadGap: - return ReadGap{Timestamp: time.Duration(read.TimestampUs) * time.Microsecond, Duration: read.Duration}, nil + return ReadGap{Timestamp: read.Timestamp, Duration: read.Duration}, nil case ffi.MoqAudioReadEnd: - return ReadEnd{End: time.Duration(read.EndUs) * time.Microsecond}, nil + return ReadEnd{End: read.End}, nil } return nil, fmt.Errorf("unknown audio read: %T", raw) } @@ -166,11 +154,7 @@ func (p *Producer) Reanchor() error { return p.inner.Reanchor() } // Write encodes and publishes one PCM frame in the configured input layout. func (p *Producer) Write(value Frame) error { - raw, err := value.ffi() - if err != nil { - return err - } - return p.inner.Write(raw) + return p.inner.Write(value) } // Reservation returns this track's bandwidth reservation, or nil without one. @@ -247,7 +231,6 @@ func (d *Consumer) Next(ctx context.Context) (Read, error) { // All ranges over every read until the track ends or the loop breaks. func (d *Consumer) All(ctx context.Context) iter.Seq2[Read, error] { return bridge.Seq(ctx, d.Next) } - // Delay is the playout delay to hold ahead of the playhead: the fixed one, or the estimate from every frame read so far. // The estimate measures when Next returns, so call it again as soon as the previous frame is handled. func (d *Consumer) Delay() time.Duration { diff --git a/go/wrapper/bridge.go b/go/wrapper/bridge.go index 116ac0f1392..3209b931ca7 100644 --- a/go/wrapper/bridge.go +++ b/go/wrapper/bridge.go @@ -10,7 +10,6 @@ import ( func init() { bridge.BroadcastConsumer = func(v any) *ffi.MoqBroadcastConsumer { return v.(*BroadcastConsumer).inner } bridge.TrackRequest = func(v any) *ffi.MoqTrackRequest { return v.(*TrackRequest).inner } - bridge.Frame = func(v any) (ffi.MoqFrame, error) { return v.(Frame).ffi() } bridge.Subscription = func(v any) (*ffi.MoqSubscription, error) { return subscriptionFFI(v.(*Subscription)) } bridge.BroadcastProducer = func(v any) *ffi.MoqBroadcastProducer { return v.(*BroadcastProducer).inner } diff --git a/go/wrapper/data_timestamps_test.go b/go/wrapper/data_timestamps_test.go index 63255dbde2c..87985b80acf 100644 --- a/go/wrapper/data_timestamps_test.go +++ b/go/wrapper/data_timestamps_test.go @@ -3,22 +3,36 @@ package moq_test import ( "context" "encoding/json" + "errors" "testing" - "time" "moq.dev/moq" "moq.dev/moq/flate" moqjson "moq.dev/moq/json" ) +// A 90 kHz tick has no exact microsecond count, so it survives only as a record. +var tick = moq.Timestamp{Value: 1, Scale: 90_000} + +func ninetyKHz() *moq.TrackInfo { + scale := uint64(90_000) + return &moq.TrackInfo{Timescale: &scale} +} + +// Every producer carries an exact timestamp, a present zero, or none at all, and +// the raw reader gets back exactly what was written. func TestDataTimestamps(t *testing.T) { - for _, mode := range []string{"json snapshot", "json stream", "flate snapshot", "flate stream"} { - for _, timed := range []bool{false, true} { - name := mode + "/untimed" - if timed { - name = mode + "/timed" - } - t.Run(name, func(t *testing.T) { + timestamps := []struct { + name string + at *moq.Timestamp + }{ + {"untimed", nil}, + {"zero", &moq.Timestamp{Value: 0, Scale: 90_000}}, + {"tick", &tick}, + } + for _, mode := range []string{"frame", "json snapshot", "json stream", "flate snapshot", "flate stream"} { + for _, timestamp := range timestamps { + t.Run(mode+"/"+timestamp.name, func(t *testing.T) { ctx, cancel := context.WithTimeout(context.Background(), testTimeout) defer cancel() broadcast, err := moq.NewBroadcastProducer() @@ -26,12 +40,9 @@ func TestDataTimestamps(t *testing.T) { t.Fatal(err) } defer broadcast.Close() - var timestamp *time.Duration var info *moq.TrackInfo - if timed { - at := 123456 * time.Microsecond - timestamp = &at - info = timedInfo() + if timestamp.at != nil { + info = ninetyKHz() } track, err := broadcast.PublishTrack("data", info) if err != nil { @@ -43,53 +54,8 @@ func TestDataTimestamps(t *testing.T) { } defer consumer.Cancel() payload := []byte("opaque payload") - switch mode { - case "json snapshot": - producer, err := moqjson.NewSnapshotProducer(broadcast, track, moqjson.SnapshotOptions{}) - if err != nil { - t.Fatal(err) - } - err = producer.Update(map[string]int{"n": 1}, timestamp) - if err != nil { - t.Fatal(err) - } - if err := producer.Finish(); err != nil { - t.Fatal(err) - } - case "json stream": - producer, err := moqjson.NewStreamProducer(broadcast, track, moqjson.StreamOptions{}) - if err != nil { - t.Fatal(err) - } - err = producer.Append(map[string]int{"n": 1}, timestamp) - if err != nil { - t.Fatal(err) - } - if err := producer.Finish(); err != nil { - t.Fatal(err) - } - case "flate snapshot": - producer, err := flate.NewSnapshotProducer(broadcast, track, flate.Options{}) - if err != nil { - t.Fatal(err) - } - if err := producer.Update(payload, timestamp); err != nil { - t.Fatal(err) - } - if err := producer.Finish(); err != nil { - t.Fatal(err) - } - case "flate stream": - producer, err := flate.NewStreamProducer(broadcast, track, flate.Options{}) - if err != nil { - t.Fatal(err) - } - if err := producer.Append(payload, timestamp); err != nil { - t.Fatal(err) - } - if err := producer.Finish(); err != nil { - t.Fatal(err) - } + if err := publishData(mode, broadcast, track, payload, timestamp.at); err != nil { + t.Fatal(err) } frame, err := consumer.ReadFrame(ctx) if err != nil { @@ -98,8 +64,9 @@ func TestDataTimestamps(t *testing.T) { if frame == nil { t.Fatal("missing frame") } - if (frame.Timestamp == nil) != (timestamp == nil) || timestamp != nil && *frame.Timestamp != *timestamp { - t.Fatalf("timestamp = %v, want %v", frame.Timestamp, timestamp) + want := timestamp.at + if (frame.Timestamp == nil) != (want == nil) || want != nil && *frame.Timestamp != *want { + t.Fatalf("timestamp = %+v, want %+v", frame.Timestamp, want) } if mode == "json snapshot" || mode == "json stream" { var value map[string]int @@ -116,3 +83,78 @@ func TestDataTimestamps(t *testing.T) { } } } + +// publishData writes one value at timestamp through the producer mode names, then finishes. +func publishData(mode string, broadcast *moq.BroadcastProducer, track *moq.TrackProducer, payload []byte, timestamp *moq.Timestamp) error { + switch mode { + case "frame": + return track.WriteFrame(moq.Frame{Payload: payload, Timestamp: timestamp}) + case "json snapshot": + producer, err := moqjson.NewSnapshotProducer(broadcast, track, moqjson.SnapshotOptions{}) + if err != nil { + return err + } + if err := producer.Update(map[string]int{"n": 1}, timestamp); err != nil { + return err + } + return producer.Finish() + case "json stream": + producer, err := moqjson.NewStreamProducer(broadcast, track, moqjson.StreamOptions{}) + if err != nil { + return err + } + if err := producer.Append(map[string]int{"n": 1}, timestamp); err != nil { + return err + } + return producer.Finish() + case "flate snapshot": + producer, err := flate.NewSnapshotProducer(broadcast, track, flate.Options{}) + if err != nil { + return err + } + if err := producer.Update(payload, timestamp); err != nil { + return err + } + return producer.Finish() + case "flate stream": + producer, err := flate.NewStreamProducer(broadcast, track, flate.Options{}) + if err != nil { + return err + } + if err := producer.Append(payload, timestamp); err != nil { + return err + } + return producer.Finish() + } + panic("unknown mode " + mode) +} + +// A zero scale, or a value or scale past what the wire carries, is refused rather +// than clamped, from a raw frame and a data producer alike. +func TestTimestampRefused(t *testing.T) { + for _, bad := range []struct { + name string + at moq.Timestamp + }{ + {"zero scale", moq.Timestamp{Value: 1, Scale: 0}}, + {"scale 2^62", moq.Timestamp{Value: 1, Scale: 1 << 62}}, + {"value 2^61", moq.Timestamp{Value: 1 << 61, Scale: 90_000}}, + } { + for _, mode := range []string{"frame", "json stream"} { + t.Run(mode+"/"+bad.name, func(t *testing.T) { + broadcast, err := moq.NewBroadcastProducer() + if err != nil { + t.Fatal(err) + } + defer broadcast.Close() + track, err := broadcast.PublishTrack("data", ninetyKHz()) + if err != nil { + t.Fatal(err) + } + if err := publishData(mode, broadcast, track, []byte("x"), &bad.at); !errors.Is(err, moq.ErrTimeOverflow) { + t.Fatalf("err = %v, want ErrTimeOverflow", err) + } + }) + } + } +} diff --git a/go/wrapper/doc.go b/go/wrapper/doc.go index 4728018d1a0..6d82136bb63 100644 --- a/go/wrapper/doc.go +++ b/go/wrapper/doc.go @@ -5,7 +5,7 @@ // idiomatic Go: context.Context cancellation, Go error returns, and Go 1.23 // range-over-func iterators (iter.Seq2) for live streams. The raw record, // enum, and small object types are re-exported here without the Moq prefix (see types.go), -// records with timestamps carry time.Duration (see records.go), so +// media timestamps are exact Timestamp records (see records.go), so // most programs never need to import the ffi package directly. // // A typical full-duplex client wires a single origin as both publish source diff --git a/go/wrapper/errors.go b/go/wrapper/errors.go index f873990bcb4..92606424e51 100644 --- a/go/wrapper/errors.go +++ b/go/wrapper/errors.go @@ -41,7 +41,7 @@ var ( ErrVideo = ffi.ErrMoqErrorVideo // ErrURL matches a malformed URL passed when connecting or publishing. ErrURL = ffi.ErrMoqErrorUrl - // ErrTimeOverflow matches a timestamp outside the supported range. + // ErrTimeOverflow matches a timestamp value or scale outside the supported range, or a zero scale. ErrTimeOverflow = ffi.ErrMoqErrorTimeOverflow // ErrLogLevel matches an unparseable log level string passed to LogLevel. ErrLogLevel = ffi.ErrMoqErrorLogLevel diff --git a/go/wrapper/example_test.go b/go/wrapper/example_test.go index 8d9694b6aad..1a7c534af48 100644 --- a/go/wrapper/example_test.go +++ b/go/wrapper/example_test.go @@ -4,7 +4,6 @@ import ( "context" "fmt" "log" - "time" "moq.dev/moq" moqmedia "moq.dev/moq/media" @@ -61,7 +60,8 @@ func ExampleClient_CreateBroadcast() { } _ = broadcast.Announce(moq.AnnounceRoute{}) - pts := 20 * time.Millisecond + // 20 ms in, counted on the Opus 48 kHz sample clock. + pts := moq.Timestamp{Value: 960, Scale: 48_000} if err := media.WriteFrame(moq.Frame{Payload: []byte("opus frame"), Timestamp: &pts}); err != nil { log.Fatal(err) } diff --git a/go/wrapper/flate/flate.go b/go/wrapper/flate/flate.go index ef830b4e6f5..a2649027c7e 100644 --- a/go/wrapper/flate/flate.go +++ b/go/wrapper/flate/flate.go @@ -2,8 +2,6 @@ package flate import ( - "time" - "moq.dev/moq" ffi "moq.dev/moq-ffi/moq" "moq.dev/moq/internal/bridge" @@ -30,12 +28,8 @@ func NewSnapshotProducer(broadcast *moq.BroadcastProducer, track *moq.TrackProdu } // Update publishes payload at timestamp on the broadcast clock; nil is untimed. -func (p *SnapshotProducer) Update(payload []byte, timestamp *time.Duration) error { - at, err := bridge.OptionalDuration(timestamp, "timestamp") - if err != nil { - return err - } - return p.inner.Update(payload, at) +func (p *SnapshotProducer) Update(payload []byte, timestamp *moq.Timestamp) error { + return p.inner.Update(payload, timestamp) } // Finish closes the track and retires its catalog entry. @@ -54,12 +48,8 @@ func NewStreamProducer(broadcast *moq.BroadcastProducer, track *moq.TrackProduce } // Append adds payload at timestamp on the broadcast clock; nil is untimed. -func (p *StreamProducer) Append(payload []byte, timestamp *time.Duration) error { - at, err := bridge.OptionalDuration(timestamp, "timestamp") - if err != nil { - return err - } - return p.inner.Append(payload, at) +func (p *StreamProducer) Append(payload []byte, timestamp *moq.Timestamp) error { + return p.inner.Append(payload, timestamp) } // Finish closes the track and retires its catalog entry. diff --git a/go/wrapper/internal/bridge/handles.go b/go/wrapper/internal/bridge/handles.go index 39dc92d85e8..1ed1fbdfeed 100644 --- a/go/wrapper/internal/bridge/handles.go +++ b/go/wrapper/internal/bridge/handles.go @@ -38,21 +38,9 @@ var BroadcastConsumer func(any) *ffi.MoqBroadcastConsumer // TrackRequest returns the handle behind a *moq.TrackRequest. var TrackRequest func(any) *ffi.MoqTrackRequest -// Frame converts a moq.Frame to the generated record. -var Frame func(any) (ffi.MoqFrame, error) - // Subscription converts a *moq.Subscription to the generated record. var Subscription func(any) (*ffi.MoqSubscription, error) -// Duration converts d to microseconds, refusing a negative duration rather -// than letting it wrap when cast to uint64. -func Duration(d time.Duration, name string) (uint64, error) { - if d < 0 { - return 0, fmt.Errorf("negative %s: %v", name, d) - } - return uint64(d.Microseconds()), nil -} - // NonNegative refuses a negative duration, which the generated converter // would panic on rather than return an error. func NonNegative(value *time.Duration, name string) error { @@ -69,15 +57,3 @@ func Rendition(rendition ffi.MoqRendition) error { } return nil } - -// OptionalDuration converts a caller's time to microseconds, preserving absence. -func OptionalDuration(value *time.Duration, name string) (*uint64, error) { - if value == nil { - return nil, nil - } - us, err := Duration(*value, name) - if err != nil { - return nil, err - } - return &us, nil -} diff --git a/go/wrapper/json/json.go b/go/wrapper/json/json.go index 744a7af7c92..60960c65ecb 100644 --- a/go/wrapper/json/json.go +++ b/go/wrapper/json/json.go @@ -15,7 +15,6 @@ import ( stdjson "encoding/json" "fmt" "iter" - "time" "moq.dev/moq" ffi "moq.dev/moq-ffi/moq" @@ -88,16 +87,12 @@ func NewSnapshotProducer(broadcast *moq.BroadcastProducer, track *moq.TrackProdu // Update publishes value at timestamp on the broadcast clock; nil is untimed. // It is a no-op when unchanged. -func (p *SnapshotProducer) Update(value any, timestamp *time.Duration) error { +func (p *SnapshotProducer) Update(value any, timestamp *moq.Timestamp) error { encoded, err := stdjson.Marshal(value) if err != nil { return err } - at, err := bridge.OptionalDuration(timestamp, "timestamp") - if err != nil { - return err - } - return p.inner.Update(string(encoded), at) + return p.inner.Update(string(encoded), timestamp) } // Demand returns a watch-only handle to whether the track has subscribers. @@ -135,16 +130,12 @@ func NewStreamProducer(broadcast *moq.BroadcastProducer, track *moq.TrackProduce } // Append adds one JSON record at timestamp on the broadcast clock; nil is untimed. -func (p *StreamProducer) Append(value any, timestamp *time.Duration) error { +func (p *StreamProducer) Append(value any, timestamp *moq.Timestamp) error { encoded, err := stdjson.Marshal(value) if err != nil { return err } - at, err := bridge.OptionalDuration(timestamp, "timestamp") - if err != nil { - return err - } - return p.inner.Append(string(encoded), at) + return p.inner.Append(string(encoded), timestamp) } // Demand returns a watch-only handle to whether the track has subscribers. @@ -165,22 +156,15 @@ func (p *StreamProducer) Finish() error { type Timed struct { // Value is the JSON document. Value stdjson.RawMessage - // Timestamp is on the broadcast clock, or nil on an untimed track. It is rounded down - // to a whole microsecond, so a tick on a track like 90 kHz may not survive a read and - // republish exactly. - Timestamp *time.Duration + // Timestamp is on the broadcast clock, or nil on an untimed track. + Timestamp *moq.Timestamp } func timed(value *ffi.MoqJsonValue) *Timed { if value == nil { return nil } - out := &Timed{Value: stdjson.RawMessage(value.Value)} - if value.TimestampUs != nil { - at := time.Duration(*value.TimestampUs) * time.Microsecond - out.Timestamp = &at - } - return out + return &Timed{Value: stdjson.RawMessage(value.Value), Timestamp: value.Timestamp} } // SnapshotConsumer receives each reconstructed JSON state. @@ -284,26 +268,18 @@ func NewWindowProducer(track *moq.TrackProducer, options WindowOptions) (*Window } // Push appends one JSON record at timestamp on the broadcast clock; nil is untimed. -func (p *WindowProducer) Push(value any, timestamp *time.Duration) error { +func (p *WindowProducer) Push(value any, timestamp *moq.Timestamp) error { encoded, err := stdjson.Marshal(value) if err != nil { return err } - at, err := bridge.OptionalDuration(timestamp, "timestamp") - if err != nil { - return err - } - return p.inner.Push(string(encoded), at) + return p.inner.Push(string(encoded), timestamp) } // Pop drops count records from the front of the window, clamped to what it holds, // at timestamp on the broadcast clock; nil is untimed. -func (p *WindowProducer) Pop(count uint64, timestamp *time.Duration) error { - at, err := bridge.OptionalDuration(timestamp, "timestamp") - if err != nil { - return err - } - return p.inner.Pop(count, at) +func (p *WindowProducer) Pop(count uint64, timestamp *moq.Timestamp) error { + return p.inner.Pop(count, timestamp) } // Cut closes the open group, so the next edit opens one restating the retained @@ -369,14 +345,14 @@ type TimedWindowEvent struct { // Timestamp is on the broadcast clock, or nil on an untimed track. A record // first learned of from a group's restatement carries that frame's time, not // its original push time. - Timestamp *time.Duration + Timestamp *moq.Timestamp } func timedWindowEvent(value *ffi.MoqJsonWindowTimed) (*TimedWindowEvent, error) { if value == nil { return nil, nil } - out := &TimedWindowEvent{} + out := &TimedWindowEvent{Timestamp: value.Timestamp} switch event := value.Event.(type) { case ffi.MoqJsonWindowEventPush: out.Event = WindowPush{Index: event.Index, Value: stdjson.RawMessage(event.Value)} @@ -387,10 +363,6 @@ func timedWindowEvent(value *ffi.MoqJsonWindowTimed) (*TimedWindowEvent, error) default: return nil, fmt.Errorf("unknown window event: %T", event) } - if value.TimestampUs != nil { - at := time.Duration(*value.TimestampUs) * time.Microsecond - out.Timestamp = &at - } return out, nil } diff --git a/go/wrapper/json/json_test.go b/go/wrapper/json/json_test.go index 14eaf9a1428..9d3727e3afc 100644 --- a/go/wrapper/json/json_test.go +++ b/go/wrapper/json/json_test.go @@ -70,7 +70,7 @@ func TestTracks(t *testing.T) { } defer snapshotConsumer.Cancel() for viewers := 1; viewers <= 4; viewers++ { - at := time.Duration(viewers) * time.Millisecond + at := moq.Timestamp{Value: uint64(viewers) * 1000, Scale: scale} if err := snapshot.Update(map[string]any{"viewers": viewers}, &at); err != nil { t.Fatal(err) } @@ -89,7 +89,7 @@ func TestTracks(t *testing.T) { if decoded["viewers"] != float64(viewers) { t.Fatalf("snapshot = %s, want viewers %d", value.Value, viewers) } - if want := time.Duration(viewers) * time.Millisecond; value.Timestamp == nil || *value.Timestamp != want { + if want := (moq.Timestamp{Value: uint64(viewers) * 1000, Scale: scale}); value.Timestamp == nil || *value.Timestamp != want { t.Fatalf("timestamp = %v, want %v", value.Timestamp, want) } } @@ -149,9 +149,8 @@ func TestWindow(t *testing.T) { } defer windowConsumer.Cancel() - ms := func(n int) *time.Duration { - at := time.Duration(n) * time.Millisecond - return &at + ms := func(n int) *moq.Timestamp { + return &moq.Timestamp{Value: uint64(n) * 1000, Scale: scale} } for n := range 3 { if err := window.Push(map[string]any{"n": n}, ms(n)); err != nil { diff --git a/go/wrapper/media/media.go b/go/wrapper/media/media.go index a88ea9bb01a..a2dc3a27b2c 100644 --- a/go/wrapper/media/media.go +++ b/go/wrapper/media/media.go @@ -85,11 +85,7 @@ type ContainerInit struct { } // MediaFrame is a container-decoded payload, presentation timestamp, and keyframe flag. -type MediaFrame struct { - Payload []byte - Timestamp time.Duration - Keyframe bool -} +type MediaFrame = ffi.MoqMediaFrame // Target is the named or requested track an importer publishes. type Target interface{ target() } @@ -137,9 +133,8 @@ func NewCatalogProducer(broadcast *moq.BroadcastProducer) (*CatalogProducer, err } // Now reads the broadcast clock, fixing it for subsequent media producers. -func (c *CatalogProducer) Now() (time.Duration, error) { - us, err := c.inner.Now() - return time.Duration(us) * time.Microsecond, err +func (c *CatalogProducer) Now() (moq.Timestamp, error) { + return c.inner.Now() } // SetVideoProperties replaces the video properties shared by all renditions. @@ -374,11 +369,7 @@ func (m *TrackProducer) Demand() (*moq.TrackDemand, error) { // WriteFrame appends frame to the media track. The importer derives keyframe status from // the bitstream, so a Frame carries only the payload and its timestamp. func (m *TrackProducer) WriteFrame(frame moq.Frame) error { - f, err := bridge.Frame(frame) - if err != nil { - return err - } - return m.inner.WriteFrame(f) + return m.inner.WriteFrame(frame) } // Discontinuity marks a timeline break, preserving the advertised jitter and delay. @@ -463,14 +454,6 @@ func (m *TrackStreamProducer) Finish() error { return m.inner.Finish() } -// mediaFrame converts the result of a Next call, keeping (nil, nil) for the end. -func mediaFrame(frame *ffi.MoqMediaFrame, err error) (*MediaFrame, error) { - if frame == nil || err != nil { - return nil, err - } - return &MediaFrame{Payload: frame.Payload, Timestamp: time.Duration(frame.TimestampUs) * time.Microsecond, Keyframe: frame.Keyframe}, nil -} - // Read is one encoded frame, a ReadGap, or a ReadEnd, in delivery order. type Read interface{ read() } @@ -479,13 +462,13 @@ type ReadFrame struct{ Frame MediaFrame } // ReadGap is lost media; what follows does not continue it. type ReadGap struct { - Timestamp time.Duration + Timestamp moq.Timestamp Duration time.Duration } // ReadEnd is where a stopped encoder's media stops. Following frames before End // are its remaining media; the first at or past End comes from a fresh encoder. -type ReadEnd struct{ End time.Duration } +type ReadEnd struct{ End moq.Timestamp } func (ReadFrame) read() {} func (ReadGap) read() {} @@ -494,15 +477,11 @@ func (ReadEnd) read() {} func mediaRead(raw ffi.MoqMediaRead) (Read, error) { switch read := raw.(type) { case ffi.MoqMediaReadFrame: - frame, err := mediaFrame(&read.Frame, nil) - if err != nil { - return nil, err - } - return ReadFrame{Frame: *frame}, nil + return ReadFrame{Frame: read.Frame}, nil case ffi.MoqMediaReadGap: - return ReadGap{Timestamp: time.Duration(read.TimestampUs) * time.Microsecond, Duration: read.Duration}, nil + return ReadGap{Timestamp: read.Timestamp, Duration: read.Duration}, nil case ffi.MoqMediaReadEnd: - return ReadEnd{End: time.Duration(read.EndUs) * time.Microsecond}, nil + return ReadEnd{End: read.End}, nil } return nil, fmt.Errorf("unknown media read: %T", raw) } @@ -544,7 +523,7 @@ func (m *GroupConsumer) Sequence() uint64 { // Next returns the next decoded frame, or (nil, nil) when the group ends. func (m *GroupConsumer) Next(ctx context.Context) (*MediaFrame, error) { - return mediaFrame(bridge.Call(ctx, m.inner.Cancel, m.inner.Next)) + return bridge.Call(ctx, m.inner.Cancel, m.inner.Next) } // All ranges over decoded frames until the group ends or the loop breaks. diff --git a/go/wrapper/media/read_test.go b/go/wrapper/media/read_test.go index 1f837a4d5ed..b284cd71e03 100644 --- a/go/wrapper/media/read_test.go +++ b/go/wrapper/media/read_test.go @@ -1,32 +1,35 @@ package media import ( - ffi "moq.dev/moq-ffi/moq" "testing" "time" + + "moq.dev/moq" + ffi "moq.dev/moq-ffi/moq" ) func TestMediaReadPreservesFramesAndBreaks(t *testing.T) { - frame, err := mediaRead(ffi.MoqMediaReadFrame{Frame: ffi.MoqMediaFrame{Payload: []byte("encoded"), TimestampUs: 123456, Keyframe: true}}) + tick := moq.Timestamp{Value: 1, Scale: 90_000} + frame, err := mediaRead(ffi.MoqMediaReadFrame{Frame: ffi.MoqMediaFrame{Payload: []byte("encoded"), Timestamp: tick, Keyframe: true}}) if err != nil { t.Fatal(err) } value, ok := frame.(ReadFrame) - if !ok || string(value.Frame.Payload) != "encoded" || value.Frame.Timestamp != 123456*time.Microsecond || !value.Frame.Keyframe { + if !ok || string(value.Frame.Payload) != "encoded" || value.Frame.Timestamp != tick || !value.Frame.Keyframe { t.Fatalf("frame: %#v", frame) } - gap, err := mediaRead(ffi.MoqMediaReadGap{TimestampUs: 123456, Duration: 78901 * time.Microsecond}) + gap, err := mediaRead(ffi.MoqMediaReadGap{Timestamp: tick, Duration: 78901 * time.Microsecond}) if err != nil { t.Fatal(err) } - if gap != (ReadGap{Timestamp: 123456 * time.Microsecond, Duration: 78901 * time.Microsecond}) { + if gap != (ReadGap{Timestamp: tick, Duration: 78901 * time.Microsecond}) { t.Fatalf("gap: %#v", gap) } - end, err := mediaRead(ffi.MoqMediaReadEnd{EndUs: 202357}) + end, err := mediaRead(ffi.MoqMediaReadEnd{End: tick}) if err != nil { t.Fatal(err) } - if end != (ReadEnd{End: 202357 * time.Microsecond}) { + if end != (ReadEnd{End: tick}) { t.Fatalf("end: %#v", end) } } diff --git a/go/wrapper/moq_test.go b/go/wrapper/moq_test.go index 9f7358e239e..6c311103124 100644 --- a/go/wrapper/moq_test.go +++ b/go/wrapper/moq_test.go @@ -111,7 +111,7 @@ func TestDynamicBroadcastRequest(t *testing.T) { if err != nil { t.Fatal(err) } - if frame == nil || string(frame.Payload) != string(payload) || frame.Timestamp == nil || *frame.Timestamp != 0 { + if frame == nil || string(frame.Payload) != string(payload) || frame.Timestamp == nil || *frame.Timestamp != *ts(0) { t.Fatalf("frame = %+v, want payload=%q ts=0", frame, payload) } @@ -132,7 +132,7 @@ func TestPublishAudioLifecycle(t *testing.T) { if err != nil { t.Fatal(err) } - if err := media.WriteFrame(moq.Frame{Payload: []byte("opus frame"), Timestamp: ts(1000 * time.Microsecond)}); err != nil { + if err := media.WriteFrame(moq.Frame{Payload: []byte("opus frame"), Timestamp: ts(1000)}); err != nil { t.Fatal(err) } if err := media.Finish(); err != nil { @@ -222,7 +222,7 @@ func TestEncodeAudioWithOpusObject(t *testing.T) { codec.Destroy() } // One 20 ms Opus frame of silence at 48 kHz mono. - if err := producer.Write(moqaudio.Frame{Data: make([]byte, 960*4)}); err != nil { + if err := producer.Write(moqaudio.Frame{Timestamp: moq.Timestamp{Scale: 48_000}, Data: make([]byte, 960*4)}); err != nil { t.Fatal(err) } if !codecFirst { @@ -300,7 +300,7 @@ func TestAudioConsumerDelay(t *testing.T) { // Two 20 ms Opus frames of silence at 48 kHz mono. for i := range 2 { - if err := audio.Write(moqaudio.Frame{Timestamp: time.Duration(i) * 20 * time.Millisecond, Data: make([]byte, 960*4)}); err != nil { + if err := audio.Write(moqaudio.Frame{Timestamp: moq.Timestamp{Value: uint64(i) * 960, Scale: 48_000}, Data: make([]byte, 960*4)}); err != nil { t.Fatal(err) } } @@ -352,7 +352,7 @@ func TestEncodeAudioFrameDurations(t *testing.T) { t.Fatal(err) } // 2.5 ms of silence at 48 kHz mono f32: exactly one encoded frame. - if err := fine.Write(moqaudio.Frame{Data: make([]byte, 120*4)}); err != nil { + if err := fine.Write(moqaudio.Frame{Timestamp: moq.Timestamp{Scale: 48_000}, Data: make([]byte, 120*4)}); err != nil { t.Fatal(err) } if err := fine.Finish(); err != nil { @@ -438,7 +438,7 @@ func testDecodeVideoFrame(t *testing.T, surface bool) { t.Fatal(err) } for i := range 10 { - if err := video.Write(moqvideo.Frame{Timestamp: time.Duration(i) * 33333 * time.Microsecond, Data: rgba}); err != nil { + if err := video.Write(moqvideo.Frame{Timestamp: moq.Timestamp{Value: uint64(i) * 1001, Scale: 30_000}, Data: rgba}); err != nil { t.Fatal(err) } } @@ -469,7 +469,7 @@ func testDecodeVideoFrame(t *testing.T, surface bool) { // Keep the encoder fed so the decoder sees frames after it joined. for i := 10; i < 40; i++ { - if err := video.Write(moqvideo.Frame{Timestamp: time.Duration(i) * 33333 * time.Microsecond, Data: rgba}); err != nil { + if err := video.Write(moqvideo.Frame{Timestamp: moq.Timestamp{Value: uint64(i) * 1001, Scale: 30_000}, Data: rgba}); err != nil { t.Fatal(err) } } @@ -597,7 +597,7 @@ func TestFetchGroupAndServeDynamicMiss(t *testing.T) { if err != nil { t.Fatal(err) } - if err := produced.WriteFrame(moq.Frame{Payload: []byte("archive"), Timestamp: ts(7 * 20_000 * time.Microsecond)}); err != nil { + if err := produced.WriteFrame(moq.Frame{Payload: []byte("archive"), Timestamp: ts(7 * 20_000)}); err != nil { t.Fatal(err) } if err := produced.Finish(); err != nil { @@ -686,7 +686,7 @@ func TestLocalPublishConsumeAudio(t *testing.T) { defer mediaConsumer.Cancel() payload := []byte("opus audio payload data") - if err := media.WriteFrame(moq.Frame{Payload: payload, Timestamp: ts(1_000_000 * time.Microsecond)}); err != nil { + if err := media.WriteFrame(moq.Frame{Payload: payload, Timestamp: ts(1_000_000)}); err != nil { t.Fatal(err) } @@ -699,7 +699,7 @@ func TestLocalPublishConsumeAudio(t *testing.T) { t.Fatalf("expected a media frame, got %T", read) } frame := &value.Frame - if string(frame.Payload) != string(payload) || uint64(frame.Timestamp.Microseconds()) != 1_000_000 { + if string(frame.Payload) != string(payload) || moq.TimestampToDuration(frame.Timestamp) != time.Second { t.Fatalf("frame = %+v, want payload=%q ts=1000000", frame, payload) } @@ -725,7 +725,7 @@ func TestLocalPublishConsumeAudio(t *testing.T) { if err != nil { t.Fatal(err) } - if frame == nil || string(frame.Payload) != string(payload) || uint64(frame.Timestamp.Microseconds()) != 1_000_000 { + if frame == nil || string(frame.Payload) != string(payload) || moq.TimestampToDuration(frame.Timestamp) != time.Second { t.Fatalf("decoded frame = %+v, want payload=%q ts=1000000", frame, payload) } } @@ -748,7 +748,7 @@ func TestTrackPublishConsume(t *testing.T) { } defer consumer.Cancel() - if err := track.WriteFrame(moq.Frame{Payload: []byte("hello"), Timestamp: ts(12_345 * time.Microsecond)}); err != nil { + if err := track.WriteFrame(moq.Frame{Payload: []byte("hello"), Timestamp: ts(12_345)}); err != nil { t.Fatal(err) } @@ -759,7 +759,7 @@ func TestTrackPublishConsume(t *testing.T) { if frame == nil { t.Fatal("expected a frame") } - if string(frame.Payload) != "hello" || frame.Timestamp == nil || *frame.Timestamp != 12_345*time.Microsecond { + if string(frame.Payload) != "hello" || frame.Timestamp == nil || *frame.Timestamp != *ts(12_345) { t.Fatalf("frame = %+v, want payload=hello ts=12345", frame) } @@ -772,7 +772,7 @@ func TestTrackPublishConsume(t *testing.T) { t.Fatal(err) } defer groupConsumer.Cancel() - if err := group.WriteFrame(moq.Frame{Payload: []byte("group"), Timestamp: ts(23_456 * time.Microsecond)}); err != nil { + if err := group.WriteFrame(moq.Frame{Payload: []byte("group"), Timestamp: ts(23_456)}); err != nil { t.Fatal(err) } if err := group.Finish(); err != nil { @@ -785,7 +785,7 @@ func TestTrackPublishConsume(t *testing.T) { if frame == nil { t.Fatal("expected a group frame") } - if string(frame.Payload) != "group" || frame.Timestamp == nil || *frame.Timestamp != 23_456*time.Microsecond { + if string(frame.Payload) != "group" || frame.Timestamp == nil || *frame.Timestamp != *ts(23_456) { t.Fatalf("frame = %+v, want payload=group ts=23456", frame) } } @@ -807,7 +807,7 @@ func TestAscendingSubscriptionReadsCachedBacklogOldestFirst(t *testing.T) { if err != nil { t.Fatal(err) } - if err := group.WriteFrame(moq.Frame{Payload: []byte("x"), Timestamp: ts(time.Duration(i) * time.Millisecond)}); err != nil { + if err := group.WriteFrame(moq.Frame{Payload: []byte("x"), Timestamp: ts(uint64(i) * 1000)}); err != nil { t.Fatal(err) } if err := group.Finish(); err != nil { @@ -868,7 +868,7 @@ func TestReadFrameSkipsEmptyThenPopulatedGroups(t *testing.T) { if err := empty.Finish(); err != nil { t.Fatal(err) } - if err := track.WriteFrame(moq.Frame{Payload: []byte("populated"), Timestamp: ts(2_000 * time.Microsecond)}); err != nil { + if err := track.WriteFrame(moq.Frame{Payload: []byte("populated"), Timestamp: ts(2_000)}); err != nil { t.Fatal(err) } @@ -876,7 +876,7 @@ func TestReadFrameSkipsEmptyThenPopulatedGroups(t *testing.T) { if err != nil { t.Fatal(err) } - if frame == nil || string(frame.Payload) != "populated" || frame.Timestamp == nil || *frame.Timestamp != 2_000*time.Microsecond { + if frame == nil || string(frame.Payload) != "populated" || frame.Timestamp == nil || *frame.Timestamp != *ts(2_000) { t.Fatalf("frame = %+v, want payload=populated ts=2000", frame) } } @@ -986,7 +986,7 @@ func TestDynamicTrackRequest(t *testing.T) { if err != nil { t.Fatal(err) } - if frame == nil || string(frame.Payload) != string(payload) || frame.Timestamp == nil || *frame.Timestamp != 0 { + if frame == nil || string(frame.Payload) != string(payload) || frame.Timestamp == nil || *frame.Timestamp != *ts(0) { t.Fatalf("frame = %+v, want payload=%q ts=0", frame, payload) } if err := track.Finish(); err != nil { @@ -1066,7 +1066,7 @@ func TestDynamicTrackRequestCanPublishAudio(t *testing.T) { defer mediaConsumer.Cancel() payload := []byte("dynamic opus frame") - if err := media.WriteFrame(moq.Frame{Payload: payload, Timestamp: ts(20_000 * time.Microsecond)}); err != nil { + if err := media.WriteFrame(moq.Frame{Payload: payload, Timestamp: ts(20_000)}); err != nil { t.Fatal(err) } @@ -1079,7 +1079,7 @@ func TestDynamicTrackRequestCanPublishAudio(t *testing.T) { t.Fatalf("expected a media frame, got %T", read) } frame := &value.Frame - if string(frame.Payload) != string(payload) || uint64(frame.Timestamp.Microseconds()) != 20_000 { + if string(frame.Payload) != string(payload) || moq.TimestampToDuration(frame.Timestamp) != 20*time.Millisecond { t.Fatalf("frame = %+v, want payload=%q ts=20000", frame, payload) } // The explicit pause marker is an encoder end even while the track stays open. @@ -1093,7 +1093,7 @@ func TestDynamicTrackRequestCanPublishAudio(t *testing.T) { if err != nil { t.Fatal(err) } - if value, ok := end.(moqmedia.ReadEnd); !ok || value.End != 20_000*time.Microsecond { + if value, ok := end.(moqmedia.ReadEnd); !ok || moq.TimestampToDuration(value.End) != 20*time.Millisecond { t.Fatalf("expected encoder end, got %T", end) } if next, err := mediaConsumer.Next(ctx); next != nil || err != nil { @@ -1696,7 +1696,8 @@ func TestClosingAPreparedAnswerRefusesTheRequest(t *testing.T) { // us is a raw frame's optional timestamp in microseconds. func us(v uint64) *uint64 { return &v } -func ts(d time.Duration) *time.Duration { return &d } +// ts is a presentation time in microseconds, the scale timedInfo declares. +func ts(us uint64) *moq.Timestamp { return &moq.Timestamp{Value: us, Scale: 1_000_000} } // timedInfo declares the microsecond timeline used by timed raw fixtures. func timedInfo() *moq.TrackInfo { diff --git a/go/wrapper/publish.go b/go/wrapper/publish.go index 9d7722985c9..00527f04382 100644 --- a/go/wrapper/publish.go +++ b/go/wrapper/publish.go @@ -220,21 +220,13 @@ func (t *TrackProducer) CreateGroup(sequence uint64) (*GroupProducer, error) { // WriteFrame writes frame as a single-frame group. func (t *TrackProducer) WriteFrame(frame Frame) error { - f, err := frame.ffi() - if err != nil { - return err - } - return t.inner.WriteFrame(f) + return t.inner.WriteFrame(frame) } // AppendDatagram sends frame as a best-effort datagram and returns the sequence number // assigned to it. Payloads are capped at 1200 bytes. There is no stream fallback. func (t *TrackProducer) AppendDatagram(frame Frame) (uint64, error) { - f, err := frame.ffi() - if err != nil { - return 0, err - } - return t.inner.AppendDatagram(f) + return t.inner.AppendDatagram(frame) } // Abort closes the track with an application error code. @@ -288,11 +280,7 @@ func (g *GroupProducer) Consume() (*GroupConsumer, error) { // WriteFrame appends frame to the group. func (g *GroupProducer) WriteFrame(frame Frame) error { - f, err := frame.ffi() - if err != nil { - return err - } - return g.inner.WriteFrame(f) + return g.inner.WriteFrame(frame) } // Finish marks the group complete. The handle remains so Abort can still run. diff --git a/go/wrapper/records.go b/go/wrapper/records.go index f6f6ab0a5a0..e26b22f6b91 100644 --- a/go/wrapper/records.go +++ b/go/wrapper/records.go @@ -1,66 +1,51 @@ package moq import ( + "fmt" "math" + "math/bits" "time" ffi "moq.dev/moq-ffi/moq" "moq.dev/moq/internal/bridge" ) -// moq-ffi spells media timestamps as integer microseconds. These records mirror -// the generated ones with time.Duration timestamps and convert at the boundary. +// Timestamp is an exact media time: Value units at Scale units per second, with Value +// at most 2^61 - 1 and Scale non-zero and at most 2^62 - 1. A read carries the track's +// scale, so a tick such as 90 kHz survives a read and republish exactly. +type Timestamp = ffi.MoqTimestamp -// fromMicros saturates past time.Duration's ~292 years rather than wrapping to -// a negative duration. -func fromMicros(us uint64) time.Duration { - if us > uint64(math.MaxInt64/int64(time.Microsecond)) { - return time.Duration(math.MaxInt64) +// TimestampFromDuration converts d exactly, at nanosecond scale, refusing a negative d. +func TimestampFromDuration(d time.Duration) (Timestamp, error) { + if d < 0 { + return Timestamp{}, fmt.Errorf("negative timestamp: %v", d) } - return time.Duration(us) * time.Microsecond + return Timestamp{Value: uint64(d), Scale: uint64(time.Second)}, nil } -func optFromMicros(us *uint64) *time.Duration { - if us == nil { - return nil +// TimestampToDuration rounds t to the nearest nanosecond, saturating past +// time.Duration's ~292 years. It panics on a zero Scale, which no read returns. +func TimestampToDuration(t Timestamp) time.Duration { + hi, lo := bits.Mul64(t.Value, uint64(time.Second)) + lo, carry := bits.Add64(lo, t.Scale/2, 0) + hi += carry + if hi >= t.Scale { + return time.Duration(math.MaxInt64) + } + ns, _ := bits.Div64(hi, lo, t.Scale) + if ns > math.MaxInt64 { + return time.Duration(math.MaxInt64) } - d := fromMicros(*us) - return &d + return time.Duration(ns) } // Frame is a raw track frame: a payload and its presentation timestamp. // Timestamp is nil on an untimed track, on both publish and receive. -type Frame struct { - Payload []byte - Timestamp *time.Duration -} - -func (f Frame) ffi() (ffi.MoqFrame, error) { - us, err := bridge.OptionalDuration(f.Timestamp, "timestamp") - return ffi.MoqFrame{Payload: f.Payload, TimestampUs: us}, err -} - -func frameFromFFI(f *ffi.MoqFrame) *Frame { - if f == nil { - return nil - } - return &Frame{Payload: f.Payload, Timestamp: optFromMicros(f.TimestampUs)} -} +type Frame = ffi.MoqFrame // Datagram is a best-effort track datagram as received: sequence number, timestamp // (nil from an untimed track), and payload. -type Datagram struct { - Sequence uint64 - Timestamp *time.Duration - Payload []byte -} - -func datagramFromFFI(d *ffi.MoqDatagram) *Datagram { - if d == nil { - return nil - } - return &Datagram{Sequence: d.Sequence, Timestamp: optFromMicros(d.TimestampUs), Payload: d.Payload} -} +type Datagram = ffi.MoqDatagram // Subscription holds subscriber-side delivery preferences: priority, the max delay // a non-latest group may fall behind before it is skipped (zero skips at once, nil diff --git a/go/wrapper/records_internal_test.go b/go/wrapper/records_internal_test.go index ed4162a166d..594f1d0f3c4 100644 --- a/go/wrapper/records_internal_test.go +++ b/go/wrapper/records_internal_test.go @@ -6,22 +6,46 @@ import ( "time" ) -// A peer's delay or max age can pass time.Duration's ~292 years, which must read as -// the longest duration rather than wrap to a negative one that is already expired. -func TestFromMicrosSaturates(t *testing.T) { - limit := uint64(math.MaxInt64 / int64(time.Microsecond)) +// A duration converts at its own nanosecond scale, so nothing rounds on the way in. +func TestTimestampFromDuration(t *testing.T) { + got, err := TimestampFromDuration(1500 * time.Millisecond) + if err != nil { + t.Fatal(err) + } + if want := (Timestamp{Value: 1_500_000_000, Scale: 1_000_000_000}); got != want { + t.Fatalf("TimestampFromDuration(1.5s) = %+v, want %+v", got, want) + } + if got := TimestampToDuration(got); got != 1500*time.Millisecond { + t.Fatalf("round trip = %v, want 1.5s", got) + } + if _, err := TimestampFromDuration(-time.Nanosecond); err == nil { + t.Fatal("negative duration converted") + } +} + +// Converting to a duration rounds to the nearest nanosecond, and a time past +// time.Duration's ~292 years reads as the longest duration rather than wrapping. +func TestTimestampToDuration(t *testing.T) { cases := []struct { - us uint64 + in Timestamp want time.Duration }{ - {us: 1, want: time.Microsecond}, - {us: limit, want: time.Duration(limit) * time.Microsecond}, - {us: limit + 1, want: time.Duration(math.MaxInt64)}, - {us: math.MaxUint64, want: time.Duration(math.MaxInt64)}, + {Timestamp{Value: 0, Scale: 90_000}, 0}, + // 11111.1 ns rounds down. + {Timestamp{Value: 1, Scale: 90_000}, 11_111}, + // 666666666.6 ns rounds up. + {Timestamp{Value: 2, Scale: 3}, 666_666_667}, + // Half a nanosecond rounds up. + {Timestamp{Value: 1, Scale: 2_000_000_000}, 1}, + {Timestamp{Value: 1001, Scale: 30_000}, 33_366_667}, + {Timestamp{Value: math.MaxInt64, Scale: 1_000_000_000}, math.MaxInt64}, + {Timestamp{Value: math.MaxInt64/1000 + 1, Scale: 1_000_000}, math.MaxInt64}, + {Timestamp{Value: 1<<61 - 1, Scale: 1}, math.MaxInt64}, + {Timestamp{Value: math.MaxUint64, Scale: math.MaxUint64}, time.Second}, } for _, c := range cases { - if got := fromMicros(c.us); got != c.want { - t.Errorf("fromMicros(%d) = %v, want %v", c.us, got, c.want) + if got := TimestampToDuration(c.in); got != c.want { + t.Errorf("TimestampToDuration(%+v) = %d, want %d", c.in, got, c.want) } } } diff --git a/go/wrapper/runtime_bench_test.go b/go/wrapper/runtime_bench_test.go index 0e6517e605d..6b85bdc6945 100644 --- a/go/wrapper/runtime_bench_test.go +++ b/go/wrapper/runtime_bench_test.go @@ -198,7 +198,7 @@ func benchThroughput(b *testing.B, c benchCase) { done <- err return } - want := time.Duration(n*frames+f) * time.Microsecond + want := moq.Timestamp{Value: uint64(n*frames + f), Scale: 1_000_000} if frame == nil || !bytes.Equal(frame.Payload, payload) || frame.Timestamp == nil || *frame.Timestamp != want { done <- fmt.Errorf("missing, reordered, or corrupt frame %d of round %d", f, n) return @@ -213,7 +213,7 @@ func benchThroughput(b *testing.B, c benchCase) { return err } for f := range frames { - timestamp := time.Duration(n*frames+f) * time.Microsecond + timestamp := moq.Timestamp{Value: uint64(n*frames + f), Scale: 1_000_000} if err := group.WriteFrame(moq.Frame{Payload: payload, Timestamp: ×tamp}); err != nil { return err } diff --git a/go/wrapper/subscribe.go b/go/wrapper/subscribe.go index e0f661387c9..c1906206d83 100644 --- a/go/wrapper/subscribe.go +++ b/go/wrapper/subscribe.go @@ -86,8 +86,7 @@ func (g *GroupConsumer) Sequence() uint64 { // ReadFrame returns the next raw frame, or (nil, nil) when the group ends. func (g *GroupConsumer) ReadFrame(ctx context.Context) (*Frame, error) { - frame, err := bridge.Call(ctx, g.inner.Cancel, g.inner.ReadFrame) - return frameFromFFI(frame), err + return bridge.Call(ctx, g.inner.Cancel, g.inner.ReadFrame) } // All ranges over raw frames until the group ends or the loop breaks. @@ -141,15 +140,13 @@ func (t *TrackConsumer) group(ctx context.Context, next func(context.Context) (* // Cancelling the context cancels this consumer, not just this call: see // package docs. func (t *TrackConsumer) ReadFrame(ctx context.Context) (*Frame, error) { - frame, err := bridge.Call(ctx, t.inner.Cancel, t.inner.ReadFrame) - return frameFromFFI(frame), err + return bridge.Call(ctx, t.inner.Cancel, t.inner.ReadFrame) } // RecvDatagram returns the next best-effort datagram in arrival order, or // (nil, nil) when the track ends. func (t *TrackConsumer) RecvDatagram(ctx context.Context) (*Datagram, error) { - datagram, err := bridge.Call(ctx, t.inner.Cancel, t.inner.RecvDatagram) - return datagramFromFFI(datagram), err + return bridge.Call(ctx, t.inner.Cancel, t.inner.RecvDatagram) } // Info returns the publisher-side track properties learned during subscription. @@ -195,9 +192,9 @@ type VideoDecodedFrame struct { inner *ffi.MoqVideoDecodedFrame } -// TimestampUs is the presentation timestamp in microseconds. -func (f *VideoDecodedFrame) TimestampUs() uint64 { - return f.inner.TimestampUs() +// Timestamp is the presentation timestamp. +func (f *VideoDecodedFrame) Timestamp() Timestamp { + return f.inner.Timestamp() } // Width is the decoded width in pixels. diff --git a/go/wrapper/types.go b/go/wrapper/types.go index a8d36371723..2519d562b5a 100644 --- a/go/wrapper/types.go +++ b/go/wrapper/types.go @@ -19,7 +19,7 @@ type ( AudioEncoderOutput = ffi.MoqAudioEncoderOutput // AudioSampleFormat is a raw PCM sample layout, mirroring WebCodecs AudioData.format. AudioSampleFormat = ffi.MoqAudioSampleFormat - // AudioFrame is one audio frame: PCM payload plus a presentation timestamp in microseconds. + // AudioFrame is one audio frame: PCM payload plus a presentation Timestamp. AudioFrame = ffi.MoqAudioFrame // ConnectionPhase is a connection lifecycle transition reported by Session.State. ConnectionPhase = ffi.MoqConnectionPhase @@ -64,7 +64,7 @@ type ( AnchorAbsolute = ffi.MoqAnchorAbsolute // AnchorRelative is the group Groups before the latest one, clamped to group 0: 0 is the latest. AnchorRelative = ffi.MoqAnchorRelative - // AnchorTime is the group containing TimestampUs, a presentation time in microseconds. + // AnchorTime is the group containing a presentation Timestamp. AnchorTime = ffi.MoqAnchorTime // Order is which of a subscription's pending groups the publisher sends first. Order = ffi.MoqOrder @@ -82,7 +82,7 @@ type ( VideoEncoderInput = ffi.MoqVideoEncoderInput // VideoEncoderOutput configures the video codec, bitrate, keyframe interval, and backend preference. VideoEncoderOutput = ffi.MoqVideoEncoderOutput - // VideoFrame is one raw video frame: pixels in the configured layout plus a presentation timestamp in microseconds. + // VideoFrame is one raw video frame: pixels in the configured layout plus a presentation Timestamp. VideoFrame = ffi.MoqVideoFrame // VideoEncoderKind selects the encoder implementation. Build one with // AutoEncoder, HardwareEncoder, SoftwareEncoder, or NamedEncoder. diff --git a/go/wrapper/video/video.go b/go/wrapper/video/video.go index 919bb268f5f..74a058f06a1 100644 --- a/go/wrapper/video/video.go +++ b/go/wrapper/video/video.go @@ -7,7 +7,6 @@ import ( "iter" "time" - "moq.dev/moq" ffi "moq.dev/moq-ffi/moq" "moq.dev/moq/internal/bridge" @@ -39,26 +38,10 @@ type Gop = ffi.MoqVideoGop func Keyframe(interval uint32) Gop { return ffi.MoqVideoGopKeyframe{Interval: interval} } // Frame is one raw picture with its presentation timestamp. -type Frame struct { - Timestamp time.Duration - Data []byte -} - -func (f Frame) ffi() (ffi.MoqVideoFrame, error) { - us, err := bridge.Duration(f.Timestamp, "video timestamp") - return ffi.MoqVideoFrame{TimestampUs: us, Data: f.Data}, err -} +type Frame = ffi.MoqVideoFrame // Packet is one encoded access unit from an Encoder. -type Packet struct { - Timestamp time.Duration - Data []byte - Keyframe bool -} - -func packet(raw ffi.MoqVideoPacket) Packet { - return Packet{Timestamp: time.Duration(raw.TimestampUs) * time.Microsecond, Data: raw.Data, Keyframe: raw.Keyframe} -} +type Packet = ffi.MoqVideoPacket // DecoderOutput configures an optional resize, a max delay, and whether frames keep the decoder's surface (macOS only). type DecoderOutput struct { @@ -119,11 +102,7 @@ func (p *Producer) Demand() (*moq.TrackDemand, error) { // Write encodes and publishes one raw picture in the configured input layout. func (p *Producer) Write(value Frame) error { - raw, err := value.ffi() - if err != nil { - return err - } - return p.inner.Write(raw) + return p.inner.Write(value) } // Cut starts a new group at the next written picture. @@ -156,22 +135,9 @@ func NewEncoder(input EncoderInput, output EncoderOutput) (*Encoder, error) { return &Encoder{inner}, nil } -func packets(raw []ffi.MoqVideoPacket) []Packet { - out := make([]Packet, len(raw)) - for i := range raw { - out[i] = packet(raw[i]) - } - return out -} - // Encode encodes one picture, returning any access units now available. func (e *Encoder) Encode(value Frame) ([]Packet, error) { - raw, err := value.ffi() - if err != nil { - return nil, err - } - result, err := e.inner.Encode(raw) - return packets(result), err + return e.inner.Encode(value) } // Cut forces the next encoded picture to start a new group. @@ -181,10 +147,10 @@ func (e *Encoder) Cut() error { return e.inner.Cut() } func (e *Encoder) SetBitrate(value uint64) error { return e.inner.SetBitrate(value) } // Flush drains buffered access units and keeps the encoder open. -func (e *Encoder) Flush() ([]Packet, error) { raw, err := e.inner.Flush(); return packets(raw), err } +func (e *Encoder) Flush() ([]Packet, error) { return e.inner.Flush() } // Finish drains and closes the encoder. -func (e *Encoder) Finish() ([]Packet, error) { raw, err := e.inner.Finish(); return packets(raw), err } +func (e *Encoder) Finish() ([]Packet, error) { return e.inner.Finish() } // Consumer subscribes to a video rendition and yields decoded frames. type Consumer struct{ inner *ffi.MoqVideoConsumer } @@ -215,7 +181,7 @@ type ReadFrame struct { // loss precedes it, and what follows does not continue it. type ReadGap struct { // Timestamp is the furthest presentation point already read. - Timestamp time.Duration + Timestamp moq.Timestamp // Duration is an upper bound on how long until the next picture resumes. Duration time.Duration } @@ -225,7 +191,7 @@ type ReadGap struct { // fresh encoder. type ReadEnd struct { // End is where the stopped encoder's media stops. - End time.Duration + End moq.Timestamp } func (ReadFrame) read() {} @@ -253,9 +219,9 @@ func (d *Consumer) Next(ctx context.Context) (Read, error) { case ffi.MoqVideoReadFrame: return ReadFrame{Frame: bridge.VideoDecodedFrame(read.Frame).(*moq.VideoDecodedFrame)}, nil case ffi.MoqVideoReadGap: - return ReadGap{Timestamp: time.Duration(read.TimestampUs) * time.Microsecond, Duration: read.Duration}, nil + return ReadGap{Timestamp: read.Timestamp, Duration: read.Duration}, nil case ffi.MoqVideoReadEnd: - return ReadEnd{End: time.Duration(read.EndUs) * time.Microsecond}, nil + return ReadEnd{End: read.End}, nil } return nil, fmt.Errorf("unknown video read: %T", *raw) } diff --git a/kt/README.md b/kt/README.md index 4c53ba75d8b..94ff160561c 100644 --- a/kt/README.md +++ b/kt/README.md @@ -58,9 +58,9 @@ The `dev.moq` package is intentionally thin: Kotlin has extension functions, so - **Flow extensions** (`Flows.kt`): `updates()`, `groups()`, and `frames()` turn the pull-based consumers into coroutine `Flow`s with cancellation wired through. - **Media** (`dev.moq.media`): catalog, importers, and container consumers, with `catalog(broadcast)` for a one-shot catalog read and `frames()` for container-decoded media. - **Fetched media**: `dev.moq.media.GroupConsumer.fetch(...).frames()` streams the decoded frames of one retained group, then completes. `dev.moq.media.GroupConsumer(group, container)` decodes a raw group instead, such as one from `recvGroup()` for arrival-order reads. -- **Timestamp extensions** (`Durations.kt`): the FFI carries media timestamps as microsecond integers, so `frame.timestamp` and its siblings read back as a `kotlin.time.Duration`. Durations such as `stats.rtt` are already `java.time.Duration`. +- **Timestamp conversions** (`Timestamp.kt`): media timestamps are exact `Timestamp(value, scale)` records. `Duration.toTimestamp()` builds one exactly at nanosecond scale, and `Timestamp.toDuration()` reads one back as a `kotlin.time.Duration`, rounded to the nearest nanosecond. Durations such as `stats.rtt` are already `java.time.Duration`. - **`logLevel(...)`**: configures native Rust tracing without importing the raw bindings package. -- **Raw datagrams**: `TrackProducer.appendDatagram(Frame(payload, timestampUs))` sends one best-effort frame and returns its sequence; `TrackConsumer.recvDatagram()` and `datagrams()` receive them. Payloads are capped at 1200 bytes, require a datagram-capable transport plus lite-05 or newer moq-lite or moq-transport, and have no stream fallback. +- **Raw datagrams**: `TrackProducer.appendDatagram(Frame(payload, timestamp))` sends one best-effort frame and returns its sequence; `TrackConsumer.recvDatagram()` and `datagrams()` receive them. Payloads are capped at 1200 bytes, require a datagram-capable transport plus lite-05 or newer moq-lite or moq-transport, and have no stream fallback. - **`MoqException.isShutdown`** (`Errors.kt`): true for the graceful `Cancelled`/`Closed` cases. ## Versioning @@ -95,7 +95,7 @@ kt/ moq/ build.gradle.kts Pure-Kotlin wrapper; coordinates dev.moq:moq src/ - jvmAndAndroidMain/kotlin/dev/moq/ Wrapper sources (Moq, Server, Aliases, Flows, Durations, Errors) + jvmAndAndroidMain/kotlin/dev/moq/ Wrapper sources (Moq, Server, Aliases, Flows, Timestamp, Errors) jvmAndAndroidTest/ Facade smoke test ``` diff --git a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Aliases.kt b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Aliases.kt index 19d384bf4c8..ebe3b6f59e1 100644 --- a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Aliases.kt +++ b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Aliases.kt @@ -99,6 +99,8 @@ typealias GroupConsumer = uniffi.moq.MoqGroupConsumer typealias Datagram = uniffi.moq.MoqDatagram /** A payload plus the timestamp it should be presented at. */ typealias Frame = uniffi.moq.MoqFrame +/** An exact media timestamp: `value` units at `scale` units per second. */ +typealias Timestamp = uniffi.moq.MoqTimestamp /** How a broadcast advertises its exact path: its static production cost (lower wins) and the publisher epoch it serves (null when unknown). */ typealias AnnounceRoute = uniffi.moq.MoqAnnounceRoute /** An observed path-prefix route: the publisher epoch it serves (null when unknown), relay hop ids (oldest first), and static production and link cost (lower wins). */ @@ -113,7 +115,7 @@ typealias Anchor = uniffi.moq.MoqAnchor typealias AnchorAbsolute = uniffi.moq.MoqAnchor.Absolute /** The group `groups` before the latest one, clamped to group 0: 0 is the latest. */ typealias AnchorRelative = uniffi.moq.MoqAnchor.Relative -/** The group containing `timestampUs`, a presentation time in microseconds. */ +/** The group containing `timestamp`, a presentation time. */ typealias AnchorTime = uniffi.moq.MoqAnchor.Time /** Which pending group the publisher sends first: `ASCENDING` or `DESCENDING`. */ typealias Order = uniffi.moq.MoqOrder diff --git a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Durations.kt b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Durations.kt deleted file mode 100644 index dc34a9985a0..00000000000 --- a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Durations.kt +++ /dev/null @@ -1,30 +0,0 @@ -package dev.moq - -import kotlin.time.Duration -import kotlin.time.Duration.Companion.microseconds - -// The FFI surface carries media timestamps as microsecond integers; durations -// already cross as java.time.Duration. Read the timestamps back as a Duration. -// These are extension properties on the typealiased records, so the `*Us` -// fields stay available for anyone building a record to send back across the -// boundary. - -/** Presentation timestamp, or null for an untimed frame. */ -val Frame.timestamp: Duration? - get() = timestampUs?.toLong()?.microseconds - -/** Presentation timestamp, or null for an untimed datagram. */ -val Datagram.timestamp: Duration? - get() = timestampUs?.toLong()?.microseconds - -/** Presentation timestamp of the first sample. */ -val AudioFrame.timestamp: Duration - get() = timestampUs.toLong().microseconds - -/** Presentation timestamp. */ -val VideoFrame.timestamp: Duration - get() = timestampUs.toLong().microseconds - -/** Presentation timestamp. */ -val VideoDecodedFrame.timestamp: Duration - get() = timestampUs().toLong().microseconds diff --git a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Timestamp.kt b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Timestamp.kt new file mode 100644 index 00000000000..447504abeff --- /dev/null +++ b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Timestamp.kt @@ -0,0 +1,34 @@ +package dev.moq + +import java.math.BigInteger +import kotlin.time.Duration +import kotlin.time.Duration.Companion.nanoseconds +import kotlin.time.Duration.Companion.seconds + +/** + * This timestamp as a [Duration], rounded to the nearest nanosecond. + * + * The [Timestamp] itself is exact; keep it, not the duration, to republish a tick such as 90 kHz. + * Throws [IllegalArgumentException] past [Duration]'s range, about 146 million years. + */ +fun Timestamp.toDuration(): Duration { + // The sub-second remainder times a billion can exceed 64 bits. + val remainder = (value % scale).toString().toBigInteger() + val divisor = scale.toString().toBigInteger() + val nanos = (remainder * BigInteger.valueOf(1_000_000_000L) + divisor.shiftRight(1)) / divisor + val duration = (value / scale).toLong().seconds + nanos.toLong().nanoseconds + // Duration saturates to infinite instead of failing. + require(duration.isFinite()) { "timestamp $value/$scale s does not fit in a Duration" } + return duration +} + +/** + * This duration as an exact [Timestamp] at nanosecond scale. + * + * Throws [IllegalArgumentException] when negative; a write refuses one past the value bound with + * `MoqException.TimeOverflow`. + */ +fun Duration.toTimestamp(): Timestamp { + require(!isNegative()) { "a timestamp cannot be negative: $this" } + return Timestamp(value = inWholeNanoseconds.toULong(), scale = 1_000_000_000uL) +} diff --git a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/audio/Audio.kt b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/audio/Audio.kt index 3f2d535634f..f8494da50a2 100644 --- a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/audio/Audio.kt +++ b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/audio/Audio.kt @@ -20,7 +20,7 @@ typealias Read = uniffi.moq.MoqAudioRead typealias ReadFrame = uniffi.moq.MoqAudioRead.Frame /** Media after what was already read was lost; what follows does not continue it. */ typealias ReadGap = uniffi.moq.MoqAudioRead.Gap -/** The publisher stopped its encoder; frames starting before `endUs` are its remaining media. */ +/** The publisher stopped its encoder; frames starting before `end` are its remaining media. */ typealias ReadEnd = uniffi.moq.MoqAudioRead.End /** One encoded payload from an [Encoder]. */ diff --git a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/json/Tracks.kt b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/json/Tracks.kt index e6d7de66f00..7b3c0c27f64 100644 --- a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/json/Tracks.kt +++ b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/json/Tracks.kt @@ -10,12 +10,11 @@ package dev.moq.json // val reader = SnapshotConsumer(consumer.subscribeTrack("status", null), SnapshotConfig()) import dev.moq.MoqJson +import dev.moq.Timestamp import dev.moq.pull import kotlinx.coroutines.flow.Flow import kotlinx.coroutines.flow.map import kotlinx.serialization.serializer -import kotlin.time.Duration -import kotlin.time.Duration.Companion.microseconds /** Publishes lossy latest-value JSON snapshots on a track it takes over. */ typealias SnapshotProducer = uniffi.moq.MoqJsonSnapshotProducer @@ -50,22 +49,8 @@ typealias WindowEventSkip = uniffi.moq.MoqJsonWindowEvent.Skip /** A [WindowEvent] and the timestamp of the frame that carried it. */ typealias WindowTimed = uniffi.moq.MoqJsonWindowTimed -/** - * The frame's timestamp on the broadcast clock, or null when untimed. Rounded down to a whole - * microsecond, so a tick on a track like 90 kHz may not survive a read and republish exactly. - */ -val Value.timestamp: Duration? - get() = timestampUs?.toLong()?.microseconds - -/** - * The frame's timestamp on the broadcast clock, or null when untimed. A record first learned of - * from a group's restatement carries that frame's time, not its original push time. - */ -val WindowTimed.timestamp: Duration? - get() = timestampUs?.toLong()?.microseconds - /** A decoded JSON value and its frame timestamp on the broadcast clock, or null when untimed. */ -data class Timed(val value: T, val timestamp: Duration?) +data class Timed(val value: T, val timestamp: Timestamp?) /** Decode [Value.value] as [T], keeping the timestamp. */ inline fun Value.decode(): Timed = @@ -76,20 +61,20 @@ inline fun Value.decode(): Timed = * * The `@Serializable` type is encoded with [MoqJson]. Pass an already-encoded * `String` to serialize with another library: the member overload takes it - * unchanged. [timestampUs] is on the broadcast clock; null is untimed. + * unchanged. [timestamp] is on the broadcast clock; null is untimed. */ -inline fun SnapshotProducer.update(value: T, timestampUs: ULong? = null) { - update(MoqJson.encodeToString(serializer(), value), timestampUs) +inline fun SnapshotProducer.update(value: T, timestamp: Timestamp? = null) { + update(MoqJson.encodeToString(serializer(), value), timestamp) } -/** Append [value] at [timestampUs] on the broadcast clock; null is untimed. */ -inline fun StreamProducer.append(value: T, timestampUs: ULong? = null) { - append(MoqJson.encodeToString(serializer(), value), timestampUs) +/** Append [value] at [timestamp] on the broadcast clock; null is untimed. */ +inline fun StreamProducer.append(value: T, timestamp: Timestamp? = null) { + append(MoqJson.encodeToString(serializer(), value), timestamp) } -/** Push [value] onto the window at [timestampUs] on the broadcast clock; null is untimed. */ -inline fun WindowProducer.push(value: T, timestampUs: ULong? = null) { - push(MoqJson.encodeToString(serializer(), value), timestampUs) +/** Push [value] onto the window at [timestamp] on the broadcast clock; null is untimed. */ +inline fun WindowProducer.push(value: T, timestamp: Timestamp? = null) { + push(MoqJson.encodeToString(serializer(), value), timestamp) } /** Decode the pushed record as [T]. */ diff --git a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/media/Media.kt b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/media/Media.kt index 09262dcea47..f92daf9afba 100644 --- a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/media/Media.kt +++ b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/media/Media.kt @@ -2,8 +2,6 @@ package dev.moq.media import dev.moq.pull import kotlinx.coroutines.flow.Flow -import kotlin.time.Duration -import kotlin.time.Duration.Companion.microseconds import dev.moq.Frame import dev.moq.MoqJson import kotlinx.serialization.serializer @@ -105,10 +103,6 @@ suspend fun catalog(broadcast: dev.moq.BroadcastConsumer): Catalog { /** Stream of decoded frames from one finite media group. */ fun GroupConsumer.frames(): Flow = pull({ cancel() }) { next() } -/** Presentation timestamp of a container-decoded frame. */ -val MediaFrame.timestamp: Duration - get() = timestampUs.toLong().microseconds - /** * Set an application catalog section from a serializable value, encoded with [MoqJson]. * @@ -118,11 +112,3 @@ val MediaFrame.timestamp: Duration inline fun CatalogProducer.setSection(name: String, value: T) { setSection(name, MoqJson.encodeToString(serializer(), value)) } - -/** The furthest presentation point already read. */ -val ReadGap.timestamp: Duration - get() = timestampUs.toLong().microseconds - -/** Where the stopped encoder's media stops. */ -val ReadEnd.end: Duration - get() = endUs.toLong().microseconds diff --git a/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt b/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt index a5517c84cbe..c2b314c70ce 100644 --- a/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt +++ b/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt @@ -29,7 +29,6 @@ import dev.moq.json.WindowProducer import dev.moq.json.decode import dev.moq.json.events import dev.moq.json.push -import dev.moq.json.timestamp import dev.moq.json.update import dev.moq.json.valuesAs import kotlinx.serialization.Serializable @@ -42,6 +41,8 @@ import kotlin.test.assertNotNull import kotlin.test.assertNull import kotlin.test.assertTrue import kotlin.time.Duration.Companion.milliseconds +import kotlin.time.Duration.Companion.nanoseconds +import kotlin.time.Duration.Companion.seconds @Serializable private data class Status(val state: String) @@ -265,7 +266,7 @@ class SmokeTest { BroadcastProducer().use { broadcast -> val track = broadcast.publishTrack("events", TrackInfo(timescale = 1_000_000uL)) val group = track.appendGroup() - group.writeFrame(Frame(payload = "cached".encodeToByteArray(), timestampUs = 0uL)) + group.writeFrame(Frame(payload = "cached".encodeToByteArray(), timestamp = Timestamp(0uL, 1_000_000uL))) group.finish() val fetched = broadcast.consume().fetchGroup( @@ -285,7 +286,7 @@ class SmokeTest { val track = broadcast.publishTrack("backlog", TrackInfo(timescale = 1_000_000uL)) for (ms in 0uL until 3uL) { val group = track.appendGroup() - group.writeFrame(Frame(payload = "x".encodeToByteArray(), timestampUs = ms * 1_000uL)) + group.writeFrame(Frame(payload = "x".encodeToByteArray(), timestamp = Timestamp(ms, 1_000uL))) group.finish() } val consumer = track.consume( @@ -307,16 +308,16 @@ class SmokeTest { val consumer = track.consume(null) track.appendGroup().finish() track.appendGroup().finish() - track.writeFrame(Frame(payload = "populated".encodeToByteArray(), timestampUs = 2_000uL)) + track.writeFrame(Frame(payload = "populated".encodeToByteArray(), timestamp = 2.milliseconds.toTimestamp())) val frame = consumer.readFrame() assertEquals("populated", frame?.payload?.decodeToString()) - assertEquals(2_000uL, frame?.timestampUs) + assertEquals(Timestamp(2_000uL, 1_000_000uL), frame?.timestamp) } } @Test fun `flate preserves optional timestamps`() = runTest { - for (timestamp in listOf(null, 123_456uL)) { + for (timestamp in listOf(null, Timestamp(123_456uL, 1_000_000uL))) { for (mode in listOf("snapshot", "stream")) { BroadcastProducer().use { broadcast -> val info = if (timestamp == null) null else TrackInfo(timescale = 1_000_000uL) @@ -334,7 +335,7 @@ class SmokeTest { } val frame = consumer.readFrame() assertEquals("payload", frame?.payload?.decodeToString()) - assertEquals(timestamp, frame?.timestampUs) + assertEquals(timestamp, frame?.timestamp) } } } @@ -348,7 +349,7 @@ class SmokeTest { track.writeFrame(Frame(payload = "payload".encodeToByteArray())) val frame = consumer.readFrame() assertEquals("payload", frame?.payload?.decodeToString()) - assertNull(frame?.timestampUs) + assertNull(frame?.timestamp) assertNull(consumer.info().timescale) track.finish() } @@ -374,7 +375,7 @@ class SmokeTest { val consumer = broadcast.consume() val (name, audio) = catalog(consumer).audio.entries.single() - media.writeFrame(Frame(payload = "opus frame".encodeToByteArray(), timestampUs = 5_000_000uL)) + media.writeFrame(Frame(payload = "opus frame".encodeToByteArray(), timestamp = 5.seconds.toTimestamp())) // Fetch while the track is still published: finishing the media producer // unpublishes it, and the fetch would then miss with NotFound. @@ -389,7 +390,7 @@ class SmokeTest { assertEquals(1, frames.size) val frame = frames.single() assertEquals("opus frame", frame.payload.decodeToString()) - assertEquals(5_000_000uL, frame.timestampUs) + assertEquals(5.seconds, frame.timestamp.toDuration()) } } } @@ -409,10 +410,41 @@ class SmokeTest { assertNotNull(audio) } - /** Microsecond timestamps read back as a Duration. */ + /** A 90 kHz tick, a present zero, and an untimed frame survive a write and read exactly. */ @Test - fun `microsecond timestamps read back as durations`() { - assertEquals(20.milliseconds, Frame(payload = ByteArray(0), timestampUs = 20_000uL).timestamp) + fun `timestamps round-trip exactly`() = runTest { + for (timestamp in listOf(Timestamp(1uL, 90_000uL), Timestamp(0uL, 90_000uL), null)) { + BroadcastProducer().use { broadcast -> + // A timed track refuses an untimed frame, so null goes to an untimed one. + val track = broadcast.publishTrack("ticks", timestamp?.let { TrackInfo(timescale = 90_000uL) }) + val consumer = track.consume(null) + track.writeFrame(Frame(payload = ByteArray(0), timestamp = timestamp)) + assertEquals(timestamp, consumer.readFrame()?.timestamp) + } + } + } + + /** A zero scale, a scale past 2^62 - 1, and a value past 2^61 - 1 are refused at the write. */ + @Test + fun `out of range timestamps are refused`() { + BroadcastProducer().use { broadcast -> + val track = broadcast.publishTrack("ticks", TrackInfo(timescale = 90_000uL)) + for (timestamp in listOf(Timestamp(1uL, 0uL), Timestamp(1uL, 1uL shl 62), Timestamp(1uL shl 61, 90_000uL))) { + assertFailsWith { track.writeFrame(Frame(payload = ByteArray(0), timestamp = timestamp)) } + } + } + } + + /** From a duration is exact at nanosecond scale; to a duration rounds to the nearest nanosecond. */ + @Test + fun `timestamps convert to and from durations`() { + assertEquals(Timestamp(20_000_000uL, 1_000_000_000uL), 20.milliseconds.toTimestamp()) + assertFailsWith { (-1).nanoseconds.toTimestamp() } + assertEquals(11_111.nanoseconds, Timestamp(1uL, 90_000uL).toDuration()) + assertEquals(666_666_667.nanoseconds, Timestamp(2uL, 3uL).toDuration()) + // The sub-second remainder times a billion overflows 64 bits at the largest scale. + assertEquals(500.milliseconds, Timestamp((1uL shl 61) - 1uL, (1uL shl 62) - 1uL).toDuration()) + assertFailsWith { Timestamp((1uL shl 61) - 1uL, 1uL).toDuration() } assertNull(AudioEncoderOutput(codec = AudioCodec.opus()).frameDuration) } @@ -423,12 +455,12 @@ class SmokeTest { val track = broadcast.publishTrack("status", TrackInfo(timescale = 1_000_000uL)) val producer = SnapshotProducer(broadcast, track, config) val consumer = SnapshotConsumer(broadcast.consume().subscribeTrack("status", null), config) - for (n in 1..4) producer.update(Status(state = "live$n"), timestampUs = n.toULong() * 1_000uL) + for (n in 1..4) producer.update(Status(state = "live$n"), timestamp = n.milliseconds.toTimestamp()) // `next` yields every state in order; `latest` skips the buffered third. - assertEquals(Timed(Status(state = "live1"), 1.milliseconds), consumer.next()?.decode()) - assertEquals(Timed(Status(state = "live2"), 2.milliseconds), consumer.next()?.decode()) - assertEquals(Timed(Status(state = "live4"), 4.milliseconds), consumer.latest()?.decode()) + assertEquals(Timed(Status(state = "live1"), Timestamp(1_000uL, 1_000_000uL)), consumer.next()?.decode()) + assertEquals(Timed(Status(state = "live2"), Timestamp(2_000uL, 1_000_000uL)), consumer.next()?.decode()) + assertEquals(Timed(Status(state = "live4"), Timestamp(4_000uL, 1_000_000uL)), consumer.latest()?.decode()) } } @@ -439,23 +471,23 @@ class SmokeTest { val track = broadcast.publishTrack("log", TrackInfo(timescale = 1_000_000uL)) val producer = WindowProducer(track, config) val consumer = WindowConsumer(broadcast.consume().subscribeTrack("log", null), config) - for (n in 1..3) producer.push(Status(state = "live$n"), timestampUs = n.toULong() * 1_000uL) - producer.pop(2uL, 4_000uL) + for (n in 1..3) producer.push(Status(state = "live$n"), timestamp = Timestamp(n.toULong(), 1_000uL)) + producer.pop(2uL, Timestamp(4uL, 1_000uL)) for (n in 0..2) { val timed = checkNotNull(consumer.next()) val push = assertIs(timed.event) assertEquals(n.toULong(), push.index) assertEquals(Status(state = "live${n + 1}"), push.decode()) - assertEquals((n + 1).milliseconds, timed.timestamp) + assertEquals((n + 1).milliseconds, timed.timestamp?.toDuration()) } val pop = checkNotNull(consumer.next()) assertEquals(WindowEventPop(0uL, 2uL), pop.event) - assertEquals(4.milliseconds, pop.timestamp) + assertEquals(4.milliseconds, pop.timestamp?.toDuration()) // The cut's new group restates record 2, which this reader already has. producer.cut() - producer.push(Status(state = "live4"), timestampUs = 5_000uL) + producer.push(Status(state = "live4"), timestamp = 5.milliseconds.toTimestamp()) producer.finish() val events = consumer.events().toList() assertEquals(1, events.size) @@ -659,7 +691,7 @@ class SmokeTest { ), ) // 2.5 ms of silence at 48 kHz mono f32: exactly one encoded frame. - fine.write(AudioFrame(timestampUs = 0uL, data = ByteArray(120 * 4))) + fine.write(AudioFrame(timestamp = Timestamp(0uL, 48_000uL), data = ByteArray(120 * 4))) fine.finish() assertFailsWith { @@ -748,7 +780,7 @@ class SmokeTest { // Two 20 ms Opus frames of silence at 48 kHz mono. for (i in 0 until 2) { - audio.write(AudioFrame(timestampUs = i.toULong() * 20_000uL, data = ByteArray(960 * 4))) + audio.write(AudioFrame(timestamp = Timestamp(i.toULong() * 960uL, 48_000uL), data = ByteArray(960 * 4))) } assertIs(fixed.next()) assertIs(estimated.next()) @@ -782,7 +814,7 @@ class SmokeTest { val rgba = ByteArray(320 * 240 * 4) { 0x80.toByte() } video.cut() for (i in 0 until 10) { - video.write(VideoFrame(timestampUs = i.toULong() * 33_333uL, data = rgba)) + video.write(VideoFrame(timestamp = Timestamp(i.toULong(), 30uL), data = rgba)) } val consumer = origin.consume().requestBroadcast("video-decode-frame") @@ -793,7 +825,7 @@ class SmokeTest { // Keep the encoder fed so the decoder sees frames after it joined. for (i in 10 until 40) { - video.write(VideoFrame(timestampUs = i.toULong() * 33_333uL, data = rgba)) + video.write(VideoFrame(timestamp = Timestamp(i.toULong(), 30uL), data = rgba)) } assertIs(decoder.next()).frame.use { frame -> @@ -817,7 +849,7 @@ class SmokeTest { @Test fun `encode audio with opus object`() { val input = AudioEncoderInput(format = AudioSampleFormat.F32, sampleRate = 48_000u, channels = 1u) - val silence = AudioFrame(timestampUs = 0uL, data = ByteArray(960 * 4)) + val silence = AudioFrame(timestamp = Timestamp(0uL, 48_000uL), data = ByteArray(960 * 4)) // The producer retains the codec, so releasing the codec and the // config in either order must still encode. diff --git a/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/docs/Prelude.kt b/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/docs/Prelude.kt index d395387e257..352c747d407 100644 --- a/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/docs/Prelude.kt +++ b/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/docs/Prelude.kt @@ -7,5 +7,5 @@ import dev.moq.media.* val opusInit: ByteArray get() = TODO() val packet: ByteArray get() = TODO() -val pts: ULong get() = TODO() +val pts: dev.moq.Timestamp get() = TODO() val rgba: ByteArray get() = TODO() diff --git a/kt/moq/src/jvmTest/kotlin/dev/moq/FfiBench.kt b/kt/moq/src/jvmTest/kotlin/dev/moq/FfiBench.kt index 2afbbded1a6..b3db8297b7f 100644 --- a/kt/moq/src/jvmTest/kotlin/dev/moq/FfiBench.kt +++ b/kt/moq/src/jvmTest/kotlin/dev/moq/FfiBench.kt @@ -94,7 +94,7 @@ class FfiBench { repeat(case.frames) { f -> val frame = assertNotNull(group.readFrame(), "group ended") assertTrue(frame.payload.contentEquals(payload), "corrupt frame $f of round $n") - assertEquals((n * case.frames + f).toULong(), frame.timestampUs) + assertEquals(Timestamp((n * case.frames + f).toULong(), 1_000_000uL), frame.timestamp) } } } @@ -102,7 +102,7 @@ class FfiBench { tracks.forEach { track -> track.appendGroup().use { group -> repeat(case.frames) { f -> - group.writeFrame(Frame(payload = payload, timestampUs = (n * case.frames + f).toULong())) + group.writeFrame(Frame(payload = payload, timestamp = Timestamp((n * case.frames + f).toULong(), 1_000_000uL))) } group.finish() } diff --git a/py/moq-ffi/tests/exit_inside_callback.py b/py/moq-ffi/tests/exit_inside_callback.py index 6fbe52f04d6..51c82157234 100644 --- a/py/moq-ffi/tests/exit_inside_callback.py +++ b/py/moq-ffi/tests/exit_inside_callback.py @@ -62,7 +62,11 @@ async def main() -> None: subscriber = await consumer.subscribe_track("data", None) # Written once the read is parked, so the runtime thread delivers the wake. - asyncio.get_running_loop().call_later(0.05, track.write_frame, moq_ffi.MoqFrame(payload=b"hello", timestamp_us=0)) + asyncio.get_running_loop().call_later( + 0.05, + track.write_frame, + moq_ffi.MoqFrame(payload=b"hello", timestamp=moq_ffi.MoqTimestamp(value=0, scale=1_000_000)), + ) frame = await subscriber.read_frame() assert frame is not None # Flushed now: a write left for exit would hand the GIL over early. diff --git a/py/moq-rs/README.md b/py/moq-rs/README.md index 95f52ebae3e..9086f7bb308 100644 --- a/py/moq-rs/README.md +++ b/py/moq-rs/README.md @@ -53,7 +53,6 @@ asyncio.run(main()) ```python import asyncio -from datetime import timedelta import moq @@ -68,9 +67,9 @@ async def main(): # Write frames # Audio has no keyframes, so `cut` is what gives it group boundaries. - audio.write_frame(payload, timestamp=timedelta(0)) + audio.write_frame(payload, timestamp=moq.Timestamp(0, 1_000)) audio.cut() - audio.write_frame(payload, timestamp=timedelta(milliseconds=20)) + audio.write_frame(payload, timestamp=moq.Timestamp(20, 1_000)) audio.cut() # A fresh epoch per run tells viewers a restart is a new broadcast. @@ -199,7 +198,7 @@ client = moq.Client( and do not keep it open. - `media.CatalogProducer(broadcast)` owns `set_video_properties`, `set_section`, and `remove_section`. It holds the broadcast weakly; writes fail with `Error.Closed` after closing - or releasing the broadcast. `.now()` returns its current media time as `timedelta` and fixes + or releasing the broadcast. `.now()` returns its current media time as a `Timestamp` and fixes the clock for subsequent producers. - `await media.CatalogConsumer.subscribe(broadcast)` streams catalog snapshots; `await media.catalog(broadcast)` reads one snapshot and releases its subscription. @@ -213,8 +212,8 @@ client = moq.Client( `TrackConsumer.recv_group()` for arrival-order reads, with container media time on each frame as it lands. -`media.TrackProducer.write_frame(payload, timestamp)` requires the caller's capture time as -`timedelta`; returned `media.MediaFrame.timestamp` uses it too. `demand()` owns the track name and +`media.TrackProducer.write_frame(payload, timestamp)` requires the caller's capture time as a +`Timestamp`; returned `media.MediaFrame.timestamp` uses it too. `demand()` owns the track name and subscriber waits. `.cut()` / `.seek(sequence)` draw group boundaries; `.finish()` ends the import. ### Data @@ -262,9 +261,10 @@ Every handle whose cleanup is `cancel()` is an async context manager, so exiting ### Types - **`media.Catalog`**. `.audio: dict[str, Audio]`, `.video: dict[str, Video]`, `.display`, `.rotation`, `.flip`. -- **`Frame`**. `.payload: bytes`, `.timestamp: timedelta | None`. The unit of every write and every raw read; `None` means untimed when publishing or reading. -- **`media.MediaFrame`**. `.payload: bytes`, `.timestamp: timedelta`, `.keyframe: bool`. The frame variant of a media read. `keyframe` marks a group start or video keyframe; for audio it is true only at a group start. -- **`Datagram`**. `.sequence: int`, `.timestamp: timedelta | None`, `.payload: bytes`. Delivered only on datagram-capable transports with lite-05 or newer moq-lite, or moq-transport. +- **`Timestamp`**. `.value: int` units at `.scale: int` units per second, exact at any scale such as 90 kHz. `Timestamp.from_timedelta(duration)` is exact at microsecond scale; `.to_timedelta()` rounds to the nearest microsecond. A write with a scale of 0 or past `2**62 - 1`, or a value past `2**61 - 1`, raises `Error.TimeOverflow`. +- **`Frame`**. `.payload: bytes`, `.timestamp: Timestamp | None`. The unit of every write and every raw read; `None` means untimed when publishing or reading. +- **`media.MediaFrame`**. `.payload: bytes`, `.timestamp: Timestamp`, `.keyframe: bool`. The frame variant of a media read. `keyframe` marks a group start or video keyframe; for audio it is true only at a group start. +- **`Datagram`**. `.sequence: int`, `.timestamp: Timestamp | None`, `.payload: bytes`. Delivered only on datagram-capable transports with lite-05 or newer moq-lite, or moq-transport. - **`media.Audio`**. `.codec`, `.sample_rate`, `.channel_count`, `.bitrate`, `.enabled`, `.description`. - **`media.Video`**. `.codec`, `.coded: Dimensions`, `.display_aspect`, `.bitrate`, `.enabled`, `.framerate`, `.description`. A false `.enabled` means no frames are coming, so don't select the rendition. - **`Subscription`**. Subscriber delivery preferences: priority, staleness, and optional group range. diff --git a/py/moq-rs/benches/ffi.py b/py/moq-rs/benches/ffi.py index 1bc5865db65..9199fe82962 100644 --- a/py/moq-rs/benches/ffi.py +++ b/py/moq-rs/benches/ffi.py @@ -10,7 +10,6 @@ import resource import time from dataclasses import dataclass -from datetime import timedelta from pathlib import Path from typing import Callable @@ -66,7 +65,7 @@ async def read(case: Case, consumer: moq.TrackConsumer, payload: bytes, n: int) frame = await group.read_frame() assert frame is not None, "group ended" assert frame.payload == payload, f"corrupt frame {f} of round {n}" - assert frame.timestamp == timedelta(microseconds=n * case.frames + f) + assert frame.timestamp == moq.Timestamp(n * case.frames + f, 1_000_000) async def throughput(case: Case, results: list[dict]) -> None: @@ -83,7 +82,7 @@ async def step(n: int) -> None: for track in tracks: group = track.append_group() for f in range(case.frames): - group.write_frame(payload, timedelta(microseconds=n * case.frames + f)) + group.write_frame(payload, moq.Timestamp(n * case.frames + f, 1_000_000)) group.finish() await asyncio.wait_for(asyncio.gather(*readers), ROUND_TIMEOUT) diff --git a/py/moq-rs/docs/index.md b/py/moq-rs/docs/index.md index cd334e75dad..f2ca675d4a6 100644 --- a/py/moq-rs/docs/index.md +++ b/py/moq-rs/docs/index.md @@ -193,7 +193,7 @@ broadcast, and producers advertise it in the catalog. ## Data types These records, enums, and objects are re-exported from the native `moq_ffi` bindings; the -wrapper groups them under `moq` and `moq.media`, with owned duration records at the boundary. Their fields are defined on the +wrapper groups them under `moq` and `moq.media`, with owned duration and timestamp records at the boundary. Their fields are defined on the Rust side ([`moq-ffi`](https://crates.io/crates/moq-ffi)). ```{eval-rst} @@ -205,6 +205,7 @@ Rust side ([`moq-ffi`](https://crates.io/crates/moq-ffi)). media.Catalog media.Container + Timestamp Frame media.MediaFrame Datagram diff --git a/py/moq-rs/examples/clock.py b/py/moq-rs/examples/clock.py index 5a5bdeb0fce..e691c0a738c 100644 --- a/py/moq-rs/examples/clock.py +++ b/py/moq-rs/examples/clock.py @@ -10,7 +10,7 @@ import argparse import asyncio -from datetime import datetime, timedelta, timezone +from datetime import datetime, timezone import moq @@ -24,13 +24,13 @@ async def publish(url: str, broadcast_name: str, track_name: str, insecure: bool while True: now = datetime.now(timezone.utc).replace(microsecond=0) - timestamp = timedelta(seconds=int(now.timestamp())) + timestamp = moq.Timestamp(int(now.timestamp()), 1) group = track.append_group() group.write_frame(now.strftime("%Y-%m-%d %H:%M:").encode(), timestamp) current_minute = now.minute while now.minute == current_minute: - timestamp = timedelta(seconds=int(now.timestamp())) + timestamp = moq.Timestamp(int(now.timestamp()), 1) group.write_frame(now.strftime("%S").encode(), timestamp) await asyncio.sleep(1 - datetime.now(timezone.utc).microsecond / 1_000_000) now = datetime.now(timezone.utc).replace(microsecond=0) diff --git a/py/moq-rs/examples/serve_clock.py b/py/moq-rs/examples/serve_clock.py index 8fff413851b..a54a0718dc5 100644 --- a/py/moq-rs/examples/serve_clock.py +++ b/py/moq-rs/examples/serve_clock.py @@ -13,7 +13,7 @@ import argparse import asyncio -from datetime import datetime, timedelta, timezone +from datetime import datetime, timezone import moq @@ -31,13 +31,13 @@ async def run(bind: str, broadcast_name: str, track_name: str, host: str) -> Non try: while True: now = datetime.now(timezone.utc).replace(microsecond=0) - timestamp = timedelta(seconds=int(now.timestamp())) + timestamp = moq.Timestamp(int(now.timestamp()), 1) group = track.append_group() group.write_frame(now.strftime("%Y-%m-%d %H:%M:").encode(), timestamp) current_minute = now.minute while now.minute == current_minute: - timestamp = timedelta(seconds=int(now.timestamp())) + timestamp = moq.Timestamp(int(now.timestamp()), 1) group.write_frame(now.strftime("%S").encode(), timestamp) await asyncio.sleep(1 - datetime.now(timezone.utc).microsecond / 1_000_000) now = datetime.now(timezone.utc).replace(microsecond=0) diff --git a/py/moq-rs/moq/__init__.py b/py/moq-rs/moq/__init__.py index 169fa743a5d..fa8d6667d34 100644 --- a/py/moq-rs/moq/__init__.py +++ b/py/moq-rs/moq/__init__.py @@ -70,6 +70,7 @@ Range, Route, Subscription, + Timestamp, TrackInfo, VideoCodec, VideoDecodedFrame, @@ -132,6 +133,7 @@ "Server", "Session", "Subscription", + "Timestamp", "Tokens", "TrackConsumer", "TrackDemand", diff --git a/py/moq-rs/moq/_read.py b/py/moq-rs/moq/_read.py index 0a244d0c286..8fb88218b8b 100644 --- a/py/moq-rs/moq/_read.py +++ b/py/moq-rs/moq/_read.py @@ -5,7 +5,9 @@ from dataclasses import dataclass from datetime import timedelta -from ._records import _from_us +from moq_ffi import MoqTimestamp + +from ._records import Timestamp @dataclass(frozen=True) @@ -17,7 +19,7 @@ class Gap: furthest presentation point already read. """ - timestamp: timedelta + timestamp: Timestamp duration: timedelta @@ -29,12 +31,12 @@ class End: remaining media; the first at or past it comes from a fresh encoder. """ - end: timedelta + end: Timestamp -def _gap(timestamp_us: int, duration: timedelta) -> Gap: - return Gap(timestamp=_from_us(timestamp_us), duration=duration) +def _gap(timestamp: MoqTimestamp, duration: timedelta) -> Gap: + return Gap(timestamp=Timestamp._from_ffi(timestamp), duration=duration) -def _end(end_us: int) -> End: - return End(end=_from_us(end_us)) +def _end(end: MoqTimestamp) -> End: + return End(end=Timestamp._from_ffi(end)) diff --git a/py/moq-rs/moq/_records.py b/py/moq-rs/moq/_records.py index 56cee34bfdd..21d7d064e4f 100644 --- a/py/moq-rs/moq/_records.py +++ b/py/moq-rs/moq/_records.py @@ -1,8 +1,7 @@ """Root records the wrapper owns, as frozen dataclasses with Python defaults. -moq-ffi spells media timestamps as integer microseconds, so ``Frame`` and -``Datagram`` convert them to ``timedelta`` at the boundary. Durations already -cross as ``timedelta``. ``ClientTls`` lives here with the rest of the client +Media timestamps cross as exact :class:`Timestamp` records; durations cross as +``timedelta``. ``ClientTls`` lives here with the rest of the client config, so a bare string passed for a list is refused instead of splitting into characters. """ @@ -12,6 +11,7 @@ from collections.abc import Sequence from dataclasses import dataclass from datetime import timedelta +from fractions import Fraction from importlib import metadata from moq_ffi import ( @@ -26,6 +26,7 @@ MoqQuicConfig, MoqRange, MoqSubscription, + MoqTimestamp, MoqTrackInfo, MoqWebSocketConfig, ) @@ -42,29 +43,50 @@ def _implementation() -> str: return "moq-py/dev" -def _to_us(value: timedelta, name: str) -> int: - if value < timedelta(0): - raise ValueError(f"{name} must not be negative: {value}") - return value // _MICROSECOND +def _strs(value: Sequence[str], name: str) -> list[str]: + # A str is itself a Sequence[str], so list() would split it into characters. + if isinstance(value, str): + raise TypeError(f"{name} takes a sequence of strings, not a str: {value!r}") + return list(value) -def _opt_us(value: timedelta | None, name: str) -> int | None: - return None if value is None else _to_us(value, name) +@dataclass(frozen=True) +class Timestamp: + """An exact media timestamp: ``value`` units at ``scale`` units per second. + ``value`` is at most ``2**61 - 1`` and ``scale`` is non-zero and at most ``2**62 - 1``; + a write past either bound raises ``moq.Error.TimeOverflow``. A read carries the + track's timescale, and a write at another scale is floored to it. + """ -def _from_us(us: int) -> timedelta: - return timedelta(microseconds=us) + value: int + scale: int + @staticmethod + def from_timedelta(duration: timedelta) -> Timestamp: + """Exactly ``duration``, at microsecond scale since that is a ``timedelta``'s own unit.""" + if duration < timedelta(0): + raise ValueError(f"timestamp must not be negative: {duration}") + return Timestamp(duration // _MICROSECOND, 1_000_000) -def _strs(value: Sequence[str], name: str) -> list[str]: - # A str is itself a Sequence[str], so list() would split it into characters. - if isinstance(value, str): - raise TypeError(f"{name} takes a sequence of strings, not a str: {value!r}") - return list(value) + def to_timedelta(self) -> timedelta: + """This timestamp rounded to the nearest microsecond, so a finer scale may lose precision.""" + return timedelta(microseconds=round(Fraction(self.value * 1_000_000, self.scale))) + + def _ffi(self) -> MoqTimestamp: + return MoqTimestamp(value=self.value, scale=self.scale) + + @staticmethod + def _from_ffi(value: MoqTimestamp) -> Timestamp: + return Timestamp(value.value, value.scale) + + +def _opt_ts(value: Timestamp | None) -> MoqTimestamp | None: + return None if value is None else value._ffi() -def _opt_from_us(us: int | None) -> timedelta | None: - return None if us is None else _from_us(us) +def _opt_from_ts(value: MoqTimestamp | None) -> Timestamp | None: + return None if value is None else Timestamp._from_ffi(value) @dataclass(frozen=True) @@ -75,14 +97,14 @@ class Frame: """ payload: bytes - timestamp: timedelta | None = None + timestamp: Timestamp | None = None def _ffi(self) -> MoqFrame: - return MoqFrame(payload=self.payload, timestamp_us=_opt_us(self.timestamp, "timestamp")) + return MoqFrame(payload=self.payload, timestamp=_opt_ts(self.timestamp)) @staticmethod def _from_ffi(frame: MoqFrame) -> Frame: - return Frame(payload=frame.payload, timestamp=_opt_from_us(frame.timestamp_us)) + return Frame(payload=frame.payload, timestamp=_opt_from_ts(frame.timestamp)) @dataclass(frozen=True) @@ -93,14 +115,14 @@ class Datagram: """ sequence: int - timestamp: timedelta | None + timestamp: Timestamp | None payload: bytes @staticmethod def _from_ffi(datagram: MoqDatagram) -> Datagram: return Datagram( sequence=datagram.sequence, - timestamp=_opt_from_us(datagram.timestamp_us), + timestamp=_opt_from_ts(datagram.timestamp), payload=datagram.payload, ) diff --git a/py/moq-rs/moq/audio.py b/py/moq-rs/moq/audio.py index 9e397de044b..2c0e2bb0b16 100644 --- a/py/moq-rs/moq/audio.py +++ b/py/moq-rs/moq/audio.py @@ -19,7 +19,7 @@ ) from ._read import End, Gap, _end, _gap -from ._records import _from_us, _to_us +from ._records import Timestamp from ._stream import _Stream from .media import Audio, AudioInit, CatalogProducer from .publish import TrackDemand @@ -40,15 +40,15 @@ class Frame: """Interleaved PCM with its presentation timestamp.""" - timestamp: timedelta + timestamp: Timestamp data: bytes def _ffi(self) -> MoqAudioFrame: - return MoqAudioFrame(timestamp_us=_to_us(self.timestamp, "timestamp"), data=self.data) + return MoqAudioFrame(timestamp=self.timestamp._ffi(), data=self.data) @staticmethod def _from_ffi(value: MoqAudioFrame) -> Frame: - return Frame(timestamp=_from_us(value.timestamp_us), data=value.data) + return Frame(timestamp=Timestamp._from_ffi(value.timestamp), data=value.data) Read = Frame | Gap | End @@ -179,9 +179,9 @@ async def _next(self) -> Read | None: if isinstance(value, MoqAudioRead.FRAME): return Frame._from_ffi(value.frame) if isinstance(value, MoqAudioRead.GAP): - return _gap(value.timestamp_us, value.duration) + return _gap(value.timestamp, value.duration) if isinstance(value, MoqAudioRead.END): - return _end(value.end_us) + return _end(value.end) raise TypeError(f"unknown audio read: {value!r}") @property diff --git a/py/moq-rs/moq/flate.py b/py/moq-rs/moq/flate.py index bd06e7c1d3e..e264fcdfa4f 100644 --- a/py/moq-rs/moq/flate.py +++ b/py/moq-rs/moq/flate.py @@ -2,12 +2,10 @@ from __future__ import annotations -from datetime import timedelta - from moq_ffi import MoqFlateConfig, MoqFlateSnapshotProducer, MoqFlateStreamProducer from . import publish -from ._records import _opt_us +from ._records import Timestamp, _opt_ts __all__ = ["SnapshotProducer", "StreamProducer"] @@ -27,9 +25,9 @@ def __init__( broadcast._inner, track._inner, MoqFlateConfig(compression=compression, mime=mime) ) - def update(self, payload: bytes, *, timestamp: timedelta | None = None) -> None: + def update(self, payload: bytes, *, timestamp: Timestamp | None = None) -> None: """Replace the payload at the given broadcast time, or leave it untimed.""" - self._inner.update(payload, _opt_us(timestamp, "timestamp")) + self._inner.update(payload, _opt_ts(timestamp)) def finish(self) -> None: """Finish the track and retire its catalog entry.""" @@ -51,9 +49,9 @@ def __init__( broadcast._inner, track._inner, MoqFlateConfig(compression=compression, mime=mime) ) - def append(self, payload: bytes, *, timestamp: timedelta | None = None) -> None: + def append(self, payload: bytes, *, timestamp: Timestamp | None = None) -> None: """Append a payload at the given broadcast time, or leave it untimed.""" - self._inner.append(payload, _opt_us(timestamp, "timestamp")) + self._inner.append(payload, _opt_ts(timestamp)) def finish(self) -> None: """Finish the track and retire its catalog entry.""" diff --git a/py/moq-rs/moq/json.py b/py/moq-rs/moq/json.py index cec68b5756b..e80ba470519 100644 --- a/py/moq-rs/moq/json.py +++ b/py/moq-rs/moq/json.py @@ -11,7 +11,6 @@ import json from dataclasses import dataclass -from datetime import timedelta from typing import Any from moq_ffi import ( @@ -30,7 +29,7 @@ ) from . import publish, subscribe -from ._records import _opt_from_us, _opt_us +from ._records import Timestamp, _opt_from_ts, _opt_ts from ._stream import _Stream from .publish import BroadcastProducer, TrackDemand @@ -53,19 +52,17 @@ class Timed: """A parsed JSON value and the timestamp of the frame that carried it. - ``timestamp`` is on the broadcast clock, and ``None`` on an untimed track. It is - rounded down to a whole microsecond, so a tick on a track like 90 kHz may not - survive a read and republish exactly. + ``timestamp`` is on the broadcast clock, and ``None`` on an untimed track. """ value: Any - timestamp: timedelta | None + timestamp: Timestamp | None @staticmethod def _from_ffi(value: MoqJsonValue | None) -> Timed | None: if value is None: return None - return Timed(value=json.loads(value.value), timestamp=_opt_from_us(value.timestamp_us)) + return Timed(value=json.loads(value.value), timestamp=_opt_from_ts(value.timestamp)) class SnapshotProducer: @@ -94,9 +91,9 @@ def demand(self) -> TrackDemand: """A watch-only handle to whether this track has subscribers.""" return TrackDemand(self._inner.demand()) - def update(self, value: Any, *, timestamp: timedelta | None = None) -> None: + def update(self, value: Any, *, timestamp: Timestamp | None = None) -> None: """Publish a new value. A no-op if unchanged from the previous update.""" - self._inner.update(json.dumps(value), _opt_us(timestamp, "timestamp")) + self._inner.update(json.dumps(value), _opt_ts(timestamp)) def finish(self) -> None: """Finish the track, closing any open group.""" @@ -121,9 +118,9 @@ def demand(self) -> TrackDemand: """A watch-only handle to whether this track has subscribers.""" return TrackDemand(self._inner.demand()) - def append(self, value: Any, *, timestamp: timedelta | None = None) -> None: + def append(self, value: Any, *, timestamp: Timestamp | None = None) -> None: """Append one record to the log.""" - self._inner.append(json.dumps(value), _opt_us(timestamp, "timestamp")) + self._inner.append(json.dumps(value), _opt_ts(timestamp)) def finish(self) -> None: """Finish the track, closing the group.""" @@ -205,13 +202,13 @@ def demand(self) -> TrackDemand: """A watch-only handle to whether this track has subscribers.""" return TrackDemand(self._inner.demand()) - def push(self, value: Any, *, timestamp: timedelta | None = None) -> None: + def push(self, value: Any, *, timestamp: Timestamp | None = None) -> None: """Append one record to the back of the window.""" - self._inner.push(json.dumps(value), _opt_us(timestamp, "timestamp")) + self._inner.push(json.dumps(value), _opt_ts(timestamp)) - def pop(self, count: int, *, timestamp: timedelta | None = None) -> None: + def pop(self, count: int, *, timestamp: Timestamp | None = None) -> None: """Drop ``count`` records from the front of the window, clamped to what it holds.""" - self._inner.pop(count, _opt_us(timestamp, "timestamp")) + self._inner.pop(count, _opt_ts(timestamp)) def cut(self) -> None: """Close the open group, so the next edit opens one restating the retained window. @@ -269,7 +266,7 @@ def _window_event(timed: MoqJsonWindowTimed | None) -> Timed | None: value = WindowSkip(range(event.start, event.end)) else: raise TypeError(f"unknown window event: {event!r}") - return Timed(value=value, timestamp=_opt_from_us(timed.timestamp_us)) + return Timed(value=value, timestamp=_opt_from_ts(timed.timestamp)) class WindowConsumer(_Stream[Timed]): diff --git a/py/moq-rs/moq/media.py b/py/moq-rs/moq/media.py index 0ac4923cffb..5caeef50176 100644 --- a/py/moq-rs/moq/media.py +++ b/py/moq-rs/moq/media.py @@ -4,7 +4,6 @@ import json from dataclasses import dataclass, field -from datetime import timedelta from typing import Any, cast from moq_ffi import MoqAudio as Audio @@ -52,7 +51,7 @@ from . import subscribe as _subscribe from ._read import End, Gap, _end, _gap -from ._records import Frame, Subscription, _from_us, _subscription +from ._records import Frame, Subscription, Timestamp, _subscription from ._stream import _Stream from .publish import BroadcastProducer, TrackDemand, TrackRequest from .subscribe import BroadcastConsumer @@ -109,12 +108,12 @@ class MediaFrame: """A container-decoded payload, presentation timestamp, and keyframe flag.""" payload: bytes - timestamp: timedelta + timestamp: Timestamp keyframe: bool @staticmethod def _from_ffi(frame: MoqMediaFrame) -> MediaFrame: - return MediaFrame(frame.payload, _from_us(frame.timestamp_us), frame.keyframe) + return MediaFrame(frame.payload, Timestamp._from_ffi(frame.timestamp), frame.keyframe) Read = MediaFrame | Gap | End @@ -127,9 +126,9 @@ class CatalogProducer: def __init__(self, broadcast: BroadcastProducer) -> None: self._inner = MoqMediaCatalogProducer(broadcast._inner) - def now(self) -> timedelta: + def now(self) -> Timestamp: """Read the broadcast clock, fixing it for subsequent media producers.""" - return _from_us(self._inner.now()) + return Timestamp._from_ffi(self._inner.now()) def set_video_properties(self, properties: VideoProperties) -> None: """Replace the video properties shared by every rendition.""" @@ -177,7 +176,7 @@ def demand(self) -> TrackDemand: """A watch-only handle to whether this media track has subscribers.""" return TrackDemand(self._inner.demand()) - def write_frame(self, payload: bytes, timestamp: timedelta) -> None: + def write_frame(self, payload: bytes, timestamp: Timestamp) -> None: """Write one encoded frame with a presentation timestamp.""" self._inner.write_frame(Frame(payload, timestamp)._ffi()) @@ -310,9 +309,9 @@ async def _next(self) -> Read | None: if isinstance(value, MoqMediaRead.FRAME): return MediaFrame._from_ffi(value.frame) if isinstance(value, MoqMediaRead.GAP): - return _gap(value.timestamp_us, value.duration) + return _gap(value.timestamp, value.duration) if isinstance(value, MoqMediaRead.END): - return _end(value.end_us) + return _end(value.end) raise TypeError(f"unknown media read: {value!r}") def cancel(self) -> None: diff --git a/py/moq-rs/moq/publish.py b/py/moq-rs/moq/publish.py index 3cb61709077..d46fdc18e78 100644 --- a/py/moq-rs/moq/publish.py +++ b/py/moq-rs/moq/publish.py @@ -23,6 +23,7 @@ AnnounceRoute, Frame, Subscription, + Timestamp, TrackInfo, ) @@ -47,7 +48,7 @@ def consume(self) -> GroupConsumer: return GroupConsumer(self._inner.consume()) - def write_frame(self, payload: bytes, timestamp: timedelta | None = None) -> None: + def write_frame(self, payload: bytes, timestamp: Timestamp | None = None) -> None: """Write a frame with its presentation timestamp.""" self._inner.write_frame(Frame(payload, timestamp)._ffi()) @@ -117,11 +118,11 @@ def create_group(self, sequence: int) -> GroupProducer: """Create a group with an explicit sequence number.""" return GroupProducer(self._inner.create_group(sequence)) - def write_frame(self, payload: bytes, timestamp: timedelta | None = None) -> None: + def write_frame(self, payload: bytes, timestamp: Timestamp | None = None) -> None: """Write a single-frame group with its presentation timestamp.""" self._inner.write_frame(Frame(payload, timestamp)._ffi()) - def append_datagram(self, payload: bytes, timestamp: timedelta | None = None) -> int: + def append_datagram(self, payload: bytes, timestamp: Timestamp | None = None) -> int: """Send a best-effort datagram and return its sequence number. Payloads are capped at 1200 bytes. Datagram delivery requires a datagram-capable diff --git a/py/moq-rs/moq/types.py b/py/moq-rs/moq/types.py index d65eaa159cf..7662dd30337 100644 --- a/py/moq-rs/moq/types.py +++ b/py/moq-rs/moq/types.py @@ -76,6 +76,7 @@ Grant, QuicConfig, Subscription, + Timestamp, TrackInfo, WebSocketConfig, ) @@ -103,6 +104,7 @@ "Range", "Route", "Subscription", + "Timestamp", "TrackInfo", "VideoCodec", "VideoEncoderInput", diff --git a/py/moq-rs/moq/video.py b/py/moq-rs/moq/video.py index 7b821d52a6d..8676fd08871 100644 --- a/py/moq-rs/moq/video.py +++ b/py/moq-rs/moq/video.py @@ -19,7 +19,7 @@ from moq_ffi import MoqVideoFrameRate as FrameRate from ._read import End, Gap, _end, _gap -from ._records import _from_us, _to_us +from ._records import Timestamp from ._stream import _Stream from .media import CatalogProducer, Dimensions, Video from .publish import TrackDemand @@ -42,24 +42,24 @@ class Frame: """One raw picture in the configured input layout, with its presentation timestamp.""" - timestamp: timedelta + timestamp: Timestamp data: bytes def _ffi(self) -> MoqVideoFrame: - return MoqVideoFrame(timestamp_us=_to_us(self.timestamp, "timestamp"), data=self.data) + return MoqVideoFrame(timestamp=self.timestamp._ffi(), data=self.data) @dataclass(frozen=True) class Packet: """One encoded access unit from an :class:`Encoder`.""" - timestamp: timedelta + timestamp: Timestamp data: bytes keyframe: bool @staticmethod def _from_ffi(value: MoqVideoPacket) -> Packet: - return Packet(timestamp=_from_us(value.timestamp_us), data=value.data, keyframe=value.keyframe) + return Packet(timestamp=Timestamp._from_ffi(value.timestamp), data=value.data, keyframe=value.keyframe) @dataclass(frozen=True) @@ -176,9 +176,9 @@ async def _next(self) -> Read | None: if isinstance(value, MoqVideoRead.FRAME): return value.frame if isinstance(value, MoqVideoRead.GAP): - return _gap(value.timestamp_us, value.duration) + return _gap(value.timestamp, value.duration) if isinstance(value, MoqVideoRead.END): - return _end(value.end_us) + return _end(value.end) raise TypeError(f"unknown video read: {value!r}") def cancel(self) -> None: diff --git a/py/moq-rs/tests/test_data_timestamps.py b/py/moq-rs/tests/test_data_timestamps.py index 918fb12dfc1..05b5d7287cc 100644 --- a/py/moq-rs/tests/test_data_timestamps.py +++ b/py/moq-rs/tests/test_data_timestamps.py @@ -1,4 +1,4 @@ -"""Data publishers preserve the caller's capture time, including absence.""" +"""Publishers preserve the caller's exact capture time, including absence.""" import asyncio import json @@ -9,12 +9,47 @@ import moq_ffi import pytest +TIMESTAMPS = [None, moq.Timestamp(0, 90_000), moq.Timestamp(1, 90_000)] + + +async def test_raw_timestamps_are_exact(): + """A present zero stays present, and one 90 kHz tick reads back as itself, not the 11 µs it floors to.""" + broadcast = moq.BroadcastProducer() + track = broadcast.publish_track("video", moq.TrackInfo(timescale=90_000)) + consumer = track.consume() + for value in [0, 1]: + track.write_frame(b"frame", moq.Timestamp(value, 90_000)) + frame = await asyncio.wait_for(consumer.read_frame(), timeout=5.0) + assert frame is not None + assert frame.timestamp == moq.Timestamp(value, 90_000) + + untimed = broadcast.publish_track("events", moq.TrackInfo(timescale=None)) + untimed_consumer = untimed.consume() + untimed.write_frame(b"event") + frame = await asyncio.wait_for(untimed_consumer.read_frame(), timeout=5.0) + assert frame is not None + assert frame.timestamp is None + + for invalid in [moq.Timestamp(0, 0), moq.Timestamp(0, 1 << 62), moq.Timestamp(1 << 61, 90_000)]: + with pytest.raises(moq.Error.TimeOverflow): + track.write_frame(b"frame", invalid) + broadcast.close() + + +def test_timedelta_conversions(): + assert moq.Timestamp.from_timedelta(timedelta(seconds=1, microseconds=5)) == moq.Timestamp(1_000_005, 1_000_000) + with pytest.raises(ValueError): + moq.Timestamp.from_timedelta(timedelta(microseconds=-1)) + # Nearest, not floored: 2/3 µs is 1 µs and 11.1 µs is 11 µs. + assert moq.Timestamp(2, 3_000_000).to_timedelta() == timedelta(microseconds=1) + assert moq.Timestamp(1, 90_000).to_timedelta() == timedelta(microseconds=11) + @pytest.mark.parametrize("mode", ["snapshot", "stream"]) -@pytest.mark.parametrize("timestamp", [None, timedelta(microseconds=123_456)]) -async def test_flate_timestamp_round_trip(mode: str, timestamp: timedelta | None): +@pytest.mark.parametrize("timestamp", TIMESTAMPS) +async def test_flate_timestamp_round_trip(mode: str, timestamp: moq.Timestamp | None): broadcast = moq.BroadcastProducer() - track = broadcast.publish_track("payload", moq.TrackInfo(timescale=None if timestamp is None else 1_000_000)) + track = broadcast.publish_track("payload", moq.TrackInfo(timescale=None if timestamp is None else timestamp.scale)) consumer = track.consume() payload = b"opaque payload" if mode == "snapshot": @@ -33,10 +68,10 @@ async def test_flate_timestamp_round_trip(mode: str, timestamp: timedelta | None @pytest.mark.parametrize("mode", ["snapshot", "stream"]) -@pytest.mark.parametrize("timestamp", [None, timedelta(microseconds=123_456)]) -async def test_json_timestamp_round_trip(mode: str, timestamp: timedelta | None): +@pytest.mark.parametrize("timestamp", TIMESTAMPS) +async def test_json_timestamp_round_trip(mode: str, timestamp: moq.Timestamp | None): broadcast = moq.BroadcastProducer() - track = broadcast.publish_track("value", moq.TrackInfo(timescale=None if timestamp is None else 1_000_000)) + track = broadcast.publish_track("value", moq.TrackInfo(timescale=None if timestamp is None else timestamp.scale)) consumer = track.consume() value = {"n": 1} if mode == "snapshot": @@ -57,7 +92,7 @@ async def test_json_timestamp_round_trip(mode: str, timestamp: timedelta | None) def test_catalog_now_uses_a_weak_broadcast_handle(): broadcast = moq.BroadcastProducer() catalog = moq.media.CatalogProducer(broadcast) - assert catalog.now() >= timedelta(0) + assert catalog.now().scale == 1_000_000 broadcast.close() with pytest.raises(moq.Error.Closed): catalog.now() @@ -77,7 +112,7 @@ def test_whole_media_frames_require_the_callers_timestamp(): broadcast, moq.media.AudioInit(format=moq.media.AudioFormat.OPUS, data=head) ) with pytest.raises(moq.Error.Codec, match="timestamp"): - producer._inner.write_frame(moq_ffi.MoqFrame(payload=b"opus frame", timestamp_us=None)) + producer._inner.write_frame(moq_ffi.MoqFrame(payload=b"opus frame", timestamp=None)) # Exercise the runtime refusal when a caller omits the required timestamp. with pytest.raises(TypeError): producer.write_frame(b"opus frame") # type: ignore[call-arg] diff --git a/py/moq-rs/tests/test_local.py b/py/moq-rs/tests/test_local.py index 4aaf944f467..2a803c826ac 100644 --- a/py/moq-rs/tests/test_local.py +++ b/py/moq-rs/tests/test_local.py @@ -154,7 +154,7 @@ def test_publish_media_lifecycle(): media = moq.media.TrackProducer.audio( broadcast, moq.media.AudioInit(format=moq.media.AudioFormat.OPUS, data=opus_head()) ) - media.write_frame(b"opus frame", timedelta(microseconds=1000)) + media.write_frame(b"opus frame", moq.Timestamp(1000, 1_000_000)) media.finish() broadcast.close() @@ -171,14 +171,14 @@ def test_publish_media_cut_and_seek(): ) for i in range(3): - media.write_frame(b"opus frame", timedelta(microseconds=i * 20_000)) + media.write_frame(b"opus frame", moq.Timestamp(i * 20_000, 1_000_000)) media.cut() # The same boundary, with the next group explicitly numbered. - media.write_frame(b"opus frame", timedelta(microseconds=60_000)) + media.write_frame(b"opus frame", moq.Timestamp(60_000, 1_000_000)) media.seek(42) media.discontinuity() - media.write_frame(b"resumed opus frame", timedelta(microseconds=100_000)) + media.write_frame(b"resumed opus frame", moq.Timestamp(100_000, 1_000_000)) media.finish() broadcast.close() @@ -228,12 +228,12 @@ async def test_local_publish_consume_audio(): media_consumer = await moq.media.TrackConsumer.subscribe(broadcast_consumer, track_name, audio) payload = b"opus audio payload data" - media.write_frame(payload, timedelta(microseconds=1_000_000)) + media.write_frame(payload, moq.Timestamp(1_000_000, 1_000_000)) async for frame in media_consumer: assert isinstance(frame, moq.media.MediaFrame) assert frame.payload == payload - assert frame.timestamp // timedelta(microseconds=1) == 1_000_000 + assert frame.timestamp == moq.Timestamp(1_000_000, 1_000_000) break break @@ -265,11 +265,11 @@ async def test_video_publish_consume(): media_consumer = await moq.media.TrackConsumer.subscribe(broadcast_consumer, track_name, video) keyframe = bytes([0x00, 0x00, 0x00, 0x01, 0x65, 0xAA, 0xBB, 0xCC]) - media.write_frame(keyframe, timedelta(microseconds=0)) + media.write_frame(keyframe, moq.Timestamp(0, 1_000_000)) async for frame in media_consumer: assert isinstance(frame, moq.media.MediaFrame) - assert frame.timestamp // timedelta(microseconds=1) == 0 + assert frame.timestamp == moq.Timestamp(0, 1_000_000) assert len(frame.payload) > 0 break @@ -313,12 +313,12 @@ async def test_multiple_frames_ordering(): timestamps = [0, 20_000, 40_000, 60_000, 80_000] for i, ts in enumerate(timestamps): - media.write_frame(f"frame-{i}".encode(), timedelta(microseconds=ts)) + media.write_frame(f"frame-{i}".encode(), moq.Timestamp(ts, 1_000_000)) for i, expected_ts in enumerate(timestamps): async for frame in media_consumer: assert isinstance(frame, moq.media.MediaFrame) - assert frame.timestamp // timedelta(microseconds=1) == expected_ts + assert frame.timestamp == moq.Timestamp(expected_ts, 1_000_000) assert frame.payload == f"frame-{i}".encode() break @@ -473,7 +473,7 @@ async def test_fetch_group_and_serve_dynamic_miss(): consumer = broadcast.consume() cached = track.append_group() - cached.write_frame(b"cached", timedelta(0)) + cached.write_frame(b"cached", moq.Timestamp(0, 1_000_000)) cached.finish() fetched = await consumer.fetch_group("events", 0, moq.FetchGroupOptions(priority=3)) @@ -491,7 +491,7 @@ async def test_fetch_group_and_serve_dynamic_miss(): assert not fill.is_wanted(8) produced = fill.accept(7) - produced.write_frame(b"archive", timedelta(microseconds=140_000)) + produced.write_frame(b"archive", moq.Timestamp(140_000, 1_000_000)) produced.finish() fetched = await asyncio.wait_for(pending, timeout=5.0) @@ -505,15 +505,15 @@ async def test_json_snapshot_roundtrip(): consumer = moq.json.SnapshotConsumer(await broadcast.consume().subscribe_track("status"), compression=True) for viewers in range(1, 5): - producer.update({"viewers": viewers}, timestamp=timedelta(milliseconds=viewers)) + producer.update({"viewers": viewers}, timestamp=moq.Timestamp(viewers, 1_000)) # Iteration yields every state in order; latest() skips the buffered third. value = await asyncio.wait_for(anext(consumer), timeout=5.0) - assert value == moq.json.Timed({"viewers": 1}, timedelta(milliseconds=1)) + assert value == moq.json.Timed({"viewers": 1}, moq.Timestamp(1_000, 1_000_000)) value = await asyncio.wait_for(anext(consumer), timeout=5.0) - assert value == moq.json.Timed({"viewers": 2}, timedelta(milliseconds=2)) + assert value == moq.json.Timed({"viewers": 2}, moq.Timestamp(2_000, 1_000_000)) value = await asyncio.wait_for(consumer.latest(), timeout=5.0) - assert value == moq.json.Timed({"viewers": 4}, timedelta(milliseconds=4)) + assert value == moq.json.Timed({"viewers": 4}, moq.Timestamp(4_000, 1_000_000)) producer.finish() assert await asyncio.wait_for(consumer.latest(), timeout=5.0) is None @@ -541,18 +541,18 @@ async def test_json_window_roundtrip(): await asyncio.wait_for(until_wanted(demand), timeout=5.0) for n in range(3): - producer.push({"n": n}, timestamp=timedelta(milliseconds=n)) - producer.pop(2, timestamp=timedelta(milliseconds=3)) + producer.push({"n": n}, timestamp=moq.Timestamp(n, 1_000)) + producer.pop(2, timestamp=moq.Timestamp(3, 1_000)) for n in range(3): event = await asyncio.wait_for(anext(consumer), timeout=5.0) - assert event == moq.json.Timed(moq.json.WindowPush(n, {"n": n}), timedelta(milliseconds=n)) + assert event == moq.json.Timed(moq.json.WindowPush(n, {"n": n}), moq.Timestamp(n * 1_000, 1_000_000)) event = await asyncio.wait_for(anext(consumer), timeout=5.0) - assert event == moq.json.Timed(moq.json.WindowPop(range(0, 2)), timedelta(milliseconds=3)) + assert event == moq.json.Timed(moq.json.WindowPop(range(0, 2)), moq.Timestamp(3_000, 1_000_000)) producer.finish() with pytest.raises(moq.Error.Closed): - producer.push({"n": 3}, timestamp=timedelta(milliseconds=4)) + producer.push({"n": 3}, timestamp=moq.Timestamp(4, 1_000)) assert [event async for event in consumer] == [] @@ -726,12 +726,12 @@ async def test_dynamic_track_request_can_publish_media(): assert audio.channel_count == 2 payload = b"dynamic opus frame" - media.write_frame(payload, timedelta(microseconds=20_000)) + media.write_frame(payload, moq.Timestamp(20_000, 1_000_000)) async for frame in media_consumer: assert isinstance(frame, moq.media.MediaFrame) assert frame.payload == payload - assert frame.timestamp // timedelta(microseconds=1) == 20_000 + assert frame.timestamp == moq.Timestamp(20_000, 1_000_000) break media.finish() @@ -756,12 +756,12 @@ async def test_dynamic_broadcast_request(): broadcast = await asyncio.wait_for(request_broadcast, timeout=5.0) track_consumer = await broadcast.subscribe_track("status") payload = b"served dynamically" - track.write_frame(payload, timedelta(microseconds=20_000)) + track.write_frame(payload, moq.Timestamp(20_000, 1_000_000)) frame = await asyncio.wait_for(track_consumer.read_frame(), timeout=5.0) assert frame is not None assert frame.payload == payload - assert frame.timestamp == timedelta(microseconds=20_000) + assert frame.timestamp == moq.Timestamp(20_000, 1_000_000) track.finish() served.close() @@ -804,7 +804,7 @@ def test_raw_group_write_multiple_frames(): group = track.append_group() for i in range(10): - group.write_frame(f"frame-{i}".encode(), timedelta(microseconds=i)) + group.write_frame(f"frame-{i}".encode(), moq.Timestamp(i, 1_000_000)) group.finish() @@ -881,9 +881,9 @@ def test_raw_parallel_groups(): assert g0.sequence == 0 assert g1.sequence == 1 - g0.write_frame(b"a0", timedelta(0)) - g1.write_frame(b"b0", timedelta(0)) - g0.write_frame(b"a1", timedelta(microseconds=1)) + g0.write_frame(b"a0", moq.Timestamp(0, 1_000_000)) + g1.write_frame(b"b0", moq.Timestamp(0, 1_000_000)) + g0.write_frame(b"a1", moq.Timestamp(1, 1_000_000)) g0.finish() g1.finish() @@ -930,7 +930,7 @@ async def test_container_consumer_default_latency_and_context_manager(): # No container argument, no explicit latency. payload = b"opus audio payload data" - media.write_frame(payload, timedelta(microseconds=1_000_000)) + media.write_frame(payload, moq.Timestamp(1_000_000, 1_000_000)) async with await moq.media.TrackConsumer.subscribe(broadcast_consumer, track_name, audio) as media_consumer: async for frame in media_consumer: @@ -1022,7 +1022,7 @@ async def test_ascending_subscription_reads_a_cached_backlog_oldest_first(): track = broadcast.publish_track("backlog", moq.TrackInfo(timescale=1_000_000)) for ms in range(3): group = track.append_group() - group.write_frame(b"x", timedelta(milliseconds=ms)) + group.write_frame(b"x", moq.Timestamp(ms, 1_000)) group.finish() consumer = track.consume( @@ -1090,7 +1090,7 @@ async def test_raw_group_sequence(): for i in range(3): group = raw.append_group() sent_sequences.append(group.sequence) - group.write_frame(f"msg-{i}".encode(), timedelta(microseconds=i)) + group.write_frame(f"msg-{i}".encode(), moq.Timestamp(i, 1_000_000)) group.finish() received_sequences = [] @@ -1169,23 +1169,23 @@ async def test_container_group_decodes_arrival_order(): consumer = await broadcast.consume().subscribe_track("audio") first = track.append_group() - first.write_frame(_legacy(1_000_000, b"a"), timedelta(milliseconds=1)) + first.write_frame(_legacy(1_000_000, b"a"), moq.Timestamp(1, 1_000)) first_media = await _recv_media(consumer) frame = await asyncio.wait_for(anext(first_media), timeout=5.0) - assert (frame.payload, frame.timestamp, frame.keyframe) == (b"a", timedelta(seconds=1), True) + assert (frame.payload, frame.timestamp, frame.keyframe) == (b"a", moq.Timestamp(1_000_000, 1_000_000), True) # A newer group lands while the first is stalled mid-way. second = track.append_group() - second.write_frame(_legacy(1_040_000, b"c"), timedelta(milliseconds=2)) + second.write_frame(_legacy(1_040_000, b"c"), moq.Timestamp(2, 1_000)) second_media = await _recv_media(consumer) assert second_media.sequence == 1 frame = await asyncio.wait_for(anext(second_media), timeout=5.0) - assert (frame.payload, frame.timestamp) == (b"c", timedelta(microseconds=1_040_000)) + assert (frame.payload, frame.timestamp) == (b"c", moq.Timestamp(1_040_000, 1_000_000)) # The stalled group resumes and is still delivered. - first.write_frame(_legacy(1_020_000, b"b"), timedelta(milliseconds=3)) + first.write_frame(_legacy(1_020_000, b"b"), moq.Timestamp(3, 1_000)) frame = await asyncio.wait_for(anext(first_media), timeout=5.0) - assert (frame.payload, frame.timestamp, frame.keyframe) == (b"b", timedelta(microseconds=1_020_000), False) + assert (frame.payload, frame.timestamp, frame.keyframe) == (b"b", moq.Timestamp(1_020_000, 1_000_000), False) first.finish() second.finish() @@ -1200,20 +1200,20 @@ async def test_container_group_takes_over_an_unread_group(): consumer = await broadcast.consume().subscribe_track("audio") group = track.append_group() - group.write_frame(_legacy(1_000_000, b"a"), timedelta(milliseconds=1)) + group.write_frame(_legacy(1_000_000, b"a"), moq.Timestamp(1, 1_000)) raw = await _recv_raw(consumer) assert await raw.read_frame() is not None with pytest.raises(moq.Error.AlreadyCommitted): moq.media.GroupConsumer(raw, _LEGACY) group = track.append_group() - group.write_frame(_legacy(1_020_000, b"b"), timedelta(milliseconds=2)) + group.write_frame(_legacy(1_020_000, b"b"), moq.Timestamp(2, 1_000)) raw = await _recv_raw(consumer) media = moq.media.GroupConsumer(raw, _LEGACY) with pytest.raises(moq.Error.Cancelled): await raw.read_frame() frame = await asyncio.wait_for(anext(media), timeout=5.0) - assert frame.timestamp == timedelta(microseconds=1_020_000) + assert frame.timestamp == moq.Timestamp(1_020_000, 1_000_000) async def test_container_group_fails_loudly(): @@ -1224,7 +1224,7 @@ async def test_container_group_fails_loudly(): group = track.append_group() # A truncated varint timestamp: the 2-byte form with only its first byte. - group.write_frame(b"\x40", timedelta(milliseconds=1)) + group.write_frame(b"\x40", moq.Timestamp(1, 1_000)) raw = await _recv_raw(consumer) with pytest.raises(moq.Error.Codec): moq.media.GroupConsumer(raw, cast(moq.media.Container, moq.media.Container.CMAF(init=b""))) @@ -1287,21 +1287,21 @@ async def test_raw_read_frame_preserves_timestamp(): track = broadcast.publish_track("status", moq.TrackInfo(timescale=1_000_000)) consumer = track.consume() - track.write_frame(b"ready", timedelta(microseconds=12_345)) + track.write_frame(b"ready", moq.Timestamp(12_345, 1_000_000)) frame = await consumer.read_frame() assert frame is not None assert frame.payload == b"ready" - assert frame.timestamp == timedelta(microseconds=12_345) + assert frame.timestamp == moq.Timestamp(12_345, 1_000_000) group = track.append_group() group_consumer = group.consume() - group.write_frame(b"group", timedelta(microseconds=23_456)) + group.write_frame(b"group", moq.Timestamp(23_456, 1_000_000)) group.finish() frame = await group_consumer.read_frame() assert frame is not None assert frame.payload == b"group" - assert frame.timestamp == timedelta(microseconds=23_456) + assert frame.timestamp == moq.Timestamp(23_456, 1_000_000) async def test_read_frame_skips_remaining_frames_in_group(): @@ -1352,11 +1352,11 @@ async def test_read_frame_skips_empty_group_on_open_track(): await asyncio.sleep(0.05) assert not read.done(), "empty group must not end an open track" - track.write_frame(b"after-empty", timedelta(microseconds=1_000)) + track.write_frame(b"after-empty", moq.Timestamp(1_000, 1_000_000)) frame = await asyncio.wait_for(read, timeout=5.0) assert frame is not None assert frame.payload == b"after-empty" - assert frame.timestamp == timedelta(microseconds=1_000) + assert frame.timestamp == moq.Timestamp(1_000, 1_000_000) async def test_read_frame_skips_empty_then_populated_groups(): @@ -1367,12 +1367,12 @@ async def test_read_frame_skips_empty_then_populated_groups(): track.append_group().finish() track.append_group().finish() - track.write_frame(b"populated", timedelta(microseconds=2_000)) + track.write_frame(b"populated", moq.Timestamp(2_000, 1_000_000)) frame = await asyncio.wait_for(consumer.read_frame(), timeout=5.0) assert frame is not None assert frame.payload == b"populated" - assert frame.timestamp == timedelta(microseconds=2_000) + assert frame.timestamp == moq.Timestamp(2_000, 1_000_000) async def test_read_frame_keeps_group_across_cancelled_call(): @@ -1389,14 +1389,14 @@ async def test_read_frame_keeps_group_across_cancelled_call(): with pytest.raises(asyncio.CancelledError): await read - group.write_frame(b"kept", timedelta(microseconds=3_000)) + group.write_frame(b"kept", moq.Timestamp(3_000, 1_000_000)) group.finish() track.finish() frame = await asyncio.wait_for(consumer.read_frame(), timeout=5.0) assert frame is not None assert frame.payload == b"kept" - assert frame.timestamp == timedelta(microseconds=3_000) + assert frame.timestamp == moq.Timestamp(3_000, 1_000_000) assert await asyncio.wait_for(consumer.read_frame(), timeout=5.0) is None @@ -1458,7 +1458,7 @@ def test_encode_audio_with_opus_object(): del output del codec # One 20 ms Opus frame of silence at 48 kHz mono. - producer.write(moq.audio.Frame(timestamp=timedelta(0), data=bytes(960 * 4))) + producer.write(moq.audio.Frame(timestamp=moq.Timestamp(0, 1_000_000), data=bytes(960 * 4))) assert producer.demand().name == "mic" producer.finish() broadcast.close() @@ -1492,7 +1492,7 @@ def output(delay: timedelta | None) -> moq.audio.DecoderOutput: # Two 20 ms Opus frames of silence at 48 kHz mono. for i in range(2): - audio.write(moq.audio.Frame(timestamp=timedelta(milliseconds=20 * i), data=bytes(960 * 4))) + audio.write(moq.audio.Frame(timestamp=moq.Timestamp(20 * i, 1_000), data=bytes(960 * 4))) assert isinstance(await asyncio.wait_for(anext(fixed), timeout=5.0), moq.audio.Frame) assert isinstance(await asyncio.wait_for(anext(estimated), timeout=5.0), moq.audio.Frame) @@ -1531,7 +1531,7 @@ async def test_decode_video_frame(): rgba = bytes([0x80]) * (320 * 240 * 4) video.cut() for i in range(10): - video.write(moq.video.Frame(timestamp=timedelta(microseconds=i * 33_333), data=rgba)) + video.write(moq.video.Frame(timestamp=moq.Timestamp(i * 33_333, 1_000_000), data=rgba)) consumer = origin.consume() broadcast_consumer = await asyncio.wait_for(consumer.request_broadcast("video-decode-frame"), timeout=5.0) @@ -1543,7 +1543,7 @@ async def test_decode_video_frame(): # Keep the encoder fed so the decoder sees frames after it joined. for i in range(10, 40): - video.write(moq.video.Frame(timestamp=timedelta(microseconds=i * 33_333), data=rgba)) + video.write(moq.video.Frame(timestamp=moq.Timestamp(i * 33_333, 1_000_000), data=rgba)) frame = await asyncio.wait_for(anext(decoder), timeout=5.0) decoder.cancel() diff --git a/py/moq-rs/tests/test_media_reads.py b/py/moq-rs/tests/test_media_reads.py index 9e583c2d6f0..1199a68904e 100644 --- a/py/moq-rs/tests/test_media_reads.py +++ b/py/moq-rs/tests/test_media_reads.py @@ -3,18 +3,20 @@ from datetime import timedelta from typing import Any, cast -from moq import media -from moq_ffi import MoqMediaFrame, MoqMediaRead +from moq import Timestamp, media +from moq_ffi import MoqMediaFrame, MoqMediaRead, MoqTimestamp async def test_tagged_media_reads_preserve_frames_breaks_and_eof(): payload = b"encoded packet" + first = MoqTimestamp(value=11_111, scale=90_000) + end = MoqTimestamp(value=18_212, scale=90_000) records = iter( [ - MoqMediaRead.FRAME(frame=MoqMediaFrame(payload=payload, timestamp_us=123_456, keyframe=True)), - MoqMediaRead.GAP(timestamp_us=123_456, duration=timedelta(microseconds=78_901)), - MoqMediaRead.END(end_us=202_357), - MoqMediaRead.FRAME(frame=MoqMediaFrame(payload=b"resumed", timestamp_us=202_357, keyframe=False)), + MoqMediaRead.FRAME(frame=MoqMediaFrame(payload=payload, timestamp=first, keyframe=True)), + MoqMediaRead.GAP(timestamp=first, duration=timedelta(microseconds=78_901)), + MoqMediaRead.END(end=end), + MoqMediaRead.FRAME(frame=MoqMediaFrame(payload=b"resumed", timestamp=end, keyframe=False)), None, ] ) @@ -24,8 +26,8 @@ async def next(self): return next(records) reader = media.TrackConsumer(cast(Any, Inner())) - assert await reader._next() == media.MediaFrame(payload, timedelta(microseconds=123_456), True) - assert await reader._next() == media.Gap(timedelta(microseconds=123_456), timedelta(microseconds=78_901)) - assert await reader._next() == media.End(timedelta(microseconds=202_357)) - assert await reader._next() == media.MediaFrame(b"resumed", timedelta(microseconds=202_357), False) + assert await reader._next() == media.MediaFrame(payload, Timestamp(11_111, 90_000), True) + assert await reader._next() == media.Gap(Timestamp(11_111, 90_000), timedelta(microseconds=78_901)) + assert await reader._next() == media.End(Timestamp(18_212, 90_000)) + assert await reader._next() == media.MediaFrame(b"resumed", Timestamp(18_212, 90_000), False) assert await reader._next() is None diff --git a/py/moq-rs/tests/test_server.py b/py/moq-rs/tests/test_server.py index 7e4c3aac91e..bbed3a9394a 100644 --- a/py/moq-rs/tests/test_server.py +++ b/py/moq-rs/tests/test_server.py @@ -80,12 +80,12 @@ async def accept_loop() -> None: media_consumer = await moq.media.TrackConsumer.subscribe(broadcast_consumer, track_name, audio) payload = b"hello over the wire" - media.write_frame(payload, timedelta(microseconds=1_000_000)) + media.write_frame(payload, moq.Timestamp(1_000_000, 1_000_000)) async for frame in media_consumer: assert isinstance(frame, moq.media.MediaFrame) assert frame.payload == payload - assert frame.timestamp // timedelta(microseconds=1) == 1_000_000 + assert frame.timestamp == moq.Timestamp(1_000_000, 1_000_000) break break diff --git a/rs/moq-c/README.md b/rs/moq-c/README.md index 8b5b8ca9141..9f648eebae3 100644 --- a/rs/moq-c/README.md +++ b/rs/moq-c/README.md @@ -75,11 +75,11 @@ int32_t moq_publish_container(uint32_t broadcast, const moq_container_init *conf int32_t moq_publish_container_write(uint32_t container, const uint8_t *payload, uintptr_t payload_size); int32_t moq_publish_container_finish(uint32_t container); int32_t moq_publish_media_finish(uint32_t media); -int32_t moq_publish_media_frame(uint32_t media, const uint8_t *payload, uintptr_t payload_size, uint64_t timestamp_us); +int32_t moq_publish_media_frame(uint32_t media, const uint8_t *payload, uintptr_t payload_size, moq_timestamp timestamp); int32_t moq_publish_track(uint32_t broadcast, const char *name, uintptr_t name_len, const moq_track_info *info); int32_t moq_publish_track_group(uint32_t track); -int32_t moq_publish_track_frame(uint32_t track, const uint8_t *payload, uintptr_t payload_size, uint64_t timestamp_us); -int32_t moq_publish_group_frame(uint32_t group, const uint8_t *payload, uintptr_t payload_size, uint64_t timestamp_us); +int32_t moq_publish_track_frame(uint32_t track, const uint8_t *payload, uintptr_t payload_size, const moq_timestamp *timestamp); +int32_t moq_publish_group_frame(uint32_t group, const uint8_t *payload, uintptr_t payload_size, const moq_timestamp *timestamp); int32_t moq_publish_group_finish(uint32_t group); int32_t moq_publish_track_finish(uint32_t track); @@ -137,8 +137,9 @@ int32_t moq_consume_track_frame_free(uint32_t frame); int32_t moq_consume_track_cancel(uint32_t track); ``` -Raw track frames use the same `moq_frame` record as media frames. Use -`moq_publish_track_frame` or `moq_publish_group_frame` to provide microsecond -presentation timestamps; `moq_consume_track_frame` returns that timestamp in -`moq_frame.timestamp_us`. moq-c creates raw tracks with a microsecond -timescale, matching the C ABI's timestamp units. +Raw track frames use the same `moq_frame` record as media frames. Timestamps +are exact `moq_timestamp` records, `value` units at `scale` units per second. +`moq_publish_track_frame` and `moq_publish_group_frame` convert theirs to the +track's timescale, a microsecond one unless `moq_track_info.timescale` sets +another, and `moq_consume_track_frame` points `moq_frame.timestamp` at the +timestamp read, valid until the frame is freed, or NULL on an untimed track. diff --git a/rs/moq-c/c-tests/audio-decode-output.c b/rs/moq-c/c-tests/audio-decode-output.c index cc881aadbb5..81bb9e5c802 100644 --- a/rs/moq-c/c-tests/audio-decode-output.c +++ b/rs/moq-c/c-tests/audio-decode-output.c @@ -51,7 +51,8 @@ static void on_catalog(void *data, int32_t id) { } static void check_frame(Context *c, const moq_audio_frame *frame) { - CHECK(frame->timestamp_us == 123000 + c->frames * 1000000 / 48000); + CHECK(frame->timestamp.scale == 1000000); + CHECK(frame->timestamp.value == 123000 + c->frames * 1000000 / 48000); size_t bytes = c->format == MOQ_AUDIO_SAMPLE_FORMAT_S16 ? 2 : 4; CHECK(frame->data_size % (bytes * c->channels) == 0); size_t count = frame->data_size / (bytes * c->channels); @@ -112,7 +113,7 @@ int main(void) { CHECK(producer > 0); float pcm[960 * 2]; for (size_t sample = 0; sample < 960; sample++) { pcm[sample * 2] = 0.25f; pcm[sample * 2 + 1] = -0.5f; } - moq_audio_frame frame = {123000, (const uint8_t *)pcm, sizeof(pcm)}; + moq_audio_frame frame = {{123000, 1000000}, (const uint8_t *)pcm, sizeof(pcm)}; CHECK(moq_encode_audio_frame((uint32_t)producer, &frame) == 0); CHECK(moq_encode_audio_finish((uint32_t)producer) == 0); diff --git a/rs/moq-c/c-tests/decode-output.c b/rs/moq-c/c-tests/decode-output.c index b342a49e950..ccf787d88ca 100644 --- a/rs/moq-c/c-tests/decode-output.c +++ b/rs/moq-c/c-tests/decode-output.c @@ -180,7 +180,7 @@ static uint64_t next_ts; static void publish_frames(int32_t producer, int count) { for (int i = 0; i < count; i++) { - moq_video_encoder_frame frame = {next_ts, gray_rgba, sizeof(gray_rgba)}; + moq_video_encoder_frame frame = {{next_ts, 1000000}, gray_rgba, sizeof(gray_rgba)}; next_ts += 33333; int32_t rc = moq_encode_video_frame((uint32_t)producer, &frame); if (rc < 0) fail("error: moq_encode_video_frame failed: %d (%s)\n", rc, moq_error()); diff --git a/rs/moq-c/c-tests/timestamps.c b/rs/moq-c/c-tests/timestamps.c new file mode 100644 index 00000000000..c1e28eb4e7d --- /dev/null +++ b/rs/moq-c/c-tests/timestamps.c @@ -0,0 +1,154 @@ +// Exact timestamps across the installed C ABI: a 90 kHz tick and a present zero +// read back unchanged from raw frames and datagrams, a JSON value carries its +// frame's timestamp, and a write refuses an out-of-range timestamp or an +// untimed frame on a timed track. moq-c only creates timed tracks, so the +// untimed read path is covered by the Rust tests. +#include + +#include +#include +#include +#include +#include +#include +#include + +#define CHECK(expr) do { if (!(expr)) { \ + fprintf(stderr, "%s:%d: %s (%s)\n", __FILE__, __LINE__, #expr, moq_error()); \ + abort(); \ +} } while (0) + +// Wait up to 10 seconds for `cond`, evaluated under the context lock. +#define WAIT_FOR(c, cond) do { \ + struct timespec deadline; \ + CHECK(clock_gettime(CLOCK_REALTIME, &deadline) == 0); \ + deadline.tv_sec += 10; \ + pthread_mutex_lock(&(c)->mutex); \ + while (!(cond)) CHECK(pthread_cond_timedwait(&(c)->changed, &(c)->mutex, &deadline) == 0); \ + pthread_mutex_unlock(&(c)->mutex); \ +} while (0) + +typedef struct { + pthread_mutex_t mutex; + pthread_cond_t changed; + int32_t broadcast, frames[2], datagram, value; + size_t frame_count; + int request_done, frames_done, datagrams_done, values_done; +} Context; + +// Record a delivered id in `slot`, or the terminal status in `done`. +static void deliver(Context *c, int32_t id, int32_t *slot, int *done) { + pthread_mutex_lock(&c->mutex); + if (id > 0) *slot = id; + else { CHECK(id == 0); *done = 1; } + pthread_cond_broadcast(&c->changed); + pthread_mutex_unlock(&c->mutex); +} + +static void on_broadcast(void *data, int32_t id) { + Context *c = data; + deliver(c, id, &c->broadcast, &c->request_done); +} + +static void on_frame(void *data, int32_t id) { + Context *c = data; + pthread_mutex_lock(&c->mutex); + if (id > 0) { CHECK(c->frame_count < 2); c->frames[c->frame_count++] = id; } + else { CHECK(id == 0); c->frames_done = 1; } + pthread_cond_broadcast(&c->changed); + pthread_mutex_unlock(&c->mutex); +} + +static void on_datagram(void *data, int32_t id) { + Context *c = data; + deliver(c, id, &c->datagram, &c->datagrams_done); +} + +static void on_value(void *data, int32_t id) { + Context *c = data; + deliver(c, id, &c->value, &c->values_done); +} + +static bool same(const moq_timestamp *got, moq_timestamp want) { + return got != NULL && got->value == want.value && got->scale == want.scale; +} + +int main(void) { + Context c = {.mutex = PTHREAD_MUTEX_INITIALIZER, .changed = PTHREAD_COND_INITIALIZER}; + int32_t origin = moq_origin_create(); + CHECK(origin > 0); + const char *path = "timestamps"; + int32_t broadcast = moq_origin_create_broadcast((uint32_t)origin, path, strlen(path)); + CHECK(broadcast > 0); + CHECK(moq_publish_announce((uint32_t)broadcast, NULL) == 0); + moq_track_info info = {0}; + info.timescale = 90000; + info.timescale_present = true; + int32_t track = moq_publish_track((uint32_t)broadcast, "ticks", 5, &info); + CHECK(track > 0); + moq_json_stream_config json_config = {false}; + int32_t json = moq_publish_json_stream((uint32_t)broadcast, "json", 4, &json_config); + CHECK(json > 0); + + const uint8_t payload[] = {1, 2, 3}; + const moq_timestamp invalid[] = {{0, 0}, {0, 1ull << 62}, {1ull << 61, 1000000}}; + for (size_t i = 0; i < sizeof(invalid) / sizeof(invalid[0]); i++) + CHECK(moq_publish_track_frame((uint32_t)track, payload, sizeof(payload), &invalid[i]) == + MOQ_ERROR_TIMESTAMP_OVERFLOW); + CHECK(moq_publish_track_frame((uint32_t)track, payload, sizeof(payload), NULL) == MOQ_ERROR_MOQ); + + CHECK(moq_origin_request((uint32_t)origin, path, strlen(path), on_broadcast, &c) > 0); + WAIT_FOR(&c, c.broadcast); + int32_t frames = moq_consume_track((uint32_t)c.broadcast, "ticks", 5, NULL, on_frame, &c); + CHECK(frames > 0); + int32_t datagrams = moq_consume_datagrams((uint32_t)c.broadcast, "ticks", 5, on_datagram, &c); + CHECK(datagrams > 0); + int32_t values = moq_consume_json_stream((uint32_t)c.broadcast, "json", 4, &json_config, on_value, &c); + CHECK(values > 0); + + // One group at a time, so the default subscription never skips the older one, and in + // time order, since a group may not start before the one preceding it. + const moq_timestamp zero = {0, 90000}, tick = {1, 90000}; + CHECK(moq_publish_track_frame((uint32_t)track, payload, sizeof(payload), &zero) == 0); + WAIT_FOR(&c, c.frame_count == 1); + CHECK(moq_publish_track_frame((uint32_t)track, payload, sizeof(payload), &tick) == 0); + WAIT_FOR(&c, c.frame_count == 2); + CHECK(moq_publish_track_datagram((uint32_t)track, payload, sizeof(payload), &tick, NULL) == 0); + WAIT_FOR(&c, c.datagram); + const char *doc = "{\"n\":1}"; + CHECK(moq_publish_json_stream_append((uint32_t)json, doc, strlen(doc)) == 0); + WAIT_FOR(&c, c.value); + + // Each timestamp points into its own read, so both stay intact until freed. + moq_frame first, second; + CHECK(moq_consume_track_frame((uint32_t)c.frames[0], &first) == 0); + CHECK(moq_consume_track_frame((uint32_t)c.frames[1], &second) == 0); + CHECK(same(first.timestamp, zero)); + CHECK(same(second.timestamp, tick)); + CHECK(moq_consume_track_frame_free((uint32_t)c.frames[0]) == 0); + CHECK(moq_consume_track_frame_free((uint32_t)c.frames[1]) == 0); + + moq_datagram datagram; + CHECK(moq_consume_datagram((uint32_t)c.datagram, &datagram) == 0); + CHECK(same(datagram.timestamp, tick)); + CHECK(moq_consume_datagram_free((uint32_t)c.datagram) == 0); + + // The JSON producer stamps each value with the broadcast clock. + moq_json_value value; + CHECK(moq_consume_json_value((uint32_t)c.value, &value) == 0); + CHECK(value.timestamp != NULL && value.timestamp->scale != 0); + CHECK(moq_consume_json_value_free((uint32_t)c.value) == 0); + + CHECK(moq_consume_track_cancel((uint32_t)frames) == 0); + CHECK(moq_consume_datagrams_cancel((uint32_t)datagrams) == 0); + CHECK(moq_consume_json_cancel((uint32_t)values) == 0); + WAIT_FOR(&c, c.frames_done && c.datagrams_done && c.values_done); + CHECK(moq_consume_close((uint32_t)c.broadcast) == 0); + CHECK(moq_publish_json_stream_finish((uint32_t)json) == 0); + CHECK(moq_publish_track_finish((uint32_t)track) == 0); + CHECK(moq_publish_close((uint32_t)broadcast) == 0); + CHECK(moq_origin_close((uint32_t)origin) == 0); + WAIT_FOR(&c, c.request_done); + fprintf(stderr, "C exact timestamps passed\n"); + return 0; +} diff --git a/rs/moq-c/src/api.rs b/rs/moq-c/src/api.rs index cbb48b75c08..25d861c6312 100644 --- a/rs/moq-c/src/api.rs +++ b/rs/moq-c/src/api.rs @@ -15,8 +15,7 @@ use tracing::Level; #[expect(non_camel_case_types, reason = "C ABI type names match moq.h")] #[derive(Clone, Copy, Debug)] pub enum moq_container_kind { - /// A QUIC varint timestamp prefix followed by the raw codec payload. - /// Timestamps are in microseconds. + /// A QUIC varint timestamp prefix in microseconds followed by the raw codec payload. MOQ_CONTAINER_KIND_LEGACY = 0, /// Fragmented MP4: each frame is a complete moof+mdat fragment, described by /// the init segment in `moq_container::init`. @@ -448,6 +447,37 @@ pub struct moq_binary_config { pub mime_len: usize, } +/// An exact media timestamp: `value` units at `scale` units per second. +/// +/// Reads carry the scale the publisher wrote, so a tick such as 90 kHz survives a read and +/// republish exactly. A write with a zero scale, a scale above `2^62 - 1`, or a value above +/// `2^61 - 1` fails with `MOQ_ERROR_TIMESTAMP_OVERFLOW`. +#[repr(C)] +#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)] +pub struct moq_timestamp { + /// The time in `scale` units, at most `2^61 - 1`. + pub value: u64, + /// Units per second, non-zero and at most `2^62 - 1`. + pub scale: u64, +} + +impl From for moq_timestamp { + fn from(timestamp: moq_net::Timestamp) -> Self { + Self { + value: timestamp.value(), + scale: timestamp.scale().as_u64(), + } + } +} + +impl TryFrom for moq_net::Timestamp { + type Error = moq_net::TimeOverflow; + + fn try_from(timestamp: moq_timestamp) -> Result { + Self::from_scale(timestamp.value, timestamp.scale) + } +} + /// A JSON value delivered by a consumer callback. #[repr(C)] pub struct moq_json_value { @@ -456,13 +486,9 @@ pub struct moq_json_value { /// The length in bytes of `json`. pub json_len: usize, - /// The timestamp of the frame that carried the value in microseconds, or 0 when - /// `timestamp_present` is false. Rounded down to a whole microsecond, so a tick on a track - /// like 90 kHz may not survive a read and republish exactly. - pub timestamp_us: u64, - - /// Whether the frame carries a timestamp. A value read from an untimed track does not. - pub timestamp_present: bool, + /// The timestamp of the frame that carried the value, or NULL on an untimed track. + /// Valid as long as `json`. + pub timestamp: *const moq_timestamp, } /// Information about a frame of media. @@ -473,13 +499,9 @@ pub struct moq_frame { /// The length in bytes of `payload`. pub payload_size: usize, - /// The presentation timestamp of the frame in microseconds, or 0 when - /// `timestamp_present` is false. - pub timestamp_us: u64, - - /// Whether the frame carries a timestamp. Media frames always do; a raw frame read - /// from an untimed track does not. - pub timestamp_present: bool, + /// The presentation timestamp of the frame, or NULL on an untimed track. Media frames + /// always have one. Valid as long as `payload`. + pub timestamp: *const moq_timestamp, /// Whether this frame opens a group or is a video keyframe; audio is true only at a group start. pub keyframe: bool, @@ -494,9 +516,9 @@ pub struct moq_media_read { pub frame: moq_frame, /// Lost media for a gap read; what follows does not continue it. pub gap: crate::moq_decode_gap, - /// Where a stopped encoder's media stops, in microseconds. Following frames before - /// this point are its remaining media; the first at or past it comes from a fresh encoder. - pub end_us: u64, + /// Where a stopped encoder's media stops. Following frames before this point are its + /// remaining media; the first at or past it comes from a fresh encoder. + pub end: moq_timestamp, } /// A best-effort raw track datagram delivered via [moq_consume_datagrams]. @@ -507,12 +529,9 @@ pub struct moq_datagram { /// The length in bytes of `payload`. pub payload_size: usize, - /// The presentation timestamp of the datagram in microseconds, or 0 when - /// `timestamp_present` is false. - pub timestamp_us: u64, - - /// Whether the datagram carries a timestamp. One read from an untimed track does not. - pub timestamp_present: bool, + /// The presentation timestamp of the datagram, or NULL on an untimed track. Valid as + /// long as `payload`. + pub timestamp: *const moq_timestamp, /// Per-track sequence number, drawn from the same namespace as groups. pub sequence: u64, @@ -536,8 +555,7 @@ pub struct moq_track_info { /// Per-frame timescale in ticks per second. pub timescale: u64, - /// Whether `timescale` is set. When false, the default microsecond timescale - /// applies, matching the `timestamp_us` units used everywhere else in this ABI. + /// Whether `timescale` is set. When false, a microsecond timescale applies. pub timescale_present: bool, /// A joining subscriber asks for a new group once the newest group's bytes after its @@ -555,8 +573,7 @@ impl TryFrom<&moq_track_info> for moq_net::track::Info { type Error = Error; fn try_from(info: &moq_track_info) -> Result { - // Raw tracks default to a microsecond timescale, matching the C ABI's - // timestamp_us units. An explicit timescale below overrides it. + // Raw tracks default to a microsecond timescale; an explicit one below overrides it. let mut out = moq_net::track::Info::default() .with_timescale(moq_net::Timescale::MICRO) .with_priority(info.priority); @@ -642,8 +659,8 @@ pub struct moq_anchor { /// The group, or with `MOQ_ANCHOR_RELATIVE` how many groups before the latest one /// (0 is the latest, and an offset past the first group clamps to it). pub group: u64, - /// The presentation time in microseconds, read only with `MOQ_ANCHOR_TIME`. - pub timestamp_us: u64, + /// The presentation time, read only with `MOQ_ANCHOR_TIME`. + pub timestamp: moq_timestamp, } /// How a [moq_anchor] names its position. @@ -674,9 +691,7 @@ fn parse_anchor(anchor: &moq_anchor) -> Result { Ok(match anchor.kind { v if v == moq_anchor_kind::MOQ_ANCHOR_ABSOLUTE as u32 => moq_net::track::Anchor::Absolute(anchor.group), v if v == moq_anchor_kind::MOQ_ANCHOR_RELATIVE as u32 => moq_net::track::Anchor::Relative(anchor.group), - v if v == moq_anchor_kind::MOQ_ANCHOR_TIME as u32 => { - moq_net::track::Anchor::Time(moq_net::Timestamp::from_micros(anchor.timestamp_us)?) - } + v if v == moq_anchor_kind::MOQ_ANCHOR_TIME as u32 => moq_net::track::Anchor::Time(anchor.timestamp.try_into()?), _ => return Err(Error::InvalidCode), }) } @@ -2524,7 +2539,6 @@ pub extern "C" fn moq_publish_container_finish(container: u32) -> i32 { /// Write data to a track. /// /// The encoding of `data` depends on the track `format`. -/// The timestamp is in microseconds. /// /// Returns a zero on success, or a negative code on failure. /// @@ -2535,13 +2549,12 @@ pub unsafe extern "C" fn moq_publish_media_frame( media: u32, payload: *const u8, payload_size: usize, - timestamp_us: u64, + timestamp: moq_timestamp, ) -> i32 { ffi::enter(move || { let media = ffi::parse_id(media)?; let payload = unsafe { ffi::parse_slice(payload, payload_size)? }; - let timestamp = hang::container::Timestamp::from_micros(timestamp_us)?; - State::lock().publish.media_frame(media, payload, timestamp) + State::lock().publish.media_frame(media, payload, timestamp.try_into()?) }) } @@ -2841,31 +2854,33 @@ pub extern "C" fn moq_publish_track_group_at(track: u32, sequence: u64) -> i32 { /// Write a single-frame group to a raw track with a timestamp. /// /// Convenience for the common one-frame-per-group pattern. Equivalent to -/// appending a group, writing one frame, and finishing it. -/// The timestamp is in microseconds. +/// appending a group, writing one frame, and finishing it. The timestamp is +/// converted to the track's timescale; NULL writes an untimed frame, which only +/// an untimed track accepts. /// /// Returns a zero on success, or a negative code on failure. /// /// # Safety /// - The caller must ensure that payload is a valid pointer to payload_size bytes of data. +/// - `timestamp` must be NULL or a valid pointer to a [moq_timestamp]. #[unsafe(no_mangle)] pub unsafe extern "C" fn moq_publish_track_frame( track: u32, payload: *const u8, payload_size: usize, - timestamp_us: u64, + timestamp: *const moq_timestamp, ) -> i32 { ffi::enter(move || { let track = ffi::parse_id(track)?; let payload = unsafe { ffi::parse_slice(payload, payload_size)? }; - let timestamp = moq_net::Timestamp::from_micros(timestamp_us)?; + let timestamp = unsafe { ffi::parse_timestamp(timestamp)? }; State::lock().publish.track_frame(track, timestamp, payload) }) } /// Send a best-effort datagram on a raw track created by [moq_publish_track]. /// -/// Takes `payload` then `timestamp_us`, matching [moq_publish_track_frame]. The payload must +/// Takes `payload` then `timestamp`, matching [moq_publish_track_frame]. The payload must /// be at most 1200 bytes. On success the datagram's per-track sequence number (shared with the /// group namespace) is written to `out_sequence` when it is non-NULL. Datagrams are /// delivered only on transports and wire versions with a datagram channel; there is no @@ -2875,19 +2890,21 @@ pub unsafe extern "C" fn moq_publish_track_frame( /// /// # Safety /// - The caller must ensure that payload is a valid pointer to payload_size bytes of data. +/// - `timestamp` must be NULL or a valid pointer to a [moq_timestamp]. /// - `out_sequence` must be NULL or a valid pointer to a `uint64_t`. #[unsafe(no_mangle)] pub unsafe extern "C" fn moq_publish_track_datagram( track: u32, payload: *const u8, payload_size: usize, - timestamp_us: u64, + timestamp: *const moq_timestamp, out_sequence: *mut u64, ) -> i32 { ffi::enter(move || { let track = ffi::parse_id(track)?; let payload = unsafe { ffi::parse_slice(payload, payload_size)? }; - let sequence = State::lock().publish.track_datagram(track, timestamp_us, payload)?; + let timestamp = unsafe { ffi::parse_timestamp(timestamp)? }; + let sequence = State::lock().publish.track_datagram(track, timestamp, payload)?; if let Some(out) = unsafe { out_sequence.as_mut() } { *out = sequence; } @@ -3232,23 +3249,25 @@ pub extern "C" fn moq_group_request_free(request: u32) -> i32 { /// Write a frame into a raw group created by [moq_publish_track_group]. /// -/// The timestamp is in microseconds. +/// The timestamp is converted to the track's timescale; NULL writes an untimed +/// frame, which only an untimed track accepts. /// /// Returns a zero on success, or a negative code on failure. /// /// # Safety /// - The caller must ensure that payload is a valid pointer to payload_size bytes of data. +/// - `timestamp` must be NULL or a valid pointer to a [moq_timestamp]. #[unsafe(no_mangle)] pub unsafe extern "C" fn moq_publish_group_frame( group: u32, payload: *const u8, payload_size: usize, - timestamp_us: u64, + timestamp: *const moq_timestamp, ) -> i32 { ffi::enter(move || { let group = ffi::parse_id(group)?; let payload = unsafe { ffi::parse_slice(payload, payload_size)? }; - let timestamp = moq_net::Timestamp::from_micros(timestamp_us)?; + let timestamp = unsafe { ffi::parse_timestamp(timestamp)? }; State::lock().publish.group_frame(group, timestamp, payload) }) } @@ -3802,7 +3821,7 @@ pub extern "C" fn moq_consume_audio_cancel(track: u32) -> i32 { } /// Read an encoded media frame, gap, or encoder end delivered by a media callback. -/// Payload pointers borrow the read until [`moq_consume_read_free`]. +/// Payload and timestamp pointers borrow the read until [`moq_consume_read_free`]. /// /// # Safety /// - `dst` must point to a writable [`moq_media_read`]. @@ -3900,10 +3919,9 @@ pub unsafe extern "C" fn moq_consume_track_update(track: u32, subscription: *con /// Read a raw frame's payload delivered via the [moq_consume_track] callback. /// /// Fills `dst.payload` / `dst.payload_size`; the pointer is valid until the -/// frame is released with [moq_consume_track_frame_free]. `dst.timestamp_us` is the -/// frame presentation timestamp in microseconds, when `dst.timestamp_present` says it -/// has one. `dst.keyframe` is reported as -/// false because raw tracks do not parse codec metadata. +/// frame is released with [moq_consume_track_frame_free], and so is `dst.timestamp`, +/// NULL on an untimed track. `dst.keyframe` is reported as false because raw tracks +/// do not parse codec metadata. /// /// Returns a zero on success, or a negative code on failure. /// @@ -3979,8 +3997,8 @@ pub unsafe extern "C" fn moq_consume_datagrams( /// Read a datagram delivered via the [moq_consume_datagrams] callback. /// /// Fills `dst.payload` / `dst.payload_size` (valid until the datagram is released with -/// [moq_consume_datagram_free]), plus `dst.timestamp_us` (when `dst.timestamp_present`) -/// and `dst.sequence`. +/// [moq_consume_datagram_free]), plus `dst.timestamp` (NULL on an untimed track, and valid +/// as long as the payload) and `dst.sequence`. /// /// Returns a zero on success, or a negative code on failure. /// @@ -4092,8 +4110,8 @@ pub unsafe extern "C" fn moq_consume_json_stream( /// Read a JSON value delivered via a [moq_consume_json_snapshot] or [moq_consume_json_stream] callback. /// -/// Fills `dst.json` / `dst.json_len` and the frame timestamp; the pointer is valid until the value is released with -/// [moq_consume_json_value_free]. +/// Fills `dst.json` / `dst.json_len` and the frame timestamp; both pointers are valid until the value is released +/// with [moq_consume_json_value_free]. /// /// Returns a zero on success, or a negative code on failure. /// diff --git a/rs/moq-c/src/audio.rs b/rs/moq-c/src/audio.rs index 0e6dad0265f..251d9c9d721 100644 --- a/rs/moq-c/src/audio.rs +++ b/rs/moq-c/src/audio.rs @@ -20,7 +20,7 @@ use tokio::sync::oneshot; use crate::decode::Read; use crate::ffi::OnStatus; -use crate::{moq_decode_gap, moq_decode_read_kind}; +use crate::{moq_decode_gap, moq_decode_read_kind, moq_timestamp}; use crate::task::Task; use crate::{Error, Id, NonZeroSlab, Shared, State, ffi}; @@ -134,8 +134,8 @@ pub struct moq_audio_decoder_output { /// (the publisher copies before returning). #[repr(C)] pub struct moq_audio_frame { - /// The presentation timestamp in microseconds. - pub timestamp_us: u64, + /// The presentation timestamp. + pub timestamp: moq_timestamp, /// The raw frame bytes in the configured layout. pub data: *const u8, /// The length in bytes of `data`. @@ -153,11 +153,11 @@ pub struct moq_audio_read { /// The lost span, for [moq_decode_read_kind::MOQ_DECODE_READ_GAP]. What follows does /// not continue what came before. pub gap: moq_decode_gap, - /// Where the stopped encoder's media stops in microseconds, for + /// Where the stopped encoder's media stops, for /// [moq_decode_read_kind::MOQ_DECODE_READ_END]. Frames that follow and start before it /// are the stopped encoder's remaining media; the first at or past it comes from a fresh /// encoder. - pub end_us: u64, + pub end: moq_timestamp, } // ---- State extensions (used internally by lib.rs) ---- @@ -288,7 +288,7 @@ impl Audio { read = consumer.read() => match read { Ok(Some(moq_audio::decode::Read::Frame(frame))) => Read::Frame(frame), Ok(Some(moq_audio::decode::Read::Gap { timestamp, duration })) => Read::gap(timestamp, duration)?, - Ok(Some(moq_audio::decode::Read::End { end })) => Read::end(end)?, + Ok(Some(moq_audio::decode::Read::End { end })) => Read::end(end), Ok(None) => return Ok(()), // One packet the codec rejected is that packet's problem: the // decoder stays usable, so drop it and keep the subscription rather @@ -315,29 +315,20 @@ impl Audio { /// Borrow a delivered read, and a frame's samples, until its handle is freed. pub fn read_info(&self, id: Id, dst: &mut moq_audio_read) -> Result<(), Error> { let read = self.reads.get(id).ok_or(Error::FrameNotFound)?; - let (kind, gap, end_us) = read.info(); + let (kind, gap, end) = read.info(); let frame = match read { Read::Frame(frame) => moq_audio_frame { - // The C ABI carries plain microseconds, so flatten the scaled - // `Timestamp` here at the boundary. Saturating rather than erroring: - // this is a getter on a frame we already decoded, and a u64 overflow - // needs a timestamp ~580,000 years out. - timestamp_us: u64::try_from(frame.timestamp.as_micros()).unwrap_or(u64::MAX), + timestamp: frame.timestamp.into(), data: frame.data.as_ptr(), data_size: frame.data.len(), }, _ => moq_audio_frame { - timestamp_us: 0, + timestamp: moq_timestamp::default(), data: std::ptr::null(), data_size: 0, }, }; - *dst = moq_audio_read { - kind, - frame, - gap, - end_us, - }; + *dst = moq_audio_read { kind, frame, gap, end }; Ok(()) } @@ -474,9 +465,7 @@ pub unsafe extern "C" fn moq_encode_audio_frame(producer: u32, frame: *const moq let frame = unsafe { frame.as_ref() }.ok_or(Error::InvalidPointer)?; let data = unsafe { ffi::parse_slice(frame.data, frame.data_size)? }; - // The C ABI carries plain microseconds; scale them at the boundary. - let timestamp = moq_net::Timestamp::from_micros(frame.timestamp_us).map_err(moq_audio::Error::from)?; - let owned = moq_audio::Frame::new(Bytes::copy_from_slice(data), timestamp); + let owned = moq_audio::Frame::new(Bytes::copy_from_slice(data), frame.timestamp.try_into()?); let producer = State::lock().audio.producer(producer)?; producer diff --git a/rs/moq-c/src/consume.rs b/rs/moq-c/src/consume.rs index 2557d98e4f5..2e0dfa8cf6c 100644 --- a/rs/moq-c/src/consume.rs +++ b/rs/moq-c/src/consume.rs @@ -12,7 +12,7 @@ use crate::ffi::OnStatus; use crate::task::Task; use crate::{ Error, Id, NonZeroSlab, State, moq_audio_config, moq_datagram, moq_frame, moq_json_value, moq_section, moq_string, - moq_video_config, moq_video_properties, + moq_timestamp, moq_video_config, moq_video_properties, }; struct ConsumeCatalog { @@ -157,29 +157,34 @@ enum RawStep { Stop, } -/// A raw frame, datagram, or JSON value timestamp in microseconds, `None` when untimed. -fn timestamp_us(timestamp: Option) -> Result, Error> { - timestamp - .map(|timestamp| timestamp.as_micros().try_into()) - .transpose() - .map_err(|_| Error::TimestampOverflow(moq_net::TimeOverflow)) +/// A buffered read plus the timestamp C borrows through a pointer, `None` when untimed. +/// +/// Boxed because the slab moves its entries as it grows, and the pointer must stay valid +/// until the read is freed. +struct Timed { + item: T, + timestamp: Option>, } -/// A JSON value pre-serialized to a string, with its frame timestamp. -struct JsonValue { - json: String, - timestamp_us: Option, -} +impl Timed { + fn new(item: T, timestamp: Option) -> Self { + Self { + item, + timestamp: timestamp.map(|timestamp| Box::new(timestamp.into())), + } + } -impl JsonValue { - fn new(value: moq_net::Timed) -> Result { - Ok(Self { - json: serde_json::to_string(&value.value)?, - timestamp_us: timestamp_us(value.at)?, - }) + /// The timestamp pointer handed to C, NULL when untimed. + fn timestamp(&self) -> *const moq_timestamp { + self.timestamp.as_deref().map_or(std::ptr::null(), std::ptr::from_ref) } } +/// A JSON value pre-serialized to a string, with its frame timestamp. +fn json_value(value: moq_net::Timed) -> Result, Error> { + Ok(Timed::new(serde_json::to_string(&value.value)?, value.at)) +} + #[derive(Default)] pub struct Consume { /// Active broadcast consumers. @@ -195,25 +200,25 @@ pub struct Consume { track_task: NonZeroSlab, /// Buffered frames ready for consumption. - reads: NonZeroSlab>, + reads: NonZeroSlab>>, /// Raw track consumer tasks (no media/container framing). raw_task: NonZeroSlab, /// Buffered raw frames ready for consumption. - raw_frame: NonZeroSlab, + raw_frame: NonZeroSlab>, /// Raw track datagram consumer tasks (best-effort, parallel to `raw_task`). datagram_task: NonZeroSlab, /// Buffered datagrams ready for consumption. - datagram: NonZeroSlab, + datagram: NonZeroSlab>, /// JSON consumer tasks (snapshot and stream share this slab). json_task: NonZeroSlab, /// Buffered JSON values ready for consumption. - json_value: NonZeroSlab, + json_value: NonZeroSlab>, } impl Consume { @@ -528,9 +533,12 @@ impl Consume { biased; _ = &mut close => return Ok(()), read = track.read() => match read? { - Some(moq_mux::container::Read::Frame { frame, .. }) => Read::Frame(frame), + Some(moq_mux::container::Read::Frame { frame, .. }) => { + let timestamp = frame.timestamp; + Read::Frame(Timed::new(frame, Some(timestamp))) + } Some(moq_mux::container::Read::Gap { timestamp, duration }) => Read::gap(timestamp, duration)?, - Some(moq_mux::container::Read::End { end, .. }) => Read::end(end)?, + Some(moq_mux::container::Read::End { end, .. }) => Read::end(end), None => return Ok(()), }, }; @@ -548,29 +556,22 @@ impl Consume { /// Read the tagged media item; payload pointers borrow it until [`Self::read_free`]. pub fn read(&self, id: Id, dst: &mut crate::moq_media_read) -> Result<(), Error> { let read = self.reads.get(id).ok_or(Error::FrameNotFound)?; - let (kind, gap, end_us) = read.info(); + let (kind, gap, end) = read.info(); let frame = match read { Read::Frame(f) => moq_frame { - payload: f.payload.as_ptr(), - payload_size: f.payload.len(), - timestamp_us: f.timestamp.as_micros().try_into().map_err(|_| moq_net::TimeOverflow)?, - timestamp_present: true, - keyframe: f.keyframe, + payload: f.item.payload.as_ptr(), + payload_size: f.item.payload.len(), + timestamp: f.timestamp(), + keyframe: f.item.keyframe, }, _ => moq_frame { payload: std::ptr::null(), payload_size: 0, - timestamp_us: 0, - timestamp_present: false, + timestamp: std::ptr::null(), keyframe: false, }, }; - *dst = crate::moq_media_read { - kind, - frame, - gap, - end_us, - }; + *dst = crate::moq_media_read { kind, frame, gap, end }; Ok(()) } @@ -708,6 +709,7 @@ impl Consume { }; // Hold the lock only to buffer the read; release it before the callback. + let frame = Timed::new(frame.payload, frame.timestamp); let frame_id = State::lock().consume.raw_frame.insert(frame)?; callback.call(Ok(frame_id)); } @@ -740,13 +742,11 @@ impl Consume { /// frame is released with [`Self::raw_frame_close`]. pub fn raw_frame(&self, frame: Id, dst: &mut moq_frame) -> Result<(), Error> { let frame = self.raw_frame.get(frame).ok_or(Error::FrameNotFound)?; - let timestamp_us = timestamp_us(frame.timestamp)?; *dst = moq_frame { - payload: frame.payload.as_ptr(), - payload_size: frame.payload.len(), - timestamp_us: timestamp_us.unwrap_or_default(), - timestamp_present: timestamp_us.is_some(), + payload: frame.item.as_ptr(), + payload_size: frame.item.len(), + timestamp: frame.timestamp(), keyframe: false, }; @@ -805,7 +805,8 @@ impl Consume { }; // Hold the lock only to buffer the datagram; release it before the callback. - let id = State::lock().consume.datagram.insert(datagram)?; + let timestamp = datagram.timestamp; + let id = State::lock().consume.datagram.insert(Timed::new(datagram, timestamp))?; callback.call(Ok(id)); } } @@ -819,14 +820,11 @@ impl Consume { pub fn datagram(&self, datagram: Id, dst: &mut moq_datagram) -> Result<(), Error> { let value = self.datagram.get(datagram).ok_or(Error::FrameNotFound)?; - let timestamp_us = timestamp_us(value.timestamp)?; - *dst = moq_datagram { - payload: value.payload.as_ptr(), - payload_size: value.payload.len(), - timestamp_us: timestamp_us.unwrap_or_default(), - timestamp_present: timestamp_us.is_some(), - sequence: value.sequence, + payload: value.item.payload.as_ptr(), + payload_size: value.item.payload.len(), + timestamp: value.timestamp(), + sequence: value.item.sequence, }; Ok(()) @@ -892,7 +890,7 @@ impl Consume { // Serialize before locking, hold the lock only to buffer the value, and release it // before the callback. - let value = JsonValue::new(value)?; + let value = json_value(value)?; let value_id = State::lock().consume.json_value.insert(value)?; callback.call(Ok(value_id)); } @@ -950,7 +948,7 @@ impl Consume { }, }; - let value = JsonValue::new(value)?; + let value = json_value(value)?; let value_id = State::lock().consume.json_value.insert(value)?; callback.call(Ok(value_id)); } @@ -968,10 +966,9 @@ impl Consume { let value = self.json_value.get(value).ok_or(Error::FrameNotFound)?; *dst = moq_json_value { - json: value.json.as_ptr() as *const c_char, - json_len: value.json.len(), - timestamp_us: value.timestamp_us.unwrap_or_default(), - timestamp_present: value.timestamp_us.is_some(), + json: value.item.as_ptr() as *const c_char, + json_len: value.item.len(), + timestamp: value.timestamp(), }; Ok(()) @@ -1090,6 +1087,10 @@ mod read_tests { track.finish().unwrap(); run.await.unwrap(); assert_eq!(ids.len(), 3); + let micros = |value| moq_timestamp { + value, + scale: 1_000_000, + }; let mut read = std::mem::MaybeUninit::::uninit(); for (index, id) in ids.into_iter().enumerate() { assert!(id > 0); @@ -1102,20 +1103,20 @@ mod read_tests { unsafe { std::slice::from_raw_parts(read.frame.payload, read.frame.payload_size) }, b"encoded" ); - assert_eq!(read.frame.timestamp_us, 10_000); - assert!(read.frame.timestamp_present && read.frame.keyframe); + assert_eq!(unsafe { *read.frame.timestamp }, micros(10_000)); + assert!(read.frame.keyframe); assert_eq!(read.gap.duration_us, 0); - assert_eq!(read.end_us, 0); + assert_eq!(read.end, moq_timestamp::default()); } 1 => { assert_eq!(read.kind, crate::moq_decode_read_kind::MOQ_DECODE_READ_GAP); - assert_eq!((read.gap.timestamp_us, read.gap.duration_us), (10_000, 10_000)); - assert!(read.frame.payload.is_null()); - assert_eq!(read.end_us, 0); + assert_eq!((read.gap.timestamp, read.gap.duration_us), (micros(10_000), 10_000)); + assert!(read.frame.payload.is_null() && read.frame.timestamp.is_null()); + assert_eq!(read.end, moq_timestamp::default()); } 2 => { assert_eq!(read.kind, crate::moq_decode_read_kind::MOQ_DECODE_READ_END); - assert_eq!(read.end_us, 20_000); + assert_eq!(read.end, micros(20_000)); assert!(read.frame.payload.is_null()); assert_eq!(read.gap.duration_us, 0); } diff --git a/rs/moq-c/src/decode.rs b/rs/moq-c/src/decode.rs index bfc57aabd43..034929b8cfa 100644 --- a/rs/moq-c/src/decode.rs +++ b/rs/moq-c/src/decode.rs @@ -3,7 +3,7 @@ //! Encoded media and both decoders hand over the same three kinds of read, so a C player //! handles loss and encoder ends alike for every media type. -use crate::Error; +use crate::{Error, moq_timestamp}; /// Which kind of media read was delivered: a frame, or a break between frames. #[repr(C)] @@ -24,53 +24,53 @@ pub enum moq_decode_read_kind { #[repr(C)] #[derive(Clone, Copy, Debug, Default)] pub struct moq_decode_gap { - /// The furthest presentation point already read, in microseconds. - pub timestamp_us: u64, + /// The furthest presentation point already read. + pub timestamp: moq_timestamp, /// An upper bound on how long until the next frame resumes, in microseconds. pub duration_us: u64, } -/// A delivered read held by its id, with its timestamps already in the C ABI's microseconds. +/// A delivered read held by its id. #[derive(Clone)] pub(crate) enum Read { Frame(F), Gap(moq_decode_gap), - End { end_us: u64 }, + End(moq_timestamp), } impl Read { pub(crate) fn gap(timestamp: moq_net::Timestamp, duration: moq_net::Timestamp) -> Result { Ok(Self::Gap(moq_decode_gap { - timestamp_us: micros(timestamp)?, - duration_us: micros(duration)?, + timestamp: timestamp.into(), + duration_us: duration + .as_micros() + .try_into() + .map_err(|_| Error::TimestampOverflow(moq_net::TimeOverflow))?, })) } - pub(crate) fn end(end: moq_net::Timestamp) -> Result { - Ok(Self::End { end_us: micros(end)? }) + pub(crate) fn end(end: moq_net::Timestamp) -> Self { + Self::End(end.into()) } /// The C kind, plus the gap and end fields a non-frame read fills. - pub(crate) fn info(&self) -> (moq_decode_read_kind, moq_decode_gap, u64) { + pub(crate) fn info(&self) -> (moq_decode_read_kind, moq_decode_gap, moq_timestamp) { match self { Self::Frame(_) => ( moq_decode_read_kind::MOQ_DECODE_READ_FRAME, moq_decode_gap::default(), - 0, + moq_timestamp::default(), ), - Self::Gap(gap) => (moq_decode_read_kind::MOQ_DECODE_READ_GAP, *gap, 0), - Self::End { end_us } => ( + Self::Gap(gap) => ( + moq_decode_read_kind::MOQ_DECODE_READ_GAP, + *gap, + moq_timestamp::default(), + ), + Self::End(end) => ( moq_decode_read_kind::MOQ_DECODE_READ_END, moq_decode_gap::default(), - *end_us, + *end, ), } } } - -fn micros(timestamp: moq_net::Timestamp) -> Result { - timestamp - .as_micros() - .try_into() - .map_err(|_| Error::TimestampOverflow(moq_net::TimeOverflow)) -} diff --git a/rs/moq-c/src/ffi.rs b/rs/moq-c/src/ffi.rs index c942f85bb34..bc612deefaa 100644 --- a/rs/moq-c/src/ffi.rs +++ b/rs/moq-c/src/ffi.rs @@ -498,6 +498,16 @@ pub unsafe fn parse_slice<'a>(data: *const u8, size: usize) -> Result<&'a [u8], Ok(data) } +/// Parse an optional timestamp, NULL meaning untimed. +/// +/// # Safety +/// `timestamp` must be NULL or a valid pointer to a [crate::moq_timestamp]. +pub unsafe fn parse_timestamp(timestamp: *const crate::moq_timestamp) -> Result, Error> { + Ok(unsafe { timestamp.as_ref() } + .map(|×tamp| timestamp.try_into()) + .transpose()?) +} + #[cfg(test)] mod tests { diff --git a/rs/moq-c/src/publish.rs b/rs/moq-c/src/publish.rs index 1f1c4c227d1..e90d3db2352 100644 --- a/rs/moq-c/src/publish.rs +++ b/rs/moq-c/src/publish.rs @@ -1076,8 +1076,13 @@ impl Publish { self.groups.insert(group) } - /// Write a single-frame group to a raw track with an explicit timestamp. - pub fn track_frame(&mut self, track: Id, timestamp: moq_net::Timestamp, payload: &[u8]) -> Result<(), Error> { + /// Write a single-frame group to a raw track, `None` when untimed. + pub fn track_frame( + &mut self, + track: Id, + timestamp: Option, + payload: &[u8], + ) -> Result<(), Error> { let track = self.tracks.get_mut(track).ok_or(Error::TrackNotFound)?; track.write_frame(timestamp, bytes::Bytes::copy_from_slice(payload))?; Ok(()) @@ -1088,9 +1093,13 @@ impl Publish { /// The payload must be at most [`moq_net::MAX_DATAGRAM_PAYLOAD`] bytes. Datagrams are /// delivered only on transports and wire versions with a datagram channel; there is no /// group fallback. - pub fn track_datagram(&mut self, track: Id, timestamp_us: u64, payload: &[u8]) -> Result { + pub fn track_datagram( + &mut self, + track: Id, + timestamp: Option, + payload: &[u8], + ) -> Result { let track = self.tracks.get_mut(track).ok_or(Error::TrackNotFound)?; - let timestamp = moq_net::Timestamp::from_micros(timestamp_us)?; Ok(track.append_datagram(timestamp, bytes::Bytes::copy_from_slice(payload))?) } @@ -1304,8 +1313,13 @@ impl Publish { Ok(()) } - /// Write a frame into a raw group with an explicit timestamp. - pub fn group_frame(&mut self, group: Id, timestamp: moq_net::Timestamp, payload: &[u8]) -> Result<(), Error> { + /// Write a frame into a raw group, `None` when untimed. + pub fn group_frame( + &mut self, + group: Id, + timestamp: Option, + payload: &[u8], + ) -> Result<(), Error> { let group = self.groups.get_mut(group).ok_or(Error::GroupNotFound)?; group.write_frame(timestamp, bytes::Bytes::copy_from_slice(payload))?; Ok(()) diff --git a/rs/moq-c/src/test.rs b/rs/moq-c/src/test.rs index 1f86b714a76..1bb7bdc0a77 100644 --- a/rs/moq-c/src/test.rs +++ b/rs/moq-c/src/test.rs @@ -7,6 +7,19 @@ use std::time::Duration; const TIMEOUT: Duration = Duration::from_secs(10); +/// A timestamp of `value` microseconds. +fn micros(value: u64) -> moq_timestamp { + moq_timestamp { + value, + scale: 1_000_000, + } +} + +/// The timestamp a read points at, `None` when untimed. +fn read_timestamp(timestamp: *const moq_timestamp) -> Option { + unsafe { timestamp.as_ref() }.copied() +} + /// Convert a positive `i32` return value to `u32`, panicking on error. fn id(raw: i32) -> u32 { assert!(raw > 0, "expected positive id, got {raw}"); @@ -255,14 +268,14 @@ fn video_read(id: u32) -> (i32, moq_video_read) { let mut read = moq_video_read { kind: moq_decode_read_kind::MOQ_DECODE_READ_END, frame: moq_video_frame { - timestamp_us: 0, + timestamp: moq_timestamp::default(), width: 0, height: 0, data: std::ptr::null(), data_size: 0, }, gap: moq_decode_gap::default(), - end_us: 0, + end: moq_timestamp::default(), }; let code = unsafe { moq_decode_video_read(id, &mut read) }; (code, read) @@ -1174,7 +1187,7 @@ fn raw_loc_video_uses_the_declared_catalog_container() { let loc = moq_loc::encode(timestamp_us, payload).unwrap(); let group = id(moq_publish_track_group(track)); assert_eq!( - unsafe { moq_publish_group_frame(group, loc.as_ptr(), loc.len(), timestamp_us) }, + unsafe { moq_publish_group_frame(group, loc.as_ptr(), loc.len(), µs(timestamp_us)) }, 0 ); assert_eq!(moq_publish_group_finish(group), 0); @@ -1183,13 +1196,15 @@ fn raw_loc_video_uses_the_declared_catalog_container() { let mut frame = moq_frame { payload: std::ptr::null(), payload_size: 0, - timestamp_us: 0, - timestamp_present: false, + timestamp: std::ptr::null(), keyframe: false, }; assert_eq!(unsafe { encoded_frame(frame_id, &mut frame) }, 0); - assert_eq!(frame.timestamp_us, timestamp_us); - assert!(frame.timestamp_present, "a media frame is always timed"); + assert_eq!( + read_timestamp(frame.timestamp), + Some(micros(timestamp_us)), + "a media frame is always timed" + ); assert!(frame.keyframe); assert_eq!( unsafe { std::slice::from_raw_parts(frame.payload, frame.payload_size) }, @@ -1504,8 +1519,8 @@ fn publish_track_invalid_broadcast() { }; assert!(unsafe { moq_publish_track(0, name.as_ptr() as *const c_char, name.len(), &info) } < 0); assert!(moq_publish_track_group(9999) < 0); - assert!(unsafe { moq_publish_track_frame(9999, name.as_ptr(), name.len(), 0) } < 0); - assert!(unsafe { moq_publish_group_frame(9999, name.as_ptr(), name.len(), 0) } < 0); + assert!(unsafe { moq_publish_track_frame(9999, name.as_ptr(), name.len(), µs(0)) } < 0); + assert!(unsafe { moq_publish_group_frame(9999, name.as_ptr(), name.len(), µs(0)) } < 0); assert!(moq_publish_track_finish(9999) < 0); assert!(moq_publish_group_finish(9999) < 0); @@ -1540,63 +1555,179 @@ fn publish_track_with_info_rejects_invalid_timescale() { assert_eq!(moq_publish_close(broadcast), 0); } -/// A raw frame read from an untimed track reports no timestamp. The C API only publishes -/// timed tracks, so the track and its frame come from moq-net. +/// Raw frames, datagrams, and JSON values read back exactly the timestamp written: a 90 kHz +/// tick that microseconds cannot express, a present zero, and untimed. The C API only creates +/// timed tracks, so the tracks and the JSON producer come from moq-net. #[test] -fn an_untimed_raw_frame_reads_untimed() { +fn timestamps_round_trip_exactly() { let origin = id(moq_origin_create()); - let path = b"raw-untimed"; + let path = b"exact-timestamps"; let broadcast = publish_broadcast(origin, path); + let consume = request_broadcast(origin, path); - let track_name = b"data"; - let track = State::lock() - .publish - .track( - Id::try_from(broadcast).unwrap(), - "data", - Some(moq_net::track::Info::default().with_timescale(None)), - ) - .unwrap(); + let tick = moq_timestamp { + value: 1, + scale: 90_000, + }; + let zero = moq_timestamp { + value: 0, + scale: 90_000, + }; + for (name, written) in [("tick", Some(tick)), ("zero", Some(zero)), ("untimed", None)] { + let info = + moq_net::track::Info::default().with_timescale(written.map(|_| moq_net::Timescale::new(90_000).unwrap())); + let create = |name: &str| -> u32 { + let mut state = State::lock(); + state + .publish + .track(Id::try_from(broadcast).unwrap(), name, Some(info.clone())) + .unwrap() + .into() + }; + let track = create(name); + let json_name = format!("{name}.json"); + let json_track = create(&json_name); + + let frames = Callback::new(); + let frame_consumer = id(unsafe { + moq_consume_track( + consume, + name.as_ptr().cast(), + name.len(), + std::ptr::null(), + Some(channel_callback), + frames.ptr, + ) + }); + let datagrams = Callback::new(); + let datagram_consumer = id(unsafe { + moq_consume_datagrams( + consume, + name.as_ptr().cast(), + name.len(), + Some(channel_callback), + datagrams.ptr, + ) + }); + let values = Callback::new(); + let config = moq_json_stream_config { compression: false }; + let value_consumer = id(unsafe { + moq_consume_json_stream( + consume, + json_name.as_ptr().cast(), + json_name.len(), + &config, + Some(channel_callback), + values.ptr, + ) + }); - let consume = request_broadcast(origin, path); - let frame_cb = Callback::new(); - let consumer = id(unsafe { - moq_consume_track( - consume, - track_name.as_ptr() as *const c_char, - track_name.len(), - std::ptr::null(), - Some(channel_callback), - frame_cb.ptr, - ) - }); + let timestamp = written.as_ref().map_or(std::ptr::null(), std::ptr::from_ref); + let payload = b"payload"; + assert_eq!( + unsafe { moq_publish_track_frame(track, payload.as_ptr(), payload.len(), timestamp) }, + 0 + ); + let frame_id = id(frames.recv()); + let mut frame = moq_frame { + payload: std::ptr::null(), + payload_size: 0, + timestamp: &tick, + keyframe: false, + }; + assert_eq!(unsafe { moq_consume_track_frame(frame_id, &mut frame) }, 0); + assert_eq!(read_timestamp(frame.timestamp), written, "{name} frame"); + assert_eq!(moq_consume_track_frame_free(frame_id), 0); - State::lock() - .publish - .track_producer(track) - .unwrap() - .write_frame(None, &b"untimed"[..]) + // The datagram subscription is live once the frame arrived on the same track. + assert_eq!( + unsafe { + moq_publish_track_datagram(track, payload.as_ptr(), payload.len(), timestamp, std::ptr::null_mut()) + }, + 0 + ); + let datagram_id = id(datagrams.recv()); + let mut datagram = moq_datagram { + payload: std::ptr::null(), + payload_size: 0, + timestamp: &tick, + sequence: 0, + }; + assert_eq!(unsafe { moq_consume_datagram(datagram_id, &mut datagram) }, 0); + assert_eq!(read_timestamp(datagram.timestamp), written, "{name} datagram"); + assert_eq!(moq_consume_datagram_free(datagram_id), 0); + + let producer = State::lock() + .publish + .track_producer(Id::try_from(json_track).unwrap()) + .unwrap() + .clone(); + let mut json = moq_json::stream::Producer::::new(producer, Default::default()); + json.append(moq_net::Timed { + value: &serde_json::json!(1), + at: written.map(|written| written.try_into().unwrap()), + }) .unwrap(); - let frame_id = id(frame_cb.recv()); - let mut frame = moq_frame { - payload: std::ptr::null(), - payload_size: 0, - timestamp_us: 7, - timestamp_present: true, - keyframe: false, - }; - assert_eq!(unsafe { moq_consume_track_frame(frame_id, &mut frame) }, 0); - assert!(!frame.timestamp_present, "an untimed frame reads untimed"); - assert_eq!(frame.timestamp_us, 0); - assert_eq!(moq_consume_track_frame_free(frame_id), 0); + let value_id = id(values.recv()); + let mut value = moq_json_value { + json: std::ptr::null(), + json_len: 0, + timestamp: &tick, + }; + assert_eq!(unsafe { moq_consume_json_value(value_id, &mut value) }, 0); + assert_eq!(read_timestamp(value.timestamp), written, "{name} JSON value"); + assert_eq!(moq_consume_json_value_free(value_id), 0); + + assert_eq!(moq_consume_track_cancel(frame_consumer), 0); + assert_eq!(frames.recv_terminal(), 0); + assert_eq!(moq_consume_datagrams_cancel(datagram_consumer), 0); + assert_eq!(datagrams.recv_terminal(), 0); + assert_eq!(moq_consume_json_cancel(value_consumer), 0); + assert_eq!(values.recv_terminal(), 0); + } - assert_eq!(moq_consume_track_cancel(consumer), 0); - assert_eq!(frame_cb.recv_terminal(), 0, "clean close delivers terminal 0"); assert_eq!(moq_consume_close(consume), 0); assert_eq!(moq_publish_close(broadcast), 0); assert_eq!(moq_origin_close(origin), 0); } +/// A write refuses a timestamp outside `moq_net::Timestamp`'s range, and an untimed write on a +/// timed track. +#[test] +fn timestamp_writes_refuse_out_of_range_and_mismatch() { + let origin = id(moq_origin_create()); + let broadcast = publish_broadcast(origin, b"timestamp-refusals"); + let name = b"data"; + let track = + id(unsafe { moq_publish_track(broadcast, name.as_ptr() as *const c_char, name.len(), std::ptr::null()) }); + + for invalid in [ + moq_timestamp { value: 0, scale: 0 }, + moq_timestamp { + value: 0, + scale: 1 << 62, + }, + moq_timestamp { + value: 1 << 61, + scale: 1_000_000, + }, + ] { + assert_eq!( + unsafe { moq_publish_track_frame(track, name.as_ptr(), name.len(), &invalid) }, + MOQ_ERROR_TIMESTAMP_OVERFLOW, + "{invalid:?}" + ); + } + assert_eq!( + unsafe { moq_publish_track_frame(track, name.as_ptr(), name.len(), std::ptr::null()) }, + MOQ_ERROR_MOQ + ); + + assert_eq!(moq_publish_track_finish(track), 0); + assert_eq!(moq_publish_close(broadcast), 0); + assert_eq!(moq_origin_close(origin), 0); +} + #[test] fn raw_track_publish_consume() { let origin = id(moq_origin_create()); @@ -1642,7 +1773,7 @@ fn raw_track_publish_consume() { let payload = b"hello raw track"; let timestamp_us = 12_345; assert_eq!( - unsafe { moq_publish_track_frame(track, payload.as_ptr(), payload.len(), timestamp_us) }, + unsafe { moq_publish_track_frame(track, payload.as_ptr(), payload.len(), µs(timestamp_us)) }, 0 ); @@ -1650,15 +1781,13 @@ fn raw_track_publish_consume() { let mut frame = moq_frame { payload: std::ptr::null(), payload_size: 0, - timestamp_us: 0, - timestamp_present: false, + timestamp: std::ptr::null(), keyframe: true, // should be overwritten with false }; assert_eq!(unsafe { moq_consume_track_frame(frame_id, &mut frame) }, 0); let received = unsafe { std::slice::from_raw_parts(frame.payload, frame.payload_size) }; assert_eq!(received, payload); - assert_eq!(frame.timestamp_us, timestamp_us); - assert!(frame.timestamp_present); + assert_eq!(read_timestamp(frame.timestamp), Some(micros(timestamp_us))); assert!(!frame.keyframe, "raw frames have no keyframe flag"); assert_eq!(moq_consume_track_frame_free(frame_id), 0); @@ -1667,7 +1796,7 @@ fn raw_track_publish_consume() { let parts: [(&[u8], u64); 2] = [(b"part-0", 20_000), (b"part-1", 30_000)]; for (part, timestamp_us) in parts { assert_eq!( - unsafe { moq_publish_group_frame(group, part.as_ptr(), part.len(), timestamp_us) }, + unsafe { moq_publish_group_frame(group, part.as_ptr(), part.len(), µs(timestamp_us)) }, 0 ); } @@ -1678,14 +1807,13 @@ fn raw_track_publish_consume() { let mut frame = moq_frame { payload: std::ptr::null(), payload_size: 0, - timestamp_us: 0, - timestamp_present: false, + timestamp: std::ptr::null(), keyframe: false, }; assert_eq!(unsafe { moq_consume_track_frame(frame_id, &mut frame) }, 0); let received = unsafe { std::slice::from_raw_parts(frame.payload, frame.payload_size) }; assert_eq!(received, expected); - assert_eq!(frame.timestamp_us, timestamp_us); + assert_eq!(read_timestamp(frame.timestamp), Some(micros(timestamp_us))); assert_eq!(moq_consume_track_frame_free(frame_id), 0); } @@ -1733,7 +1861,7 @@ fn raw_track_datagram_publish_consume() { let payload = b"hello datagram"; let mut sequence: u64 = u64::MAX; assert_eq!( - unsafe { moq_publish_track_datagram(track, payload.as_ptr(), payload.len(), 120_000, &mut sequence) }, + unsafe { moq_publish_track_datagram(track, payload.as_ptr(), payload.len(), µs(120_000), &mut sequence) }, 0 ); @@ -1741,14 +1869,13 @@ fn raw_track_datagram_publish_consume() { let mut datagram = moq_datagram { payload: std::ptr::null(), payload_size: 0, - timestamp_us: 0, - timestamp_present: false, + timestamp: std::ptr::null(), sequence: 0, }; assert_eq!(unsafe { moq_consume_datagram(dg_id, &mut datagram) }, 0); let received = unsafe { std::slice::from_raw_parts(datagram.payload, datagram.payload_size) }; assert_eq!(received, payload); - assert_eq!(datagram.timestamp_us, 120_000); + assert_eq!(read_timestamp(datagram.timestamp), Some(micros(120_000))); assert_eq!(datagram.sequence, sequence); assert_eq!(moq_consume_datagram_free(dg_id), 0); @@ -1819,7 +1946,7 @@ fn raw_track_subscription_options_and_update() { let payloads: [&[u8]; 3] = [b"zero", b"one", b"two"]; for (i, payload) in payloads.into_iter().enumerate() { assert_eq!( - unsafe { moq_publish_track_frame(track, payload.as_ptr(), payload.len(), i as u64 * 20_000) }, + unsafe { moq_publish_track_frame(track, payload.as_ptr(), payload.len(), µs(i as u64 * 20_000)) }, 0 ); } @@ -1831,12 +1958,12 @@ fn raw_track_subscription_options_and_update() { start: moq_anchor { kind: moq_anchor_kind::MOQ_ANCHOR_ABSOLUTE as u32, group: 1, - timestamp_us: 0, + timestamp: moq_timestamp::default(), }, end: moq_anchor { kind: moq_anchor_kind::MOQ_ANCHOR_ABSOLUTE as u32, group: 2, - timestamp_us: 0, + timestamp: moq_timestamp::default(), }, end_present: true, }]; @@ -1863,14 +1990,13 @@ fn raw_track_subscription_options_and_update() { let mut frame = moq_frame { payload: std::ptr::null(), payload_size: 0, - timestamp_us: 0, - timestamp_present: false, + timestamp: std::ptr::null(), keyframe: false, }; assert_eq!(unsafe { moq_consume_track_frame(frame_id, &mut frame) }, 0); let received = unsafe { std::slice::from_raw_parts(frame.payload, frame.payload_size) }; assert_eq!(received, b"one"); - assert_eq!(frame.timestamp_us, 20_000); + assert_eq!(read_timestamp(frame.timestamp), Some(micros(20_000))); assert_eq!(moq_consume_track_frame_free(frame_id), 0); let widened = [moq_range { @@ -1890,14 +2016,13 @@ fn raw_track_subscription_options_and_update() { let mut frame = moq_frame { payload: std::ptr::null(), payload_size: 0, - timestamp_us: 0, - timestamp_present: false, + timestamp: std::ptr::null(), keyframe: false, }; assert_eq!(unsafe { moq_consume_track_frame(frame_id, &mut frame) }, 0); let received = unsafe { std::slice::from_raw_parts(frame.payload, frame.payload_size) }; assert_eq!(received, b"two"); - assert_eq!(frame.timestamp_us, 40_000); + assert_eq!(read_timestamp(frame.timestamp), Some(micros(40_000))); assert_eq!(moq_consume_track_frame_free(frame_id), 0); assert_eq!(moq_consume_track_cancel(consumer), 0); @@ -1932,7 +2057,7 @@ fn raw_track_time_anchor() { let payloads: [&[u8]; 3] = [b"zero", b"one", b"two"]; for (i, payload) in payloads.into_iter().enumerate() { assert_eq!( - unsafe { moq_publish_track_frame(track, payload.as_ptr(), payload.len(), i as u64 * 20_000) }, + unsafe { moq_publish_track_frame(track, payload.as_ptr(), payload.len(), µs(i as u64 * 20_000)) }, 0 ); } @@ -1944,12 +2069,12 @@ fn raw_track_time_anchor() { start: moq_anchor { kind: moq_anchor_kind::MOQ_ANCHOR_TIME as u32, group: 0, - timestamp_us: 30_000, + timestamp: micros(30_000), }, end: moq_anchor { kind: moq_anchor_kind::MOQ_ANCHOR_ABSOLUTE as u32, group: 0, - timestamp_us: 0, + timestamp: moq_timestamp::default(), }, end_present: false, }]; @@ -1977,8 +2102,7 @@ fn raw_track_time_anchor() { let mut frame = moq_frame { payload: std::ptr::null(), payload_size: 0, - timestamp_us: 0, - timestamp_present: false, + timestamp: std::ptr::null(), keyframe: false, }; assert_eq!(unsafe { moq_consume_track_frame(frame_id, &mut frame) }, 0); @@ -2043,12 +2167,12 @@ fn raw_track_update_refuses_time_on_untimed() { start: moq_anchor { kind: moq_anchor_kind::MOQ_ANCHOR_TIME as u32, group: 0, - timestamp_us: 0, + timestamp: moq_timestamp::default(), }, end: moq_anchor { kind: moq_anchor_kind::MOQ_ANCHOR_ABSOLUTE as u32, group: 0, - timestamp_us: 0, + timestamp: moq_timestamp::default(), }, end_present: false, }]; @@ -2068,8 +2192,7 @@ fn raw_track_update_refuses_time_on_untimed() { let mut frame = moq_frame { payload: std::ptr::null(), payload_size: 0, - timestamp_us: 0, - timestamp_present: false, + timestamp: std::ptr::null(), keyframe: false, }; assert_eq!(unsafe { moq_consume_track_frame(frame_id, &mut frame) }, 0); @@ -2101,14 +2224,14 @@ fn raw_track_relative_update_counts_from_the_track_edge() { }); let publish = |payload: &[u8]| { assert_eq!( - unsafe { moq_publish_track_frame(track, payload.as_ptr(), payload.len(), 0) }, + unsafe { moq_publish_track_frame(track, payload.as_ptr(), payload.len(), µs(0)) }, 0 ); }; let anchor = |kind: moq_anchor_kind, group: u64| moq_anchor { kind: kind as u32, group, - timestamp_us: 0, + timestamp: moq_timestamp::default(), }; let subscribe = |ranges: &[moq_range]| moq_subscription { priority: 0, @@ -2123,8 +2246,7 @@ fn raw_track_relative_update_counts_from_the_track_edge() { let mut frame = moq_frame { payload: std::ptr::null(), payload_size: 0, - timestamp_us: 0, - timestamp_present: false, + timestamp: std::ptr::null(), keyframe: false, }; assert_eq!(unsafe { moq_consume_track_frame(frame_id, &mut frame) }, 0); @@ -2209,7 +2331,7 @@ fn json_snapshot_publish_consume() { ) }); - let mut last_us = 0; + let mut last = 0; for expected in [r#"{"a":1}"#, r#"{"a":2}"#] { assert_eq!( unsafe { moq_publish_json_snapshot_update(producer, expected.as_ptr() as *const c_char, expected.len()) }, @@ -2219,14 +2341,13 @@ fn json_snapshot_publish_consume() { let mut value = moq_json_value { json: std::ptr::null(), json_len: 0, - timestamp_us: 0, - timestamp_present: false, + timestamp: std::ptr::null(), }; assert_eq!(unsafe { moq_consume_json_value(value_id, &mut value) }, 0); // The producer stamps each value with the broadcast clock. - assert!(value.timestamp_present); - assert!(value.timestamp_us >= last_us); - last_us = value.timestamp_us; + let at = read_timestamp(value.timestamp).expect("a stamped value is timed"); + assert!(at.value >= last); + last = at.value; let received = unsafe { std::slice::from_raw_parts(value.json.cast::(), value.json_len) }; assert_eq!( serde_json::from_slice::(received).unwrap(), @@ -2279,7 +2400,7 @@ fn json_stream_publish_consume() { ) }); - let mut last_us = 0; + let mut last = 0; for expected in [r#"{"n":0}"#, r#"{"n":1}"#, r#"{"n":2}"#] { assert_eq!( unsafe { moq_publish_json_stream_append(producer, expected.as_ptr() as *const c_char, expected.len()) }, @@ -2289,14 +2410,13 @@ fn json_stream_publish_consume() { let mut value = moq_json_value { json: std::ptr::null(), json_len: 0, - timestamp_us: 0, - timestamp_present: false, + timestamp: std::ptr::null(), }; assert_eq!(unsafe { moq_consume_json_value(value_id, &mut value) }, 0); // The producer stamps each value with the broadcast clock. - assert!(value.timestamp_present); - assert!(value.timestamp_us >= last_us); - last_us = value.timestamp_us; + let at = read_timestamp(value.timestamp).expect("a stamped value is timed"); + assert!(at.value >= last); + last = at.value; let received = unsafe { std::slice::from_raw_parts(value.json.cast::(), value.json_len) }; assert_eq!( serde_json::from_slice::(received).unwrap(), @@ -2350,7 +2470,7 @@ fn publish_finish_serves_finished_tracks_until_closed() { let track = id(unsafe { moq_publish_track(broadcast, name.as_ptr() as *const c_char, name.len(), &info) }); let payload = b"tail"; assert_eq!( - unsafe { moq_publish_track_frame(track, payload.as_ptr(), payload.len(), 1_000) }, + unsafe { moq_publish_track_frame(track, payload.as_ptr(), payload.len(), µs(1_000)) }, 0 ); assert_eq!(moq_publish_track_finish(track), 0); @@ -2363,7 +2483,7 @@ fn publish_finish_serves_finished_tracks_until_closed() { )); let frame = b"opus frame"; assert_eq!( - unsafe { moq_publish_media_frame(media, frame.as_ptr(), frame.len(), 1_000) }, + unsafe { moq_publish_media_frame(media, frame.as_ptr(), frame.len(), micros(1_000)) }, 0 ); assert_eq!(moq_publish_media_finish(media), 0); @@ -2394,8 +2514,7 @@ fn publish_finish_serves_finished_tracks_until_closed() { let mut frame = moq_frame { payload: std::ptr::null(), payload_size: 0, - timestamp_us: 0, - timestamp_present: false, + timestamp: std::ptr::null(), keyframe: false, }; assert_eq!(unsafe { moq_consume_track_frame(frame_id, &mut frame) }, 0); @@ -2485,7 +2604,7 @@ fn double_close_all_resource_types() { let payload = b"test"; assert_eq!( - unsafe { moq_publish_media_frame(media, payload.as_ptr(), payload.len(), 1_000_000) }, + unsafe { moq_publish_media_frame(media, payload.as_ptr(), payload.len(), micros(1_000_000)) }, 0 ); let frame_id = id(frame_cb.recv()); @@ -2524,7 +2643,7 @@ fn media_cut_bounds_audio_groups() { let payload = b"test"; for i in 0..3u64 { assert_eq!( - unsafe { moq_publish_media_frame(media, payload.as_ptr(), payload.len(), i * 20_000) }, + unsafe { moq_publish_media_frame(media, payload.as_ptr(), payload.len(), micros(i * 20_000)) }, 0 ); assert_eq!(moq_publish_media_cut(media), 0, "each packet is its own group"); @@ -2532,7 +2651,7 @@ fn media_cut_bounds_audio_groups() { // The same boundary, with the next group explicitly numbered. assert_eq!( - unsafe { moq_publish_media_frame(media, payload.as_ptr(), payload.len(), 60_000) }, + unsafe { moq_publish_media_frame(media, payload.as_ptr(), payload.len(), micros(60_000)) }, 0 ); assert_eq!(moq_publish_media_seek(media, 42), 0); @@ -2978,7 +3097,7 @@ fn track_demand_reports_the_wanted_group() { let group = id(moq_publish_track_group(track)); for timestamp_us in [0, 1_000] { assert_eq!( - unsafe { moq_publish_group_frame(group, name.as_ptr(), name.len(), timestamp_us) }, + unsafe { moq_publish_group_frame(group, name.as_ptr(), name.len(), µs(timestamp_us)) }, 0 ); } @@ -3137,15 +3256,14 @@ fn dynamic_serves_track_requests() { let payload = b"hello dynamic track"; assert_eq!( - unsafe { moq_publish_track_frame(track, payload.as_ptr(), payload.len(), 42) }, + unsafe { moq_publish_track_frame(track, payload.as_ptr(), payload.len(), µs(42)) }, 0 ); let frame_id = id(frame_cb.recv()); let mut frame = moq_frame { payload: std::ptr::null(), payload_size: 0, - timestamp_us: 0, - timestamp_present: false, + timestamp: std::ptr::null(), keyframe: false, }; assert_eq!(unsafe { moq_consume_track_frame(frame_id, &mut frame) }, 0); @@ -3153,7 +3271,7 @@ fn dynamic_serves_track_requests() { unsafe { std::slice::from_raw_parts(frame.payload, frame.payload_size) }, payload ); - assert_eq!(frame.timestamp_us, 42); + assert_eq!(read_timestamp(frame.timestamp), Some(micros(42))); assert_eq!(moq_consume_track_frame_free(frame_id), 0); // A second request is aborted, and its subscriber sees the application code. @@ -3232,7 +3350,7 @@ fn dynamic_track_request_publishes_media() { let payload = b"opus frame"; assert_eq!( - unsafe { moq_publish_media_frame(media, payload.as_ptr(), payload.len(), 1000) }, + unsafe { moq_publish_media_frame(media, payload.as_ptr(), payload.len(), micros(1000)) }, 0 ); let frame_id = id(frame_cb.recv()); @@ -3331,7 +3449,7 @@ fn track_dynamic_serves_a_fetch_miss() { assert!(moq_group_request_free(request) < 0, "accept consumes the request"); let payload = b"fetched"; assert_eq!( - unsafe { moq_publish_group_frame(group, payload.as_ptr(), payload.len(), 100_000) }, + unsafe { moq_publish_group_frame(group, payload.as_ptr(), payload.len(), µs(100_000)) }, 0 ); assert_eq!(moq_publish_group_finish(group), 0); @@ -3461,7 +3579,7 @@ fn a_rejected_group_request_binds_only_its_readers() { let group = id(moq_group_request_accept(request)); let payload = b"fetched"; assert_eq!( - unsafe { moq_publish_group_frame(group, payload.as_ptr(), payload.len(), 6_000) }, + unsafe { moq_publish_group_frame(group, payload.as_ptr(), payload.len(), µs(6_000)) }, 0 ); assert_eq!(moq_publish_group_finish(group), 0); @@ -3499,7 +3617,7 @@ fn track_request_dynamic_survives_accept() { let group = id(moq_group_request_accept(group_request)); let payload = b"archive"; assert_eq!( - unsafe { moq_publish_group_frame(group, payload.as_ptr(), payload.len(), 180_000) }, + unsafe { moq_publish_group_frame(group, payload.as_ptr(), payload.len(), µs(180_000)) }, 0 ); assert_eq!(moq_publish_group_finish(group), 0); @@ -3580,7 +3698,7 @@ fn local_publish_consume() { let payload = b"opus audio payload data"; let timestamp_us: u64 = 1_000_000; assert_eq!( - unsafe { moq_publish_media_frame(media, payload.as_ptr(), payload.len(), timestamp_us) }, + unsafe { moq_publish_media_frame(media, payload.as_ptr(), payload.len(), micros(timestamp_us)) }, 0 ); @@ -3589,13 +3707,12 @@ fn local_publish_consume() { let mut frame = moq_frame { payload: std::ptr::null(), payload_size: 0, - timestamp_us: 0, - timestamp_present: false, + timestamp: std::ptr::null(), keyframe: false, }; assert_eq!(unsafe { encoded_frame(frame_id, &mut frame) }, 0); assert_eq!(frame.payload_size, payload.len()); - assert_eq!(frame.timestamp_us, timestamp_us); + assert_eq!(read_timestamp(frame.timestamp), Some(micros(timestamp_us))); let received = unsafe { std::slice::from_raw_parts(frame.payload, frame.payload_size) }; assert_eq!(received, payload, "frame payload should match"); @@ -3744,7 +3861,7 @@ fn consume_audio_follows_a_sibling_broadcast_reference() { let payload = b"opus audio payload data"; let timestamp_us: u64 = 1_000_000; assert_eq!( - unsafe { moq_publish_media_frame(media, payload.as_ptr(), payload.len(), timestamp_us) }, + unsafe { moq_publish_media_frame(media, payload.as_ptr(), payload.len(), micros(timestamp_us)) }, 0 ); @@ -3752,14 +3869,13 @@ fn consume_audio_follows_a_sibling_broadcast_reference() { let mut frame = moq_frame { payload: std::ptr::null(), payload_size: 0, - timestamp_us: 0, - timestamp_present: false, + timestamp: std::ptr::null(), keyframe: false, }; assert_eq!(unsafe { encoded_frame(frame_id, &mut frame) }, 0); let received = unsafe { std::slice::from_raw_parts(frame.payload, frame.payload_size) }; assert_eq!(received, payload, "the sibling broadcast's frame should arrive"); - assert_eq!(frame.timestamp_us, timestamp_us); + assert_eq!(read_timestamp(frame.timestamp), Some(micros(timestamp_us))); assert_eq!(moq_consume_read_free(frame_id), 0); assert_eq!(moq_consume_audio_cancel(track), 0); @@ -4114,7 +4230,7 @@ fn video_publish_consume() { let keyframe = [0x00, 0x00, 0x00, 0x01, 0x65, 0xAA, 0xBB, 0xCC]; assert_eq!( - unsafe { moq_publish_media_frame(media, keyframe.as_ptr(), keyframe.len(), 0) }, + unsafe { moq_publish_media_frame(media, keyframe.as_ptr(), keyframe.len(), micros(0)) }, 0 ); @@ -4122,12 +4238,11 @@ fn video_publish_consume() { let mut frame = moq_frame { payload: std::ptr::null(), payload_size: 0, - timestamp_us: 0, - timestamp_present: false, + timestamp: std::ptr::null(), keyframe: false, }; assert_eq!(unsafe { encoded_frame(frame_id, &mut frame) }, 0); - assert_eq!(frame.timestamp_us, 0); + assert_eq!(read_timestamp(frame.timestamp), Some(micros(0))); assert!(frame.payload_size > 0, "frame should have payload data"); assert_eq!(moq_consume_read_free(frame_id), 0); @@ -4180,7 +4295,7 @@ fn audio_raw_publish() { let samples = vec![0.0f32; 960 * 2]; let pcm = unsafe { std::slice::from_raw_parts(samples.as_ptr().cast::(), std::mem::size_of_val(&samples[..])) }; let frame = moq_audio_frame { - timestamp_us: 0, + timestamp: micros(0), data: pcm.as_ptr(), data_size: pcm.len(), }; @@ -4238,7 +4353,7 @@ fn audio_raw_publish_frame_durations() { let samples = vec![0.0f32; 120 * 2]; let pcm = unsafe { std::slice::from_raw_parts(samples.as_ptr().cast::(), std::mem::size_of_val(&samples[..])) }; let frame = moq_audio_frame { - timestamp_us: 0, + timestamp: micros(0), data: pcm.as_ptr(), data_size: pcm.len(), }; @@ -4286,7 +4401,7 @@ fn audio_raw_decode_reads_the_encoder_end() { .flat_map(|i| (i as f32 / SAMPLES as f32).to_le_bytes()) .collect(); let frame = moq_audio_frame { - timestamp_us: START_US, + timestamp: micros(START_US), data: pcm.as_ptr(), data_size: pcm.len(), }; @@ -4316,12 +4431,12 @@ fn audio_raw_decode_reads_the_encoder_end() { let mut read = moq_audio_read { kind: moq_decode_read_kind::MOQ_DECODE_READ_GAP, frame: moq_audio_frame { - timestamp_us: 0, + timestamp: moq_timestamp::default(), data: std::ptr::null(), data_size: 0, }, gap: moq_decode_gap::default(), - end_us: 0, + end: moq_timestamp::default(), }; assert_eq!(unsafe { moq_decode_audio_read(id(code), &mut read) }, 0); match read.kind { @@ -4330,13 +4445,13 @@ fn audio_raw_decode_reads_the_encoder_end() { } moq_decode_read_kind::MOQ_DECODE_READ_END => { assert!(read.frame.data.is_null(), "an end carries no samples"); - ends.push(read.end_us); + ends.push(read.end); } moq_decode_read_kind::MOQ_DECODE_READ_GAP => panic!("nothing was lost"), } assert_eq!(moq_decode_audio_read_free(id(code)), 0); } - assert_eq!(ends, [START_US + SAMPLES as u64 * 1_000_000 / 48_000]); + assert_eq!(ends, [micros(START_US + SAMPLES as u64 * 1_000_000 / 48_000)]); assert_eq!(moq_consume_catalog_free(catalog_id), 0); assert_eq!(moq_consume_catalog_cancel(catalog_task), 0); @@ -4379,7 +4494,7 @@ fn video_raw_publish_consume() { let rgba = gray_rgba(320, 240); let publish = |index: u64| { let frame = moq_video_encoder_frame { - timestamp_us: index * 1_001_000 / 30, + timestamp: micros(index * 1_001_000 / 30), data: rgba.as_ptr(), data_size: rgba.len(), }; @@ -4541,7 +4656,7 @@ fn decode_first_frame(output: &moq_video_decoder_output) -> (u32, u32, usize) { let rgba = gray_rgba(320, 240); let publish = |index: u64| { let frame = moq_video_encoder_frame { - timestamp_us: index * 33_333, + timestamp: micros(index * 33_333), data: rgba.as_ptr(), data_size: rgba.len(), }; @@ -4658,7 +4773,7 @@ fn video_raw_publish_from_many_threads() { assert_eq!(moq_encode_video_cut(producer), 0); } let frame = moq_video_encoder_frame { - timestamp_us: i * 33_333, + timestamp: micros(i * 33_333), data: rgba.as_ptr(), data_size: rgba.len(), }; @@ -4681,7 +4796,7 @@ fn video_raw_publish_from_many_threads() { /// Publish one mid-gray frame to a raw video producer, returning the status code. fn publish_gray(producer: u32, rgba: &[u8]) -> i32 { let frame = moq_video_encoder_frame { - timestamp_us: 0, + timestamp: micros(0), data: rgba.as_ptr(), data_size: rgba.len(), }; @@ -4861,7 +4976,7 @@ fn video_raw_publish_rejects_frame_size_mismatch() { // of its own, so this is caught as a wrong-sized picture. let rgba = gray_rgba(640, 480); let frame = moq_video_encoder_frame { - timestamp_us: 0, + timestamp: micros(0), data: rgba.as_ptr(), data_size: rgba.len(), }; @@ -5027,7 +5142,14 @@ fn video_raw_decode() { for (i, frame) in frames.iter().enumerate() { assert_eq!( - unsafe { moq_publish_media_frame(media, frame.payload.as_ptr(), frame.payload.len(), (i as u64) * 33_000) }, + unsafe { + moq_publish_media_frame( + media, + frame.payload.as_ptr(), + frame.payload.len(), + micros((i as u64) * 33_000), + ) + }, 0 ); } @@ -5094,7 +5216,7 @@ fn multiple_frames_ordering() { for (i, &ts) in timestamps.iter().enumerate() { let payload = format!("frame-{i}"); assert_eq!( - unsafe { moq_publish_media_frame(media, payload.as_ptr(), payload.len(), ts) }, + unsafe { moq_publish_media_frame(media, payload.as_ptr(), payload.len(), micros(ts)) }, 0 ); } @@ -5104,12 +5226,15 @@ fn multiple_frames_ordering() { let mut frame = moq_frame { payload: std::ptr::null(), payload_size: 0, - timestamp_us: 0, - timestamp_present: false, + timestamp: std::ptr::null(), keyframe: false, }; assert_eq!(unsafe { encoded_frame(frame_id, &mut frame) }, 0); - assert_eq!(frame.timestamp_us, expected_ts, "frame {i} has wrong timestamp"); + assert_eq!( + read_timestamp(frame.timestamp), + Some(micros(expected_ts)), + "frame {i} has wrong timestamp" + ); let received = unsafe { std::slice::from_raw_parts(frame.payload, frame.payload_size) }; let expected = format!("frame-{i}"); @@ -6168,13 +6293,13 @@ fn server_accepts_a_session() { let (consumer, frames) = subscribe_named_track(consumed, b"tail"); let first = b"ready"; assert_eq!( - unsafe { moq_publish_track_frame(track, first.as_ptr(), first.len(), 0) }, + unsafe { moq_publish_track_frame(track, first.as_ptr(), first.len(), µs(0)) }, 0 ); assert_eq!(moq_consume_track_frame_free(id(frames.recv())), 0); let tail = vec![42; 64 * 1024]; assert_eq!( - unsafe { moq_publish_track_frame(track, tail.as_ptr(), tail.len(), 1) }, + unsafe { moq_publish_track_frame(track, tail.as_ptr(), tail.len(), µs(1)) }, 0 ); assert_eq!(moq_publish_track_finish(track), 0); @@ -6317,8 +6442,7 @@ fn read_raw_frames(consume: u32, name: &[u8], count: usize) -> Vec> { let mut frame = moq_frame { payload: std::ptr::null(), payload_size: 0, - timestamp_us: 0, - timestamp_present: false, + timestamp: std::ptr::null(), keyframe: false, }; assert_eq!(unsafe { moq_consume_track_frame(frame_id, &mut frame) }, 0); diff --git a/rs/moq-c/src/video.rs b/rs/moq-c/src/video.rs index 248a2dd3493..03247fbd723 100644 --- a/rs/moq-c/src/video.rs +++ b/rs/moq-c/src/video.rs @@ -21,7 +21,7 @@ use tokio::sync::oneshot; use crate::decode::Read; use crate::ffi::OnStatus; use crate::task::Task; -use crate::{Error, Id, NonZeroSlab, Shared, State, ffi, moq_decode_gap, moq_decode_read_kind}; +use crate::{Error, Id, NonZeroSlab, Shared, State, ffi, moq_decode_gap, moq_decode_read_kind, moq_timestamp}; // ---- C-visible types ---- @@ -147,8 +147,8 @@ pub struct moq_video_encode_options { /// dimensions, since there they are what the stream turned out to be. #[repr(C)] pub struct moq_video_encoder_frame { - /// Presentation timestamp, in microseconds. - pub timestamp_us: u64, + /// The presentation timestamp. + pub timestamp: moq_timestamp, /// The raw frame bytes in the configured layout. pub data: *const u8, /// The length in bytes of `data`. @@ -197,8 +197,8 @@ pub struct moq_video_decoder_output { /// dimensions because the encoder already fixed them. #[repr(C)] pub struct moq_video_frame { - /// The presentation timestamp in microseconds. - pub timestamp_us: u64, + /// The presentation timestamp. + pub timestamp: moq_timestamp, /// The decoded width in pixels. pub width: u32, /// The decoded height in pixels. @@ -220,10 +220,10 @@ pub struct moq_video_read { /// The lost span, for [moq_decode_read_kind::MOQ_DECODE_READ_GAP]. Every picture from /// before the loss precedes it, and what follows does not continue what came before. pub gap: moq_decode_gap, - /// Where the stopped encoder's media stops in microseconds, for + /// Where the stopped encoder's media stops, for /// [moq_decode_read_kind::MOQ_DECODE_READ_END]. The stopped encoder's last pictures /// precede it; what follows comes from a fresh encoder. - pub end_us: u64, + pub end: moq_timestamp, } // ---- State extension (used internally by lib.rs) ---- @@ -500,7 +500,7 @@ fn finalize( } impl VideoEncoder { - fn publish_frame(&mut self, timestamp_us: u64, data: &[u8]) -> Result<(), Error> { + fn publish_frame(&mut self, timestamp: moq_net::Timestamp, data: &[u8]) -> Result<(), Error> { if let Some(followed) = &self.followed { followed.check()?; } @@ -518,7 +518,7 @@ impl VideoEncoder { let Some(encoder) = self.encoder.as_mut() else { return Ok(()); }; - let frame = moq_video::Frame::new(surface, moq_net::Timestamp::from_micros(timestamp_us)?); + let frame = moq_video::Frame::new(surface, timestamp); // A backend that pipelines hands back an earlier frame's output, so this is // zero or more access units rather than one per call. let encoded = block_on(encoder.encode(frame))?; @@ -810,7 +810,7 @@ impl Video { pixels: OnceLock::new(), })), Some(moq_video::decode::Read::Gap { timestamp, duration }) => Read::gap(timestamp, duration)?, - Some(moq_video::decode::Read::End { end }) => Read::end(end)?, + Some(moq_video::decode::Read::End { end }) => Read::end(end), None => return Ok(()), }, }; @@ -1042,7 +1042,7 @@ pub unsafe extern "C" fn moq_encode_video_frame(producer: u32, frame: *const moq .lock() .as_mut() .ok_or(Error::MediaNotFound)? - .publish_frame(frame.timestamp_us, data) + .publish_frame(frame.timestamp.try_into()?, data) }) } @@ -1221,13 +1221,12 @@ pub unsafe extern "C" fn moq_decode_video_read(id: u32, dst: *mut moq_video_read let id = ffi::parse_id(id)?; let dst = unsafe { dst.as_mut() }.ok_or(Error::InvalidPointer)?; let read = State::lock().video.read(id)?; - let (kind, gap, end_us) = read.info(); + let (kind, gap, end) = read.info(); let frame = match &read { Read::Frame(frame) => { let pixels = frame.pixels()?; moq_video_frame { - // The decoded Timestamp is bounded by a QUIC varint, so its microseconds fit. - timestamp_us: frame.frame.timestamp.as_micros() as u64, + timestamp: frame.frame.timestamp.into(), width: pixels.width, height: pixels.height, // The slab keeps its `Arc` until the id is freed, and the pixels are @@ -1237,19 +1236,14 @@ pub unsafe extern "C" fn moq_decode_video_read(id: u32, dst: *mut moq_video_read } } _ => moq_video_frame { - timestamp_us: 0, + timestamp: moq_timestamp::default(), width: 0, height: 0, data: std::ptr::null(), data_size: 0, }, }; - *dst = moq_video_read { - kind, - frame, - gap, - end_us, - }; + *dst = moq_video_read { kind, frame, gap, end }; Ok(()) }) } diff --git a/rs/moq-ffi/src/media.rs b/rs/moq-ffi/src/media.rs index 4cfff9c400f..452095f1a24 100644 --- a/rs/moq-ffi/src/media.rs +++ b/rs/moq-ffi/src/media.rs @@ -746,14 +746,13 @@ impl MoqMediaCatalogProducer { })) } - /// Read the broadcast clock in microseconds, fixing it for subsequent media producers. - pub fn now(&self) -> Result { + /// Read the broadcast clock, fixing it for subsequent media producers. + pub fn now(&self) -> Result { let _guard = crate::ffi::enter(); - self.broadcast.upgrade().ok_or(MoqError::Closed)?.with_state(|state| { - u64::try_from(state.catalog.clock().now().as_micros()).map_err(|_| MoqError::Codec { - reason: "broadcast clock exceeds microsecond timestamp range".into(), - }) - }) + self.broadcast + .upgrade() + .ok_or(MoqError::Closed)? + .with_state(|state| Ok(state.catalog.clock().now().into())) } /// Replace shared video properties, clearing fields that are absent. diff --git a/swift/README.md b/swift/README.md index 84d598e4fb1..8a677f51f92 100644 --- a/swift/README.md +++ b/swift/README.md @@ -77,7 +77,7 @@ Every consumer conforms to `AsyncSequence`, so `for try await x in consumer` wor Incoming server `Request` values expose the query-free `path` before acceptance. It is consistent across transports and is empty for the root or missing path. The encoded `query` may contain credentials. -Raw tracks also expose best-effort datagrams: `TrackProducer.appendDatagram(_:timestampUs:)` +Raw tracks also expose best-effort datagrams: `TrackProducer.appendDatagram(_:timestamp:)` returns the assigned sequence number, `TrackConsumer.recvDatagram()` receives one datagram, and `TrackConsumer.datagrams` streams them in arrival order. Payloads are capped at 1200 bytes. Datagrams require a datagram-capable transport and lite-05 or newer moq-lite, or moq-transport; diff --git a/swift/Sources/Moq/Aliases.swift b/swift/Sources/Moq/Aliases.swift index 390792a4e61..30a1f2c4476 100644 --- a/swift/Sources/Moq/Aliases.swift +++ b/swift/Sources/Moq/Aliases.swift @@ -7,6 +7,8 @@ import MoqFFI // instead (see Client.swift, Broadcast.swift, etc.), so MoqFFI's `Moq`-prefixed // classes never appear in the public API. +/// An exact media timestamp: `value` units at `scale` units per second. +public typealias Timestamp = MoqFFI.MoqTimestamp /// A payload plus the presentation timestamp it should play at. The unit of /// every raw write and raw read. public typealias Frame = MoqFFI.MoqFrame @@ -122,7 +124,7 @@ extension Subscription { /// A span of a track to deliver: from `start` up to `end`, or onward when `end` is `nil`. public typealias Range = MoqFFI.MoqRange /// Where one end of a `Range` falls: `.absolute(group:)`, `.relative(groups:)` - /// back from the latest group, or `.time(timestampUs:)` for the group containing it. + /// back from the latest group, or `.time(timestamp:)` for the group containing it. public typealias Anchor = MoqFFI.MoqAnchor /// Which pending group the publisher sends first: `.ascending` or `.descending`. public typealias Order = MoqFFI.MoqOrder diff --git a/swift/Sources/Moq/Flate.swift b/swift/Sources/Moq/Flate.swift index 3ed5ba6a974..486b08383a7 100644 --- a/swift/Sources/Moq/Flate.swift +++ b/swift/Sources/Moq/Flate.swift @@ -15,8 +15,8 @@ extension Flate { } /// Replace the payload at the given broadcast time, or leave it untimed when nil. - public func update(_ payload: Data, timestampUs: UInt64? = nil) throws { - try ffi.update(payload: payload, timestampUs: timestampUs) + public func update(_ payload: Data, timestamp: Timestamp? = nil) throws { + try ffi.update(payload: payload, timestamp: timestamp) } /// Close the track and retire its catalog entry. @@ -33,8 +33,8 @@ extension Flate { } /// Append a payload at the given broadcast time, or leave it untimed when nil. - public func append(_ payload: Data, timestampUs: UInt64? = nil) throws { - try ffi.append(payload: payload, timestampUs: timestampUs) + public func append(_ payload: Data, timestamp: Timestamp? = nil) throws { + try ffi.append(payload: payload, timestamp: timestamp) } /// Close the track and retire its catalog entry. diff --git a/swift/Sources/Moq/Json.swift b/swift/Sources/Moq/Json.swift index 6657da163e4..09f6710f52f 100644 --- a/swift/Sources/Moq/Json.swift +++ b/swift/Sources/Moq/Json.swift @@ -16,20 +16,18 @@ extension Json { public struct Timed { /// The decoded value. public let value: Value - /// The frame's timestamp on the broadcast clock in microseconds, or `nil` when untimed. - /// Rounded down to a whole microsecond, so a tick on a track like 90 kHz may not survive - /// a read and republish exactly. - public let timestampUs: UInt64? + /// The frame's timestamp on the broadcast clock, or `nil` when untimed. + public let timestamp: Timestamp? /// Pair `value` with its frame timestamp. - public init(value: Value, timestampUs: UInt64?) { + public init(value: Value, timestamp: Timestamp?) { self.value = value - self.timestampUs = timestampUs + self.timestamp = timestamp } init?(_ ffi: MoqJsonValue?) throws where Value: Decodable { guard let ffi else { return nil } - self.init(value: try decodeJson(ffi.value), timestampUs: ffi.timestampUs) + self.init(value: try decodeJson(ffi.value), timestamp: ffi.timestamp) } } @@ -62,8 +60,8 @@ extension Json { /// Publish a new value, encoded as a snapshot or merge-patch delta automatically. A no-op /// if unchanged from the previous update. - public func update(_ value: Value, timestampUs: UInt64? = nil) throws { - try ffi.update(value: encodeJson(value), timestampUs: timestampUs) + public func update(_ value: Value, timestamp: Timestamp? = nil) throws { + try ffi.update(value: encodeJson(value), timestamp: timestamp) } /// A watch-only handle to whether the track has subscribers. @@ -137,8 +135,8 @@ extension Json { } /// Append one record to the log. - public func append(_ value: Value, timestampUs: UInt64? = nil) throws { - try ffi.append(value: encodeJson(value), timestampUs: timestampUs) + public func append(_ value: Value, timestamp: Timestamp? = nil) throws { + try ffi.append(value: encodeJson(value), timestamp: timestamp) } /// A watch-only handle to whether the track has subscribers. @@ -210,13 +208,13 @@ extension Json { } /// Append one record to the back of the window. - public func push(_ value: Value, timestampUs: UInt64? = nil) throws { - try ffi.push(value: encodeJson(value), timestampUs: timestampUs) + public func push(_ value: Value, timestamp: Timestamp? = nil) throws { + try ffi.push(value: encodeJson(value), timestamp: timestamp) } /// Drop `count` records from the front of the window, clamped to what it holds. - public func pop(_ count: UInt64, timestampUs: UInt64? = nil) throws { - try ffi.pop(count: count, timestampUs: timestampUs) + public func pop(_ count: UInt64, timestamp: Timestamp? = nil) throws { + try ffi.pop(count: count, timestamp: timestamp) } /// Close the open group, so the next edit opens one restating the retained window. A no-op @@ -273,7 +271,7 @@ extension Json { case let .pop(start, end): event = .pop(start.. UInt64 { try ffi.now() } + /// Read the broadcast clock, fixing it for subsequent media producers. + public func now() throws -> Timestamp { try ffi.now() } /// Replace the video properties shared by every rendition. public func setVideoProperties(_ properties: VideoProperties) throws { try ffi.setVideoProperties(properties: properties) } /// Set an application catalog section from its serialized JSON value. @@ -238,12 +238,12 @@ public enum Media { TrackDemand(try ffi.demand()) } - /// Write a frame with the given presentation timestamp (microseconds). + /// Write a frame with the given presentation timestamp. /// /// The importer derives keyframe status from the bitstream, so only the payload and its /// timestamp cross the boundary. - public func writeFrame(_ payload: Data, timestampUs: UInt64) throws { - try ffi.writeFrame(frame: Frame(payload: payload, timestampUs: timestampUs)) + public func writeFrame(_ payload: Data, timestamp: Timestamp) throws { + try ffi.writeFrame(frame: Frame(payload: payload, timestamp: timestamp)) } /// Mark a timeline break, preserving the advertised jitter and delay. diff --git a/swift/Sources/Moq/Timestamp.swift b/swift/Sources/Moq/Timestamp.swift new file mode 100644 index 00000000000..ec70c0728ac --- /dev/null +++ b/swift/Sources/Moq/Timestamp.swift @@ -0,0 +1,52 @@ +import MoqFFI + +// The bounds moq-ffi enforces on a write, so a conversion refuses what a write would. +private let maxValue: UInt64 = (1 << 61) - 1 +private let maxScale: UInt64 = (1 << 62) - 1 +private let attosecondsPerSecond: UInt64 = 1_000_000_000_000_000_000 + +@available(macOS 13, iOS 16, *) +extension Timestamp { + /// The timestamp exactly equal to `duration`, at the finest power-of-ten scale that fits. + /// + /// `Duration` counts attoseconds, so the scale starts at 10^18 and steps down one power of ten + /// each time the value would pass `2^61 - 1` (about 2.3 s of attoseconds, 73 years of + /// nanoseconds), down to whole seconds. Throws `MoqError.TimeOverflow` for a negative duration, + /// or one with finer precision than the largest scale whose value fits. + public init(_ duration: Duration) throws { + guard duration >= .zero else { throw MoqError.TimeOverflow } + let (seconds, attoseconds) = duration.components + var scale = attosecondsPerSecond + var divisor: UInt64 = 1 + while scale > 0 { + let (whole, overflow) = UInt64(seconds).multipliedReportingOverflow(by: scale) + let (fraction, remainder) = UInt64(attoseconds).quotientAndRemainder(dividingBy: divisor) + // `fraction` is below `scale`, which is below `maxValue`, so the subtraction can't wrap. + if !overflow, whole <= maxValue - fraction { + // A coarser scale can't hold what this one drops, so stop here either way. + guard remainder == 0 else { throw MoqError.TimeOverflow } + self.init(value: whole + fraction, scale: scale) + return + } + scale /= 10 + divisor *= 10 + } + throw MoqError.TimeOverflow + } + + /// This timestamp as a `Duration`, rounded to the nearest attosecond. + /// + /// Exact when `scale` divides 10^18, such as microseconds or nanoseconds; a 90 kHz tick rounds, + /// so keep the record itself to republish a read exactly. Throws `MoqError.TimeOverflow` for a + /// record outside the bounds a write accepts. + public var duration: Duration { + get throws { + guard scale != 0, scale <= maxScale, value <= maxValue else { throw MoqError.TimeOverflow } + let (seconds, remainder) = value.quotientAndRemainder(dividingBy: scale) + // `remainder` is below `scale`, so the quotient is below 10^18 and fits. + var (attoseconds, rest) = scale.dividingFullWidth(remainder.multipliedFullWidth(by: attosecondsPerSecond)) + if rest >= scale - rest { attoseconds += 1 } + return Duration(secondsComponent: Int64(seconds), attosecondsComponent: Int64(attoseconds)) + } + } +} diff --git a/swift/Sources/Moq/Track.swift b/swift/Sources/Moq/Track.swift index 7a3f1d23c1f..f4a3dd1d820 100644 --- a/swift/Sources/Moq/Track.swift +++ b/swift/Sources/Moq/Track.swift @@ -176,17 +176,17 @@ public final class TrackProducer: Sendable { GroupProducer(try ffi.createGroup(sequence: sequence)) } - /// Write a single-frame group with a timestamp in microseconds. - public func writeFrame(_ payload: Data, timestampUs: UInt64? = nil) throws { - try ffi.writeFrame(frame: Frame(payload: payload, timestampUs: timestampUs)) + /// Write a single-frame group with a presentation timestamp, or untimed when nil. + public func writeFrame(_ payload: Data, timestamp: Timestamp? = nil) throws { + try ffi.writeFrame(frame: Frame(payload: payload, timestamp: timestamp)) } /// Send a best-effort datagram and return its sequence number. /// - /// `timestampUs` is the presentation timestamp in microseconds. Payloads are + /// `timestamp` is the presentation timestamp, or untimed when nil. Payloads are /// capped at 1200 bytes. There is no stream fallback. - public func appendDatagram(_ payload: Data, timestampUs: UInt64? = nil) throws -> UInt64 { - try ffi.appendDatagram(frame: Frame(payload: payload, timestampUs: timestampUs)) + public func appendDatagram(_ payload: Data, timestamp: Timestamp? = nil) throws -> UInt64 { + try ffi.appendDatagram(frame: Frame(payload: payload, timestamp: timestamp)) } /// Abort the track with an application error code, failing active consumers. @@ -224,9 +224,9 @@ public final class GroupProducer: Sendable { GroupConsumer(try ffi.consume()) } - /// Write a frame with a timestamp in microseconds. - public func writeFrame(_ payload: Data, timestampUs: UInt64? = nil) throws { - try ffi.writeFrame(frame: Frame(payload: payload, timestampUs: timestampUs)) + /// Write a frame with a presentation timestamp, or untimed when nil. + public func writeFrame(_ payload: Data, timestamp: Timestamp? = nil) throws { + try ffi.writeFrame(frame: Frame(payload: payload, timestamp: timestamp)) } /// Mark the group complete. No more frames can be written. diff --git a/swift/Tests/MoqTests/Docs/Prelude.swift b/swift/Tests/MoqTests/Docs/Prelude.swift index f900542855a..a8516215bde 100644 --- a/swift/Tests/MoqTests/Docs/Prelude.swift +++ b/swift/Tests/MoqTests/Docs/Prelude.swift @@ -6,6 +6,6 @@ import Moq var opusInit: Data { fatalError() } var packet: Data { fatalError() } -var pts: UInt64 { fatalError() } +var pts: Timestamp { fatalError() } var rgba: Data { fatalError() } var session: Session { fatalError() } diff --git a/swift/Tests/MoqTests/FfiBench.swift b/swift/Tests/MoqTests/FfiBench.swift index 77aeac67abd..4275ea5153e 100644 --- a/swift/Tests/MoqTests/FfiBench.swift +++ b/swift/Tests/MoqTests/FfiBench.swift @@ -86,13 +86,13 @@ final class FfiBench: XCTestCase { let received = try await group.readFrame() let frame = try XCTUnwrap(received, "group ended") XCTAssertEqual(frame.payload, payload) - XCTAssertEqual(frame.timestampUs, UInt64(n * c.frames + f)) + XCTAssertEqual(frame.timestamp, Timestamp(value: UInt64(n * c.frames + f), scale: 1_000_000)) } } } for track in tracks { let group = try track.appendGroup() - for f in 0.. AnnounceEv return try XCTUnwrap(next, "announce stream ended") } +/// A timestamp in microseconds. +private func micros(_ value: UInt64) -> Timestamp { + Timestamp(value: value, scale: 1_000_000) +} + +/// Assert `body` throws `MoqError.TimeOverflow`. +private func assertTimeOverflow(_ body: @autoclosure () throws -> T, file: StaticString = #filePath, line: UInt = #line) { + XCTAssertThrowsError(try body(), file: file, line: line) { error in + guard case MoqError.TimeOverflow = error else { + return XCTFail("expected TimeOverflow, got \(error)", file: file, line: line) + } + } +} + final class SmokeTests: XCTestCase { func testContainerTimebaseBelongsToOneBroadcast() throws { let owner = try BroadcastProducer() @@ -42,7 +56,7 @@ final class SmokeTests: XCTestCase { let track = try broadcast.publishTrack(name: "backlog", info: TrackInfo(timescale: 1_000_000)) for ms: UInt64 in 0..<3 { let group = try track.appendGroup() - try group.writeFrame(Data("x".utf8), timestampUs: ms * 1_000) + try group.writeFrame(Data("x".utf8), timestamp: micros(ms * 1_000)) try group.finish() } let consumer = try track.consume(subscription: Subscription( @@ -311,7 +325,7 @@ final class SmokeTests: XCTestCase { let broadcast = try BroadcastProducer() let track = try broadcast.publishTrack(name: "events", info: TrackInfo(timescale: 1_000_000)) let group = try track.appendGroup() - try group.writeFrame(Data("cached".utf8), timestampUs: 0) + try group.writeFrame(Data("cached".utf8), timestamp: micros(0)) try group.finish() let consumer = try broadcast.consume() @@ -342,16 +356,16 @@ final class SmokeTests: XCTestCase { track: try await broadcast.consume().subscribeTrack(name: "status"), compression: true) for viewers in 1...4 { - try producer.update(Status(state: "live", viewers: viewers), timestampUs: UInt64(viewers) * 1000) + try producer.update(Status(state: "live", viewers: viewers), timestamp: micros(UInt64(viewers) * 1000)) } // `next` yields every state in order; `latest` skips the buffered third. let first = try await consumer.next() - XCTAssertEqual(first, Json.Timed(value: Status(state: "live", viewers: 1), timestampUs: 1000)) + XCTAssertEqual(first, Json.Timed(value: Status(state: "live", viewers: 1), timestamp: micros(1000))) let second = try await consumer.next() - XCTAssertEqual(second, Json.Timed(value: Status(state: "live", viewers: 2), timestampUs: 2000)) + XCTAssertEqual(second, Json.Timed(value: Status(state: "live", viewers: 2), timestamp: micros(2000))) let latest = try await consumer.latest() - XCTAssertEqual(latest, Json.Timed(value: Status(state: "live", viewers: 4), timestampUs: 4000)) + XCTAssertEqual(latest, Json.Timed(value: Status(state: "live", viewers: 4), timestamp: micros(4000))) consumer.cancel() try producer.finish() @@ -372,7 +386,7 @@ final class SmokeTests: XCTestCase { for n in 0..<3 { try producer.append(Event(n: n)) let record = try await consumer.next() - XCTAssertEqual(record, Json.Timed(value: Event(n: n), timestampUs: nil)) + XCTAssertEqual(record, Json.Timed(value: Event(n: n), timestamp: nil)) } consumer.cancel() @@ -392,23 +406,23 @@ final class SmokeTests: XCTestCase { track: try await broadcast.consume().subscribeTrack(name: "log"), compression: true) for n in 0..<3 { - try producer.push(Event(n: n), timestampUs: UInt64(n) * 1000) + try producer.push(Event(n: n), timestamp: micros(UInt64(n) * 1000)) } - try producer.pop(2, timestampUs: 3000) + try producer.pop(2, timestamp: micros(3000)) for n in 0..<3 { let event = try await consumer.next() XCTAssertEqual( - event, Json.Timed(value: .push(index: UInt64(n), value: Event(n: n)), timestampUs: UInt64(n) * 1000)) + event, Json.Timed(value: .push(index: UInt64(n), value: Event(n: n)), timestamp: micros(UInt64(n) * 1000))) } let pop = try await consumer.next() - XCTAssertEqual(pop, Json.Timed(value: .pop(0..<2), timestampUs: 3000)) + XCTAssertEqual(pop, Json.Timed(value: .pop(0..<2), timestamp: micros(3000))) // The cut's new group restates record 2, which this reader already has. try producer.cut() - try producer.push(Event(n: 3), timestampUs: 4000) + try producer.push(Event(n: 3), timestamp: micros(4000)) let pushed = try await consumer.next() - XCTAssertEqual(pushed, Json.Timed(value: .push(index: 3, value: Event(n: 3)), timestampUs: 4000)) + XCTAssertEqual(pushed, Json.Timed(value: .push(index: 3, value: Event(n: 3)), timestamp: micros(4000))) try producer.finish() let end = try await consumer.next() @@ -445,26 +459,27 @@ final class SmokeTests: XCTestCase { } func testFlateTimestampsRoundTrip() async throws { - for timestamp in [nil, UInt64(123_456)] { + // A 90 kHz tick, which no microsecond count holds exactly. + for timestamp in [nil, Timestamp(value: 123_457, scale: 90_000)] { for mode in ["snapshot", "stream"] { let broadcast = try BroadcastProducer() - let info: TrackInfo? = timestamp.map { _ in TrackInfo(timescale: 1_000_000) } + let info: TrackInfo? = timestamp.map { TrackInfo(timescale: $0.scale) } let track = try broadcast.publishTrack(name: "data", info: info) let consumer = try track.consume() let payload = Data("payload".utf8) if mode == "snapshot" { let producer = try Flate.SnapshotProducer(broadcast: broadcast, track: track) - try producer.update(payload, timestampUs: timestamp) + try producer.update(payload, timestamp: timestamp) try producer.finish() } else { let producer = try Flate.StreamProducer(broadcast: broadcast, track: track) - try producer.append(payload, timestampUs: timestamp) + try producer.append(payload, timestamp: timestamp) try producer.finish() } let received = try await consumer.readFrame() let frame = try XCTUnwrap(received) XCTAssertEqual(frame.payload, payload) - XCTAssertEqual(frame.timestampUs, timestamp) + XCTAssertEqual(frame.timestamp, timestamp) try broadcast.close() } } @@ -478,7 +493,7 @@ final class SmokeTests: XCTestCase { let received = try await consumer.readFrame() let frame = try XCTUnwrap(received) XCTAssertEqual(frame.payload, Data("payload".utf8)) - XCTAssertNil(frame.timestampUs) + XCTAssertNil(frame.timestamp) XCTAssertNil(consumer.info().timescale) try track.finish() try broadcast.close() @@ -490,26 +505,75 @@ final class SmokeTests: XCTestCase { let consumer = try track.consume() let payload = Data("ready".utf8) - try track.writeFrame(payload, timestampUs: 12_345) + try track.writeFrame(payload, timestamp: micros(12_345)) let frame = try await consumer.readFrame() XCTAssertEqual(frame?.payload, payload) - XCTAssertEqual(frame?.timestampUs, 12_345) + XCTAssertEqual(frame?.timestamp, micros(12_345)) let group = try track.appendGroup() let groupConsumer = try group.consume() let groupPayload = Data("group".utf8) - try group.writeFrame(groupPayload, timestampUs: 23_456) + try group.writeFrame(groupPayload, timestamp: micros(23_456)) try group.finish() let groupFrame = try await groupConsumer.readFrame() XCTAssertEqual(groupFrame?.payload, groupPayload) - XCTAssertEqual(groupFrame?.timestampUs, 23_456) + XCTAssertEqual(groupFrame?.timestamp, micros(23_456)) try track.finish() try broadcast.close() } + func testTimestampsAreExact() async throws { + let broadcast = try BroadcastProducer() + let track = try broadcast.publishTrack(name: "video", info: TrackInfo(timescale: 90_000)) + let consumer = try track.consume() + + // A present zero stays present, and one 90 kHz tick reads back as itself rather than + // the 11 µs it floors to. + for value: UInt64 in [0, 1] { + let timestamp = Timestamp(value: value, scale: 90_000) + try track.writeFrame(Data("frame".utf8), timestamp: timestamp) + let frame = try await consumer.readFrame() + XCTAssertEqual(frame?.timestamp, timestamp) + } + + for invalid in [ + Timestamp(value: 0, scale: 0), + Timestamp(value: 0, scale: 1 << 62), + Timestamp(value: 1 << 61, scale: 90_000), + ] { + assertTimeOverflow(try track.writeFrame(Data("frame".utf8), timestamp: invalid)) + assertTimeOverflow(try invalid.duration) + } + + try track.finish() + try broadcast.close() + } + + @available(macOS 13, iOS 16, *) + func testTimestampDurations() throws { + // Exact at the finest power-of-ten scale whose value fits. + let atto: UInt64 = 1_000_000_000_000_000_000 + XCTAssertEqual(try Timestamp(.zero), Timestamp(value: 0, scale: atto)) + XCTAssertEqual(try Timestamp(.milliseconds(20)), Timestamp(value: atto / 50, scale: atto)) + XCTAssertEqual(try Timestamp(.seconds(3_600)), Timestamp(value: 3_600 * (atto / 10_000), scale: atto / 10_000)) + XCTAssertEqual(try Timestamp(.seconds((1 << 61) - 1)), Timestamp(value: (1 << 61) - 1, scale: 1)) + assertTimeOverflow(try Timestamp(.seconds(1 << 61))) + assertTimeOverflow(try Timestamp(.seconds(-1))) + // Three seconds of attoseconds passes 2^61, and the attosecond doesn't survive a coarser scale. + assertTimeOverflow(try Timestamp(.seconds(3) + Duration(secondsComponent: 0, attosecondsComponent: 1))) + + // Back to the nearest attosecond: a 90 kHz tick is 11_111_111_111_111.1 as, and 2/3 s rounds up. + let tick = Duration(secondsComponent: 0, attosecondsComponent: 11_111_111_111_111) + XCTAssertEqual(try Timestamp(value: 1, scale: 90_000).duration, tick) + let twoThirds = Duration(secondsComponent: 0, attosecondsComponent: 666_666_666_666_666_667) + XCTAssertEqual(try Timestamp(value: 2, scale: 3).duration, twoThirds) + XCTAssertEqual(try micros(1_500_000).duration, .milliseconds(1_500)) + XCTAssertEqual(try Timestamp(.seconds(3_600)).duration, .seconds(3_600)) + } + func testReadFrameSkipsEmptyThenPopulatedGroups() async throws { let broadcast = try BroadcastProducer() let track = try broadcast.publishTrack(name: "status", info: TrackInfo(timescale: 1_000_000)) @@ -517,11 +581,11 @@ final class SmokeTests: XCTestCase { try track.appendGroup().finish() try track.appendGroup().finish() - try track.writeFrame(Data("populated".utf8), timestampUs: 2_000) + try track.writeFrame(Data("populated".utf8), timestamp: micros(2_000)) let frame = try await consumer.readFrame() XCTAssertEqual(frame?.payload, Data("populated".utf8)) - XCTAssertEqual(frame?.timestampUs, 2_000) + XCTAssertEqual(frame?.timestamp, micros(2_000)) try track.finish() try broadcast.close() @@ -555,7 +619,7 @@ final class SmokeTests: XCTestCase { track: "fine" ) // 2.5 ms of silence at 48 kHz mono f32: exactly one encoded frame. - try fine.write(AudioFrame(timestampUs: 0, data: Data(count: 120 * 4))) + try fine.write(AudioFrame(timestamp: micros(0), data: Data(count: 120 * 4))) try fine.finish() XCTAssertThrowsError( @@ -606,7 +670,7 @@ final class SmokeTests: XCTestCase { // Two 20 ms Opus frames of silence at 48 kHz mono. for i in 0..<2 { - try audio.write(AudioFrame(timestampUs: UInt64(i) * 20_000, data: Data(count: 960 * 4))) + try audio.write(AudioFrame(timestamp: micros(UInt64(i) * 20_000), data: Data(count: 960 * 4))) } let fixedFrame = try await fixed.next() XCTAssertNotNil(fixedFrame) @@ -639,7 +703,7 @@ final class SmokeTests: XCTestCase { let rgba = Data(repeating: 0x80, count: 320 * 240 * 4) try video.cut() for i in 0..<10 { - try video.write(VideoFrame(timestampUs: UInt64(i) * 33_333, data: rgba)) + try video.write(VideoFrame(timestamp: micros(UInt64(i) * 33_333), data: rgba)) } let consumer = try await origin.consume().requestBroadcast(path: "video-decode-frame") @@ -653,7 +717,7 @@ final class SmokeTests: XCTestCase { // Keep the encoder fed so the decoder sees frames after it joined. for i in 10..<40 { - try video.write(VideoFrame(timestampUs: UInt64(i) * 33_333, data: rgba)) + try video.write(VideoFrame(timestamp: micros(UInt64(i) * 33_333), data: rgba)) } let next = try await decoder.next() @@ -677,7 +741,7 @@ final class SmokeTests: XCTestCase { func testEncodeAudioWithOpusObject() throws { // The config retains the codec, so releasing either first must still encode. let input = AudioEncoderInput(format: .f32, sampleRate: 48_000, channels: 1) - let silence = AudioFrame(timestampUs: 0, data: Data(count: 960 * 4)) + let silence = AudioFrame(timestamp: micros(0), data: Data(count: 960 * 4)) // Release the codec before encoding: `output` retains it. do { diff --git a/test/interop/clients/c/subscribe.c b/test/interop/clients/c/subscribe.c index 0353ce0ddaf..af81793a279 100644 --- a/test/interop/clients/c/subscribe.c +++ b/test/interop/clients/c/subscribe.c @@ -164,7 +164,10 @@ static void on_audio(void *ud, int32_t id) { moq_audio_frame f = read.frame; if (status == 0 && read.kind == MOQ_DECODE_READ_FRAME && a->samples < a->want) { uint64_t samples = f.data_size / a->frame_bytes; - fprintf(a->log, "%llu %llu\n", (unsigned long long)f.timestamp_us, (unsigned long long)samples); + // tone.py reads whole microseconds; splitting off the seconds keeps the product in range. + moq_timestamp ts = f.timestamp; + unsigned long long us = ts.value / ts.scale * 1000000 + ts.value % ts.scale * 1000000 / ts.scale; + fprintf(a->log, "%llu %llu\n", us, (unsigned long long)samples); fwrite(f.data, 1, f.data_size, a->pcm); a->samples += samples; if (a->samples >= a->want) { @@ -378,7 +381,7 @@ static void on_finish_health_frame(void *ud, int32_t frame) { pthread_mutex_lock(&c->mu); if (read < 0 || info.payload_size != sizeof(payload) - 1 || memcmp(info.payload, payload, sizeof(payload) - 1) != 0 || - info.timestamp_present || ++c->finish.health_frames != 1) c->finish.failed = 1; + info.timestamp != NULL || ++c->finish.health_frames != 1) c->finish.failed = 1; pthread_cond_broadcast(&c->cv); pthread_mutex_unlock(&c->mu); moq_consume_track_frame_free((uint32_t)frame); diff --git a/test/interop/clients/cpp/main.cpp b/test/interop/clients/cpp/main.cpp index 1a7f5b50f78..f3be4b8522b 100644 --- a/test/interop/clients/cpp/main.cpp +++ b/test/interop/clients/cpp/main.cpp @@ -165,8 +165,7 @@ void publish_tone( ) { const auto started = Clock::now(); std::vector data(AUDIO_BATCH_SAMPLES * tones.size() * sizeof(float)); - uint64_t timestamp_us = 0; - size_t phase = 0; + uint64_t phase = 0; while (!stop.load()) { for (size_t i = 0; i < AUDIO_BATCH_SAMPLES; i++) { for (size_t c = 0; c < tones.size(); c++) { @@ -177,11 +176,10 @@ void publish_tone( std::memcpy(&data[(i * tones.size() + c) * sizeof(float)], &sample, sizeof(float)); } } - ok(audio->write({timestamp_us, data}), "tone write"); + ok(audio->write({{phase, AUDIO_RATE}, data}), "tone write"); phase += AUDIO_BATCH_SAMPLES; - timestamp_us += AUDIO_BATCH_US; // Pace against the start, so encoding cost doesn't accumulate as drift. - std::this_thread::sleep_until(started + std::chrono::microseconds(timestamp_us)); + std::this_thread::sleep_until(started + std::chrono::microseconds(phase * 1'000'000 / AUDIO_RATE)); } } @@ -314,7 +312,9 @@ void decode_audio( const auto *frame = &variant->frame; const size_t samples = frame->data.size() / frame_bytes; - log << frame->timestamp_us << " " << samples << "\n"; + // tone.py reads whole microseconds; splitting off the seconds keeps the product in range. + const auto &ts = frame->timestamp; + log << ts.value / ts.scale * 1'000'000 + ts.value % ts.scale * 1'000'000 / ts.scale << " " << samples << "\n"; pcm.write(reinterpret_cast(frame->data.data()), static_cast(frame->data.size())); decoded += samples; } @@ -405,7 +405,7 @@ int subscribe( auto group = until(track->next_group(), read_deadline, "health group"); if (!group) fail("missing health group"); auto frame = until(group->read_frame(), read_deadline, "health frame"); - if (!frame || std::string(frame->payload.begin(), frame->payload.end()) != "session-alive" || frame->timestamp_us) { + if (!frame || std::string(frame->payload.begin(), frame->payload.end()) != "session-alive" || frame->timestamp) { fail("health payload or timestamp"); } if (until(group->read_frame(), read_deadline, "health group EOF") || diff --git a/test/interop/clients/go/main.go b/test/interop/clients/go/main.go index 196b3f2bdd1..f0e038a7d06 100644 --- a/test/interop/clients/go/main.go +++ b/test/interop/clients/go/main.go @@ -70,7 +70,6 @@ func publishTone(ctx context.Context, audio *moqaudio.Producer, tones []float64) defer ticker.Stop() data := make([]byte, audioBatchSamples*len(tones)*4) - timestampUs := uint64(0) phase := 0 for { select { @@ -84,12 +83,12 @@ func publishTone(ctx context.Context, audio *moqaudio.Producer, tones []float64) binary.LittleEndian.PutUint32(data[(i*len(tones)+c)*4:], math.Float32bits(float32(sample))) } } - if err := audio.Write(moqaudio.Frame{Timestamp: time.Duration(timestampUs) * time.Microsecond, Data: data}); err != nil { + // Stamped on the sample clock, so every batch time is exact. + if err := audio.Write(moqaudio.Frame{Timestamp: moq.Timestamp{Value: uint64(phase), Scale: audioRate}, Data: data}); err != nil { fmt.Fprintf(os.Stderr, "tone: %v\n", err) return } phase += audioBatchSamples - timestampUs += audioBatchUs } } @@ -498,7 +497,7 @@ func decodeAudio(ctx context.Context, consumer *moq.BroadcastConsumer, id string } samples := len(frame.Data) / frameBytes - fmt.Fprintf(log, "%d %d\n", frame.Timestamp.Microseconds(), samples) + fmt.Fprintf(log, "%d %d\n", moq.TimestampToDuration(frame.Timestamp).Microseconds(), samples) if _, err := pcm.Write(frame.Data); err != nil { return err } diff --git a/test/interop/clients/python/interop.py b/test/interop/clients/python/interop.py index 23a071c9815..92dc208dbf8 100644 --- a/test/interop/clients/python/interop.py +++ b/test/interop/clients/python/interop.py @@ -61,7 +61,7 @@ async def _publish_tone(audio: moq.audio.Producer, tones: list[int]) -> None: ] audio.write( moq.audio.Frame( - timestamp=timedelta(microseconds=timestamp_us), data=struct.pack(f"<{len(samples)}f", *samples) + timestamp=moq.Timestamp(timestamp_us, 1_000_000), data=struct.pack(f"<{len(samples)}f", *samples) ) ) phase += AUDIO_BATCH_SAMPLES @@ -263,7 +263,7 @@ async def _decode_audio( if isinstance(frame, moq.audio.End): raise RuntimeError("audio track ended early") samples = len(frame.data) // frame_bytes - log.write(f"{frame.timestamp // timedelta(microseconds=1)} {samples}\n") + log.write(f"{frame.timestamp.to_timedelta() // timedelta(microseconds=1)} {samples}\n") pcm.write(frame.data) decoded += samples if decoded * 1000 >= audio_ms * audio.sample_rate: diff --git a/test/wasm/baseline/consumer.ts b/test/wasm/baseline/consumer.ts index 1b30a668051..862af90e226 100644 --- a/test/wasm/baseline/consumer.ts +++ b/test/wasm/baseline/consumer.ts @@ -175,7 +175,9 @@ async function run(config: Sample) { const got = await group.readFrame(); if ( !got || - (timed ? got.timestampUs !== BigInt(frame * 1000) : got.timestampUs !== undefined) + (timed + ? got.timestamp?.value !== BigInt(frame) || got.timestamp.scale !== 1000n + : got.timestamp !== undefined) ) throw new Error(`incorrect UniFFI frame timestamp ${frame}`); check(new Uint8Array(got.payload), frame); diff --git a/test/wasm/baseline/uniffi.ts b/test/wasm/baseline/uniffi.ts index 8cc3dc01a10..940a3bd8012 100644 --- a/test/wasm/baseline/uniffi.ts +++ b/test/wasm/baseline/uniffi.ts @@ -27,6 +27,6 @@ interface Track { interface Group { sequence(): bigint; - readFrame(): Promise<{ payload: ArrayBuffer; timestampUs?: bigint } | undefined>; + readFrame(): Promise<{ payload: ArrayBuffer; timestamp?: { value: bigint; scale: bigint } } | undefined>; cancel(): void; } diff --git a/test/wasm/uniffi/cases.ts b/test/wasm/uniffi/cases.ts index fb08d31051b..77de1e4ac41 100644 --- a/test/wasm/uniffi/cases.ts +++ b/test/wasm/uniffi/cases.ts @@ -60,9 +60,12 @@ const MAX_TIMESTAMP = 2n ** 61n - 1n; /** The ladder's timestamp for `sequence`, capped where a timestamp stops. */ const stamp = (sequence: bigint) => (sequence < MAX_TIMESTAMP ? sequence : MAX_TIMESTAMP); -/** Microsecond ticks, so `timestampUs` passes through unscaled. */ +/** Microsecond ticks, so a `us` timestamp reads back at the scale it was written. */ const TIMED = MoqTrackInfo.create({ timescale: 1_000_000n }); +/** `value` microseconds. */ +const us = (value: bigint) => ({ value, scale: 1_000_000n }); + const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms)); function payload(size: number): ArrayBuffer { @@ -176,10 +179,10 @@ const local: Record Promise> = { using fixture = localGroup(sequence); const { group, consumer } = fixture; if (consumer.sequence() !== sequence) throw new Error(`sequence ${consumer.sequence()} != ${sequence}`); - group.writeFrame({ payload: payload(1), timestampUs: stamp(sequence) }); + group.writeFrame({ payload: payload(1), timestamp: us(stamp(sequence)) }); const frame = await consumer.readFrame(); - if (frame?.timestampUs !== stamp(sequence)) - throw new Error(`timestamp ${frame?.timestampUs} != ${stamp(sequence)}`); + if (frame?.timestamp?.value !== stamp(sequence)) + throw new Error(`timestamp ${frame?.timestamp?.value} != ${stamp(sequence)}`); } return undefined; }, @@ -188,7 +191,7 @@ const local: Record Promise> = { using fixture = localGroup(); const { group } = fixture; try { - group.writeFrame({ payload: payload(1), timestampUs: MAX_TIMESTAMP + 1n }); + group.writeFrame({ payload: payload(1), timestamp: us(MAX_TIMESTAMP + 1n) }); } catch (err) { return (err as Error).message; } @@ -210,7 +213,7 @@ const local: Record Promise> = { (err: unknown) => err, ); if (!error) throw new Error("aborted read resolved"); - group.writeFrame({ payload: payload(3), timestampUs: 0n }); + group.writeFrame({ payload: payload(3), timestamp: us(0n) }); const next = await within(consumer.readFrame(), 1000, "read after abort"); if (next?.payload.byteLength !== 3) throw new Error("the frame after an abort went missing"); return `rejects with ${(error as Error).name}: ${(error as Error).message}`; @@ -251,7 +254,7 @@ const local: Record Promise> = { const read = consumer.readFrame(); (consumer as MoqGroupConsumer).uniffiDestroy(); if (!(await pending(read))) throw new Error("free settled the pending read"); - group.writeFrame({ payload: payload(2), timestampUs: 0n }); + group.writeFrame({ payload: payload(2), timestamp: us(0n) }); const frame = await within(read, 1000, "read after free"); return `resolves later with ${frame?.payload.byteLength} bytes`; }, @@ -343,7 +346,7 @@ const remote: Record Promise> = { const seen: string[] = []; for (const sequence of [5n, 2n ** 32n, 2n ** 53n - 1n, ...HIGH]) { const group = track.createGroup(sequence); - group.writeFrame({ payload: payload(160), timestampUs: stamp(sequence) }); + group.writeFrame({ payload: payload(160), timestamp: us(stamp(sequence)) }); group.finish(); const got = (await within(sub.recvGroup(), 5000, `recvGroup ${sequence} after [${seen}]`)) as | MoqGroupConsumerLike @@ -352,7 +355,8 @@ const remote: Record Promise> = { const frame = await got.readFrame(); // Lite-02 carries no timestamp and a lite-05/06 subscriber drops it; the rest keep it exact. const expected = /^moq-lite-0[1-6]$/.test(relay.version) ? undefined : stamp(sequence); - if (frame?.timestampUs !== expected) throw new Error(`timestamp ${frame?.timestampUs} != ${expected}`); + if (frame?.timestamp?.value !== expected) + throw new Error(`timestamp ${frame?.timestamp?.value} != ${expected}`); seen.push(String(sequence)); } return undefined; @@ -397,7 +401,7 @@ const remote: Record Promise> = { const consumer = await within(subscriber.consume().announcedBroadcast(path).available(), 5000, "announce"); const sub = await consumer.subscribeTrack("data", undefined); const group = track.appendGroup(); - group.writeFrame({ payload: payload(4), timestampUs: 0n }); + group.writeFrame({ payload: payload(4), timestamp: us(0n) }); const got = await within(sub.recvGroup(), 5000, "recvGroup"); if (!got) throw new Error("no group"); await got.readFrame(); @@ -447,7 +451,7 @@ async function bench(): Promise { using fixture = localGroup(); const { group, broadcast } = fixture; const start = performance.now(); - for (let i = 0; i < BATCH; i++) group.writeFrame({ payload: bytes, timestampUs: 0n }); + for (let i = 0; i < BATCH; i++) group.writeFrame({ payload: bytes, timestamp: us(0n) }); const elapsed = performance.now() - start; broadcast.close(); return elapsed; @@ -455,7 +459,7 @@ async function bench(): Promise { await measure(`async read_frame, buffered ${size}B`, batches, async () => { using fixture = localGroup(); const { group, consumer, broadcast } = fixture; - for (let i = 0; i < BATCH; i++) group.writeFrame({ payload: bytes, timestampUs: 0n }); + for (let i = 0; i < BATCH; i++) group.writeFrame({ payload: bytes, timestamp: us(0n) }); const start = performance.now(); for (let i = 0; i < BATCH; i++) await consumer.readFrame(); const elapsed = performance.now() - start; @@ -473,7 +477,7 @@ async function bench(): Promise { const start = performance.now(); for (let i = 0; i < BATCH; i++) { const read = consumer.readFrame(); - group.writeFrame({ payload: bytes, timestampUs: 0n }); + group.writeFrame({ payload: bytes, timestamp: us(0n) }); await read; } const elapsed = performance.now() - start; From 8547267f9e5bbb72cb84d4ed6f74a7bba6f5e0f3 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 27 Oct 2026 18:19:27 -0700 Subject: [PATCH 04/12] chore(quest): finish binding-timestamps; format and regenerate dart bindings Co-Authored-By: Claude Opus 5.5 --- dart/moq_ffi/lib/src/moq.dart | 14 +++--- quest/m1/README.md | 1 - quest/m1/binding-timestamps.md | 73 ---------------------------- quest/m1/release-audit/README.md | 1 - quest/m1/time-addressing/bindings.md | 4 +- rs/moq-ffi/src/audio.rs | 5 +- rs/moq-ffi/src/bench.rs | 4 +- rs/moq-ffi/src/media.rs | 9 ++-- rs/moq-ffi/src/test.rs | 36 +++++++++----- 9 files changed, 39 insertions(+), 108 deletions(-) delete mode 100644 quest/m1/binding-timestamps.md diff --git a/dart/moq_ffi/lib/src/moq.dart b/dart/moq_ffi/lib/src/moq.dart index 769d0588685..144963523ed 100644 --- a/dart/moq_ffi/lib/src/moq.dart +++ b/dart/moq_ffi/lib/src/moq.dart @@ -8,9 +8,7 @@ import "dart:ffi"; import "dart:io" show Platform, File, Directory; import "dart:isolate"; import "dart:typed_data"; - import "package:ffi/ffi.dart"; - import "uniffi_runtime.dart"; export "uniffi_runtime.dart"; @@ -11036,7 +11034,7 @@ class FfiConverterMoqMediaCatalogConsumer { abstract class MoqMediaCatalogProducerInterface { void finish(); - int now(); + MoqTimestamp now(); void removeSection({required String name}); void setSection({required String name, required String json}); void setVideoProperties({required MoqVideoProperties properties}); @@ -11096,13 +11094,13 @@ class MoqMediaCatalogProducer implements MoqMediaCatalogProducerInterface { }, moqExceptionErrorHandler); } - int now() { + MoqTimestamp now() { return rustCallWithLifter( (status) => uniffi_moq_ffi_fn_method_moqmediacatalogproducer_now( uniffiClonePointer(), status, ), - FfiConverterUInt64.lift, + FfiConverterMoqTimestamp.lift, moqExceptionErrorHandler, ); } @@ -18309,10 +18307,10 @@ external void uniffi_moq_ffi_fn_method_moqmediacatalogproducer_finish( Pointer uniffiStatus, ); -@Native, Pointer)>( +@Native, Pointer)>( assetId: _uniffiAssetId, ) -external int uniffi_moq_ffi_fn_method_moqmediacatalogproducer_now( +external RustBuffer uniffi_moq_ffi_fn_method_moqmediacatalogproducer_now( Pointer ptr, Pointer uniffiStatus, ); @@ -21243,7 +21241,7 @@ void _checkApiChecksums() { 62353) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } - if (uniffi_moq_ffi_checksum_method_moqmediacatalogproducer_now() != 14140) { + if (uniffi_moq_ffi_checksum_method_moqmediacatalogproducer_now() != 17945) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } if (uniffi_moq_ffi_checksum_method_moqmediacatalogproducer_remove_section() != diff --git a/quest/m1/README.md b/quest/m1/README.md index d6efb7f4888..92697457f1f 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -121,7 +121,6 @@ surface and zero-copy texture import, land before the cut. - [Routing guide](/quest/m1/routing-guide.md) - concepts and practical outbound federation setup - [moq-c at parity](/quest/m1/c/README.md) - the hand-written `moq-c` ships at the cut with every m1 binding feature moq-ffi gains - [Lite-05/06 timestamps pass through](/quest/m1/lite-timestamps-through.md) - a timed track received over lite-05/06 stays timed and is forwarded with its timestamps over every version -- [Exact timestamps in every binding](/quest/m1/binding-timestamps.md) - bindings carry `{value, scale}` timestamps instead of lossy microseconds - [Announcement takeover](/quest/m1/announce-takeover.md) - a new independent route explicitly continues instances served through its predecessor, with shared Rust/JS semantics and lite-07 wire - [The transport may start a group mid-way](/quest/m1/transport-frame-offsets.md) - a hop may request and deliver a group from any frame it needs, while applications still ask for whole groups - [Subscribe ranges](/quest/m1/subscribe-ranges/README.md) - a lite-07 SUBSCRIBE asks for past and live ranges with absolute or relative ends, in either order, and replaces FETCH; merged ranges never starve a subscriber; relays fill misses by range, including over moq-transport diff --git a/quest/m1/binding-timestamps.md b/quest/m1/binding-timestamps.md deleted file mode 100644 index 9b75e4b5baa..00000000000 --- a/quest/m1/binding-timestamps.md +++ /dev/null @@ -1,73 +0,0 @@ -# [L] Exact timestamps in every binding - -## Goal - -Every binding (moq-ffi, moq-c, cpp and cpp/obs, and the py, swift, kt, go and -dart wrappers) carries media timestamps as an exact `{value, scale}` record -mirroring `moq_net::Timestamp`, with untimed as absent. It replaces the lossy -microsecond fields on frames, datagrams, media and audio frames, producer -arguments, and the JSON data values (`MoqJsonValue`, `moq_json_value`, and each -wrapper's `Timed`). - -The Rust core and `@moq/net` already carry exact timestamps. Wire: none. -Public API: breaking in every binding. - -## Plan - -Today every binding speaks microseconds: moq-ffi `timestamp_us: Option` -(about 160 sites in 9 files: `MoqFrame`, `MoqDatagram`, `MoqMediaFrame`, audio -frames, json/flate producer `update`/`append`, media `flush`, the -subscription start `MoqAnchor::Time`), moq-c `timestamp_us` plus -`timestamp_present` pairs (about 140 sites in 6 files, plus -`moq_anchor.timestamp_us` read as `MOQ_ANCHOR_TIME`), and -each wrapper's native type (Python `timedelta`, Go `*time.Duration`, Swift -`UInt64`, Kotlin `Duration`, Dart `int`, C++ `std::optional`, OBS -microseconds). Reads floor through `as_micros()`, so any scale that does not -divide a microsecond loses: a 90 kHz tick reads as 11 µs, and republishing it -onto a 90 kHz track floors again to tick 0. - -Decided with the maintainer on 2026-10-18: - -- **Scope is the bindings only.** The core and JS types stay as they are. -- **m1**, beside data consumer timestamps. -- **#5677 shipped** the data-value timestamps with the interim microsecond - fields; this quest converts every site at once, `MoqJsonValue` included. -- **Shape mirrors the core:** one `{value, scale}` per value, `value` bounded - as `Timestamp::new` bounds it (`2^61 - 1` since - [#6168](https://github.com/moq-dev/moq/pull/6168), decided 2026-10-22) - and `scale` non-zero and at most `2^62 - 1`, matching `Timescale::new`. The FFI boundary refuses anything else with - an error. Rejected: raw ticks at the track scale beside - `MoqTrackInfo.timescale`, because a producer argument needs its own scale - and per-value records match the core and JS. -- **Names:** UniFFI record `MoqTimestamp`, C `moq_timestamp`, wrappers - `Timestamp`. -- **C untimed is a nullable pointer:** `const moq_timestamp *`, `NULL` for - untimed, in arguments and callback structs. No sentinel scale and no - `_present` flag; the existing `timestamp_present` pairs go. -- **Wrappers expose the record plus duration helpers** to and from the - language's duration type (`timedelta`, `Duration`, `time.Duration`, ...). - From a duration is exact at the duration's own scale. To a duration rounds - to nearest and says so in its doc; the record itself stays exact. -- **One PR across every binding**, per the cross-package sync table, so each - binding breaks once. No shim: the microsecond fields are removed, not kept - beside the record. The Impact bullet says how to migrate each package, and `doc/lib/*` - and `doc/bin/obs.md` update in the same PR. - -Verification: round-trip a 90 kHz tick, a present zero, and untimed through -moq-ffi, moq-c, C++ and every wrapper's tests; refuse scale 0, an -out-of-range scale, and an out-of-range value; `just test interop --all`. - -Decided 2026-10-25 (maintainer), reversing the 2026-10-20 decision to wait -on the generated C package: the hand-written `moq-c` ships at this cut with -parity to moq-ffi for every m1 binding feature, so the moq-c half lands -there, and the generated C line follows after the cut. - -Decided 2026-10-27 (maintainer): producer arguments keep an optional -timestamp until the cut, so producers may still write untimed frames. Reads -keep "untimed as absent" until then too. At the cut -[time addressing](/quest/m1/time-addressing/README.md) makes every track -timed, and [bindings by start](/quest/m1/time-addressing/bindings.md) drops -that `Option` from reads only. - -Wall and monotonic times stay `moq_clock::Wall` and `moq_clock::Instant`, not -media timestamps; keep the types distinct. diff --git a/quest/m1/release-audit/README.md b/quest/m1/release-audit/README.md index 040306f9d8e..d0687a8aa0a 100644 --- a/quest/m1/release-audit/README.md +++ b/quest/m1/release-audit/README.md @@ -95,6 +95,5 @@ work, because obs-moq ships on its own schedule. - [Compressed tracks](/quest/m1/compress/README.md) - application migration has an existing owner - [Measured release performance](/quest/m1/release-perf/README.md) - existing paired benchmark regressions and their confirmation runs - [Transport performance audit](/quest/m2/audit-perf.md) - congestion-control coverage remains outstanding -- [Binding timestamps](/quest/m1/binding-timestamps.md) - exact timestamps across language APIs - [Dependency audit](/quest/m2/audit-deps.md) - existing advisory inventory - [Publish and adopt](/quest/m2/release/README.md) - API/feature review, merge order, candidate checks, publication, and installed-artifact proof diff --git a/quest/m1/time-addressing/bindings.md b/quest/m1/time-addressing/bindings.md index 67efa3eef4c..e86a0684aa2 100644 --- a/quest/m1/time-addressing/bindings.md +++ b/quest/m1/time-addressing/bindings.md @@ -9,8 +9,7 @@ failover, with each `doc/lib` page and the PR's Impact section saying how to mig ## Plan Follow the cross-package sync table from `rs/moq-ffi` outward. Timestamps -already cross the bindings as `{value, scale}` -([exact timestamps](/quest/m1/binding-timestamps.md)), so a start reuses that +already cross the bindings as `{value, scale}`, so a start reuses that type. Decided 2026-10-27 (maintainer): every track is timed after the cut, so reads drop the `Option` that exact timestamps keeps for untimed. Only reads drop it here; producer arguments keep their optional timestamp. @@ -20,4 +19,3 @@ Public API: breaking in every binding. Wire: none. ## Required - [Rust groups by start](/quest/m1/time-addressing/model.md) - the API these wrap -- [Exact timestamps in every binding](/quest/m1/binding-timestamps.md) - the timestamp type a start uses diff --git a/rs/moq-ffi/src/audio.rs b/rs/moq-ffi/src/audio.rs index 1718c37db37..6267a24010d 100644 --- a/rs/moq-ffi/src/audio.rs +++ b/rs/moq-ffi/src/audio.rs @@ -364,10 +364,7 @@ impl TryFrom for moq_audio::Frame { type Error = moq_audio::Error; fn try_from(f: MoqAudioFrame) -> Result { - Ok(Self::new( - f.data.into(), - f.timestamp.try_into()?, - )) + Ok(Self::new(f.data.into(), f.timestamp.try_into()?)) } } diff --git a/rs/moq-ffi/src/bench.rs b/rs/moq-ffi/src/bench.rs index acc51712718..86e1359eff0 100644 --- a/rs/moq-ffi/src/bench.rs +++ b/rs/moq-ffi/src/bench.rs @@ -165,7 +165,9 @@ async fn ffi_round( let mut read = Vec::with_capacity(frames); for _ in 0..frames { let frame = group.read_frame().await.unwrap().expect("group ended"); - let timestamp = frame.timestamp.map(|t| moq_net::Timestamp::try_from(t).unwrap().as_micros() as u64); + let timestamp = frame + .timestamp + .map(|t| moq_net::Timestamp::try_from(t).unwrap().as_micros() as u64); read.push((frame.payload, timestamp)); } read diff --git a/rs/moq-ffi/src/media.rs b/rs/moq-ffi/src/media.rs index 452095f1a24..fb78b33ce07 100644 --- a/rs/moq-ffi/src/media.rs +++ b/rs/moq-ffi/src/media.rs @@ -6,9 +6,7 @@ use std::sync::{Arc, Weak}; use bytes::Buf; use moq_mux::catalog::hang::Extra; -use crate::consumer::{ - MoqBroadcastConsumer, MoqFetchGroupOptions, MoqGroupConsumer, MoqSubscription, map_fetch_error, -}; +use crate::consumer::{MoqBroadcastConsumer, MoqFetchGroupOptions, MoqGroupConsumer, MoqSubscription, map_fetch_error}; use crate::demand::MoqTrackDemand; use crate::error::MoqError; use crate::ffi::Task; @@ -1477,7 +1475,10 @@ mod read_tests { .await .unwrap(); let timestamp = |us| moq_net::Timestamp::from_micros(us).unwrap(); - let micros = |value| MoqTimestamp { value, scale: 1_000_000 }; + let micros = |value| MoqTimestamp { + value, + scale: 1_000_000, + }; let mut first = track.create_group(0u64.into()).unwrap(); format() .write( diff --git a/rs/moq-ffi/src/test.rs b/rs/moq-ffi/src/test.rs index b119930a8cc..843b0b651be 100644 --- a/rs/moq-ffi/src/test.rs +++ b/rs/moq-ffi/src/test.rs @@ -759,12 +759,19 @@ async fn audio_raw_publish_from_many_threads() { let frame = match read { MoqAudioRead::Frame { frame } => frame, MoqAudioRead::End { end } => { - assert_eq!(micros(end), 250_000 + 8 * 20_000, "the finish ends after the last frame"); + assert_eq!( + micros(end), + 250_000 + 8 * 20_000, + "the finish ends after the last frame" + ); continue; } MoqAudioRead::Gap { .. } => panic!("nothing was lost"), }; - assert_eq!(micros(frame.timestamp), 250_000 + pcm.len() as u64 / 2 * 1_000_000 / 48_000); + assert_eq!( + micros(frame.timestamp), + 250_000 + pcm.len() as u64 / 2 * 1_000_000 / 48_000 + ); pcm.extend(frame.data.as_chunks::<4>().0.iter().map(|s| f32::from_le_bytes(*s))); } assert_eq!(pcm.len(), 8 * 960 * 2, "finish must preserve the entire PCM duration"); @@ -1258,7 +1265,13 @@ async fn subscribe(broadcast: &MoqBroadcastProducer, name: &str) -> Arc 0); + assert!(now.value > 0); media .write_frame(MoqFrame { payload: b"opus frame".to_vec(), @@ -1667,10 +1680,7 @@ async fn json_window_cut_restates_the_window() { for event in events { assert_eq!( next_window(&consumer).await, - Some(MoqJsonWindowTimed { - event, - timestamp: None, - }) + Some(MoqJsonWindowTimed { event, timestamp: None }) ); } @@ -1751,10 +1761,7 @@ async fn json_window_refreshes_a_bounded_checkpoint_for_a_joiner() { for event in events { assert_eq!( next_window(&consumer).await, - Some(MoqJsonWindowTimed { - event, - timestamp: None, - }) + Some(MoqJsonWindowTimed { event, timestamp: None }) ); } @@ -2181,7 +2188,10 @@ async fn timestamps_are_exact() { payload: b"frame".to_vec(), timestamp: Some(invalid), }; - assert!(matches!(track.write_frame(frame), Err(MoqError::TimeOverflow)), "{invalid:?}"); + assert!( + matches!(track.write_frame(frame), Err(MoqError::TimeOverflow)), + "{invalid:?}" + ); let range = MoqRange { start: MoqAnchor::Time { timestamp: invalid }, end: None, From ce24401d1c7a656d05a4764fb4e44981cbf225ff Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 27 Oct 2026 19:13:15 -0700 Subject: [PATCH 05/12] feat(bindings)!: floor timestamp conversions, wrap Python anchors, stamp moq-c data writes - Every wrapper's Timestamp-to-duration conversion rounds down to a whole unit, matching moq-net's own conversions and the C/C++ interop clients. - Python wraps Anchor, Range, and VideoDecodedFrame so a time anchor takes and a decoded frame returns moq.Timestamp. - moq-c's JSON and binary writes take a nullable const moq_timestamp *; NULL keeps stamping the broadcast clock. - Swift's macOS 13-only duration assertion moves into the annotated test. Co-Authored-By: Claude Opus 5.5 --- dart/moq/lib/src/timestamp.dart | 5 +- dart/moq/test/moq_test.dart | 5 +- doc/lib/c/index.md | 2 +- doc/lib/dart/index.md | 2 +- doc/lib/go/index.md | 2 +- doc/lib/kt/index.md | 2 +- doc/lib/py/index.md | 2 +- doc/lib/swift/index.md | 2 +- go/wrapper/records.go | 7 +- go/wrapper/records_internal_test.go | 12 +- kt/README.md | 2 +- .../kotlin/dev/moq/Timestamp.kt | 4 +- .../kotlin/dev/moq/SmokeTest.kt | 5 +- py/moq-rs/README.md | 2 +- py/moq-rs/moq/_records.py | 110 +++++++++++++++++- py/moq-rs/moq/types.py | 15 +-- py/moq-rs/moq/video.py | 9 +- py/moq-rs/tests/test_data_timestamps.py | 5 +- py/moq-rs/tests/test_local.py | 27 ++++- rs/moq-c/c-tests/timestamps.c | 14 ++- rs/moq-c/src/api.rs | 50 ++++++-- rs/moq-c/src/publish.rs | 55 ++++++--- rs/moq-c/src/test.rs | 50 +++++++- swift/Sources/Moq/Timestamp.swift | 5 +- swift/Tests/MoqTests/SmokeTests.swift | 16 ++- 25 files changed, 318 insertions(+), 92 deletions(-) diff --git a/dart/moq/lib/src/timestamp.dart b/dart/moq/lib/src/timestamp.dart index 14a10361bb9..67dcbe62a45 100644 --- a/dart/moq/lib/src/timestamp.dart +++ b/dart/moq/lib/src/timestamp.dart @@ -4,7 +4,7 @@ final _microsPerSecond = BigInt.from(Duration.microsecondsPerSecond); /// Converts a [MoqTimestamp] to Dart's [Duration]. extension TimestampDuration on MoqTimestamp { - /// This timestamp as a [Duration], rounded to the nearest microsecond. + /// This timestamp as a [Duration], rounded down to a whole microsecond. /// /// The timestamp itself is exact; keep it, not the duration, to republish a /// tick such as 90 kHz. Throws a [RangeError] when the result does not fit @@ -12,8 +12,7 @@ extension TimestampDuration on MoqTimestamp { Duration toDuration() { // value * 10^6 can exceed 64 bits at the allowed bounds. final units = BigInt.from(scale); - final micros = - (BigInt.from(value) * _microsPerSecond + units ~/ BigInt.two) ~/ units; + final micros = BigInt.from(value) * _microsPerSecond ~/ units; if (!micros.isValidInt) { throw RangeError('timestamp $value/$scale s does not fit in a Duration'); } diff --git a/dart/moq/test/moq_test.dart b/dart/moq/test/moq_test.dart index b240de889f8..ff70f4c72a9 100644 --- a/dart/moq/test/moq_test.dart +++ b/dart/moq/test/moq_test.dart @@ -467,11 +467,12 @@ void main() { final exact = const Duration(milliseconds: 20).toTimestamp(); expect([exact.value, exact.scale], [20000, 1000000]); expect(exact.toDuration(), const Duration(milliseconds: 20)); - // 5 ticks at 90 kHz is 55.6 us: rounded to nearest, not floored. + // 5 ticks at 90 kHz is 55.6 us, and half a microsecond is 0.5: both round down. expect( Timestamp(value: 5, scale: 90000).toDuration(), - const Duration(microseconds: 56), + const Duration(microseconds: 55), ); + expect(Timestamp(value: 1, scale: 2000000).toDuration(), Duration.zero); expect( () => Timestamp(value: (1 << 61) - 1, scale: 1).toDuration(), throwsRangeError, diff --git a/doc/lib/c/index.md b/doc/lib/c/index.md index 079c62a826a..aebfb483947 100644 --- a/doc/lib/c/index.md +++ b/doc/lib/c/index.md @@ -80,7 +80,7 @@ inside. The header is the reference: each function carries a doc comment. - **Audio needs cuts.** Video groups at its keyframes, but audio forms a group only where you call `moq_publish_media_cut`: after every frame, or at a segment cadence to align with video. - **Ending cleanly.** When the input ends, finish every track, then call `moq_publish_catalog_finish()` to finish the catalog, which ends the content. The broadcast stays announced and keeps serving the finished tracks, so a subscriber still catching up can drain them, until `moq_publish_close()` takes it offline. How long to keep it up is yours to decide. A track still open at the close ends with `UNROUTABLE`, which readers take as the publisher leaving, and its handle is released. - **Timeline breaks.** On a seek or pause, call `moq_publish_media_discontinuity`, then keep timestamps moving forward and resume video on a keyframe. -- **Timestamps.** A `moq_timestamp` is exact: `value` units at `scale` units per second, so a 90 kHz tick survives a read and republish. Frames, datagrams, and JSON values point `timestamp` at theirs, NULL on an untimed track and valid as long as the payload. Tracks moq-c creates are timed, so their writes need one. A zero scale or an out-of-range value fails with `MOQ_ERROR_TIMESTAMP_OVERFLOW`. +- **Timestamps.** A `moq_timestamp` is exact: `value` units at `scale` units per second, so a 90 kHz tick survives a read and republish. Frames, datagrams, and JSON values point `timestamp` at theirs, NULL on an untimed track and valid as long as the payload. Tracks moq-c creates are timed, so their raw writes need one. JSON and binary writes take one too, converted to their track's milliseconds; NULL stamps the broadcast clock's current time. A zero scale or an out-of-range value fails with `MOQ_ERROR_TIMESTAMP_OVERFLOW`. - **JSON values.** `moq_consume_json_value` fills `moq_json_value` with the document and its frame's timestamp. A snapshot consumer's callback fires for each state in order, but a group superseded before it is read is skipped. - **Decoded reads.** `moq_decode_audio` and `moq_decode_video` deliver read ids in order: a frame, a gap where media was lost, or an end where the publisher stopped its encoder. Check `kind` on what `moq_decode_audio_read` or `moq_decode_video_read` writes. Free each id with `moq_decode_audio_read_free` or `moq_decode_video_read_free` promptly: a held video frame holds a decoder buffer, and the decoder stalls. - **Stats.** `moq_session_stats()` fills `moq_connection_stats` with `rtt_us`, `estimated_send_rate_bps`, and the byte and packet counters (`bytes_sent`, `bytes_received`, `bytes_lost`, `packets_sent`, `packets_received`, `packets_lost`). Each has a `_valid` flag, false when the transport does not report it, which is not the same as zero. `moq_session_snapshot()` adds the negotiated `protocol`. A failed dial or dropped connection reaches the session's `on_state` with its `failure` code, and `moq_error()` gives the reason during that callback. Hold the handle returned by `moq_session_recv_bandwidth()` to request receive estimates. `moq_bandwidth_consumer_peek()` reads the estimate and `moq_bandwidth_consumer_changed()` waits for a change. `moq_bandwidth_consumer_close()` releases demand; the last consumer stops PROBE. Stats snapshots do not request it. diff --git a/doc/lib/dart/index.md b/doc/lib/dart/index.md index d0d1110ee6e..de3ef1e447e 100644 --- a/doc/lib/dart/index.md +++ b/doc/lib/dart/index.md @@ -22,7 +22,7 @@ A missing data timestamp stays untimed; the library never substitutes zero or no `package:moq/json.dart` consumers return `Value` (`value`, `timestamp`) from `next()`; a snapshot consumer yields each state in order, and `latest()` skips to the newest. Media times are exact `Timestamp` records, `value` units at `scale` units per second, so a 90 kHz tick survives a -read and republish. `Duration.toTimestamp()` converts exactly; `Timestamp.toDuration()` rounds to the nearest microsecond. +read and republish. `Duration.toTimestamp()` converts exactly; `Timestamp.toDuration()` rounds down to a whole microsecond. Raw tracks with a `null` timescale are untimed on both publish and receive. `MoqTrackInfo.compress` on a raw track sends each group DEFLATE-compressed to opt-in `moq-lite-07-wip` peers; other peers, and every reader here, get the original frames. `@moq/net` cannot read a compressed track yet. Whole-frame media writes require caller time; container imports keep their own timeline handling. diff --git a/doc/lib/go/index.md b/doc/lib/go/index.md index 416f8c5da8c..da853134ca5 100644 --- a/doc/lib/go/index.md +++ b/doc/lib/go/index.md @@ -18,7 +18,7 @@ Construct `NewAudioTrackProducer` / `NewVideoTrackProducer` from a broadcast, an and a `Named` or `Requested` target. `NewCatalogProducer` holds its broadcast weakly; catalog writes fail with `ErrClosed` after the broadcast closes. Media timestamps are exact `moq.Timestamp` records (`Value` at `Scale` units per second), so a 90 kHz tick survives a read and republish; -`TimestampFromDuration` and `TimestampToDuration` convert. +`TimestampFromDuration` converts exactly; `TimestampToDuration` rounds down to a whole nanosecond. A missing data timestamp stays untimed; the library never substitutes zero or now. Raw tracks with a `nil` timescale are untimed on both publish and receive. `TrackInfo.Compress` on a raw track sends each group DEFLATE-compressed to opt-in `moq-lite-07-wip` peers; other peers, and every reader here, get the original frames. `@moq/net` cannot read a compressed track yet. diff --git a/doc/lib/kt/index.md b/doc/lib/kt/index.md index 44760db836d..8932738a785 100644 --- a/doc/lib/kt/index.md +++ b/doc/lib/kt/index.md @@ -21,7 +21,7 @@ A missing data timestamp stays untimed; the library never substitutes zero or no `dev.moq.json` consumers' `values()` emits `Value` (`value`, `timestamp`) and `valuesAs()` emits `Timed`; a snapshot consumer yields each state in order, and `latest()` skips to the newest. A `Timestamp(value, scale)` is exact and reads back at the track's timescale, so a 90 kHz tick republishes unchanged. -`Duration.toTimestamp()` is exact at nanosecond scale; `Timestamp.toDuration()` rounds to the nearest nanosecond. +`Duration.toTimestamp()` is exact at nanosecond scale; `Timestamp.toDuration()` rounds down to a whole nanosecond. Raw tracks with a `null` timescale are untimed on both publish and receive. `MoqTrackInfo.compress` on a raw track sends each group DEFLATE-compressed to opt-in `moq-lite-07-wip` peers; other peers, and every reader here, get the original frames. `@moq/net` cannot read a compressed track yet. Whole-frame media writes require caller time; container imports keep their own timeline handling. diff --git a/doc/lib/py/index.md b/doc/lib/py/index.md index 516e077aa26..2bc932f8a5a 100644 --- a/doc/lib/py/index.md +++ b/doc/lib/py/index.md @@ -23,7 +23,7 @@ broadcast and does not keep it open. `ContainerProducer` takes chunks split anyw so a raw byte stream needs no other importer. `ContainerFormat.FMP4` splits each fragment into one frame per sample. Media timestamps are exact `moq.Timestamp(value, scale)` records, so a 90 kHz tick survives a read and republish. -`Timestamp.from_timedelta` is exact; `.to_timedelta()` rounds to the nearest microsecond. +`Timestamp.from_timedelta` is exact; `.to_timedelta()` rounds down to a whole microsecond. A missing data timestamp stays untimed; the library never substitutes zero or now. JSON consumers yield `moq.json.Timed(value, timestamp)`; a snapshot consumer yields each state in order, and `await consumer.latest()` skips to the newest. A window consumer's value is a `WindowPush`, `WindowPop`, or `WindowSkip`. diff --git a/doc/lib/swift/index.md b/doc/lib/swift/index.md index e12cfc43120..97d0b0927f6 100644 --- a/doc/lib/swift/index.md +++ b/doc/lib/swift/index.md @@ -19,7 +19,7 @@ updates catalog properties and sections without keeping the broadcast open. Its writes fail after closing or releasing the broadcast. Media timestamps are exact `Timestamp` records, `value` units at `scale` units per second, carried at the track's timescale (a write at another scale rounds down to it). On macOS 13+ and iOS, `try Timestamp(duration)` converts a `Duration` exactly, -and `try timestamp.duration` rounds back to the nearest attosecond. +and `try timestamp.duration` rounds down to a whole attosecond. `Flate.SnapshotProducer` / `StreamProducer` publish opaque bytes with an optional `timestamp`. A missing data timestamp stays untimed; the library never substitutes zero or now. `Json` consumers yield `Json.Timed` (`value`, `timestamp`); a snapshot consumer yields each state in order, diff --git a/go/wrapper/records.go b/go/wrapper/records.go index e26b22f6b91..e8b64a33aaf 100644 --- a/go/wrapper/records.go +++ b/go/wrapper/records.go @@ -23,12 +23,11 @@ func TimestampFromDuration(d time.Duration) (Timestamp, error) { return Timestamp{Value: uint64(d), Scale: uint64(time.Second)}, nil } -// TimestampToDuration rounds t to the nearest nanosecond, saturating past -// time.Duration's ~292 years. It panics on a zero Scale, which no read returns. +// TimestampToDuration converts t to a time.Duration, rounded down to a whole +// nanosecond, saturating past time.Duration's ~292 years. It panics on a zero +// Scale, which no read returns. func TimestampToDuration(t Timestamp) time.Duration { hi, lo := bits.Mul64(t.Value, uint64(time.Second)) - lo, carry := bits.Add64(lo, t.Scale/2, 0) - hi += carry if hi >= t.Scale { return time.Duration(math.MaxInt64) } diff --git a/go/wrapper/records_internal_test.go b/go/wrapper/records_internal_test.go index 594f1d0f3c4..c1dc8b2e447 100644 --- a/go/wrapper/records_internal_test.go +++ b/go/wrapper/records_internal_test.go @@ -23,7 +23,7 @@ func TestTimestampFromDuration(t *testing.T) { } } -// Converting to a duration rounds to the nearest nanosecond, and a time past +// Converting to a duration rounds down to a whole nanosecond, and a time past // time.Duration's ~292 years reads as the longest duration rather than wrapping. func TestTimestampToDuration(t *testing.T) { cases := []struct { @@ -31,13 +31,11 @@ func TestTimestampToDuration(t *testing.T) { want time.Duration }{ {Timestamp{Value: 0, Scale: 90_000}, 0}, - // 11111.1 ns rounds down. + // 11111.1 ns, 666666666.6 ns, and half a nanosecond all round down. {Timestamp{Value: 1, Scale: 90_000}, 11_111}, - // 666666666.6 ns rounds up. - {Timestamp{Value: 2, Scale: 3}, 666_666_667}, - // Half a nanosecond rounds up. - {Timestamp{Value: 1, Scale: 2_000_000_000}, 1}, - {Timestamp{Value: 1001, Scale: 30_000}, 33_366_667}, + {Timestamp{Value: 2, Scale: 3}, 666_666_666}, + {Timestamp{Value: 1, Scale: 2_000_000_000}, 0}, + {Timestamp{Value: 1001, Scale: 30_000}, 33_366_666}, {Timestamp{Value: math.MaxInt64, Scale: 1_000_000_000}, math.MaxInt64}, {Timestamp{Value: math.MaxInt64/1000 + 1, Scale: 1_000_000}, math.MaxInt64}, {Timestamp{Value: 1<<61 - 1, Scale: 1}, math.MaxInt64}, diff --git a/kt/README.md b/kt/README.md index 94ff160561c..e47303adf24 100644 --- a/kt/README.md +++ b/kt/README.md @@ -58,7 +58,7 @@ The `dev.moq` package is intentionally thin: Kotlin has extension functions, so - **Flow extensions** (`Flows.kt`): `updates()`, `groups()`, and `frames()` turn the pull-based consumers into coroutine `Flow`s with cancellation wired through. - **Media** (`dev.moq.media`): catalog, importers, and container consumers, with `catalog(broadcast)` for a one-shot catalog read and `frames()` for container-decoded media. - **Fetched media**: `dev.moq.media.GroupConsumer.fetch(...).frames()` streams the decoded frames of one retained group, then completes. `dev.moq.media.GroupConsumer(group, container)` decodes a raw group instead, such as one from `recvGroup()` for arrival-order reads. -- **Timestamp conversions** (`Timestamp.kt`): media timestamps are exact `Timestamp(value, scale)` records. `Duration.toTimestamp()` builds one exactly at nanosecond scale, and `Timestamp.toDuration()` reads one back as a `kotlin.time.Duration`, rounded to the nearest nanosecond. Durations such as `stats.rtt` are already `java.time.Duration`. +- **Timestamp conversions** (`Timestamp.kt`): media timestamps are exact `Timestamp(value, scale)` records. `Duration.toTimestamp()` builds one exactly at nanosecond scale, and `Timestamp.toDuration()` reads one back as a `kotlin.time.Duration`, rounded down to a whole nanosecond. Durations such as `stats.rtt` are already `java.time.Duration`. - **`logLevel(...)`**: configures native Rust tracing without importing the raw bindings package. - **Raw datagrams**: `TrackProducer.appendDatagram(Frame(payload, timestamp))` sends one best-effort frame and returns its sequence; `TrackConsumer.recvDatagram()` and `datagrams()` receive them. Payloads are capped at 1200 bytes, require a datagram-capable transport plus lite-05 or newer moq-lite or moq-transport, and have no stream fallback. - **`MoqException.isShutdown`** (`Errors.kt`): true for the graceful `Cancelled`/`Closed` cases. diff --git a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Timestamp.kt b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Timestamp.kt index 447504abeff..e6675856781 100644 --- a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Timestamp.kt +++ b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Timestamp.kt @@ -6,7 +6,7 @@ import kotlin.time.Duration.Companion.nanoseconds import kotlin.time.Duration.Companion.seconds /** - * This timestamp as a [Duration], rounded to the nearest nanosecond. + * This timestamp as a [Duration], rounded down to a whole nanosecond. * * The [Timestamp] itself is exact; keep it, not the duration, to republish a tick such as 90 kHz. * Throws [IllegalArgumentException] past [Duration]'s range, about 146 million years. @@ -15,7 +15,7 @@ fun Timestamp.toDuration(): Duration { // The sub-second remainder times a billion can exceed 64 bits. val remainder = (value % scale).toString().toBigInteger() val divisor = scale.toString().toBigInteger() - val nanos = (remainder * BigInteger.valueOf(1_000_000_000L) + divisor.shiftRight(1)) / divisor + val nanos = remainder * BigInteger.valueOf(1_000_000_000L) / divisor val duration = (value / scale).toLong().seconds + nanos.toLong().nanoseconds // Duration saturates to infinite instead of failing. require(duration.isFinite()) { "timestamp $value/$scale s does not fit in a Duration" } diff --git a/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt b/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt index c2b314c70ce..c73fa5e9acf 100644 --- a/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt +++ b/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt @@ -435,13 +435,14 @@ class SmokeTest { } } - /** From a duration is exact at nanosecond scale; to a duration rounds to the nearest nanosecond. */ + /** From a duration is exact at nanosecond scale; to a duration rounds down to a whole nanosecond. */ @Test fun `timestamps convert to and from durations`() { assertEquals(Timestamp(20_000_000uL, 1_000_000_000uL), 20.milliseconds.toTimestamp()) assertFailsWith { (-1).nanoseconds.toTimestamp() } assertEquals(11_111.nanoseconds, Timestamp(1uL, 90_000uL).toDuration()) - assertEquals(666_666_667.nanoseconds, Timestamp(2uL, 3uL).toDuration()) + assertEquals(666_666_666.nanoseconds, Timestamp(2uL, 3uL).toDuration()) + assertEquals(0.nanoseconds, Timestamp(1uL, 2_000_000_000uL).toDuration()) // The sub-second remainder times a billion overflows 64 bits at the largest scale. assertEquals(500.milliseconds, Timestamp((1uL shl 61) - 1uL, (1uL shl 62) - 1uL).toDuration()) assertFailsWith { Timestamp((1uL shl 61) - 1uL, 1uL).toDuration() } diff --git a/py/moq-rs/README.md b/py/moq-rs/README.md index 9086f7bb308..afd93c7876b 100644 --- a/py/moq-rs/README.md +++ b/py/moq-rs/README.md @@ -261,7 +261,7 @@ Every handle whose cleanup is `cancel()` is an async context manager, so exiting ### Types - **`media.Catalog`**. `.audio: dict[str, Audio]`, `.video: dict[str, Video]`, `.display`, `.rotation`, `.flip`. -- **`Timestamp`**. `.value: int` units at `.scale: int` units per second, exact at any scale such as 90 kHz. `Timestamp.from_timedelta(duration)` is exact at microsecond scale; `.to_timedelta()` rounds to the nearest microsecond. A write with a scale of 0 or past `2**62 - 1`, or a value past `2**61 - 1`, raises `Error.TimeOverflow`. +- **`Timestamp`**. `.value: int` units at `.scale: int` units per second, exact at any scale such as 90 kHz. `Timestamp.from_timedelta(duration)` is exact at microsecond scale; `.to_timedelta()` rounds down to a whole microsecond. A write with a scale of 0 or past `2**62 - 1`, or a value past `2**61 - 1`, raises `Error.TimeOverflow`. - **`Frame`**. `.payload: bytes`, `.timestamp: Timestamp | None`. The unit of every write and every raw read; `None` means untimed when publishing or reading. - **`media.MediaFrame`**. `.payload: bytes`, `.timestamp: Timestamp`, `.keyframe: bool`. The frame variant of a media read. `keyframe` marks a group start or video keyframe; for audio it is true only at a group start. - **`Datagram`**. `.sequence: int`, `.timestamp: Timestamp | None`, `.payload: bytes`. Delivered only on datagram-capable transports with lite-05 or newer moq-lite, or moq-transport. diff --git a/py/moq-rs/moq/_records.py b/py/moq-rs/moq/_records.py index 21d7d064e4f..51e8a0ef710 100644 --- a/py/moq-rs/moq/_records.py +++ b/py/moq-rs/moq/_records.py @@ -11,10 +11,11 @@ from collections.abc import Sequence from dataclasses import dataclass from datetime import timedelta -from fractions import Fraction from importlib import metadata +from typing import ClassVar, cast from moq_ffi import ( + MoqAnchor, MoqBackoff, MoqClientTls, MoqCongestionControl, @@ -28,6 +29,9 @@ MoqSubscription, MoqTimestamp, MoqTrackInfo, + MoqVideoDecodedFrame, + MoqVideoPixelFormat, + MoqVideoSurface, MoqWebSocketConfig, ) @@ -70,8 +74,11 @@ def from_timedelta(duration: timedelta) -> Timestamp: return Timestamp(duration // _MICROSECOND, 1_000_000) def to_timedelta(self) -> timedelta: - """This timestamp rounded to the nearest microsecond, so a finer scale may lose precision.""" - return timedelta(microseconds=round(Fraction(self.value * 1_000_000, self.scale))) + """This timestamp as a ``timedelta``, rounded down to a whole microsecond. + + The timestamp itself is exact; keep it, not the ``timedelta``, to republish a tick such as 90 kHz. + """ + return timedelta(microseconds=self.value * 1_000_000 // self.scale) def _ffi(self) -> MoqTimestamp: return MoqTimestamp(value=self.value, scale=self.scale) @@ -127,6 +134,72 @@ def _from_ffi(datagram: MoqDatagram) -> Datagram: ) +class Anchor: + """Where one end of a :class:`Range` falls, mirroring moq-net's ``track::Anchor``. + + Build one with ``Anchor.ABSOLUTE(group=...)``, ``Anchor.RELATIVE(groups=...)``, or + ``Anchor.TIME(timestamp=...)``. + """ + + ABSOLUTE: ClassVar[type[_AnchorAbsolute]] + RELATIVE: ClassVar[type[_AnchorRelative]] + TIME: ClassVar[type[_AnchorTime]] + + def _ffi(self) -> MoqAnchor: + raise TypeError("build an Anchor with Anchor.ABSOLUTE, Anchor.RELATIVE, or Anchor.TIME") + + +# The generated variants subclass MoqAnchor only at runtime, so each _ffi casts for pyright. +@dataclass(frozen=True) +class _AnchorAbsolute(Anchor): + """This group, delivered from its first frame.""" + + group: int + + def _ffi(self) -> MoqAnchor: + return cast(MoqAnchor, MoqAnchor.ABSOLUTE(group=self.group)) + + +@dataclass(frozen=True) +class _AnchorRelative(Anchor): + """The group this many before the latest, clamped to group 0: ``0`` is the latest group.""" + + groups: int + + def _ffi(self) -> MoqAnchor: + return cast(MoqAnchor, MoqAnchor.RELATIVE(groups=self.groups)) + + +@dataclass(frozen=True) +class _AnchorTime(Anchor): + """The group containing this presentation time. An untimed track refuses it.""" + + timestamp: Timestamp + + def _ffi(self) -> MoqAnchor: + return cast(MoqAnchor, MoqAnchor.TIME(timestamp=self.timestamp._ffi())) + + +Anchor.ABSOLUTE = _AnchorAbsolute +Anchor.RELATIVE = _AnchorRelative +Anchor.TIME = _AnchorTime + + +@dataclass(frozen=True) +class Range: + """A span of a track to deliver, from ``start`` to ``end``, ``None`` to keep following the live edge. + + A relative or time start is the first frame of its group, and a relative or time end + includes its whole group. An absolute end is exclusive. + """ + + start: Anchor + end: Anchor | None = None + + def _ffi(self) -> MoqRange: + return MoqRange(start=self.start._ffi(), end=None if self.end is None else self.end._ffi()) + + @dataclass(frozen=True) class Subscription: """Subscriber-side delivery preferences, mirroring moq-net's ``track::Subscription``. @@ -141,14 +214,14 @@ class Subscription: priority: int = 0 max_delay: timedelta | None = timedelta(0) - ranges: Sequence[MoqRange] | None = None + ranges: Sequence[Range] | None = None order: MoqOrder | None = None def _ffi(self) -> MoqSubscription: return MoqSubscription( priority=self.priority, max_delay=self.max_delay, - ranges=None if self.ranges is None else list(self.ranges), + ranges=None if self.ranges is None else [r._ffi() for r in self.ranges], order=self.order, ) @@ -364,3 +437,30 @@ def _from_ffi(grant: MoqGrant | None) -> Grant | None: subscribe=tuple(grant.subscribe), expires=grant.expires, ) + + +class VideoDecodedFrame: + """One decoded picture. It owns the decoder's buffer until garbage collected, so drop it promptly.""" + + def __init__(self, inner: MoqVideoDecodedFrame) -> None: + self._inner = inner + + def timestamp(self) -> Timestamp: + """The presentation timestamp, at the track's timescale.""" + return Timestamp._from_ffi(self._inner.timestamp()) + + def width(self) -> int: + """The picture's width in pixels.""" + return self._inner.width() + + def height(self) -> int: + """The picture's height in pixels.""" + return self._inner.height() + + def pixels(self, format: MoqVideoPixelFormat) -> bytes: + """The picture converted to tightly packed CPU pixels in ``format``.""" + return self._inner.pixels(format) + + def surface(self) -> MoqVideoSurface | None: + """The decoder's platform surface, when the decoder output asked for one.""" + return self._inner.surface() diff --git a/py/moq-rs/moq/types.py b/py/moq-rs/moq/types.py index 7662dd30337..bec288b3578 100644 --- a/py/moq-rs/moq/types.py +++ b/py/moq-rs/moq/types.py @@ -1,11 +1,9 @@ """Re-export moq-ffi record types without the Moq prefix. -Records the wrapper gives Python defaults or timestamp conversions are owned in `_records` instead. +Records the wrapper gives Python defaults or timestamp conversions, and handles that return a +timestamp, are owned in `_records` instead. """ -from moq_ffi import ( - MoqAnchor as Anchor, -) from moq_ffi import ( MoqAnnounceRoute as AnnounceRoute, ) @@ -39,18 +37,12 @@ from moq_ffi import ( MoqProtocolKind as ProtocolKind, ) -from moq_ffi import ( - MoqRange as Range, -) from moq_ffi import ( MoqRoute as Route, ) from moq_ffi import ( MoqVideoCodec as VideoCodec, ) -from moq_ffi import ( - MoqVideoDecodedFrame as VideoDecodedFrame, -) from moq_ffi import ( MoqVideoEncoderInput as VideoEncoderInput, ) @@ -68,6 +60,7 @@ ) from ._records import ( + Anchor, Backoff, ClientTls, ConnectionStats, @@ -75,9 +68,11 @@ Frame, Grant, QuicConfig, + Range, Subscription, Timestamp, TrackInfo, + VideoDecodedFrame, WebSocketConfig, ) diff --git a/py/moq-rs/moq/video.py b/py/moq-rs/moq/video.py index 8676fd08871..b2ecbeb2871 100644 --- a/py/moq-rs/moq/video.py +++ b/py/moq-rs/moq/video.py @@ -4,7 +4,6 @@ from dataclasses import dataclass from datetime import timedelta -from typing import Union from moq_ffi import ( MoqVideoConsumer, @@ -19,22 +18,20 @@ from moq_ffi import MoqVideoFrameRate as FrameRate from ._read import End, Gap, _end, _gap -from ._records import Timestamp +from ._records import Timestamp, VideoDecodedFrame from ._stream import _Stream from .media import CatalogProducer, Dimensions, Video from .publish import TrackDemand from .session import Allocator, Reservation from .subscribe import BroadcastConsumer from .types import VideoCodec as Codec -from .types import VideoDecodedFrame from .types import VideoEncoderInput as EncoderInput from .types import VideoEncoderKind as EncoderKind from .types import VideoEncoderOutput as EncoderOutput from .types import VideoGop as Gop from .types import VideoPixelFormat as PixelFormat -# A Union rather than `|`: the generated frame class does not support `|` with other types. -Read = Union[VideoDecodedFrame, Gap, End] +Read = VideoDecodedFrame | Gap | End """One item a :class:`Consumer` reads, in delivery order: a decoded picture, or a break between them.""" @@ -174,7 +171,7 @@ async def _next(self) -> Read | None: if value is None: return None if isinstance(value, MoqVideoRead.FRAME): - return value.frame + return VideoDecodedFrame(value.frame) if isinstance(value, MoqVideoRead.GAP): return _gap(value.timestamp, value.duration) if isinstance(value, MoqVideoRead.END): diff --git a/py/moq-rs/tests/test_data_timestamps.py b/py/moq-rs/tests/test_data_timestamps.py index 05b5d7287cc..1c8554c6273 100644 --- a/py/moq-rs/tests/test_data_timestamps.py +++ b/py/moq-rs/tests/test_data_timestamps.py @@ -40,8 +40,9 @@ def test_timedelta_conversions(): assert moq.Timestamp.from_timedelta(timedelta(seconds=1, microseconds=5)) == moq.Timestamp(1_000_005, 1_000_000) with pytest.raises(ValueError): moq.Timestamp.from_timedelta(timedelta(microseconds=-1)) - # Nearest, not floored: 2/3 µs is 1 µs and 11.1 µs is 11 µs. - assert moq.Timestamp(2, 3_000_000).to_timedelta() == timedelta(microseconds=1) + # Rounded down, like moq-net: half a microsecond and 2/3 of one are both 0, and 11.1 µs is 11 µs. + assert moq.Timestamp(1, 2_000_000).to_timedelta() == timedelta(0) + assert moq.Timestamp(2, 3_000_000).to_timedelta() == timedelta(0) assert moq.Timestamp(1, 90_000).to_timedelta() == timedelta(microseconds=11) diff --git a/py/moq-rs/tests/test_local.py b/py/moq-rs/tests/test_local.py index 2a803c826ac..b445800e589 100644 --- a/py/moq-rs/tests/test_local.py +++ b/py/moq-rs/tests/test_local.py @@ -12,7 +12,7 @@ import pytest # Every group from the first, rather than only what the live edge still reaches. -FROM_GROUP_0 = [moq.Range(start=cast(moq.Anchor, moq.Anchor.ABSOLUTE(group=0)))] +FROM_GROUP_0 = [moq.Range(start=moq.Anchor.ABSOLUTE(group=0))] async def until_wanted(demand: moq.TrackDemand, wanted: bool = True) -> None: @@ -1028,7 +1028,7 @@ async def test_ascending_subscription_reads_a_cached_backlog_oldest_first(): consumer = track.consume( moq.Subscription( max_delay=timedelta(seconds=10), - ranges=[moq.Range(start=cast(moq.Anchor, moq.Anchor.RELATIVE(groups=2)))], + ranges=[moq.Range(start=moq.Anchor.RELATIVE(groups=2))], order=moq.Order.ASCENDING, ) ) @@ -1040,6 +1040,28 @@ async def test_ascending_subscription_reads_a_cached_backlog_oldest_first(): assert sequences == [0, 1, 2] +async def test_time_anchor_starts_at_the_group_containing_it(): + """A time anchor takes a wrapper Timestamp and starts at the group containing that time.""" + broadcast = moq.BroadcastProducer() + track = broadcast.publish_track("timed", moq.TrackInfo(timescale=1_000)) + for second in range(3): + group = track.append_group() + group.write_frame(b"x", moq.Timestamp(second, 1)) + group.finish() + + start = moq.Anchor.TIME(timestamp=moq.Timestamp(1_500, 1_000)) + consumer = track.consume( + moq.Subscription( + max_delay=timedelta(seconds=10), + ranges=[moq.Range(start=start)], + order=moq.Order.ASCENDING, + ) + ) + group = await asyncio.wait_for(consumer.recv_group(), timeout=5.0) + assert group is not None + assert group.sequence == 1 + + async def test_raw_group_producer_consume_direct(): """Consume a single group directly from the group producer.""" broadcast = moq.BroadcastProducer() @@ -1548,6 +1570,7 @@ async def test_decode_video_frame(): frame = await asyncio.wait_for(anext(decoder), timeout=5.0) decoder.cancel() assert isinstance(frame, moq.VideoDecodedFrame) + assert frame.timestamp().scale == 1_000_000 i420 = frame.pixels(moq.VideoPixelFormat.I420) diff --git a/rs/moq-c/c-tests/timestamps.c b/rs/moq-c/c-tests/timestamps.c index c1e28eb4e7d..fa9681c6f8e 100644 --- a/rs/moq-c/c-tests/timestamps.c +++ b/rs/moq-c/c-tests/timestamps.c @@ -91,10 +91,14 @@ int main(void) { CHECK(json > 0); const uint8_t payload[] = {1, 2, 3}; + const char *doc = "{\"n\":1}"; const moq_timestamp invalid[] = {{0, 0}, {0, 1ull << 62}, {1ull << 61, 1000000}}; - for (size_t i = 0; i < sizeof(invalid) / sizeof(invalid[0]); i++) + for (size_t i = 0; i < sizeof(invalid) / sizeof(invalid[0]); i++) { CHECK(moq_publish_track_frame((uint32_t)track, payload, sizeof(payload), &invalid[i]) == MOQ_ERROR_TIMESTAMP_OVERFLOW); + CHECK(moq_publish_json_stream_append((uint32_t)json, doc, strlen(doc), &invalid[i]) == + MOQ_ERROR_TIMESTAMP_OVERFLOW); + } CHECK(moq_publish_track_frame((uint32_t)track, payload, sizeof(payload), NULL) == MOQ_ERROR_MOQ); CHECK(moq_origin_request((uint32_t)origin, path, strlen(path), on_broadcast, &c) > 0); @@ -115,8 +119,9 @@ int main(void) { WAIT_FOR(&c, c.frame_count == 2); CHECK(moq_publish_track_datagram((uint32_t)track, payload, sizeof(payload), &tick, NULL) == 0); WAIT_FOR(&c, c.datagram); - const char *doc = "{\"n\":1}"; - CHECK(moq_publish_json_stream_append((uint32_t)json, doc, strlen(doc)) == 0); + // JSON tracks moq-c creates count milliseconds. + const moq_timestamp stamped = {1500, 1000}; + CHECK(moq_publish_json_stream_append((uint32_t)json, doc, strlen(doc), &stamped) == 0); WAIT_FOR(&c, c.value); // Each timestamp points into its own read, so both stay intact until freed. @@ -133,10 +138,9 @@ int main(void) { CHECK(same(datagram.timestamp, tick)); CHECK(moq_consume_datagram_free((uint32_t)c.datagram) == 0); - // The JSON producer stamps each value with the broadcast clock. moq_json_value value; CHECK(moq_consume_json_value((uint32_t)c.value, &value) == 0); - CHECK(value.timestamp != NULL && value.timestamp->scale != 0); + CHECK(same(value.timestamp, stamped)); CHECK(moq_consume_json_value_free((uint32_t)c.value) == 0); CHECK(moq_consume_track_cancel((uint32_t)frames) == 0); diff --git a/rs/moq-c/src/api.rs b/rs/moq-c/src/api.rs index 25d861c6312..c834ff3df58 100644 --- a/rs/moq-c/src/api.rs +++ b/rs/moq-c/src/api.rs @@ -3324,17 +3324,27 @@ pub unsafe extern "C" fn moq_publish_json_snapshot( /// Publish a new value to a JSON snapshot track. `value` is a UTF-8 JSON document. A no-op if /// unchanged from the previous update. /// +/// `timestamp` is when the value was captured, converted to the track's millisecond timescale; +/// NULL stamps the broadcast clock's current time. +/// /// Returns a zero on success, or a negative code on failure. /// /// # Safety /// - The caller must ensure `value` is a valid pointer to `value_len` bytes. +/// - `timestamp` must be NULL or a valid pointer to a [moq_timestamp]. #[unsafe(no_mangle)] -pub unsafe extern "C" fn moq_publish_json_snapshot_update(json: u32, value: *const c_char, value_len: usize) -> i32 { +pub unsafe extern "C" fn moq_publish_json_snapshot_update( + json: u32, + value: *const c_char, + value_len: usize, + timestamp: *const moq_timestamp, +) -> i32 { ffi::enter(move || { let json = ffi::parse_id(json)?; let value = unsafe { ffi::parse_slice(value.cast::(), value_len)? }; let value = serde_json::from_slice(value)?; - State::lock().publish.json_snapshot_update(json, value) + let timestamp = unsafe { ffi::parse_timestamp(timestamp)? }; + State::lock().publish.json_snapshot_update(json, value, timestamp) }) } @@ -3378,17 +3388,27 @@ pub unsafe extern "C" fn moq_publish_json_stream( /// Append one record to a JSON stream track. `value` is a UTF-8 JSON document. /// +/// `timestamp` is when the value was captured, converted to the track's millisecond timescale; +/// NULL stamps the broadcast clock's current time. +/// /// Returns a zero on success, or a negative code on failure. /// /// # Safety /// - The caller must ensure `value` is a valid pointer to `value_len` bytes. +/// - `timestamp` must be NULL or a valid pointer to a [moq_timestamp]. #[unsafe(no_mangle)] -pub unsafe extern "C" fn moq_publish_json_stream_append(stream: u32, value: *const c_char, value_len: usize) -> i32 { +pub unsafe extern "C" fn moq_publish_json_stream_append( + stream: u32, + value: *const c_char, + value_len: usize, + timestamp: *const moq_timestamp, +) -> i32 { ffi::enter(move || { let stream = ffi::parse_id(stream)?; let value = unsafe { ffi::parse_slice(value.cast::(), value_len)? }; let value = serde_json::from_slice(value)?; - State::lock().publish.json_stream_append(stream, value) + let timestamp = unsafe { ffi::parse_timestamp(timestamp)? }; + State::lock().publish.json_stream_append(stream, value, timestamp) }) } @@ -3445,20 +3465,26 @@ pub unsafe extern "C" fn moq_publish_binary_snapshot( /// Publish a new payload to a binary snapshot track, superseding the last. /// +/// `timestamp` is when the value was captured, converted to the track's millisecond timescale; +/// NULL stamps the broadcast clock's current time. +/// /// Returns a zero on success, or a negative code on failure. /// /// # Safety /// - The caller must ensure `payload` is a valid pointer to `payload_len` bytes. +/// - `timestamp` must be NULL or a valid pointer to a [moq_timestamp]. #[unsafe(no_mangle)] pub unsafe extern "C" fn moq_publish_binary_snapshot_update( binary: u32, payload: *const u8, payload_len: usize, + timestamp: *const moq_timestamp, ) -> i32 { ffi::enter(move || { let binary = ffi::parse_id(binary)?; let payload = unsafe { ffi::parse_slice(payload, payload_len)? }; - State::lock().publish.binary_snapshot_update(binary, payload) + let timestamp = unsafe { ffi::parse_timestamp(timestamp)? }; + State::lock().publish.binary_snapshot_update(binary, payload, timestamp) }) } @@ -3501,16 +3527,26 @@ pub unsafe extern "C" fn moq_publish_binary_stream( /// Append one payload to a binary stream track. /// +/// `timestamp` is when the value was captured, converted to the track's millisecond timescale; +/// NULL stamps the broadcast clock's current time. +/// /// Returns a zero on success, or a negative code on failure. /// /// # Safety /// - The caller must ensure `payload` is a valid pointer to `payload_len` bytes. +/// - `timestamp` must be NULL or a valid pointer to a [moq_timestamp]. #[unsafe(no_mangle)] -pub unsafe extern "C" fn moq_publish_binary_stream_append(stream: u32, payload: *const u8, payload_len: usize) -> i32 { +pub unsafe extern "C" fn moq_publish_binary_stream_append( + stream: u32, + payload: *const u8, + payload_len: usize, + timestamp: *const moq_timestamp, +) -> i32 { ffi::enter(move || { let stream = ffi::parse_id(stream)?; let payload = unsafe { ffi::parse_slice(payload, payload_len)? }; - State::lock().publish.binary_stream_append(stream, payload) + let timestamp = unsafe { ffi::parse_timestamp(timestamp)? }; + State::lock().publish.binary_stream_append(stream, payload, timestamp) }) } diff --git a/rs/moq-c/src/publish.rs b/rs/moq-c/src/publish.rs index e90d3db2352..489b623b739 100644 --- a/rs/moq-c/src/publish.rs +++ b/rs/moq-c/src/publish.rs @@ -260,8 +260,8 @@ impl std::ops::DerefMut for Kept { } } -// Legacy C data methods stamp writes on one fixed broadcast clock without retaining -// another catalog handle after a failed stream retires its listing. +// C data methods stamp a write the caller left unstamped on one fixed broadcast clock, +// without retaining another catalog handle after a failed stream retires its listing. struct Data { producer: T, clock: moq_mux::Clock, @@ -1214,10 +1214,15 @@ impl Publish { } /// Publish a new value to a JSON snapshot track. A no-op if unchanged. - pub fn json_snapshot_update(&mut self, json: Id, value: serde_json::Value) -> Result<(), Error> { + pub fn json_snapshot_update( + &mut self, + json: Id, + value: serde_json::Value, + timestamp: Option, + ) -> Result<(), Error> { let json = &mut self.json_snapshot.get_mut(json).ok_or(Error::TrackNotFound)?.data; - json.producer - .update(moq_net::Timed::from(&value).at(json.clock.now()))?; + let at = timestamp.unwrap_or_else(|| json.clock.now()); + json.producer.update(moq_net::Timed::from(&value).at(at))?; Ok(()) } @@ -1243,11 +1248,15 @@ impl Publish { } /// Append one record to a JSON stream track. - pub fn json_stream_append(&mut self, stream: Id, value: serde_json::Value) -> Result<(), Error> { + pub fn json_stream_append( + &mut self, + stream: Id, + value: serde_json::Value, + timestamp: Option, + ) -> Result<(), Error> { let producer = self.json_stream.get_mut(stream).ok_or(Error::TrackNotFound)?; - producer - .producer - .append(moq_net::Timed::from(&value).at(producer.clock.now()))?; + let at = timestamp.unwrap_or_else(|| producer.clock.now()); + producer.producer.append(moq_net::Timed::from(&value).at(at))?; Ok(()) } @@ -1270,11 +1279,17 @@ impl Publish { } /// Publish a new payload to a binary snapshot track, superseding the last. - pub fn binary_snapshot_update(&mut self, binary: Id, payload: &[u8]) -> Result<(), Error> { + pub fn binary_snapshot_update( + &mut self, + binary: Id, + payload: &[u8], + timestamp: Option, + ) -> Result<(), Error> { let producer = self.binary_snapshot.get_mut(binary).ok_or(Error::TrackNotFound)?; + let at = timestamp.unwrap_or_else(|| producer.clock.now()); producer .producer - .update(moq_net::Timed::from(bytes::Bytes::copy_from_slice(payload)).at(producer.clock.now()))?; + .update(moq_net::Timed::from(bytes::Bytes::copy_from_slice(payload)).at(at))?; Ok(()) } @@ -1297,11 +1312,17 @@ impl Publish { } /// Append one payload to a binary stream track. - pub fn binary_stream_append(&mut self, stream: Id, payload: &[u8]) -> Result<(), Error> { + pub fn binary_stream_append( + &mut self, + stream: Id, + payload: &[u8], + timestamp: Option, + ) -> Result<(), Error> { let producer = self.binary_stream.get_mut(stream).ok_or(Error::TrackNotFound)?; + let at = timestamp.unwrap_or_else(|| producer.clock.now()); producer .producer - .append(moq_net::Timed::from(bytes::Bytes::copy_from_slice(payload)).at(producer.clock.now()))?; + .append(moq_net::Timed::from(bytes::Bytes::copy_from_slice(payload)).at(at))?; Ok(()) } @@ -1497,19 +1518,19 @@ mod children_tests { } let json = serde_json::Value::Null; assert!(matches!( - state.publish.json_snapshot_update(json_snapshot, json.clone()), + state.publish.json_snapshot_update(json_snapshot, json.clone(), None), Err(Error::TrackNotFound) )); assert!(matches!( - state.publish.json_stream_append(json_stream, json), + state.publish.json_stream_append(json_stream, json, None), Err(Error::TrackNotFound) )); assert!(matches!( - state.publish.binary_snapshot_update(binary_snapshot, b"late"), + state.publish.binary_snapshot_update(binary_snapshot, b"late", None), Err(Error::TrackNotFound) )); assert!(matches!( - state.publish.binary_stream_append(binary_stream, b"late"), + state.publish.binary_stream_append(binary_stream, b"late", None), Err(Error::TrackNotFound) )); } diff --git a/rs/moq-c/src/test.rs b/rs/moq-c/src/test.rs index 1bb7bdc0a77..42e5ccd4590 100644 --- a/rs/moq-c/src/test.rs +++ b/rs/moq-c/src/test.rs @@ -2334,7 +2334,14 @@ fn json_snapshot_publish_consume() { let mut last = 0; for expected in [r#"{"a":1}"#, r#"{"a":2}"#] { assert_eq!( - unsafe { moq_publish_json_snapshot_update(producer, expected.as_ptr() as *const c_char, expected.len()) }, + unsafe { + moq_publish_json_snapshot_update( + producer, + expected.as_ptr() as *const c_char, + expected.len(), + std::ptr::null(), + ) + }, 0 ); let value_id = id(value_cb.recv()); @@ -2403,7 +2410,14 @@ fn json_stream_publish_consume() { let mut last = 0; for expected in [r#"{"n":0}"#, r#"{"n":1}"#, r#"{"n":2}"#] { assert_eq!( - unsafe { moq_publish_json_stream_append(producer, expected.as_ptr() as *const c_char, expected.len()) }, + unsafe { + moq_publish_json_stream_append( + producer, + expected.as_ptr() as *const c_char, + expected.len(), + std::ptr::null(), + ) + }, 0 ); let value_id = id(value_cb.recv()); @@ -2425,6 +2439,27 @@ fn json_stream_publish_consume() { assert_eq!(moq_consume_json_value_free(value_id), 0); } + // A caller's timestamp replaces the clock's, floored to the track's millisecond scale. + let expected = r#"{"n":3}"#; + let at = moq_timestamp { + value: (last + 1_000) * 90 + 45, + scale: 90_000, + }; + assert_eq!( + unsafe { moq_publish_json_stream_append(producer, expected.as_ptr() as *const c_char, expected.len(), &at) }, + 0 + ); + let value_id = id(value_cb.recv()); + let mut value = moq_json_value { + json: std::ptr::null(), + json_len: 0, + timestamp: std::ptr::null(), + }; + assert_eq!(unsafe { moq_consume_json_value(value_id, &mut value) }, 0); + let read = read_timestamp(value.timestamp).expect("a stamped value is timed"); + assert_eq!((read.value, read.scale), (last + 1_000, 1_000)); + assert_eq!(moq_consume_json_value_free(value_id), 0); + assert_eq!(moq_consume_json_cancel(consumer), 0); assert_eq!(value_cb.recv_terminal(), 0, "clean close delivers terminal 0"); assert!(moq_consume_json_cancel(consumer) < 0, "double-close should fail"); @@ -6544,7 +6579,7 @@ fn binary_snapshot_is_advertised_and_delivered() { // The payload reaches a raw subscriber of the same track name, untouched. let payload = [0xff_u8, 0xd8, 0xff, 0xe0, 1, 2, 3]; assert_eq!( - unsafe { moq_publish_binary_snapshot_update(producer, payload.as_ptr(), payload.len()) }, + unsafe { moq_publish_binary_snapshot_update(producer, payload.as_ptr(), payload.len(), std::ptr::null()) }, 0 ); let consume = request_broadcast(origin, path); @@ -6589,11 +6624,18 @@ fn binary_stream_is_advertised_and_delivered() { assert_eq!(entry.mode, hang::catalog::Mode::Stream); assert_eq!(entry.mime, None); + // A timestamp past the bounds is refused before anything is appended. + let invalid = moq_timestamp { value: 1, scale: 0 }; + assert_eq!( + unsafe { moq_publish_binary_stream_append(producer, b"bad".as_ptr(), 3, &invalid) }, + MOQ_ERROR_TIMESTAMP_OVERFLOW + ); + // Every appended payload is delivered, in order. let payloads: [&[u8]; 2] = [b"first", b"second"]; for payload in payloads { assert_eq!( - unsafe { moq_publish_binary_stream_append(producer, payload.as_ptr(), payload.len()) }, + unsafe { moq_publish_binary_stream_append(producer, payload.as_ptr(), payload.len(), std::ptr::null()) }, 0 ); } diff --git a/swift/Sources/Moq/Timestamp.swift b/swift/Sources/Moq/Timestamp.swift index ec70c0728ac..c5be8733cf4 100644 --- a/swift/Sources/Moq/Timestamp.swift +++ b/swift/Sources/Moq/Timestamp.swift @@ -34,7 +34,7 @@ extension Timestamp { throw MoqError.TimeOverflow } - /// This timestamp as a `Duration`, rounded to the nearest attosecond. + /// This timestamp as a `Duration`, rounded down to a whole attosecond. /// /// Exact when `scale` divides 10^18, such as microseconds or nanoseconds; a 90 kHz tick rounds, /// so keep the record itself to republish a read exactly. Throws `MoqError.TimeOverflow` for a @@ -44,8 +44,7 @@ extension Timestamp { guard scale != 0, scale <= maxScale, value <= maxValue else { throw MoqError.TimeOverflow } let (seconds, remainder) = value.quotientAndRemainder(dividingBy: scale) // `remainder` is below `scale`, so the quotient is below 10^18 and fits. - var (attoseconds, rest) = scale.dividingFullWidth(remainder.multipliedFullWidth(by: attosecondsPerSecond)) - if rest >= scale - rest { attoseconds += 1 } + let (attoseconds, _) = scale.dividingFullWidth(remainder.multipliedFullWidth(by: attosecondsPerSecond)) return Duration(secondsComponent: Int64(seconds), attosecondsComponent: Int64(attoseconds)) } } diff --git a/swift/Tests/MoqTests/SmokeTests.swift b/swift/Tests/MoqTests/SmokeTests.swift index a6193e91755..8f3ad9d3e34 100644 --- a/swift/Tests/MoqTests/SmokeTests.swift +++ b/swift/Tests/MoqTests/SmokeTests.swift @@ -545,7 +545,6 @@ final class SmokeTests: XCTestCase { Timestamp(value: 1 << 61, scale: 90_000), ] { assertTimeOverflow(try track.writeFrame(Data("frame".utf8), timestamp: invalid)) - assertTimeOverflow(try invalid.duration) } try track.finish() @@ -565,13 +564,24 @@ final class SmokeTests: XCTestCase { // Three seconds of attoseconds passes 2^61, and the attosecond doesn't survive a coarser scale. assertTimeOverflow(try Timestamp(.seconds(3) + Duration(secondsComponent: 0, attosecondsComponent: 1))) - // Back to the nearest attosecond: a 90 kHz tick is 11_111_111_111_111.1 as, and 2/3 s rounds up. + // Back down to a whole attosecond: a 90 kHz tick is 11_111_111_111_111.1 as, 2/3 s ends in + // ...6.6 as, and half an attosecond is 0. let tick = Duration(secondsComponent: 0, attosecondsComponent: 11_111_111_111_111) XCTAssertEqual(try Timestamp(value: 1, scale: 90_000).duration, tick) - let twoThirds = Duration(secondsComponent: 0, attosecondsComponent: 666_666_666_666_666_667) + let twoThirds = Duration(secondsComponent: 0, attosecondsComponent: 666_666_666_666_666_666) XCTAssertEqual(try Timestamp(value: 2, scale: 3).duration, twoThirds) + XCTAssertEqual(try Timestamp(value: 1, scale: 2 * atto).duration, .zero) XCTAssertEqual(try micros(1_500_000).duration, .milliseconds(1_500)) XCTAssertEqual(try Timestamp(.seconds(3_600)).duration, .seconds(3_600)) + + // A record outside what a write accepts is refused rather than converted. + for invalid in [ + Timestamp(value: 0, scale: 0), + Timestamp(value: 0, scale: 1 << 62), + Timestamp(value: 1 << 61, scale: 90_000), + ] { + assertTimeOverflow(try invalid.duration) + } } func testReadFrameSkipsEmptyThenPopulatedGroups() async throws { From 047432d3dfe758cc45603b3b73a670fae98a6809 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 27 Oct 2026 19:29:23 -0700 Subject: [PATCH 06/12] test(kt): the largest-scale conversion floors to just under half a second Co-Authored-By: Claude Opus 5.5 --- kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt b/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt index c73fa5e9acf..67df6f339ac 100644 --- a/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt +++ b/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt @@ -443,8 +443,9 @@ class SmokeTest { assertEquals(11_111.nanoseconds, Timestamp(1uL, 90_000uL).toDuration()) assertEquals(666_666_666.nanoseconds, Timestamp(2uL, 3uL).toDuration()) assertEquals(0.nanoseconds, Timestamp(1uL, 2_000_000_000uL).toDuration()) - // The sub-second remainder times a billion overflows 64 bits at the largest scale. - assertEquals(500.milliseconds, Timestamp((1uL shl 61) - 1uL, (1uL shl 62) - 1uL).toDuration()) + // The sub-second remainder times a billion overflows 64 bits at the largest scale, and the + // result is just under half a second. + assertEquals(499_999_999.nanoseconds, Timestamp((1uL shl 61) - 1uL, (1uL shl 62) - 1uL).toDuration()) assertFailsWith { Timestamp((1uL shl 61) - 1uL, 1uL).toDuration() } assertNull(AudioEncoderOutput(codec = AudioCodec.opus()).frameDuration) } From bf641ddb34034a3146dcae4d5e9da6763d4bcbab Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 29 Oct 2026 09:11:12 -0700 Subject: [PATCH 07/12] fix(go): TimestampToDuration panics on a zero scale instead of saturating Co-Authored-By: Claude Opus 5.5 --- go/wrapper/records.go | 3 +++ go/wrapper/records_internal_test.go | 11 +++++++++++ 2 files changed, 14 insertions(+) diff --git a/go/wrapper/records.go b/go/wrapper/records.go index e8b64a33aaf..789dadc9f73 100644 --- a/go/wrapper/records.go +++ b/go/wrapper/records.go @@ -27,6 +27,9 @@ func TimestampFromDuration(d time.Duration) (Timestamp, error) { // nanosecond, saturating past time.Duration's ~292 years. It panics on a zero // Scale, which no read returns. func TimestampToDuration(t Timestamp) time.Duration { + if t.Scale == 0 { + panic("moq: timestamp with a zero scale") + } hi, lo := bits.Mul64(t.Value, uint64(time.Second)) if hi >= t.Scale { return time.Duration(math.MaxInt64) diff --git a/go/wrapper/records_internal_test.go b/go/wrapper/records_internal_test.go index c1dc8b2e447..d1170fdadfd 100644 --- a/go/wrapper/records_internal_test.go +++ b/go/wrapper/records_internal_test.go @@ -47,3 +47,14 @@ func TestTimestampToDuration(t *testing.T) { } } } + +// A zero scale, such as an unset Timestamp{}, panics rather than reading as the +// longest duration. +func TestTimestampToDurationZeroScale(t *testing.T) { + defer func() { + if recover() == nil { + t.Fatal("TimestampToDuration(Timestamp{}) did not panic") + } + }() + TimestampToDuration(Timestamp{}) +} From f7b33c6e74c1645f3ed35cd46fa93fc97f4320ca Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 29 Oct 2026 11:10:34 -0700 Subject: [PATCH 08/12] style(c): format merged video timestamp assertions Co-Authored-By: GPT-6.1 Sol --- rs/moq-c/src/video.rs | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) diff --git a/rs/moq-c/src/video.rs b/rs/moq-c/src/video.rs index e0a498e8c2a..fe8a719e732 100644 --- a/rs/moq-c/src/video.rs +++ b/rs/moq-c/src/video.rs @@ -1341,7 +1341,14 @@ mod tests { follow_grant(&shared).unwrap(); let before = shared.lock().as_ref().unwrap().reservation.clone().unwrap(); let small = vec![0x80; 320 * 240 * 4]; - assert!(!shared.lock().as_mut().unwrap().publish_frame(moq_net::Timestamp::ZERO, &small).unwrap()); + assert!( + !shared + .lock() + .as_mut() + .unwrap() + .publish_frame(moq_net::Timestamp::ZERO, &small) + .unwrap() + ); // Disabled, then resumed onto the larger picture. { @@ -1354,7 +1361,12 @@ mod tests { .unwrap(); } let large = vec![0x80; 640 * 480 * 4]; - let moved = shared.lock().as_mut().unwrap().publish_frame(moq_net::Timestamp::from_micros(66_666).unwrap(), &large).unwrap(); + let moved = shared + .lock() + .as_mut() + .unwrap() + .publish_frame(moq_net::Timestamp::from_micros(66_666).unwrap(), &large) + .unwrap(); assert!(moved, "the larger picture is a new codec string"); follow_grant(&shared).unwrap(); let guard = shared.lock(); From f0f03da387d36512214c64ad069d8ce0b273d9c8 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 31 Oct 2026 03:00:05 -0700 Subject: [PATCH 09/12] fix(bindings): exact timestamps on main's insert_datagram and parity table Python's insert_datagram takes a Timestamp like append_datagram, and the wasm parity inventory drops its microseconds-only row now that moq-ffi carries exact {value, scale} timestamps. Co-Authored-By: Claude Opus 5.5 --- py/moq-rs/moq/publish.py | 2 +- test/wasm/README.md | 1 - 2 files changed, 1 insertion(+), 2 deletions(-) diff --git a/py/moq-rs/moq/publish.py b/py/moq-rs/moq/publish.py index 346ccf9c8a4..bb48b38ae2a 100644 --- a/py/moq-rs/moq/publish.py +++ b/py/moq-rs/moq/publish.py @@ -130,7 +130,7 @@ def append_datagram(self, payload: bytes, timestamp: Timestamp | None = None) -> """ return self._inner.append_datagram(Frame(payload, timestamp)._ffi()) - def insert_datagram(self, sequence: int, payload: bytes, timestamp: timedelta | None = None) -> None: + def insert_datagram(self, sequence: int, payload: bytes, timestamp: Timestamp | None = None) -> None: """Send a best-effort datagram at an explicit sequence number. For a caller that allocates its own sequences; :meth:`append_datagram` diff --git a/test/wasm/README.md b/test/wasm/README.md index 28eb2d44d0d..7112fe7caba 100644 --- a/test/wasm/README.md +++ b/test/wasm/README.md @@ -203,7 +203,6 @@ Still missing or partial, by what the consumer does: | frame `arrived` time | hang | `MoqFrame` carries no arrival time | | `group.tryReadFrame()` | hang | async `read_frame` only | | `abort(err: Error)` on a track or group | hang | `abort(code)` only | -| `Time.Timestamp` in a track's timescale | hang, publish | microseconds only | | `Group.MAX_GROUP_CACHE_BYTES` and `_FRAMES` | json | not exported | Arrival times need the Rust and JS clocks to agree on origin and units first. Tokens and From 6080b71c0770ae9dd94e253e25f5e58e9a17d246 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sun, 1 Nov 2026 15:39:53 -0800 Subject: [PATCH 10/12] kt: ktfmt the merged timestamp tests Co-Authored-By: Claude Opus 5.5 --- .../kotlin/dev/moq/SmokeTest.kt | 24 +++++++++++++++---- kt/moq/src/jvmTest/kotlin/dev/moq/FfiBench.kt | 3 ++- 2 files changed, 21 insertions(+), 6 deletions(-) diff --git a/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt b/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt index 8cd1b16fce6..c82ead5ca1a 100644 --- a/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt +++ b/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt @@ -274,7 +274,12 @@ class SmokeTest { BroadcastProducer().use { broadcast -> val track = broadcast.publishTrack("events", TrackInfo(timescale = 1_000_000uL)) val group = track.appendGroup() - group.writeFrame(Frame(payload = "cached".encodeToByteArray(), timestamp = Timestamp(0uL, 1_000_000uL))) + group.writeFrame( + Frame( + payload = "cached".encodeToByteArray(), + timestamp = Timestamp(0uL, 1_000_000uL), + ) + ) group.finish() val fetched = @@ -380,7 +385,10 @@ class SmokeTest { val (name, audio) = catalog(consumer).audio.entries.single() media.writeFrame( - Frame(payload = "opus frame".encodeToByteArray(), timestamp = 5.seconds.toTimestamp()) + Frame( + payload = "opus frame".encodeToByteArray(), + timestamp = 5.seconds.toTimestamp(), + ) ) // Fetch while the track is still published: finishing the media producer @@ -479,7 +487,9 @@ class SmokeTest { 499_999_999.nanoseconds, Timestamp((1uL shl 61) - 1uL, (1uL shl 62) - 1uL).toDuration(), ) - assertFailsWith { Timestamp((1uL shl 61) - 1uL, 1uL).toDuration() } + assertFailsWith { + Timestamp((1uL shl 61) - 1uL, 1uL).toDuration() + } assertNull(AudioEncoderOutput(codec = AudioCodec.opus()).frameDuration) } @@ -1016,7 +1026,9 @@ class SmokeTest { val rgba = ByteArray(320 * 240 * 4) { 0x80.toByte() } video.cut() for (i in 0 until 10) { - video.write(VideoFrame(timestamp = Timestamp(i.toULong(), 30uL), data = rgba)) + video.write( + VideoFrame(timestamp = Timestamp(i.toULong(), 30uL), data = rgba) + ) } val consumer = origin.consume().request("video-decode-frame") @@ -1028,7 +1040,9 @@ class SmokeTest { // Keep the encoder fed so the decoder sees frames after it joined. for (i in 10 until 40) { - video.write(VideoFrame(timestamp = Timestamp(i.toULong(), 30uL), data = rgba)) + video.write( + VideoFrame(timestamp = Timestamp(i.toULong(), 30uL), data = rgba) + ) } assertIs(decoder.next()).frame.use { frame -> diff --git a/kt/moq/src/jvmTest/kotlin/dev/moq/FfiBench.kt b/kt/moq/src/jvmTest/kotlin/dev/moq/FfiBench.kt index 093a041c198..1fa325f5e59 100644 --- a/kt/moq/src/jvmTest/kotlin/dev/moq/FfiBench.kt +++ b/kt/moq/src/jvmTest/kotlin/dev/moq/FfiBench.kt @@ -120,7 +120,8 @@ class FfiBench { group.writeFrame( Frame( payload = payload, - timestamp = Timestamp((n * case.frames + f).toULong(), 1_000_000uL), + timestamp = + Timestamp((n * case.frames + f).toULong(), 1_000_000uL), ) ) } From 751ecea80ae62921050a21dc1d0afc822f3a7dd1 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sun, 1 Nov 2026 15:40:21 -0800 Subject: [PATCH 11/12] swift: swift-format the merged timestamp tests Co-Authored-By: Claude Opus 5.5 --- swift/Tests/MoqTests/FfiBench.swift | 8 ++++++-- swift/Tests/MoqTests/SmokeTests.swift | 7 +++++-- 2 files changed, 11 insertions(+), 4 deletions(-) diff --git a/swift/Tests/MoqTests/FfiBench.swift b/swift/Tests/MoqTests/FfiBench.swift index f6509a658bb..205c02660a4 100644 --- a/swift/Tests/MoqTests/FfiBench.swift +++ b/swift/Tests/MoqTests/FfiBench.swift @@ -89,13 +89,17 @@ final class FfiBench: XCTestCase { let received = try await group.readFrame() let frame = try XCTUnwrap(received, "group ended") XCTAssertEqual(frame.payload, payload) - XCTAssertEqual(frame.timestamp, Timestamp(value: UInt64(n * c.frames + f), scale: 1_000_000)) + XCTAssertEqual( + frame.timestamp, Timestamp(value: UInt64(n * c.frames + f), scale: 1_000_000)) } } } for track in tracks { let group = try track.appendGroup() - for f in 0.. Timestamp { } /// Assert `body` throws `MoqError.TimeOverflow`. -private func assertTimeOverflow(_ body: @autoclosure () throws -> T, file: StaticString = #filePath, line: UInt = #line) { +private func assertTimeOverflow( + _ body: @autoclosure () throws -> T, file: StaticString = #filePath, line: UInt = #line +) { XCTAssertThrowsError(try body(), file: file, line: line) { error in guard case MoqError.TimeOverflow = error else { return XCTFail("expected TimeOverflow, got \(error)", file: file, line: line) @@ -466,7 +468,8 @@ final class SmokeTests: XCTestCase { for n in 0..<3 { let event = try await consumer.next() XCTAssertEqual( - event, Json.Timed(value: .push(index: UInt64(n), value: Event(n: n)), timestamp: micros(UInt64(n) * 1000))) + event, + Json.Timed(value: .push(index: UInt64(n), value: Event(n: n)), timestamp: micros(UInt64(n) * 1000))) } let pop = try await consumer.next() XCTAssertEqual(pop, Json.Timed(value: .pop(0..<2), timestamp: micros(3000))) From 17ce02ad803b7ded56c01707249c927574ad5956 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sun, 1 Nov 2026 16:13:15 -0800 Subject: [PATCH 12/12] fix(bindings): restore Go InsertDatagram build, drop stale py import, test exact datagram ticks The earlier mechanical merge left Go's InsertDatagram calling the removed Frame.ffi() (Frame is now ffi.MoqFrame) and an unused timedelta import in moq.video. timestamps_are_exact now also inserts a 90 kHz datagram and reads the tick back exactly, and uses the ambient clock timeout. Co-Authored-By: Claude Opus 5.5 --- go/wrapper/publish.go | 6 +----- py/moq-rs/moq/video.py | 1 - rs/moq-ffi/src/test.rs | 24 +++++++++++++++++++++++- 3 files changed, 24 insertions(+), 7 deletions(-) diff --git a/go/wrapper/publish.go b/go/wrapper/publish.go index e2180d90c7f..aa808095ccc 100644 --- a/go/wrapper/publish.go +++ b/go/wrapper/publish.go @@ -218,11 +218,7 @@ func (t *TrackProducer) AppendDatagram(frame Frame) (uint64, error) { // InsertDatagram sends frame as a best-effort datagram at an explicit sequence, for a // caller that allocates its own. AppendDatagram continues after the largest one. func (t *TrackProducer) InsertDatagram(sequence uint64, frame Frame) error { - f, err := frame.ffi() - if err != nil { - return err - } - return t.inner.InsertDatagram(sequence, f) + return t.inner.InsertDatagram(sequence, frame) } // Largest reports the newest group or datagram written, at its newest frame, or nil diff --git a/py/moq-rs/moq/video.py b/py/moq-rs/moq/video.py index e0156beb522..2c7c8ad88cd 100644 --- a/py/moq-rs/moq/video.py +++ b/py/moq-rs/moq/video.py @@ -3,7 +3,6 @@ from __future__ import annotations from dataclasses import dataclass -from datetime import timedelta from moq_ffi import ( MoqVideoConsumer, diff --git a/rs/moq-ffi/src/test.rs b/rs/moq-ffi/src/test.rs index bdb76176547..419ca4cd434 100644 --- a/rs/moq-ffi/src/test.rs +++ b/rs/moq-ffi/src/test.rs @@ -2175,7 +2175,7 @@ async fn timestamps_are_exact() { timestamp: Some(timestamp), }) .unwrap(); - let frame = tokio::time::timeout(TIMEOUT, consumer.read_frame()) + let frame = kio::clock::timeout(TIMEOUT, consumer.read_frame()) .await .unwrap() .unwrap() @@ -2183,6 +2183,28 @@ async fn timestamps_are_exact() { assert_eq!(frame.timestamp, Some(timestamp)); } + // An inserted datagram keeps the exact tick too. + let tick = MoqTimestamp { + value: 1, + scale: 90_000, + }; + track + .insert_datagram( + 7, + MoqFrame { + payload: b"datagram".to_vec(), + timestamp: Some(tick), + }, + ) + .unwrap(); + let datagram = kio::clock::timeout(TIMEOUT, consumer.recv_datagram()) + .await + .unwrap() + .unwrap() + .unwrap(); + assert_eq!(datagram.sequence, 7); + assert_eq!(datagram.timestamp, Some(tick)); + for invalid in [ MoqTimestamp { value: 0, scale: 0 }, MoqTimestamp {