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
18 changes: 1 addition & 17 deletions dart/moq_ffi/lib/src/moq.dart
Original file line number Diff line number Diff line change
Expand Up @@ -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";

Expand Down Expand Up @@ -2304,7 +2302,6 @@ class MoqVideo {
final int preference;
final double? framerate;
final MoqContainer container;
final Duration? warmup;
MoqVideo({
this.label = null,
this.broadcast = null,
Expand All @@ -2319,7 +2316,6 @@ class MoqVideo {
this.preference = 0,
this.framerate,
required this.container,
this.warmup = null,
});
}

Expand Down Expand Up @@ -2395,11 +2391,6 @@ class FfiConverterMoqVideo {
);
final container = container_lifted.value;
new_offset += container_lifted.bytesRead;
final warmup_lifted = FfiConverterOptionalDuration.read(
Uint8List.view(buf.buffer, new_offset),
);
final warmup = warmup_lifted.value;
new_offset += warmup_lifted.bytesRead;
return LiftRetVal(
MoqVideo(
label: label,
Expand All @@ -2415,7 +2406,6 @@ class FfiConverterMoqVideo {
preference: preference,
framerate: framerate,
container: container,
warmup: warmup,
),
new_offset - buf.offsetInBytes,
);
Expand All @@ -2436,7 +2426,6 @@ class FfiConverterMoqVideo {
FfiConverterInt32.allocationSize(value.preference) +
FfiConverterOptionalDouble64.allocationSize(value.framerate) +
FfiConverterMoqContainer.allocationSize(value.container) +
FfiConverterOptionalDuration.allocationSize(value.warmup) +
0;
final buf = Uint8List(total_length);
write(value, buf);
Expand Down Expand Up @@ -2497,10 +2486,6 @@ class FfiConverterMoqVideo {
value.container,
Uint8List.view(buf.buffer, new_offset),
);
new_offset += FfiConverterOptionalDuration.write(
value.warmup,
Uint8List.view(buf.buffer, new_offset),
);
return new_offset - buf.offsetInBytes;
}

Expand All @@ -2518,7 +2503,6 @@ class FfiConverterMoqVideo {
FfiConverterInt32.allocationSize(value.preference) +
FfiConverterOptionalDouble64.allocationSize(value.framerate) +
FfiConverterMoqContainer.allocationSize(value.container) +
FfiConverterOptionalDuration.allocationSize(value.warmup) +
0;
}
}
Expand Down Expand Up @@ -25898,7 +25882,7 @@ void _checkApiChecksums() {
throw UniffiInternalError.panicked("UniFFI API checksum mismatch");
}
if (uniffi_moq_ffi_checksum_constructor_moqmediatrackconsumer_subscribe() !=
16252) {
25805) {
throw UniffiInternalError.panicked("UniFFI API checksum mismatch");
}
if (uniffi_moq_ffi_checksum_constructor_moqmediatrackproducer_audio() !=
Expand Down
2 changes: 1 addition & 1 deletion doc/concept/hang.md
Original file line number Diff line number Diff line change
Expand Up @@ -74,7 +74,7 @@ A few things the catalog can express beyond decoder config:
- **Preference.** A video rendition may carry a signed `preference`, default `0`. A player keeps only the highest preference it can decode, then picks by size and bitrate within it, as do the single-rendition egresses (RTMP play, WHEP, FLV, the transcoder's source). A publisher that adds its own H.264 copy of an H.265 source marks the copy `-1`, so only a viewer that can't decode H.265 pulls it. Picking a rendition by name still overrides it. The field is written only when nonzero.
- **Join interval.** The root `media.join.interval` promises that every audio and video track starts a group at least that often: the longest GOP any of them publishes. It is fixed for the broadcast, and the [HLS gateway](/bin/hls) numbers every rendition's segments on the grid it fixes, segments the smallest whole multiple of it at least a second long, from each group's first timestamp, so renditions share segment numbers. A publisher that knows its GOP declares it; Rust publishers (`moq-mux` and everything built on it) without one measure each track over its first second or group, whichever is longer, and `@moq/publish` declares its encoders' `join`. A broadcast without it gets no HLS playlists.
- **Clock.** The optional `media.clock` maps PTS zero to wall time so every media track shares one fixed epoch after timescale conversion. Publish independent sources as sibling broadcasts under one prefix, such as `robot/front.hang` and `robot/rear.hang`; each broadcast's audio and video entries are renditions of that source. In one Rust publisher, pass the same `moq_mux::Clock` to each `catalog::Config::with_clock`; JS publishers on one page already share the page clock. Consumers discover the siblings by prefix and align their timestamps through the advertised wall mapping; `@moq/watch` plays one broadcast at a time.
- **Version.** The root `version` is the oldest moq-hang draft that reads the catalog correctly, written only when a field needs one newer than 03: a `track` that differs from its ID, or a video `warmup`. Readers ignore fields they don't know, but refuse a `version` above their own with a typed "unsupported catalog version" error, so a player can say to upgrade instead of misreading the catalog. An additive field never raises it.
- **Version.** The root `version` is the oldest moq-hang draft that reads the catalog correctly, written only when a field needs one newer than 03: a `track` that differs from its ID. Readers ignore fields they don't know, but refuse a `version` above their own with a typed "unsupported catalog version" error, so a player can say to upgrade instead of misreading the catalog. An additive field never raises it.
- **Extensions.** The root is a loose object. Applications add their own sections (`scte35`, for example) next to the ones hang defines, optionally naming a track that carries the data. Every library exposes a way to write your section without clobbering the built-in ones, and readers ignore what they don't know.

## Media reports
Expand Down
2 changes: 1 addition & 1 deletion doc/lib/c/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,7 @@ same frame/gap/end tags as decoded audio and video. Release every kind with
`moq_consume_read_free`; frame payload pointers borrow that handle. A gap breaks
continuity. An encoder end is not callback EOF: frames before its endpoint are the old
encoder's drain, and the first at or past it starts fresh. Callback 0 ends the stream.
These consumers include the rendition's catalog `warmup` in both the history fetched at
These consumers include an audio rendition's catalog `warmup` in both the history fetched at
join and the subscription budget. Feed that history to your decoder before presenting
output; the requested max delay still controls steady-state skips.

Expand Down
9 changes: 0 additions & 9 deletions doc/lib/js/watch.md
Original file line number Diff line number Diff line change
Expand Up @@ -63,15 +63,6 @@ The failing track closes its subscription and stops decoding. Select another
source or rendition to clear the failure; the player does not resubscribe to
broken media automatically.

A video rendition encoded with intra refresh has no keyframes, and its catalog
`warmup` says how long a decoder takes to clean up after joining. The player
joins such a rendition that much earlier and decodes from the group start, but
shows nothing until the warmup has passed, after a join and after each skip.
An H.264 group opens on a recovery point that is not an IDR, which Chromium's
WebCodecs refuses unless it counts zero frames, so the player inserts one that
does before the first slice. Firefox and Safari are untested, and Chromium
refuses an H.265 group that opens without an IDR.

`el.broadcast.out.status` is `connecting`, `offline`, `loading`, `live`, `error`, or `unsupported`.
It reads `connecting` until a session could have announced the broadcast: while the
connection dials, redials, or was refused (`el.connection.error` says why), and until the
Expand Down
2 changes: 1 addition & 1 deletion doc/lib/rs/hang.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ hang is the format, not the pipeline. [`moq-mux`](/lib/rs/moq-mux) produces the
catalog for you and decodes any container in group order
(`moq_mux::container::Consumer`). Its `Delay { min, max }` says how far behind
the live edge to play: it skips groups that fall past `max`, and starts at the
group covering the live edge less `min` (your playout delay), plus a rendition's
group covering the live edge less `min` (your playout delay), plus an audio rendition's
catalog `warmup` passed to a `Playout`, waiting up to that long for it when the
newest group arrives first. Both default to zero, which starts at the newest
group at once. A backlog that landed before the first read starts within `max`
Expand Down
39 changes: 15 additions & 24 deletions drafts/draft-lcurley-moq-hang.md
Original file line number Diff line number Diff line change
Expand Up @@ -183,12 +183,9 @@ A consumer MUST refuse a catalog whose `version` is above the draft it implement

A publisher writes the highest draft whose fields the catalog uses that an older consumer would misread, and omits `version` while that is 3.
A change raises the version only when a consumer that ignored it would misread the catalog, never for a field it can safely ignore.
This draft needs `version` 4 for:
This draft needs `version` 4 only for a `track` ({{field-track}}) other than the entry's ID, which an older consumer subscribes to instead.

- a `track` ({{field-track}}) other than the entry's ID, which an older consumer subscribes to instead;
- a video `warmup` ({{field-warmup}}) above zero, since an older consumer starts decoding a group at a picture that is not a keyframe.

Every other catalog change in this draft is safe to ignore: `enabled` ({{field-enabled}}) leaves an older consumer selecting a disabled rendition, which plays nothing; `media` ({{media}}) only offers the clock and join interval, which an older consumer goes without; `stats` and `echo` ({{media-stats}}) only offer optional tracks; `include` ({{include}}) only offers broadcasts to open on selection; video `reorder` leaves an older consumer inferring decode times from timestamps; `jitter`, `delay`, audio `warmup`, and the data track estimates are hints.
Every other catalog change in this draft is safe to ignore: `enabled` ({{field-enabled}}) leaves an older consumer selecting a disabled rendition, which plays nothing; `media` ({{media}}) only offers the clock and join interval, which an older consumer goes without; `stats` and `echo` ({{media-stats}}) only offer optional tracks; `include` ({{include}}) only offers broadcasts to open on selection; video `reorder` leaves an older consumer inferring decode times from timestamps; `jitter`, `delay`, audio `warmup` ({{field-warmup}}), and the data track estimates are hints.

## Media {#media}
The catalog's root `media` field holds what applies to every audio and video track:
Expand Down Expand Up @@ -479,6 +476,7 @@ In addition to the WebCodecs fields, each rendition MAY carry the common renditi
~~~
type AudioDecoderConfigExtensions = {
"layout": string | undefined,
"warmup": number | undefined,
}
~~~

Expand All @@ -489,6 +487,14 @@ type AudioDecoderConfigExtensions = {

An Opus frame timestamp counts the samples the OpusHead pre-skip trims: a consumer presents each decoded sample the pre-skip, at 48 kHz, earlier than its frame timestamp places it, so the first sample kept plays at the first decoded frame's timestamp.

### warmup {#field-warmup}

An audio rendition MAY declare `warmup`, an integer duration in milliseconds after a group start before its decoded output is presentable without decoding the previous group: the decoder's pre-roll, for example 80 milliseconds for Opus.
A publisher MUST round a fractional-millisecond warmup up to the next whole millisecond.
Absent or `0` means every group start is immediately presentable.
After a non-continuous join, a consumer MUST decode from the group start and MUST NOT present samples stamped before the group's start plus `warmup`.
It SHOULD join `warmup` earlier to obtain the requested presentation time.

### PCM {#audio-pcm}

Hang defines the `"pcm"` audio codec for uncompressed samples.
Expand Down Expand Up @@ -800,19 +806,6 @@ For example:
- A B-frame stream contributes its reorder delay, the presentation timestamp minus the decode timestamp.
- A fragment or packet batch contributes the media span between its earliest and latest timestamps.

### warmup {#field-warmup}

An audio or video rendition MAY declare `warmup`, an integer duration in milliseconds after a group start before its decoded output is presentable without decoding the previous group.
A publisher MUST round a fractional-millisecond warmup up to the next whole millisecond.
Absent or `0` means every group start is immediately presentable.
After a non-continuous join, a consumer MUST decode from the group start.
It SHOULD join `warmup` earlier to obtain the requested presentation time.
Unless it also decodes from an earlier group start, it MUST NOT present frames stamped before the group's start plus `warmup`.
A consumer that does MAY present those frames, which can show decoding artifacts, but MUST switch to the earlier decoder's frames once that decoder reaches the presented timestamp.

For video, `warmup` can describe a refresh cycle during which decoding converges without an initial keyframe.
For audio, it describes decoder pre-roll, for example 80 milliseconds for Opus, and does not change the group-start rule.

### delay {#field-delay}
The maximum amount, in milliseconds, by which a frame's presentation timestamp has trailed one that another rendition of the broadcast had already written.
If absent, a consumer SHOULD assume the rendition does not trail the others.
Expand Down Expand Up @@ -923,11 +916,9 @@ The `kind` field selects the framing; a consumer MUST ignore a rendition whose `
A container without a string `kind`, or with a recognized `kind` missing its fields, makes the rendition malformed ({{malformed}}).
Every container shares the same group rules:

A video group MUST start at a random access point: a keyframe unless the rendition declares `warmup` ({{field-warmup}}), in which case it MAY start at a picture from which decoding converges within that duration.
Other groups MUST start with a keyframe.
A group containing only a discontinuity marker is exempt from these rules.
Each group MUST start with a keyframe, except a group that contains only a discontinuity marker.
If the codec does not support delta frames (e.g. audio), a group MAY consist of multiple keyframes.
Otherwise, a group MUST consist of its random access picture followed by zero or more delta frames.
Otherwise, a group MUST consist of a single keyframe followed by zero or more delta frames.

A group with no decodable frames is a walk-now discontinuity: one empty codec payload and no media.
An empty payload is data on a data track, so in every container a data track's marker is one object with no bytes, which is no frame; it ends at the furthest point the consumer has read.
Expand Down Expand Up @@ -1123,7 +1114,7 @@ This document has no IANA actions.
- Replaced the root `archive` section and its per-track timelines with the root `media` section ({{media}}). Its `join.interval` is the longest group of any audio or video track, fixed for the broadcast, and the grid an edge numbers HLS and DASH segments on, each segment the smallest whole multiple of it at least a second long, from each group's first timestamp ({{hls}}); the root `clock` moved to `media.clock`. Segment indexes, frame positions, `end`, `keyframe`, `timescale`, `replay`, `replayEpoch`, `store`, and `version` are gone.
- A reader refuses a JSON frame in which an object repeats a member name.
- A malformed audio or video rendition ({{malformed}}) refuses the catalog: a known codec string without valid parameters, a zero or out-of-range dimension, sample rate, or channel count, a bitrate or duration above 2^53 - 1, or a container without a string `kind`.
- 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.
- 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 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.
Expand All @@ -1140,7 +1131,7 @@ This document has no IANA actions.
- Specified MSF text metadata preservation and refusal of unrepresentable text packaging during gateway conversion.
- Specified conversion between relative broadcast references and MSF track namespaces without changing track identity, reading a namespace aligned with the catalog path's trailing segments as the catalog itself.

- Added optional audio and video `warmup` durations, rounded up to whole milliseconds, and allowed video groups to start at convergent random access pictures. A consumer also decoding from an earlier group start may present frames before `warmup`, switching to that decoder once it reaches the presented timestamp.
- Added the optional audio `warmup` ({{field-warmup}}): the decoder pre-roll after a group start, rounded up to whole milliseconds, that a consumer decodes but does not present after a join.
- Defined `jitter` from media timestamps alone, the reorder delay and batch spans a publisher writes, replacing fixed frame-duration hints and wall-clock flush lateness.
- Timed CMAF samples from the frame timestamp, which is the fragment's earliest presentation time; `tfdt` is only relative within the fragment, and places the samples of an untimed frame. A timed CMAF track counts in its `mdhd` ticks.
- Replaced the live-edge floor with monotonic group starts: a group may overlap the previous group's content but not start before it.
Expand Down
13 changes: 3 additions & 10 deletions go/wrapper/internal/bridge/handles.go
Original file line number Diff line number Diff line change
Expand Up @@ -62,13 +62,11 @@ func NonNegative(value *time.Duration, name string) error {
return nil
}

// Rendition refuses a rendition's negative jitter or warmup, for the same reason.
// Rendition refuses an audio rendition's negative jitter or warmup, for the same reason. A video
// rendition carries no duration.
func Rendition(rendition ffi.MoqRendition) error {
switch rendition := rendition.(type) {
case ffi.MoqRenditionAudio:
if rendition, ok := rendition.(ffi.MoqRenditionAudio); ok {
return Audio(rendition.Config)
case ffi.MoqRenditionVideo:
return Video(rendition.Config)
}
return nil
}
Expand All @@ -80,8 +78,3 @@ func Audio(audio ffi.MoqAudio) error {
}
return NonNegative(audio.Warmup, "warmup")
}

// Video refuses a video rendition's negative warmup.
func Video(video ffi.MoqVideo) error {
return NonNegative(video.Warmup, "warmup")
}
10 changes: 3 additions & 7 deletions go/wrapper/media/media_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -62,13 +62,9 @@ func TestRefusesNegativeDurations(t *testing.T) {
if _, err := (&moq.BroadcastConsumer{}).Resolve(ctx, rendition); err == nil {
t.Fatal("a negative jitter was resolved, want an error")
}
for _, warmup := range []media.Rendition{
media.AudioRendition("audio", media.Audio{Warmup: &negative}),
media.VideoRendition("video", media.Video{Warmup: &negative}),
} {
if _, err := media.NewTrackConsumer(ctx, nil, media.TrackConfig{Rendition: warmup}); err == nil {
t.Fatal("a negative warmup was subscribed, want an error")
}
warmup := media.AudioRendition("audio", media.Audio{Warmup: &negative})
if _, err := media.NewTrackConsumer(ctx, nil, media.TrackConfig{Rendition: warmup}); err == nil {
t.Fatal("a negative warmup was subscribed, want an error")
}
}

Expand Down
3 changes: 0 additions & 3 deletions go/wrapper/video/video.go
Original file line number Diff line number Diff line change
Expand Up @@ -163,9 +163,6 @@ type Consumer struct{ inner *ffi.MoqVideoConsumer }

// Subscribe subscribes to the catalog rendition id, following its broadcast and track.
func Subscribe(ctx context.Context, broadcast *moq.BroadcastConsumer, id string, rendition media.Video, output DecoderOutput) (*Consumer, error) {
if err := bridge.Video(rendition); err != nil {
return nil, err
}
out, err := output.ffi()
if err != nil {
return nil, err
Expand Down
17 changes: 0 additions & 17 deletions go/wrapper/video/video_internal_test.go

This file was deleted.

Loading