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

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 3 additions & 2 deletions drafts/draft-lcurley-moq-hang.md
Original file line number Diff line number Diff line change
Expand Up @@ -875,7 +875,7 @@ type PublisherRendition = {
type ViewerRendition = {
frames?: number, bytes?: number, decoded?: number, late?: number,
errors?: number, stalls?: number, stalled?: number, underruns?: number,
arrival?: { timestamp: number, wall: number }, latency?: number,
arrival?: { timestamp: number, wall: number },
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
}
type Transport = {
rtt?: number, rate?: number, lostBytes?: number, lostPackets?: number, age?: number,
Expand All @@ -896,7 +896,7 @@ An empty rendition entry is valid and represents zero cumulative counters; its I
Publisher `keyframes` counts sent keyframes; `skipped` counts frames skipped before sending.
Viewer `decoded`, `late`, and `errors` count decoded frames, frames too late for playout, and decode errors.
`stalls` counts playout stalls, `stalled` is cumulative stalled duration, and `underruns` counts audio buffer underruns.
`bitrate` is the latest target encoder bitrate, `latency` the latest playout latency, and `arrival` pairs the newest received media timestamp with its arrival wall time.
`bitrate` is the latest target encoder bitrate, and `arrival` pairs the newest received media timestamp with its arrival wall time.
Durations and media timestamps are milliseconds; `arrival.wall` is milliseconds since the MoQ epoch (2020-01-01T00:00:00Z).
Sub-millisecond durations and timestamps are floored when encoded.
Rates are bits per second.
Expand Down Expand Up @@ -1126,6 +1126,7 @@ This document has no IANA actions.
- Added the root `version` ({{catalog-version}}): the oldest draft that reads the catalog, which a consumer refuses when above its own. A `track` other than the entry's ID or a video `warmup` needs 4. Consumers MUST ignore unknown fields.
- A data track marks a discontinuity with a group of one object with no bytes, since its empty payload is data. An object with no bytes on an audio or video track, or sharing its group, is malformed.
- Removed the Recording section: the store layout is a moq-archive format, documented with that crate, not part of this draft.
- Removed the viewer feedback `latency` field.
- Added the optional video `preference` field: a consumer selects automatically among the highest preference it can decode.
- Added the optional video `reorder` field: the most frames that can precede one in decode order and follow it in presentation, fixed for the track once declared. A consumer that authors decode times derives them from it and the current group alone, refusing deeper reordering; without it, a consumer infers them from timestamps.
- Added an optional `instance` beside every rendition and data track `broadcast` reference ({{field-instance}}). A consumer reads each referenced path from the first broadcast it resolves for a catalog instance; a present `instance` fails a rendition that resolves another stream, and is best effort against an Instance a receiver minted.
Expand Down
2 changes: 0 additions & 2 deletions js/hang/api/index.api.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,6 @@ export namespace Echo {
errors: ZodMiniOptional<$ZodBranded<ZodMiniNumber<number>, "u53", "out">>;
frames: ZodMiniOptional<$ZodBranded<ZodMiniNumber<number>, "u53", "out">>;
late: ZodMiniOptional<$ZodBranded<ZodMiniNumber<number>, "u53", "out">>;
latency: ZodMiniOptional<ZodMiniPipe<ZodMiniNullable<$ZodBranded<ZodMiniNumber<number>, "u53", "out">>, ZodMiniTransform<number & $brand<"u53"> | undefined, number & $brand<"u53"> | null>>>;
stalled: ZodMiniOptional<$ZodBranded<ZodMiniNumber<number>, "u53", "out">>;
stalls: ZodMiniOptional<$ZodBranded<ZodMiniNumber<number>, "u53", "out">>;
underruns: ZodMiniOptional<$ZodBranded<ZodMiniNumber<number>, "u53", "out">>;
Expand All @@ -62,7 +61,6 @@ export namespace Echo {
errors?: number & $brand<"u53"> | undefined;
frames?: number & $brand<"u53"> | undefined;
late?: number & $brand<"u53"> | undefined;
latency?: number & $brand<"u53"> | undefined;
stalled?: number & $brand<"u53"> | undefined;
stalls?: number & $brand<"u53"> | undefined;
underruns?: number & $brand<"u53"> | undefined;
Expand Down
3 changes: 0 additions & 3 deletions js/hang/src/echo.ts
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,6 @@ import type { Path } from "@moq/net";
import * as z from "zod/mini";
import { u53Schema } from "./catalog/integers";
import { renditions } from "./catalog/section";
import { measurementSchema } from "./snapshot";
import { TransportSchema } from "./stats";

/** The newest received media timestamp paired with its arrival wall time. */
Expand Down Expand Up @@ -46,8 +45,6 @@ export const RenditionSchema = z.object({
z.transform((value) => value ?? undefined),
),
),
// Latest playout latency in milliseconds; absent when unavailable.
latency: measurementSchema,
});
/** One rendition's delivery counters and latest playout measurements. */
export type Rendition = z.infer<typeof RenditionSchema>;
Expand Down
5 changes: 1 addition & 4 deletions js/hang/src/stats.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -25,13 +25,11 @@ test("missing rendition counters mean zero while parsing preserves omission", ()
expect(stats.renditions?.reset.frames ?? 0).toBe(0);
expect(echo.renditions?.reset.stalled ?? 0).toBe(0);
expect(stats.renditions?.reset.bitrate).toBeUndefined();
expect(echo.renditions?.reset.latency).toBeUndefined();
expect(stats.transport).toBeUndefined();
expect(Object.hasOwn(stats, "transport")).toBe(false);
expect(Object.hasOwn(stats.renditions?.reset ?? {}, "frames")).toBe(false);
expect(Object.hasOwn(stats.renditions?.reset ?? {}, "bitrate")).toBe(false);
expect(Object.hasOwn(echo.renditions?.reset ?? {}, "arrival")).toBe(false);
expect(Object.hasOwn(echo.renditions?.reset ?? {}, "latency")).toBe(false);
expect(Stats.SnapshotSchema.parse({})).toEqual({});
expect(Echo.SnapshotSchema.parse({})).toEqual({});
});
Expand All @@ -57,7 +55,7 @@ test("optional null measurements mean unavailable rather than measured zero", ()
),
),
).toEqual({ transport: {}, renditions: { hd: {} } });
expect(JSON.parse(JSON.stringify(Echo.RenditionSchema.parse({ latency: null, arrival: null })))).toEqual({});
expect(JSON.parse(JSON.stringify(Echo.RenditionSchema.parse({ arrival: null })))).toEqual({});
});

test("unknown track fields are ignored and flattened snapshot extensions survive", () => {
Expand All @@ -77,7 +75,6 @@ test("shared invalid counters refuse instead of rounding", async () => {
for (const value of cases) expect(() => Stats.RenditionSchema.parse(value)).toThrow();
for (const value of [
{ stalled: -1 },
{ latency: 0.5 },
{ arrival: { timestamp: Number.MAX_SAFE_INTEGER + 1, wall: 0 } },
{ arrival: { timestamp: 0, wall: -1 } },
{ arrival: {} },
Expand Down
1 change: 0 additions & 1 deletion quest/m2/api-shape/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -61,6 +61,5 @@ Rejected in planning:

- [moq-net's small surface fixes](/quest/m2/api-shape/net.md) - one spelling per session, admission, compression, proxy, and priority surface, and no public wire codes
- [Transports take shared types](/quest/m2/api-shape/transport.md) - moq-uring takes a congestion factory and rustls configs, and the tokio server request stops exposing its QUIC internals
- [Media crates' small surface fixes](/quest/m2/api-shape/media.md) - exporters, the container consumer, catalog color range, rate grant, moq-stats, JSON, and MSF each have one path and one name
- [JS Key.sign takes exactly Claims](/quest/m2/api-shape/auth-sign.md) - `@moq/auth` signs only `Claims`, with no legacy `put`/`get` input, like Rust
- [Bindings' small surface fixes](/quest/m2/api-shape/bindings.md) - Go's read cancel, JSON producer construction, and the Python wheel's test module
46 changes: 0 additions & 46 deletions quest/m2/api-shape/media.md

This file was deleted.

2 changes: 1 addition & 1 deletion quest/m3/export-live-start.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,4 +18,4 @@ and so every recording also starts up to 2 s before it was started
(`rs/moq-studio/src/record.rs`). Only TS export reports stats today; fMP4 and
MP4 report no sample counts, which the recorder needs to say what it wrote.

Changed 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests): [api-shape/media](/quest/m2/api-shape/media.md) gives fMP4, MP4, MKV, and FLV a `moq_net::Delay { min, max }` before the cut, so splitting the start from the skip budget is an implementation fix, not a break.
Changed 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests): [moq-dev/moq#8298](https://github.com/moq-dev/moq/pull/8298) gives fMP4, MP4, MKV, and FLV a `moq_net::Delay { min, max }` before the cut, so splitting the start from the skip budget is an implementation fix, not a break.
2 changes: 1 addition & 1 deletion quest/m4/aac-sbr-config.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,4 +12,4 @@ Decided 2026-10-30 (maintainer, follow-up planning after the /quest-afk run). Ad

Public API: an additive field on `moq_mux::codec::aac::Config`. Wire: none.

Changed 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests): [api-shape/media](/quest/m2/api-shape/media.md) makes `aac::Config` `#[non_exhaustive]` before the cut, so the new field is additive.
Changed 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests): [moq-dev/moq#8298](https://github.com/moq-dev/moq/pull/8298) makes `aac::Config` `#[non_exhaustive]` before the cut, so the new field is additive.
2 changes: 1 addition & 1 deletion quest/m5/json-value-diff.md
Original file line number Diff line number Diff line change
Expand Up @@ -54,7 +54,7 @@ Context:
- `moq_json::diff<T>` has no in-repo callers since #7400. With a `Value` diff
it could take `&Value`, or be removed.

Changed 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests): `moq_json::{diff, Diff}` become private before the cut ([api-shape/media](/quest/m2/api-shape/media.md)), so this work is internal.
Changed 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests): `moq_json::{diff, Diff}` become private before the cut ([moq-dev/moq#8298](https://github.com/moq-dev/moq/pull/8298)), so this work is internal.

## Related

Expand Down
2 changes: 1 addition & 1 deletion quest/m5/latency-ledger.md
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,7 @@ probes, which was the right trade to get it running. This quest promotes them.
so the sum-to-end-to-end identity (with its named `unaccounted`
remainder) can be added once a spanning clock exists.

Changed 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests): hang echo's producer-less `latency` is deleted before the cut ([api-shape/media](/quest/m2/api-shape/media.md)), so this adds its measurement additively.
Changed 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests): hang echo's producer-less `latency` is deleted before the cut ([moq-dev/moq#8298](https://github.com/moq-dev/moq/pull/8298)), so this adds its measurement additively.

## Required

Expand Down
3 changes: 1 addition & 2 deletions rs/hang/fixtures/echo-snapshot.json
Original file line number Diff line number Diff line change
Expand Up @@ -19,8 +19,7 @@
"arrival": {
"timestamp": 30000,
"wall": 175184640000
},
"latency": 200
}
},
"reset": {}
}
Expand Down
3 changes: 1 addition & 2 deletions rs/hang/fixtures/echo-zero.json
Original file line number Diff line number Diff line change
Expand Up @@ -12,8 +12,7 @@
"arrival": {
"timestamp": 0,
"wall": 0
},
"latency": 0
}
}
}
}
16 changes: 6 additions & 10 deletions rs/hang/src/catalog/clock.rs
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,6 @@ use serde::{Deserialize, Deserializer, Serialize};

use crate::Result;

/// The moq epoch (2020-01-01T00:00:00Z) in Unix-epoch milliseconds.
pub const MOQ_EPOCH_UNIX_MILLIS: u64 = 1_577_836_800_000;

/// The largest integer JSON preserves exactly (2^53 - 1).
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
pub const MAX_SAFE_INTEGER: u64 = 9_007_199_254_740_991;

Expand Down Expand Up @@ -38,7 +35,7 @@ struct Wire {
/// The broadcast's one continuous clock, advertised at the catalog root.
///
/// [`wall`](Self::wall) is the wall-clock time of PTS zero since the moq epoch
/// ([`MOQ_EPOCH_UNIX_MILLIS`], 2020-01-01). Its embedded timescale is serialized beside it as
/// ([`Wall::MOQ_EPOCH`](kio::clock::Wall::MOQ_EPOCH), 2020-01-01). Its embedded timescale is serialized beside it as
/// `{ wall, timescale }`, preserving the catalog wire shape while keeping the pair inseparable in
/// Rust. Every media track and every HLS record refer to this mapping after timescale conversion.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
Expand Down Expand Up @@ -90,9 +87,8 @@ impl Clock {
let nanos = (num % den).checked_mul(1_000_000_000).ok_or_else(overflow)? / den;
let since_moq_epoch = std::time::Duration::new(secs, nanos as u32);
// A catalog can name a wall beyond the clock's nanosecond range.
kio::clock::Wall::UNIX_EPOCH
.checked_add(std::time::Duration::from_millis(MOQ_EPOCH_UNIX_MILLIS))
.and_then(|moq_epoch| moq_epoch.checked_add(since_moq_epoch))
kio::clock::Wall::MOQ_EPOCH
.checked_add(since_moq_epoch)
.ok_or_else(overflow)
}
}
Expand Down Expand Up @@ -187,13 +183,13 @@ mod test {
#[test]
fn wall_clock_converts_across_timescales() {
let clock = Clock::new(moq_net::Timestamp::from_micros(1_000_000).unwrap()).unwrap();
let epoch = kio::clock::Wall::UNIX_EPOCH + std::time::Duration::from_millis(MOQ_EPOCH_UNIX_MILLIS + 1_000);
let epoch = kio::clock::Wall::MOQ_EPOCH + std::time::Duration::from_millis(1_000);
assert_eq!(
clock.wall_clock(moq_net::Timestamp::from_millis(0).unwrap()).unwrap(),
epoch
);

let second = kio::clock::Wall::UNIX_EPOCH + std::time::Duration::from_millis(MOQ_EPOCH_UNIX_MILLIS + 2_000);
let second = kio::clock::Wall::MOQ_EPOCH + std::time::Duration::from_millis(2_000);
assert_eq!(
clock
.wall_clock(moq_net::Timestamp::from_millis(1000).unwrap())
Expand All @@ -217,7 +213,7 @@ mod test {
/// Regression: the result was floored to the millisecond, dropping the sub-millisecond part.
#[test]
fn wall_clock_keeps_sub_millisecond_precision() {
let moq_epoch = kio::clock::Wall::UNIX_EPOCH + std::time::Duration::from_millis(MOQ_EPOCH_UNIX_MILLIS);
let moq_epoch = kio::clock::Wall::MOQ_EPOCH;
let micros = |v| moq_net::Timestamp::from_micros(v).unwrap();
let nanos = std::time::Duration::from_nanos;

Expand Down
3 changes: 1 addition & 2 deletions rs/hang/src/catalog/root.rs
Original file line number Diff line number Diff line change
Expand Up @@ -1230,8 +1230,7 @@ mod test {
assert_eq!(catalog.media.interval(), Some(std::time::Duration::from_secs(2)));

// PTS 2000 ms lands 2s after the wall epoch, whatever the track timescale.
let expected = kio::clock::Wall::UNIX_EPOCH
+ std::time::Duration::from_millis(crate::catalog::MOQ_EPOCH_UNIX_MILLIS + 1_751_846_402_000);
let expected = kio::clock::Wall::MOQ_EPOCH + std::time::Duration::from_millis(1_751_846_402_000);
assert_eq!(
clock
.wall_clock(moq_net::Timestamp::from_millis(2000).unwrap())
Expand Down
6 changes: 3 additions & 3 deletions rs/hang/src/catalog/video/color.rs
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ pub struct Color {
pub matrix: Option<u8>,

/// The numeric range of the samples.
pub range: Option<Range>,
pub range: Option<ColorRange>,

/// The display the content was mastered on, as SMPTE ST 2086.
pub mastering: Option<Mastering>,
Expand All @@ -34,7 +34,7 @@ pub struct Color {
/// The numeric range of the samples, as H.273's `VideoFullRangeFlag`.
#[derive(Serialize, Deserialize, Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[serde(rename_all = "lowercase")]
pub enum Range {
pub enum ColorRange {
/// Studio swing: 8-bit luma spans 16..235 and chroma 16..240.
Limited,
/// Full swing: every 8-bit code is used.
Expand Down Expand Up @@ -88,7 +88,7 @@ mod test {
primaries: Some(9),
transfer: Some(16),
matrix: Some(9),
range: Some(Range::Limited),
range: Some(ColorRange::Limited),
mastering: Some(Mastering {
red: Chromaticity { x: 0.708, y: 0.292 },
green: Chromaticity { x: 0.17, y: 0.797 },
Expand Down
4 changes: 0 additions & 4 deletions rs/hang/src/echo.rs
Original file line number Diff line number Diff line change
Expand Up @@ -61,10 +61,6 @@ pub struct Rendition {
/// The newest media timestamp received and its arrival wall time.
#[serde(skip_serializing_if = "Option::is_none")]
pub arrival: Option<Arrival>,
/// Latest playout latency.
#[serde_as(as = "Option<Millis>")]
#[serde(skip_serializing_if = "Option::is_none")]
pub latency: Option<Duration>,
}

/// The newest received media timestamp paired with its arrival wall time.
Expand Down
Loading
Loading