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
2 changes: 1 addition & 1 deletion cpp/moq/bench/main.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -196,7 +196,7 @@ int main()
} while (seconds(start) < budget);
results.push_back({std::string("call/") + name, "ns", seconds(start) * 1e9 / calls});
};
call("sequence", [&] { group->sequence(); });
call("start", [&] { group->start(); });
call("info", [&] { (void)consumer->info(); });
std::filesystem::create_directories(out);
std::ofstream file(std::filesystem::path(out) / "cpp.json");
Expand Down
2 changes: 1 addition & 1 deletion dart/moq/bench/ffi.dart
Original file line number Diff line number Diff line change
Expand Up @@ -175,7 +175,7 @@ Future<void> main() async {
});
}

call('sequence', group.sequence);
call('start', group.start);
call('info', consumer.info);
consumer.dispose();
group.dispose();
Expand Down
2 changes: 1 addition & 1 deletion dart/moq/lib/media.dart
Original file line number Diff line number Diff line change
Expand Up @@ -105,7 +105,7 @@ typedef AudioRendition = AudioMoqRendition;
/// A catalog rendition and live delivery options.
typedef TrackConfig = MoqMediaTrackConfig;

/// A catalog rendition's group sequence and fetch delivery options.
/// A catalog rendition's group start and fetch delivery options.
typedef GroupConfig = MoqMediaGroupConfig;

/// The packaging advertised for a media track.
Expand Down
6 changes: 3 additions & 3 deletions dart/moq/lib/src/aliases.dart
Original file line number Diff line number Diff line change
Expand Up @@ -136,7 +136,7 @@ typedef TrackRequests = MoqTrackRequests;
/// A watch-only handle to whether a published track has subscribers; holding it keeps nothing open.
typedef TrackDemand = MoqTrackDemand;

/// The read side of a raw track: yields groups in sequence order, skipping ahead if it falls behind.
/// The read side of a raw track: yields groups in start order, skipping ahead if it falls behind.
typedef TrackConsumer = MoqTrackConsumer;

/// A run of groups readers miss: accept each group you have and drop the rest.
Expand Down Expand Up @@ -211,10 +211,10 @@ typedef Anchor = MoqAnchor;
/// Which pending group the publisher sends first.
typedef Order = MoqOrder;

/// A location within a track: a group sequence and a frame index in it.
/// A location within a track: a group start and a frame index in it.
typedef Position = MoqPosition;

/// Options for fetching one past group by sequence.
/// Options for fetching one past group by start.
typedef FetchGroupOptions = MoqFetchGroupOptions;

/// How a track's frames are compressed on the wire: `Compression.deflate()`, or null in
Expand Down
6 changes: 3 additions & 3 deletions dart/moq/test/moq_test.dart
Original file line number Diff line number Diff line change
Expand Up @@ -264,12 +264,12 @@ void main() {
order: Order.ascending,
),
);
final sequences = <int>[];
final starts = <int>[];
for (var i = 0; i < 3; i++) {
final group = await consumer.recvGroup().timeout(timeout);
sequences.add(group!.sequence());
starts.add(group!.start());
}
expect(sequences, [0, 1, 2]);
expect(starts, [0, 1, 2]);
broadcast.close();
},
);
Expand Down
6 changes: 3 additions & 3 deletions doc/lib/c/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -87,9 +87,9 @@ keeps it across `moq_route_withdraw()` and `moq_route_announce()`, so a restarte
being a new route, is a new stream that `moq_origin_follow` hands viewers instead of a stalled
broadcast; the path stays `MOQ_ANNOUNCE_KIND_PRESENT` throughout. The follow callback
reports each instance as `MOQ_FOLLOW_EVENT_ONLINE` with its handle,
`MOQ_FOLLOW_EVENT_OFFLINE` when the path goes offline, and one `MOQ_FOLLOW_EVENT_END`. Set `instance` only for a publisher that continues its group sequences
`MOQ_FOLLOW_EVENT_OFFLINE` when the path goes offline, and one `MOQ_FOLLOW_EVENT_END`. Set `instance` only for a publisher that continues its group starts
across restarts, and raise `epoch` on each: readers stitch every route of one instance
together, so restarting the sequences under an old instance splices unrelated groups into
together, so restarting the starts under an old instance splices unrelated groups into
their tracks. To serve paths on demand, `moq_origin_claim()` returns a claim handle and delivers each request to
answer with `moq_broadcast_request_serve()`, `moq_broadcast_request_route()`, or
`moq_broadcast_request_reject()`; `moq_claim_announce()`, `moq_claim_withdraw()`,
Expand Down Expand Up @@ -128,7 +128,7 @@ inside. The header is the reference: each function carries a doc comment.
- **Discovery.** Announcement captures are always a list of wildcard matches, empty when the filter has no wildcards.
- **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()` or `moq_route_free()` takes it offline. How long to keep it up is yours to decide. A track still open at the close ends with `UNROUTABLE` (an internal error over moq-transport, which has no such code), and its handle is released. Readers follow a publisher's runs by announcement, not by that error: see [identity and recovery](/concept/identity).
- **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, valid as long as the payload. An untimed track has no scale, so there `has_scale` is false and `value` is the frame's group key (a datagram's sequence); every write takes one, with `moq_publish_group_sequence` naming a group's key. Stream tracks moq-c creates are timed, so their raw writes need one. Datagram tracks are separate and default to untimed; set their timescale when creating them to require timestamps. Stamp media frames and JSON writes from `moq_publish_catalog_now()`, the broadcast clock every track in the broadcast shares; media on a timeline of its own advertises the gap to the JSON tracks as catalog `delay`. JSON writes are converted to their track's milliseconds. A NULL timestamp on any write fails with `MOQ_ERROR_INVALID_POINTER`. A zero scale with `has_scale` set, 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, valid as long as the payload. An untimed track has no scale, so there `has_scale` is false and `value` is the frame's group key (a datagram's sequence); every write takes one, with `moq_publish_group_start` naming a group's key. Stream tracks moq-c creates are timed, so their raw writes need one. Datagram tracks are separate and default to untimed; set their timescale when creating them to require timestamps. Stamp media frames and JSON writes from `moq_publish_catalog_now()`, the broadcast clock every track in the broadcast shares; media on a timeline of its own advertises the gap to the JSON tracks as catalog `delay`. JSON writes are converted to their track's milliseconds. A NULL timestamp on any write fails with `MOQ_ERROR_INVALID_POINTER`. A zero scale with `has_scale` set, 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.
- **JSON windows.** `moq_publish_json_window` publishes a sliding run of records: `moq_publish_json_window_push` appends at the back, `moq_publish_json_window_pop` drops from the front, and `moq_publish_json_window_cut` closes the open group at a natural boundary. The catalog has no window mode, so a reader names the track. `moq_consume_json_window_event` fills `moq_json_window_event` with a push (the record at `start`, in `json`), a pop of `[start, end)`, or a skip of `[start, end)` that this reader joined too late to receive. Set `checkpoint_records` to bound what each new group restates for a window you never pop.
- **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. A decoder reads everything the track still holds unless a live player sets `start` to `MOQ_DECODE_START_LATEST`, which joins at the newest group and skips the cached backlog. A decoder setup refusal reports `MOQ_ERROR_UNSUPPORTED_CONFIG` on its terminal callback, so the caller can try another rendition; later peer or decode failures retain their own error codes.
Expand Down
2 changes: 1 addition & 1 deletion doc/lib/dart/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -136,7 +136,7 @@ print(route.instance());
final mine = route.broadcast();
final track = mine.publishTrack(name: 'video', info: null);
final group = track.appendGroup();
group.writeFrame(frame: Frame(payload: bytes, timestamp: Timestamp.unscaled(group.sequence())));
group.writeFrame(frame: Frame(payload: bytes, timestamp: Timestamp.unscaled(group.start())));
group.finish();
track.finish();
mine.close(); // ends the route too
Expand Down
4 changes: 2 additions & 2 deletions doc/lib/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -71,13 +71,13 @@ how it looks in that language:
- **Publish and subscribe to media** with the hang catalog filled in from the bitstream, or hand over raw pixels and PCM and let the binding encode and decode (VideoToolbox, Media Foundation, NVENC, openh264, Opus). The built-in video encoder can follow the connection's send estimate. The audio decoder reports the playout delay to buffer ahead of the playhead, fixed or estimated from arrivals, so read each frame as soon as the last is handled rather than pacing reads to the speaker.
- **Raw stream tracks** of arbitrary bytes, with per-subscriber priority and max delay, and separate live datagram tracks without groups or caching.
- **JSON tracks** as a latest value with merge-patch deltas, an append log, or a sliding window of records. Each value reads back with its frame timestamp, and a snapshot reader either replays every state or skips to the newest.
- **Fetch** a single cached group by sequence.
- **Fetch** a single cached group by start.
- **Catalog extensions**: write your own section next to `video` and `audio`, and read others' back.
- **Routes**: see which relays a broadcast came through, and advertise a cost as a standby publisher.
- **Connection stats** and **errors** that tell an auth rejection (don't retry) from a shutdown or a transport failure.
- **Authorization in band**: read the grant the relay sent back (the patterns this side may publish and subscribe to, and when it lapses), and present a fresh token before the current one expires, without reconnecting. It needs `moq-lite-07-wip`, which is opt-in.

C cannot fetch a single group by sequence.
C cannot fetch a single group by start.

## Upgrading

Expand Down
4 changes: 2 additions & 2 deletions doc/lib/layers.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,8 +43,8 @@ Sessions, origins, broadcasts, tracks, and groups: `Client`, `Server`,
| C | `moq_session_*`, `moq_origin_*`, `moq_publish_track_*`, `moq_consume_track_*` | `moq_publish_track` |

On-demand broadcast requests in every binding can answer with held content
without announcing an exact route. The answer uses the claim's
continuous sequence space at that path. Use a fresh publication for a job
without announcing an exact route. The answer continues the claim's
group starts at that path. Use a fresh publication for a job
that may restart independently; see [work on demand](/concept/identity#work-on-demand)
and the [Go](/lib/go/) and [C](/lib/c/) binding references.

Expand Down
2 changes: 1 addition & 1 deletion go/wrapper/errors.go
Original file line number Diff line number Diff line change
Expand Up @@ -77,7 +77,7 @@ var (
ErrUnsupported = ffi.ErrMoqErrorUnsupported
// ErrUnsupportedConfig is returned when media setup refuses a rendition or decoder output.
ErrUnsupportedConfig = ffi.ErrMoqErrorUnsupportedConfig
// ErrAlreadyCommitted is returned when a track already reading one way (arrival order, sequence order, or a typed reader) is asked to read another; subscribe again for a second cursor.
// ErrAlreadyCommitted is returned when a track already reading one way (arrival order, start order, or a typed reader) is asked to read another; subscribe again for a second cursor.
ErrAlreadyCommitted = ffi.ErrMoqErrorAlreadyCommitted
// ErrInvalidInstance is returned when an instance is empty.
ErrInvalidInstance = ffi.ErrMoqErrorInvalidInstance
Expand Down
24 changes: 12 additions & 12 deletions go/wrapper/media/media.go
Original file line number Diff line number Diff line change
Expand Up @@ -287,7 +287,7 @@ func NewTrackConsumer(ctx context.Context, broadcast *moq.BroadcastConsumer, con
// GroupConfig names a catalog rendition's group and fetch delivery options.
type GroupConfig struct {
Rendition Rendition
Sequence uint64
Start uint64
Options *moq.FetchGroupOptions
}

Expand All @@ -301,7 +301,7 @@ func FetchGroup(ctx context.Context, broadcast *moq.BroadcastConsumer, config Gr
return nil, err
}
}
inner, err := ffi.MoqMediaGroupConsumerFetch(ctx, bridge.BroadcastConsumer(broadcast), ffi.MoqMediaGroupConfig{Rendition: config.Rendition, Sequence: config.Sequence, Options: config.Options})
inner, err := ffi.MoqMediaGroupConsumerFetch(ctx, bridge.BroadcastConsumer(broadcast), ffi.MoqMediaGroupConfig{Rendition: config.Rendition, Start: config.Start, Options: config.Options})
if err != nil {
return nil, err
}
Expand Down Expand Up @@ -443,12 +443,12 @@ func (m *TrackProducer) Cut() error {
return m.inner.Cut()
}

// Seek draws a group boundary and numbers the next group sequence.
// Seek draws a group boundary and starts the next group at start.
//
// Cut with an explicit sequence, for a publisher whose group numbers have to be
// Cut with an explicit start, for a publisher whose group starts have to be
// deterministic: two encoders aligning per GOP so a consumer can fail over between them.
func (m *TrackProducer) Seek(sequence uint64) error {
return m.inner.Seek(sequence)
func (m *TrackProducer) Seek(start uint64) error {
return m.inner.Seek(start)
}

// AbortUnwanted closes the track with an application error code, but only while
Expand Down Expand Up @@ -491,9 +491,9 @@ func (c *ContainerProducer) Cut() error {
return c.inner.Cut()
}

// Seek starts a new segment and numbers its groups sequence.
func (c *ContainerProducer) Seek(sequence uint64) error {
return c.inner.Seek(sequence)
// Seek starts a new segment and starts its groups at start.
func (c *ContainerProducer) Seek(start uint64) error {
return c.inner.Seek(start)
}

// Finish finishes every track this container publishes.
Expand Down Expand Up @@ -613,9 +613,9 @@ type GroupConsumer struct {
inner *ffi.MoqMediaGroupConsumer
}

// Sequence is this group's sequence number within the track.
func (m *GroupConsumer) Sequence() uint64 {
return m.inner.Sequence()
// Start is this group's start within the track.
func (m *GroupConsumer) Start() uint64 {
return m.inner.Start()
}

// Next returns the next decoded frame, or (nil, nil) when the group ends.
Expand Down
18 changes: 9 additions & 9 deletions go/wrapper/moq_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -999,7 +999,7 @@ func TestAscendingSubscriptionReadsCachedBacklogOldestFirst(t *testing.T) {
}
defer consumer.Cancel()

var sequences []uint64
var starts []uint64
for range 3 {
group, err := consumer.RecvGroup(ctx)
if err != nil {
Expand All @@ -1008,10 +1008,10 @@ func TestAscendingSubscriptionReadsCachedBacklogOldestFirst(t *testing.T) {
if group == nil {
t.Fatal("expected a group")
}
sequences = append(sequences, group.Sequence())
starts = append(starts, group.Start())
}
if !slices.Equal(sequences, []uint64{0, 1, 2}) {
t.Fatalf("sequences = %v, want [0 1 2]", sequences)
if !slices.Equal(starts, []uint64{0, 1, 2}) {
t.Fatalf("starts = %v, want [0 1 2]", starts)
}
}

Expand Down Expand Up @@ -1066,8 +1066,8 @@ func TestTrackSparseGroupsAndKnownEnd(t *testing.T) {
if err != nil {
t.Fatal(err)
}
if group.Sequence() != 2 {
t.Fatalf("sequence = %d, want 2", group.Sequence())
if group.Start() != 2 {
t.Fatalf("start = %d, want 2", group.Start())
}
if err := group.Finish(); err != nil {
t.Fatal(err)
Expand All @@ -1083,7 +1083,7 @@ func TestTrackSparseGroupsAndKnownEnd(t *testing.T) {
t.Fatal(err)
}
if _, err := track.CreateGroup(5); err == nil {
t.Fatal("expected group at final sequence to fail")
t.Fatal("expected group at final start to fail")
}
if err := track.Finish(); err != nil {
t.Fatal(err)
Expand Down Expand Up @@ -1343,8 +1343,8 @@ func TestRecvGroupCancelKeepsConsumer(t *testing.T) {
if err != nil {
t.Fatalf("RecvGroup after cancel = %v", err)
}
if got == nil || got.Sequence() != group.Sequence() {
t.Fatalf("RecvGroup after cancel = %v, want group %d", got, group.Sequence())
if got == nil || got.Start() != group.Start() {
t.Fatalf("RecvGroup after cancel = %v, want group %d", got, group.Start())
}
}

Expand Down
6 changes: 3 additions & 3 deletions go/wrapper/origin.go
Original file line number Diff line number Diff line change
Expand Up @@ -44,9 +44,9 @@ type RouteOptions struct {
// Cost is the static production cost: lower wins among routes covering the same prefix.
Cost uint64
// Instance is a stable stream to serve, or nil to mint a fresh one. Set it only for a
// publisher that continues its group sequences across restarts and raises Epoch on each,
// publisher that continues its group starts across restarts and raises Epoch on each,
// or to forward an announced route's stream as is: readers stitch every route of one
// instance together, so restarting the sequences under an old instance splices unrelated
// instance together, so restarting the starts under an old instance splices unrelated
// groups into their tracks.
Instance *Instance
// Epoch is which run of a stable Instance this is: only the highest is eligible. Ignored without one.
Expand Down Expand Up @@ -256,7 +256,7 @@ func (r *BroadcastRequest) Route(options RouteOptions) (*Route, error) {
return newRoute(inner), nil
}

// Serve answers with held content under the claim's continuous sequence space,
// Serve answers with held content under the claim's continuous group starts,
// without announcing an exact route. The broadcast remains the caller's to release.
func (r *BroadcastRequest) Serve(broadcast *BroadcastConsumer) error {
return r.inner.Serve(broadcast.inner)
Expand Down
Loading