diff --git a/cpp/moq/include/moq/moq.hpp b/cpp/moq/include/moq/moq.hpp index ae4236d7187..67a403ee551 100644 --- a/cpp/moq/include/moq/moq.hpp +++ b/cpp/moq/include/moq/moq.hpp @@ -70,6 +70,8 @@ using JsonStreamConsumer = MoqJsonStreamConsumer; using JsonStreamProducer = MoqJsonStreamProducer; using MediaCatalogConsumer = MoqMediaCatalogConsumer; using MediaCatalogProducer = MoqMediaCatalogProducer; +/// Shares one source timestamp offset without keeping its broadcast open. +using MediaTimebase = MoqMediaTimebase; using MediaTrackConsumer = MoqMediaTrackConsumer; using MediaGroupConsumer = MoqMediaGroupConsumer; using MediaContainerProducer = MoqMediaContainerProducer; @@ -104,6 +106,8 @@ using ClientConfig = MoqClientConfig; using ClientTls = MoqClientTls; using ConnectionStats = MoqConnectionStats; using ContainerInit = MoqContainerInit; +/// A byte-stream container format and an optional shared source timebase. +using ContainerStreamInit = MoqContainerStreamInit; using Datagram = MoqDatagram; using Dimensions = MoqDimensions; using FetchGroupOptions = MoqFetchGroupOptions; diff --git a/cpp/moq/test/probe.cpp b/cpp/moq/test/probe.cpp index 5993ae536bd..cc1086587e7 100644 --- a/cpp/moq/test/probe.cpp +++ b/cpp/moq/test/probe.cpp @@ -99,6 +99,19 @@ Coroutine read_one(std::shared_ptr consumer, std::optional(foreign_chunks.error().get_variant())); + auto foreign_stream = moq::MediaContainerStreamProducer::init(timebase_other, {moq::ContainerFormat::kFmp4, timebase}); + CHECK(!foreign_stream); + CHECK(std::holds_alternative(foreign_stream.error().get_variant())); + ok(timebase_owner->close(), "close timebase owner"); + CHECK(!moq::MediaTimebase::init(timebase_owner)); + ok(timebase_other->close(), "close timebase other"); + // A synchronous error is a returned value, not an exception. auto unbound = ok(moq::Server::init({}), "server init"); auto fingerprints = unbound->cert_fingerprints(); diff --git a/dart/moq/lib/media.dart b/dart/moq/lib/media.dart index cdacce18930..e1944cb8e1a 100644 --- a/dart/moq/lib/media.dart +++ b/dart/moq/lib/media.dart @@ -57,7 +57,13 @@ typedef AudioFormat = MoqAudioFormat; /// A container that publishes its own tracks. typedef ContainerFormat = MoqContainerFormat; -/// A container format and its leading bytes. +/// A shared source timestamp offset that does not keep its broadcast open. +typedef Timebase = MoqMediaTimebase; + +/// A byte-stream container format and an optional shared source timebase. +typedef ContainerStreamInit = MoqContainerStreamInit; + +/// A container format, its leading bytes, and an optional shared source timebase. typedef ContainerInit = MoqContainerInit; /// A width and height pair, in pixels. diff --git a/dart/moq/test/moq_test.dart b/dart/moq/test/moq_test.dart index 2999057501c..8793cfc4d29 100644 --- a/dart/moq/test/moq_test.dart +++ b/dart/moq/test/moq_test.dart @@ -17,6 +17,39 @@ Future nextRoute(AnnounceConsumer announced) async { } void main() { + test('container timebase belongs to one broadcast', () { + final owner = BroadcastProducer(); + final other = BroadcastProducer(); + final timebase = moq_media.Timebase(broadcast: owner); + expect( + () => moq_media.ContainerProducer( + broadcast: other, + init: moq_media.ContainerInit( + format: moq_media.ContainerFormat.fmp4, + data: Uint8List(0), + timebase: timebase, + ), + ), + throwsA(isA()), + ); + expect( + () => moq_media.ContainerStreamProducer( + broadcast: other, + init: moq_media.ContainerStreamInit( + format: moq_media.ContainerFormat.fmp4, + timebase: timebase, + ), + ), + throwsA(isA()), + ); + owner.close(); + expect( + () => moq_media.Timebase(broadcast: owner), + throwsA(isA()), + ); + other.close(); + }); + test('diagnostic errors expose their named reason', () { final error = TransportMoqException('reset'); expect(error.reason, 'reset'); diff --git a/dart/moq_ffi/lib/src/moq.dart b/dart/moq_ffi/lib/src/moq.dart index 0cbc832bdb4..92aba78c293 100644 --- a/dart/moq_ffi/lib/src/moq.dart +++ b/dart/moq_ffi/lib/src/moq.dart @@ -776,7 +776,12 @@ class FfiConverterMoqCatalog { class MoqContainerInit { final MoqContainerFormat format; final Uint8List data; - MoqContainerInit({required this.format, required this.data}); + final MoqMediaTimebase? timebase; + MoqContainerInit({ + required this.format, + required this.data, + this.timebase = null, + }); } class FfiConverterMoqContainerInit { @@ -796,8 +801,13 @@ class FfiConverterMoqContainerInit { ); final data = data_lifted.value; new_offset += data_lifted.bytesRead; + final timebase_lifted = FfiConverterOptionalMoqMediaTimebase.read( + Uint8List.view(buf.buffer, new_offset), + ); + final timebase = timebase_lifted.value; + new_offset += timebase_lifted.bytesRead; return LiftRetVal( - MoqContainerInit(format: format, data: data), + MoqContainerInit(format: format, data: data, timebase: timebase), new_offset - buf.offsetInBytes, ); } @@ -806,6 +816,7 @@ class FfiConverterMoqContainerInit { final total_length = FfiConverterMoqContainerFormat.allocationSize(value.format) + FfiConverterUint8List.allocationSize(value.data) + + FfiConverterOptionalMoqMediaTimebase.allocationSize(value.timebase) + 0; final buf = Uint8List(total_length); write(value, buf); @@ -822,12 +833,76 @@ class FfiConverterMoqContainerInit { value.data, Uint8List.view(buf.buffer, new_offset), ); + new_offset += FfiConverterOptionalMoqMediaTimebase.write( + value.timebase, + Uint8List.view(buf.buffer, new_offset), + ); return new_offset - buf.offsetInBytes; } static int allocationSize(MoqContainerInit value) { return FfiConverterMoqContainerFormat.allocationSize(value.format) + FfiConverterUint8List.allocationSize(value.data) + + FfiConverterOptionalMoqMediaTimebase.allocationSize(value.timebase) + + 0; + } +} + +class MoqContainerStreamInit { + final MoqContainerFormat format; + final MoqMediaTimebase? timebase; + MoqContainerStreamInit({required this.format, this.timebase = null}); +} + +class FfiConverterMoqContainerStreamInit { + static MoqContainerStreamInit lift(RustBuffer buf) { + return FfiConverterMoqContainerStreamInit.read(buf.asUint8List()).value; + } + + static LiftRetVal read(Uint8List buf) { + int new_offset = buf.offsetInBytes; + final format_lifted = FfiConverterMoqContainerFormat.read( + Uint8List.view(buf.buffer, new_offset), + ); + final format = format_lifted.value; + new_offset += format_lifted.bytesRead; + final timebase_lifted = FfiConverterOptionalMoqMediaTimebase.read( + Uint8List.view(buf.buffer, new_offset), + ); + final timebase = timebase_lifted.value; + new_offset += timebase_lifted.bytesRead; + return LiftRetVal( + MoqContainerStreamInit(format: format, timebase: timebase), + new_offset - buf.offsetInBytes, + ); + } + + static RustBuffer lower(MoqContainerStreamInit value) { + final total_length = + FfiConverterMoqContainerFormat.allocationSize(value.format) + + FfiConverterOptionalMoqMediaTimebase.allocationSize(value.timebase) + + 0; + final buf = Uint8List(total_length); + write(value, buf); + return toRustBuffer(buf); + } + + static int write(MoqContainerStreamInit value, Uint8List buf) { + int new_offset = buf.offsetInBytes; + new_offset += FfiConverterMoqContainerFormat.write( + value.format, + Uint8List.view(buf.buffer, new_offset), + ); + new_offset += FfiConverterOptionalMoqMediaTimebase.write( + value.timebase, + Uint8List.view(buf.buffer, new_offset), + ); + return new_offset - buf.offsetInBytes; + } + + static int allocationSize(MoqContainerStreamInit value) { + return FfiConverterMoqContainerFormat.allocationSize(value.format) + + FfiConverterOptionalMoqMediaTimebase.allocationSize(value.timebase) + 0; } } @@ -6688,12 +6763,12 @@ class MoqMediaContainerStreamProducer } MoqMediaContainerStreamProducer({ required MoqBroadcastProducer broadcast, - required MoqContainerFormat format, + required MoqContainerStreamInit init, }) : _ptr = rustCall( (status) => uniffi_moq_ffi_fn_constructor_moqmediacontainerstreamproducer_new( FfiConverterMoqBroadcastProducer.lower(broadcast), - FfiConverterMoqContainerFormat.lower(format), + FfiConverterMoqContainerStreamInit.lower(init), status, ), moqExceptionErrorHandler, @@ -6888,6 +6963,68 @@ class FfiConverterMoqMediaGroupConsumer { } } +abstract class MoqMediaTimebaseInterface {} + +final _MoqMediaTimebaseFinalizer = Finalizer>((ptr) { + rustCall((status) => uniffi_moq_ffi_fn_free_moqmediatimebase(ptr, status)); +}); + +class MoqMediaTimebase implements MoqMediaTimebaseInterface { + late final Pointer _ptr; + MoqMediaTimebase._(this._ptr) { + _MoqMediaTimebaseFinalizer.attach(this, _ptr, detach: this); + } + MoqMediaTimebase({required MoqBroadcastProducer broadcast}) + : _ptr = rustCall( + (status) => uniffi_moq_ffi_fn_constructor_moqmediatimebase_new( + FfiConverterMoqBroadcastProducer.lower(broadcast), + status, + ), + moqExceptionErrorHandler, + ) { + _MoqMediaTimebaseFinalizer.attach(this, _ptr, detach: this); + } + factory MoqMediaTimebase.lift(Pointer ptr) { + return MoqMediaTimebase._(ptr); + } + Pointer uniffiClonePointer() { + return rustCall( + (status) => uniffi_moq_ffi_fn_clone_moqmediatimebase(_ptr, status), + ); + } + + void dispose() { + _MoqMediaTimebaseFinalizer.detach(this); + rustCall((status) => uniffi_moq_ffi_fn_free_moqmediatimebase(_ptr, status)); + } +} + +class FfiConverterMoqMediaTimebase { + static MoqMediaTimebase lift(Pointer ptr) { + return MoqMediaTimebase.lift(ptr); + } + + static Pointer lower(MoqMediaTimebase value) { + return value.uniffiClonePointer(); + } + + static int allocationSize(MoqMediaTimebase value) { + return 8; + } + + static LiftRetVal read(Uint8List buf) { + final handle = buf.buffer.asByteData(buf.offsetInBytes).getInt64(0); + final pointer = Pointer.fromAddress(handle); + return LiftRetVal(MoqMediaTimebase.lift(pointer), 8); + } + + static int write(MoqMediaTimebase value, Uint8List buf) { + final handle = lower(value); + buf.buffer.asByteData(buf.offsetInBytes).setInt64(0, handle.address); + return 8; + } +} + abstract class MoqMediaTrackConsumerInterface { void cancel(); Future next(); @@ -9764,6 +9901,53 @@ class FfiConverterOptionalMoqMediaFrame { } } +class FfiConverterOptionalMoqMediaTimebase { + static MoqMediaTimebase? lift(RustBuffer buf) { + return FfiConverterOptionalMoqMediaTimebase.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 = FfiConverterMoqMediaTimebase.read( + Uint8List.view(buf.buffer, buf.offsetInBytes + 1), + ); + return LiftRetVal(result.value, result.bytesRead + 1); + } + + static int allocationSize([MoqMediaTimebase? value]) { + if (value == null) { + return 1; + } + return FfiConverterMoqMediaTimebase.allocationSize(value) + 1; + } + + static RustBuffer lower(MoqMediaTimebase? value) { + if (value == null) { + return toRustBuffer(Uint8List.fromList([0])); + } + final buf = Uint8List( + FfiConverterOptionalMoqMediaTimebase.allocationSize(value), + ); + FfiConverterOptionalMoqMediaTimebase.write(value, buf); + return toRustBuffer(buf); + } + + static int write(MoqMediaTimebase? value, Uint8List buf) { + if (value == null) { + buf[0] = 0; + return 1; + } + buf[0] = 1; + return FfiConverterMoqMediaTimebase.write( + value, + Uint8List.view(buf.buffer, buf.offsetInBytes + 1), + ) + + 1; + } +} + class FfiConverterOptionalMoqOriginProducer { static MoqOriginProducer? lift(RustBuffer buf) { return FfiConverterOptionalMoqOriginProducer.read(buf.asUint8List()).value; @@ -11223,7 +11407,7 @@ external void uniffi_moq_ffi_fn_free_moqmediacontainerstreamproducer( external Pointer uniffi_moq_ffi_fn_constructor_moqmediacontainerstreamproducer_new( Pointer broadcast, - RustBuffer format, + RustBuffer init, Pointer uniffiStatus, ); @@ -11299,6 +11483,30 @@ external int uniffi_moq_ffi_fn_method_moqmediagroupconsumer_sequence( Pointer uniffiStatus, ); +@Native Function(Pointer, Pointer)>( + assetId: _uniffiAssetId, +) +external Pointer uniffi_moq_ffi_fn_clone_moqmediatimebase( + Pointer handle, + Pointer uniffiStatus, +); + +@Native, Pointer)>( + assetId: _uniffiAssetId, +) +external void uniffi_moq_ffi_fn_free_moqmediatimebase( + Pointer handle, + Pointer uniffiStatus, +); + +@Native Function(Pointer, Pointer)>( + assetId: _uniffiAssetId, +) +external Pointer uniffi_moq_ffi_fn_constructor_moqmediatimebase_new( + Pointer broadcast, + Pointer uniffiStatus, +); + @Native Function(Pointer, Pointer)>( assetId: _uniffiAssetId, ) @@ -13225,6 +13433,9 @@ external int uniffi_moq_ffi_checksum_constructor_moqmediagroupconsumer_fetch(); @Native(assetId: _uniffiAssetId) external int uniffi_moq_ffi_checksum_constructor_moqmediagroupconsumer_new(); +@Native(assetId: _uniffiAssetId) +external int uniffi_moq_ffi_checksum_constructor_moqmediatimebase_new(); + @Native(assetId: _uniffiAssetId) external int uniffi_moq_ffi_checksum_constructor_moqmediatrackconsumer_subscribe(); @@ -13753,11 +13964,11 @@ void _checkApiChecksums() { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } if (uniffi_moq_ffi_checksum_constructor_moqmediacontainerproducer_new() != - 7951) { + 41369) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } if (uniffi_moq_ffi_checksum_constructor_moqmediacontainerstreamproducer_new() != - 32133) { + 54958) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } if (uniffi_moq_ffi_checksum_constructor_moqmediagroupconsumer_fetch() != @@ -13768,6 +13979,9 @@ void _checkApiChecksums() { 14424) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } + if (uniffi_moq_ffi_checksum_constructor_moqmediatimebase_new() != 21606) { + throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); + } if (uniffi_moq_ffi_checksum_constructor_moqmediatrackconsumer_subscribe() != 24751) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); diff --git a/doc/lib/cpp/index.md b/doc/lib/cpp/index.md index 17f4d282fa6..be4e51991fd 100644 --- a/doc/lib/cpp/index.md +++ b/doc/lib/cpp/index.md @@ -109,6 +109,10 @@ if (auto catalog = ok(catalogs->next().get())) { // std::nullopt once the cata `MediaTrackConsumer` reads in decode order. For arrival-order reads, decode each group from `TrackConsumer::recv_group` with `moq::MediaGroupConsumer::init(group, container)`; frames carry container media time as they land. +Share `moq::MediaTimebase::init(broadcast)` through container init records when several +imports use one source timeline. `MediaContainerStreamProducer::init` takes +`ContainerStreamInit`; omitting its timebase keeps an independent offset. A timebase +belongs to its broadcast and does not keep it open. ```cpp // Publish encoded frames, or raw pixels with the codec inside the binding. diff --git a/doc/lib/dart/index.md b/doc/lib/dart/index.md index 6d9f8a59e89..5f755bc089d 100644 --- a/doc/lib/dart/index.md +++ b/doc/lib/dart/index.md @@ -23,6 +23,10 @@ Raw tracks with a `null` timescale are untimed on both publish and receive. 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. +Share `media.Timebase(broadcast: ...)` through container init records when several +imports use one source timeline. `ContainerStreamProducer` takes `ContainerStreamInit`; +omitting its timebase keeps an independent offset. A timebase belongs to its broadcast +and does not keep it open. `media.CatalogConsumer.subscribe`, `media.TrackConsumer.subscribe`, and `media.GroupConsumer.fetch` construct the read side from a broadcast. For arrival-order reads, decode each group from `TrackConsumer.recvGroup()` with `media.GroupConsumer(group: ..., container: ...)`; frames diff --git a/doc/lib/go/index.md b/doc/lib/go/index.md index 30ee4e429f8..5d73a98a0ab 100644 --- a/doc/lib/go/index.md +++ b/doc/lib/go/index.md @@ -24,6 +24,10 @@ and the JSON producers take a final `*time.Duration` timestamp argument (`nil` f 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. +Share `media.NewTimebase(broadcast)` through container init records when several imports +use one source timeline. `NewContainerStreamProducer` takes `ContainerStreamInit`; +omitting its timebase keeps an independent offset. Timebases belong to one broadcast +and do not keep it open; release the handle with `Close` on the calling goroutine. For arrival-order reads, decode each group from `moq.TrackConsumer.RecvGroup` with `media.NewGroupConsumer`; frames carry container media time as they land. `media.FetchGroup` fetches and decodes one past group. diff --git a/doc/lib/kt/index.md b/doc/lib/kt/index.md index b97dc806e3a..01546c6de3f 100644 --- a/doc/lib/kt/index.md +++ b/doc/lib/kt/index.md @@ -22,6 +22,10 @@ Raw tracks with a `null` timescale are untimed on both publish and receive. 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. +Share `Timebase(broadcast)` through container init records when several imports use +one source timeline. `ContainerStreamProducer` takes `ContainerStreamInit`; omitting +its timebase keeps an independent offset. A timebase belongs to its broadcast and +does not keep it open. Construct readers with `CatalogConsumer.subscribe`, `TrackConsumer.subscribe`, or `GroupConsumer.fetch`. For arrival-order reads, decode each group from `dev.moq.TrackConsumer.recvGroup()` with `dev.moq.media.GroupConsumer(group, container)`; frames diff --git a/doc/lib/py/index.md b/doc/lib/py/index.md index 9e93327eb8a..ad63a2e9856 100644 --- a/doc/lib/py/index.md +++ b/doc/lib/py/index.md @@ -17,6 +17,10 @@ x64. Use `Named(name)` or `Requested(request)` as the target for `TrackProducer.audio` / `.video`. `CatalogProducer(broadcast)` holds the broadcast weakly and owns catalog properties and sections; its writes fail with `Error.Closed` after the broadcast closes or is released. +Share `media.Timebase(broadcast)` through container init records when several imports +use one source timeline. `ContainerStreamProducer` takes `ContainerStreamInit`; +omitting its timebase keeps an independent offset. A timebase belongs to its broadcast +and does not keep it open. `MediaFrame.timestamp`, media writes, and `flush` use `datetime.timedelta`. A missing data timestamp stays untimed; the library never substitutes zero or now. Raw tracks with a `None` timescale are untimed on both publish and receive. diff --git a/doc/lib/swift/index.md b/doc/lib/swift/index.md index 51c5c017921..a3bcd5a4ffe 100644 --- a/doc/lib/swift/index.md +++ b/doc/lib/swift/index.md @@ -23,6 +23,10 @@ Raw tracks with a `nil` timescale are untimed on both publish and receive. Whole-frame media writes require caller time; container imports keep their own timeline handling. Timed raw/data tracks require caller-supplied timestamps. Use `Media.CatalogProducer.now()` to stamp a locally created event on the broadcast clock; reading it fixes that clock for later media producers. +Share `Media.Timebase(broadcast:)` through container init records when several imports +use one source timeline. `ContainerStreamProducer` takes `ContainerStreamInit`; +omitting its timebase keeps an independent offset. A timebase belongs to its broadcast +and does not keep it open. For arrival-order reads, decode each group from `TrackConsumer.recvGroup()` with `Media.GroupConsumer(group:container:)`; frames carry container media time as they land. diff --git a/doc/setup/upgrade.md b/doc/setup/upgrade.md index 81081ce06a2..09980fbbde4 100644 --- a/doc/setup/upgrade.md +++ b/doc/setup/upgrade.md @@ -255,6 +255,11 @@ These land with the next breaking release, not the 2026-09-23 train. container imports keep their existing timeline handling. `media.CatalogProducer.now()` samples and fixes the broadcast clock for explicit local-event stamps. A supplied timestamp ahead of now is published rather than refused. +- **Container byte-stream importers take an init record.** The bindings' + `ContainerStreamProducer` (moq-ffi's `MoqMediaContainerStreamProducer`) takes + a `ContainerStreamInit` holding the format instead of a bare format. Its + optional `timebase`, also on `ContainerInit`, shares one source's offset + across container imports; leave it unset for the previous independent offset. - **moq-mux importers publish the catalog at their first frame.** The fMP4, MKV, and MPEG-TS importers used to publish it at their init segment (`moov`, `Tracks`, or the first PMT) on a provisional clock, then re-anchor it on the diff --git a/go/wrapper/README.md b/go/wrapper/README.md index b4d9c81ec09..01a0d08ac0f 100644 --- a/go/wrapper/README.md +++ b/go/wrapper/README.md @@ -79,7 +79,11 @@ take a broadcast, a `Named` or `Requested` target, and an `AudioInit` / `VideoIn A `Named` target chooses a track name or lets the importer derive one; a `Requested` target takes over a subscriber's pending request. A duplicate name fails. `VideoInit.Hint` seeds fields the bitstream cannot supply. `NewContainerProducer` / -`NewContainerStreamProducer` demux whole chunks or a byte stream into their own tracks. +`NewContainerStreamProducer` demux whole chunks or a byte stream into their own tracks, +using `ContainerInit` or `ContainerStreamInit`. Share `NewTimebase(broadcast)` in these +records for containers on one source timeline; omitting it gives each an independent +offset. Timebases belong to one broadcast and do not keep it open. Call `Close` to +release the timebase handle on the calling goroutine. `NewCatalogProducer` holds its broadcast weakly and owns catalog properties and sections. `NewCatalogConsumer`, `NewTrackConsumer`, and `FetchGroup` read catalog snapshots, live media, and one fetched media group. `NewGroupConsumer` diff --git a/go/wrapper/media/media.go b/go/wrapper/media/media.go index c380b701635..e796c8f70ea 100644 --- a/go/wrapper/media/media.go +++ b/go/wrapper/media/media.go @@ -46,10 +46,41 @@ type ( AudioInit = ffi.MoqAudioInit // VideoInit describes a video codec, initialization bytes, and hints. VideoInit = ffi.MoqVideoInit - // ContainerInit describes a container and its leading bytes. - ContainerInit = ffi.MoqContainerInit ) +// Timebase shares a source's timestamp offset without keeping its broadcast open. +type Timebase struct{ inner *ffi.MoqMediaTimebase } + +// NewTimebase creates a shared source timebase owned by broadcast. +func NewTimebase(broadcast *moq.BroadcastProducer) (*Timebase, error) { + inner, err := ffi.NewMoqMediaTimebase(bridge.BroadcastProducer(broadcast)) + if err != nil { + return nil, err + } + return &Timebase{inner: inner}, nil +} + +// Close releases this timebase handle on the calling goroutine; existing imports keep their offset. +func (t *Timebase) Close() { t.inner.Destroy() } + +// ContainerInit describes a container, its leading bytes and an optional shared timebase. +type ContainerInit struct { + // Format selects the container parser. + Format ContainerFormat + // Data supplies the leading container bytes. + Data []byte + // Timebase shares a source offset, or nil for an independent offset. + Timebase *Timebase +} + +// ContainerStreamInit describes a byte-stream container and an optional shared timebase. +type ContainerStreamInit struct { + // Format selects the container parser. + Format ContainerFormat + // Timebase shares a source offset, or nil for an independent offset. + Timebase *Timebase +} + // MediaFrame is a container-decoded payload, presentation timestamp, and keyframe flag. type MediaFrame struct { Payload []byte @@ -166,7 +197,11 @@ func NewVideoTrackStreamProducer(broadcast *moq.BroadcastProducer, target Target // NewContainerProducer imports complete container chunks. func NewContainerProducer(broadcast *moq.BroadcastProducer, init ContainerInit) (*ContainerProducer, error) { - inner, err := ffi.NewMoqMediaContainerProducer(bridge.BroadcastProducer(broadcast), init) + var timebase **ffi.MoqMediaTimebase + if init.Timebase != nil { + timebase = &init.Timebase.inner + } + inner, err := ffi.NewMoqMediaContainerProducer(bridge.BroadcastProducer(broadcast), ffi.MoqContainerInit{Format: init.Format, Data: init.Data, Timebase: timebase}) if err != nil { return nil, err } @@ -174,8 +209,12 @@ func NewContainerProducer(broadcast *moq.BroadcastProducer, init ContainerInit) } // NewContainerStreamProducer imports a container byte stream. -func NewContainerStreamProducer(broadcast *moq.BroadcastProducer, format ContainerFormat) (*ContainerStreamProducer, error) { - inner, err := ffi.NewMoqMediaContainerStreamProducer(bridge.BroadcastProducer(broadcast), format) +func NewContainerStreamProducer(broadcast *moq.BroadcastProducer, init ContainerStreamInit) (*ContainerStreamProducer, error) { + var timebase **ffi.MoqMediaTimebase + if init.Timebase != nil { + timebase = &init.Timebase.inner + } + inner, err := ffi.NewMoqMediaContainerStreamProducer(bridge.BroadcastProducer(broadcast), ffi.MoqContainerStreamInit{Format: init.Format, Timebase: timebase}) if err != nil { return nil, err } diff --git a/go/wrapper/media/media_test.go b/go/wrapper/media/media_test.go index 5b051a99afa..58a0ffa8a88 100644 --- a/go/wrapper/media/media_test.go +++ b/go/wrapper/media/media_test.go @@ -41,3 +41,33 @@ func TestRequestedTargetRequiresRequest(t *testing.T) { } } } + +func TestContainerTimebaseBelongsToOneBroadcast(t *testing.T) { + owner, err := moq.NewBroadcastProducer() + if err != nil { + t.Fatal(err) + } + defer owner.Close() + other, err := moq.NewBroadcastProducer() + if err != nil { + t.Fatal(err) + } + defer other.Close() + timebase, err := media.NewTimebase(owner) + if err != nil { + t.Fatal(err) + } + defer timebase.Close() + if _, err := media.NewContainerProducer(other, media.ContainerInit{Format: media.ContainerFormatFmp4, Timebase: timebase}); !errors.Is(err, moq.ErrCodec) { + t.Fatalf("foreign chunk timebase: %v", err) + } + if _, err := media.NewContainerStreamProducer(other, media.ContainerStreamInit{Format: media.ContainerFormatFmp4, Timebase: timebase}); !errors.Is(err, moq.ErrCodec) { + t.Fatalf("foreign stream timebase: %v", err) + } + if err := owner.Close(); err != nil { + t.Fatal(err) + } + if _, err := media.NewTimebase(owner); !errors.Is(err, moq.ErrClosed) { + t.Fatalf("closed owner: %v", err) + } +} 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 e2977cf0721..63dd4ba37fc 100644 --- a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/media/Media.kt +++ b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/media/Media.kt @@ -47,7 +47,11 @@ typealias VideoProperties = uniffi.moq.MoqVideoProperties typealias AudioInit = uniffi.moq.MoqAudioInit /** A video codec, optional init bytes, a label, and catalog hints. */ typealias VideoInit = uniffi.moq.MoqVideoInit -/** A container format and its leading bytes. */ +/** A shared source timestamp offset that does not keep its broadcast open. */ +typealias Timebase = uniffi.moq.MoqMediaTimebase +/** A byte-stream container format and an optional shared source timebase. */ +typealias ContainerStreamInit = uniffi.moq.MoqContainerStreamInit +/** A container format, its leading bytes, and an optional shared source timebase. */ typealias ContainerInit = uniffi.moq.MoqContainerInit /** The catalog description of an audio track: codec, sample rate, channels, whether it is enabled, and container. */ typealias Audio = uniffi.moq.MoqAudio diff --git a/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt b/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt index ee1d6fc7cbf..dc6885d550b 100644 --- a/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt +++ b/kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt @@ -50,6 +50,24 @@ private fun opusHead(): ByteArray = ) class SmokeTest { + @Test + fun `container timebase belongs to one broadcast`() { + BroadcastProducer().use { owner -> + BroadcastProducer().use { other -> + Timebase(owner).use { timebase -> + assertFailsWith { + ContainerProducer(other, ContainerInit(ContainerFormat.FMP4, byteArrayOf(), timebase)) + } + assertFailsWith { + ContainerStreamProducer(other, ContainerStreamInit(ContainerFormat.FMP4, timebase)) + } + owner.end() + assertFailsWith { Timebase(owner) } + } + } + } + } + @Test fun `diagnostic errors expose their named reason`() { val error = MoqException.Transport(reason = "reset") diff --git a/py/moq-rs/README.md b/py/moq-rs/README.md index 570e8f33224..d06777db90e 100644 --- a/py/moq-rs/README.md +++ b/py/moq-rs/README.md @@ -184,7 +184,10 @@ client = moq.Client( `Requested(request)` takes over a pending subscriber request, whose name is already fixed. - `media.TrackStreamProducer.video(...)` infers video frame boundaries from a byte stream. - `media.ContainerProducer(broadcast, ContainerInit(...))` demuxes complete container chunks; - `media.ContainerStreamProducer(broadcast, format)` recovers framing from a byte stream. + `media.ContainerStreamProducer(broadcast, ContainerStreamInit(...))` recovers framing from a byte stream. + Share `media.Timebase(broadcast)` in the init records for containers on one source timeline; + omitting it gives each container an independent offset. Timebases belong to one broadcast + 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 diff --git a/py/moq-rs/docs/index.md b/py/moq-rs/docs/index.md index 0f3c42e2772..b9d7a592fa5 100644 --- a/py/moq-rs/docs/index.md +++ b/py/moq-rs/docs/index.md @@ -98,6 +98,9 @@ Every importer takes a broadcast; single-track imports choose a `Named` or `Requ TrackStreamProducer ContainerProducer ContainerStreamProducer + ContainerInit + ContainerStreamInit + Timebase TrackConsumer GroupConsumer Named diff --git a/py/moq-rs/moq/media.py b/py/moq-rs/moq/media.py index e98272b661f..81610c6f79a 100644 --- a/py/moq-rs/moq/media.py +++ b/py/moq-rs/moq/media.py @@ -3,7 +3,7 @@ from __future__ import annotations import json -from dataclasses import dataclass +from dataclasses import dataclass, field from datetime import timedelta from typing import Any, cast @@ -22,10 +22,8 @@ MoqContainerFormat as ContainerFormat, ) from moq_ffi import ( - MoqContainerInit as ContainerInit, -) -from moq_ffi import MoqDimensions as Dimensions -from moq_ffi import ( + MoqContainerInit, + MoqContainerStreamInit, MoqError, MoqMediaCatalogConsumer, MoqMediaCatalogProducer, @@ -35,11 +33,13 @@ MoqMediaGroupConfig, MoqMediaGroupConsumer, MoqMediaTarget, + MoqMediaTimebase, MoqMediaTrackConfig, MoqMediaTrackConsumer, MoqMediaTrackProducer, MoqMediaTrackStreamProducer, ) +from moq_ffi import MoqDimensions as Dimensions from moq_ffi import MoqVideo as Video from moq_ffi import MoqVideoFormat as VideoFormat from moq_ffi import MoqVideoHint as VideoHint @@ -57,6 +57,38 @@ from .types import FetchGroupOptions +class Timebase: + """Share one source's timestamp offset without keeping its broadcast open.""" + + def __init__(self, broadcast: BroadcastProducer) -> None: + self._inner = MoqMediaTimebase(broadcast._inner) + + +@dataclass(frozen=True) +class ContainerInit: + """A container format, its leading bytes, and an optional shared source timebase.""" + + format: ContainerFormat + data: bytes + timebase: Timebase | None = field(default=None, kw_only=True) + + def _ffi(self) -> MoqContainerInit: + return MoqContainerInit( + format=self.format, data=self.data, timebase=self.timebase._inner if self.timebase else None + ) + + +@dataclass(frozen=True) +class ContainerStreamInit: + """A byte-stream container format and an optional shared source timebase.""" + + format: ContainerFormat + timebase: Timebase | None = field(default=None, kw_only=True) + + def _ffi(self) -> MoqContainerStreamInit: + return MoqContainerStreamInit(format=self.format, timebase=self.timebase._inner if self.timebase else None) + + @dataclass(frozen=True) class Named: """Publish a new track with a chosen name, or a format-derived unique name.""" @@ -190,7 +222,7 @@ class ContainerProducer: """ def __init__(self, broadcast: BroadcastProducer, init: ContainerInit) -> None: - self._inner = MoqMediaContainerProducer(broadcast._inner, init) + self._inner = MoqMediaContainerProducer(broadcast._inner, init._ffi()) def write(self, payload: bytes) -> None: """Write a whole chunk of container bytes.""" @@ -217,8 +249,8 @@ def finish(self) -> None: class ContainerStreamProducer: """Publish a container fed by a raw byte stream, which recovers its own framing.""" - def __init__(self, broadcast: BroadcastProducer, format: ContainerFormat) -> None: - self._inner = MoqMediaContainerStreamProducer(broadcast._inner, format) + def __init__(self, broadcast: BroadcastProducer, init: ContainerStreamInit) -> None: + self._inner = MoqMediaContainerStreamProducer(broadcast._inner, init._ffi()) def write(self, payload: bytes) -> None: """Push raw container bytes; chunk boundaries don't matter.""" @@ -434,5 +466,7 @@ async def catalog(broadcast: BroadcastConsumer) -> Catalog: "AudioInit", "VideoInit", "ContainerInit", + "ContainerStreamInit", + "Timebase", "catalog", ] diff --git a/py/moq-rs/tests/test_local.py b/py/moq-rs/tests/test_local.py index 85a28fc6d3c..805084da9d2 100644 --- a/py/moq-rs/tests/test_local.py +++ b/py/moq-rs/tests/test_local.py @@ -1451,3 +1451,21 @@ def test_media_catalog_handle_closes_with_broadcast(): broadcast.close() with pytest.raises(moq.Error.Closed): # type: ignore[attr-defined] catalog.remove_section("app") + + +def test_container_timebase_belongs_to_one_broadcast(): + owner = moq.BroadcastProducer() + other = moq.BroadcastProducer() + timebase = moq.media.Timebase(owner) + with pytest.raises(moq.Error.Codec, match="another broadcast"): + moq.media.ContainerProducer( + other, moq.media.ContainerInit(moq.media.ContainerFormat.FMP4, b"", timebase=timebase) + ) + with pytest.raises(moq.Error.Codec, match="another broadcast"): + moq.media.ContainerStreamProducer( + other, moq.media.ContainerStreamInit(moq.media.ContainerFormat.FMP4, timebase=timebase) + ) + owner.close() + with pytest.raises(moq.Error.Closed): + moq.media.Timebase(owner) + other.close() diff --git a/quest/m1/README.md b/quest/m1/README.md index 05c0803f7f7..8990a88b23d 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -157,7 +157,6 @@ above them. - [Plan: HLS export failure signal](/quest/m1/hls-failure-signal.md) - decide what players see when the exporter's timeline fails, live or history, so a truncated recording never looks complete - [Close tail drain](/quest/m1/close-tail-drain.md) - after a peer close, subscribers read the group streams their transport already delivered instead of aborting them, so a finished tail arrives on every version - [Publisher linger](/quest/m1/publisher-linger.md) - every finishing publisher keeps its broadcast up for the media max-age so subscribers can drain it -- [Shared timebase in the bindings](/quest/m1/ffi-timebase.md) - binding apps publish several containers from one source on one shared offset - [Vulkan Video encode on AMD](/quest/m1/vulkan-encode.md) - H.264 and H.265 from an external Vulkan image on RADV, hand-rolled on ash, proven on an RX 9070 - [VA-API encodes an external Vulkan image](/quest/m1/vaapi-vulkan-import.md) - an explicit-sync DMA-BUF reaches Intel's encoder, proven on Arrow Lake - [Current LOC Timestamp only](/quest/m1/ietf-loc-timestamp.md) - moq-transport Timestamps are read only from LOC property 0x10, and 0x06 is opaque on every draft diff --git a/quest/m1/ffi-timebase.md b/quest/m1/ffi-timebase.md deleted file mode 100644 index 750cdb058dd..00000000000 --- a/quest/m1/ffi-timebase.md +++ /dev/null @@ -1,42 +0,0 @@ -# [M] Shared timebase in the bindings - -## Goal - -A binding app can publish several containers from one source on one shared -offset, so separate audio and video containers stay synchronized on a clock -already in use. Container constructors currently reserve a fresh -`catalog::Timebase` per call, making their offsets depend on first arrival. - -## Plan - -Decided in the 2026-10-10 audit, adapting the approved shared-offset behavior -to the media constructors introduced by #4519: - -- `Media.Timebase(broadcast)` constructs the shared handle, mirrored as - `MoqMediaTimebase` in FFI and `Timebase` under each wrapper's media namespace. - Prefer this constructor over a factory on CatalogProducer; it needs no - extra catalog handle and keeps media methods off the net broadcast API. -- Container init carries an optional timebase. Present uses that shared - reservation; absent preserves a fresh offset. The container stream - constructor takes an init record with format and optional timebase instead - of a bare format. Change the constructor, not a compatibility variant. -- A timebase belongs to one broadcast/catalog. Refuse pairing it with another; - do not let the handle independently keep a publication alive. Mirror the - current media handle ownership rather than introducing a second lifetime. -- Apply it to current media container constructors and every wrapper. C uses - the generated binding surface; the hand-written C API gets no new features. -- Codec producers still take caller timestamps with no offset. `Timebase::place` - stays Rust-only until a consumer needs it. Include this constructor break in m1. -- Update existing container-publishing docs inline. No additional timebase guide. - -Test two containers sharing an offset after the clock is already taken, -independent offsets when omitted, foreign-broadcast refusal, and handle -teardown. Use controlled time and existing interop CI; run -`just test interop --all` and `just check`. - -Public API: media Timebase and optional init fields across bindings; the -stream constructor takes a record. Wire: none. - -## Related - -- [Generated C](/quest/m1/c/README.md) - mirrors the FFI surface instead of extending the retired hand-written API diff --git a/quest/m2/sibling-broadcasts.md b/quest/m2/sibling-broadcasts.md index 3d7e4e11934..2dd81884f05 100644 --- a/quest/m2/sibling-broadcasts.md +++ b/quest/m2/sibling-broadcasts.md @@ -21,7 +21,7 @@ Non-goals: plays one broadcast; aligning siblings is the consumer's job, through the shared clock. - Sharing a clock across broadcasts from the bindings, which expose no mux - `Clock`; extend [the shared timebase](/quest/m1/ffi-timebase.md) when a + `Clock`; extend [the shared container timebase](/rs/moq-ffi/src/media.rs) when a binding app needs it. - Tying a `json` or `binary` track to one source. Those sections are application-defined; an application that needs the association defines it, @@ -59,4 +59,4 @@ Public API: none. Wire: none. ## Related - [Teleoperation](/quest/m2/teleop/README.md) - the robot line whose multi-camera case motivates this -- [Shared timebase in the bindings](/quest/m1/ffi-timebase.md) - shares one offset within a binding broadcast; sharing across broadcasts would extend it +- [Shared container timebase](/rs/moq-ffi/src/media.rs) - shares one offset within a binding broadcast; sharing across broadcasts would extend it diff --git a/rs/moq-ffi/src/media.rs b/rs/moq-ffi/src/media.rs index e769bb6bcdd..23c748352d7 100644 --- a/rs/moq-ffi/src/media.rs +++ b/rs/moq-ffi/src/media.rs @@ -286,7 +286,78 @@ pub struct MoqVideoInit { pub hint: Option, } -/// What a container publish needs: a format and its leading bytes. +/// Shares one source's timestamp offset across containers without keeping its broadcast open. +#[derive(uniffi::Object)] +pub struct MoqMediaTimebase { + broadcast: Weak, + // Stable identity even when a Rust caller unwraps the outer Arc and moves the handle. + key: Arc<()>, +} + +#[uniffi::export] +impl MoqMediaTimebase { + /// Create a source timebase owned by this broadcast. + #[uniffi::constructor] + pub fn new(broadcast: Arc) -> Result, MoqError> { + let handle = Arc::new(Self { + broadcast: Arc::downgrade(&broadcast), + key: Arc::new(()), + }); + broadcast.with_state(|state| { + state + .timebases + .insert(Arc::as_ptr(&handle.key) as usize, state.catalog.timebase()); + Ok(()) + })?; + Ok(handle) + } +} + +impl MoqMediaTimebase { + fn reserve( + &self, + broadcast: &MoqBroadcastProducer, + state: &crate::producer::BroadcastProducer, + ) -> Result, MoqError> { + if !std::ptr::eq(self.broadcast.as_ptr(), broadcast) { + return Err(MoqError::Codec { + reason: "timebase belongs to another broadcast".into(), + }); + } + let timebase = state + .timebases + .get(&(Arc::as_ptr(&self.key) as usize)) + .ok_or(MoqError::Closed)?; + Ok(timebase.reserve()) + } +} + +impl Drop for MoqMediaTimebase { + fn drop(&mut self) { + if let Some(broadcast) = self.broadcast.upgrade() + && let Some(state) = broadcast.state.lock().unwrap().as_mut() + { + state.timebases.remove(&(Arc::as_ptr(&self.key) as usize)); + } + } +} + +/// Reserve a container's catalog slot under the owner lock, from `timebase` when shared, so the +/// importer is constructed after the lock is released. +fn reserve_container( + broadcast: &MoqBroadcastProducer, + timebase: Option<&MoqMediaTimebase>, +) -> Result<(moq_net::broadcast::Producer, moq_mux::catalog::Reserved), MoqError> { + broadcast.with_state(|state| { + let reserved = match timebase { + Some(timebase) => timebase.reserve(broadcast, state)?, + None => state.catalog.reserve(), + }; + Ok((state.broadcast.clone(), reserved)) + }) +} + +/// A container format, its leading bytes, and an optional shared source timebase. /// /// A container publishes and describes its own tracks, so there is no label or hint here: a /// rendition field would have no single track to land on. @@ -296,6 +367,19 @@ pub struct MoqContainerInit { pub format: MoqContainerFormat, /// The leading chunk of the container, decoded immediately. May be empty. pub data: Vec, + /// A shared source timebase, or absent for an independent offset. + #[uniffi(default = None)] + pub timebase: Option>, +} + +/// A byte-stream container format and an optional shared source timebase. +#[derive(Clone, uniffi::Record)] +pub struct MoqContainerStreamInit { + /// The container format. + pub format: MoqContainerFormat, + /// A shared source timebase, or absent for an independent offset. + #[uniffi(default = None)] + pub timebase: Option>, } impl From for moq_mux::catalog::VideoHint { @@ -367,12 +451,6 @@ impl From for moq_mux::import::VideoInit { } } -impl From for moq_mux::import::ContainerInit { - fn from(init: MoqContainerInit) -> Self { - moq_mux::import::ContainerInit::new(init.format.into(), init.data) - } -} - pub(crate) fn convert_catalog(catalog: &moq_mux::catalog::hang::Catalog) -> MoqCatalog { let video = catalog .video @@ -720,21 +798,19 @@ impl MoqMediaTrackProducer { #[uniffi::export] impl MoqMediaContainerProducer { /// Construct an importer from this broadcast. + /// + /// A supplied timebase must belong to this broadcast; absence gives it an independent offset. #[uniffi::constructor] pub fn new( broadcast: &MoqBroadcastProducer, init: MoqContainerInit, ) -> Result, MoqError> { let _guard = crate::ffi::enter(); - let guard = broadcast.state.lock().unwrap(); - let state = guard.as_ref().ok_or(MoqError::Closed)?; - - let init: moq_mux::import::ContainerInit = init.into(); - let import = moq_mux::import::Container::new(state.broadcast.clone(), state.catalog.reserve(), &init).map_err( - |err| MoqError::Codec { - reason: format!("init failed: {err}"), - }, - )?; + let native = moq_mux::import::ContainerInit::new(init.format.into(), init.data); + let (target, reserved) = reserve_container(broadcast, init.timebase.as_deref())?; + let import = moq_mux::import::Container::new(target, reserved, &native).map_err(|err| MoqError::Codec { + reason: format!("init failed: {err}"), + })?; Ok(Arc::new(MoqMediaContainerProducer { inner: std::sync::Mutex::new(Some(ContainerProducer { import })), @@ -778,20 +854,20 @@ impl MoqMediaTrackStreamProducer { #[uniffi::export] impl MoqMediaContainerStreamProducer { /// Construct an importer from this broadcast. + /// + /// A supplied timebase must belong to this broadcast; absence gives it an independent offset. #[uniffi::constructor] pub fn new( broadcast: &MoqBroadcastProducer, - format: MoqContainerFormat, + init: MoqContainerStreamInit, ) -> Result, MoqError> { let _guard = crate::ffi::enter(); - let guard = broadcast.state.lock().unwrap(); - let state = guard.as_ref().ok_or(MoqError::Closed)?; - - let import = - moq_mux::import::ContainerStream::new(state.broadcast.clone(), state.catalog.reserve(), format.into()) - .map_err(|err| MoqError::Codec { - reason: format!("init failed: {err}"), - })?; + let (target, reserved) = reserve_container(broadcast, init.timebase.as_deref())?; + let import = moq_mux::import::ContainerStream::new(target, reserved, init.format.into()).map_err(|err| { + MoqError::Codec { + reason: format!("init failed: {err}"), + } + })?; Ok(Arc::new(MoqMediaContainerStreamProducer { inner: std::sync::Mutex::new(Some(ContainerStreamProducer { import })), @@ -1340,3 +1416,289 @@ mod catalog_tests { consumer.cancel(); } } + +#[cfg(all(test, not(target_arch = "wasm32")))] +mod timebase_tests { + use super::*; + use std::time::Duration; + + fn source() -> moq_mux::container::fmp4::Muxer { + let mut config = hang::catalog::VideoConfig::new(hang::catalog::VideoCodec::VP8); + config.coded_width = Some(16); + config.coded_height = Some(16); + moq_mux::container::fmp4::Muxer::video(&config).unwrap() + } + + fn fragment(source: &moq_mux::container::fmp4::Muxer, seconds: u64, tag: u8) -> bytes::Bytes { + source + .fragment( + 0, + &[moq_mux::container::Frame { + timestamp: moq_net::Timestamp::from_scale(seconds, 1).unwrap(), + payload: bytes::Bytes::from(vec![tag]), + keyframe: true, + duration: Some(moq_net::Timestamp::from_millis(20).unwrap()), + }], + ) + .unwrap() + } + + #[tokio::test(start_paused = true)] + async fn containers_of_one_source_keep_their_relative_media_time() { + for shared in [false, true] { + // Construct under the paused runtime, before exported entry points enter their worker. + let broadcast = + Arc::new(MoqBroadcastProducer::from_inner(moq_net::broadcast::Info::new().produce()).unwrap()); + let catalog = broadcast.with_state(|state| Ok(state.catalog.clone())).unwrap(); + let clock = catalog.clock(); + let consumer = broadcast.consume_inner().unwrap(); + let source = source(); + let init = source.init().unwrap().unwrap(); + let audio = moq_mux::container::fmp4::Muxer::audio(&hang::catalog::AudioConfig::new( + hang::catalog::AudioCodec::Opus, + 48_000, + 2, + )) + .unwrap(); + let audio_init = audio.init().unwrap().unwrap(); + let timebase = shared.then(|| MoqMediaTimebase::new(broadcast.clone()).unwrap()); + let chunks = MoqMediaContainerProducer::new( + &broadcast, + MoqContainerInit { + format: MoqContainerFormat::Fmp4, + data: init.to_vec(), + timebase: timebase.clone(), + }, + ) + .unwrap(); + let stream = MoqMediaContainerStreamProducer::new( + &broadcast, + MoqContainerStreamInit { + format: MoqContainerFormat::Fmp4, + timebase, + }, + ) + .unwrap(); + stream + .inner + .lock() + .unwrap() + .as_mut() + .unwrap() + .import + .decode(&audio_init) + .unwrap(); + tokio::time::advance(Duration::from_secs(1)).await; + let first = clock.now().as_micros(); + // Drive the private importers on the paused clock, without entering the unpaused FFI worker. + chunks + .inner + .lock() + .unwrap() + .as_mut() + .unwrap() + .import + .decode(&fragment(&source, 3600, 1)) + .unwrap(); + tokio::time::advance(Duration::from_secs(5)).await; + stream + .inner + .lock() + .unwrap() + .as_mut() + .unwrap() + .import + .decode(&fragment(&audio, 3602, 2)) + .unwrap(); + let mut readers = Vec::new(); + let snapshot = catalog.snapshot(); + let containers = + snapshot + .video + .renditions + .into_iter() + .map(|(name, config)| (name, moq_mux::catalog::hang::Container::try_from(&config).unwrap())) + .chain( + snapshot.audio.renditions.into_iter().map(|(name, config)| { + (name, moq_mux::catalog::hang::Container::try_from(&config).unwrap()) + }), + ); + for (name, container) in containers { + let track = consumer + .track(&name) + .unwrap() + .subscribe(moq_net::track::Subscription::default().with_max_delay(Duration::from_secs(30))) + .await + .unwrap(); + readers.push(moq_mux::container::Consumer::new(track, container)); + } + chunks.finish().unwrap(); + stream.finish().unwrap(); + let mut times = HashMap::new(); + for mut media in readers { + while let Some(read) = media.read().await.unwrap() { + if let moq_mux::container::Read::Frame { frame, .. } = read { + times.insert(frame.payload[0], frame.timestamp.as_micros()); + } + } + } + assert_eq!(times[&1], first); + assert_eq!( + times[&2], + first + if shared { 2_000_000 } else { 5_000_000 }, + "shared={shared}" + ); + } + } + + #[test] + fn a_timebase_refuses_foreign_or_closed_broadcasts() { + let owner = MoqBroadcastProducer::new().unwrap(); + let other = MoqBroadcastProducer::new().unwrap(); + let timebase = MoqMediaTimebase::new(owner.clone()).unwrap(); + assert!(matches!(MoqMediaContainerProducer::new(&other, MoqContainerInit { + format: MoqContainerFormat::Fmp4, data: Vec::new(), timebase: Some(timebase.clone()), + }), Err(MoqError::Codec { reason }) if reason.contains("another broadcast"))); + assert!( + matches!(MoqMediaContainerStreamProducer::new(&other, MoqContainerStreamInit { + format: MoqContainerFormat::Fmp4, timebase: Some(timebase.clone()), + }), Err(MoqError::Codec { reason }) if reason.contains("another broadcast")) + ); + owner.close().unwrap(); + assert!(matches!(MoqMediaTimebase::new(owner.clone()), Err(MoqError::Closed))); + assert!(matches!( + MoqMediaContainerStreamProducer::new( + &owner, + MoqContainerStreamInit { + format: MoqContainerFormat::Fmp4, + timebase: Some(timebase), + } + ), + Err(MoqError::Closed) + )); + } + + #[test] + fn moving_a_rust_handle_still_releases_its_owner_entry() { + let owner = MoqBroadcastProducer::new().unwrap(); + let handle = MoqMediaTimebase::new(owner.clone()).unwrap(); + let Ok(handle) = Arc::try_unwrap(handle) else { + panic!("timebase acquired a strong owner") + }; + drop(handle); + assert!(owner.with_state(|state| Ok(state.timebases.is_empty())).unwrap()); + } + + #[test] + fn temporary_timebases_leave_only_the_importers_reservation() { + let broadcast = MoqBroadcastProducer::new().unwrap(); + let chunks = MoqMediaContainerProducer::new( + &broadcast, + MoqContainerInit { + format: MoqContainerFormat::Fmp4, + data: Vec::new(), + timebase: Some(MoqMediaTimebase::new(broadcast.clone()).unwrap()), + }, + ) + .unwrap(); + let stream = MoqMediaContainerStreamProducer::new( + &broadcast, + MoqContainerStreamInit { + format: MoqContainerFormat::Fmp4, + timebase: Some(MoqMediaTimebase::new(broadcast.clone()).unwrap()), + }, + ) + .unwrap(); + assert!(broadcast.with_state(|state| Ok(state.timebases.is_empty())).unwrap()); + chunks.finish().unwrap(); + stream.finish().unwrap(); + } + + #[tokio::test(start_paused = true)] + async fn a_timebase_never_holds_the_publication_open() { + for close in [false, true] { + let broadcast = MoqBroadcastProducer::new().unwrap(); + let timebase = MoqMediaTimebase::new(broadcast.clone()).unwrap(); + let track = broadcast + .consume_inner() + .unwrap() + .track(hang::catalog::Catalog::DEFAULT_NAME) + .unwrap() + .subscribe(moq_net::track::Subscription::default()) + .await + .unwrap(); + let mut catalog = moq_mux::catalog::hang::Consumer::::new(track); + assert!(catalog.poll_next(&kio::Waiter::noop()).is_pending()); + let weak = Arc::downgrade(&broadcast); + if close { + broadcast.close().unwrap(); + } + drop(broadcast); + assert!(weak.upgrade().is_none(), "timebase retained its broadcast handle"); + assert!( + catalog.poll_next(&kio::Waiter::noop()).is_ready(), + "timebase retained catalog outputs" + ); + drop(timebase); + } + } + + #[tokio::test(start_paused = true)] + async fn an_unused_timebase_does_not_withhold_the_catalog() { + let owner = MoqBroadcastProducer::new().unwrap(); + let _timebase = MoqMediaTimebase::new(owner.clone()).unwrap(); + let track = owner + .consume_inner() + .unwrap() + .track(hang::catalog::Catalog::DEFAULT_NAME) + .unwrap() + .subscribe(moq_net::track::Subscription::default()) + .await + .unwrap(); + let mut reader = moq_mux::catalog::hang::Consumer::::new(track); + let catalog = MoqMediaCatalogProducer::new(owner.clone()).unwrap(); + catalog.set_section("app".into(), "{}".into()).unwrap(); + assert!(matches!( + reader.poll_next(&kio::Waiter::noop()), + std::task::Poll::Ready(Ok(Some(_))) + )); + } + + /// Sweep the owner table and the touched importer count independently. + #[test] + #[ignore = "benchmark, runs in Nightly"] + fn benchmark_timebase_reservation_fanout() { + eprintln!("timebases,containers,ns_per_container"); + for entries in [1, 32, 1024] { + let owner = MoqBroadcastProducer::new().unwrap(); + let timebases: Vec<_> = (0..entries) + .map(|_| MoqMediaTimebase::new(owner.clone()).unwrap()) + .collect(); + let reserve = || { + let importer = MoqMediaContainerStreamProducer::new( + &owner, + MoqContainerStreamInit { + format: MoqContainerFormat::Fmp4, + timebase: Some(std::hint::black_box(timebases.last().unwrap()).clone()), + }, + ) + .unwrap(); + importer.finish().unwrap(); + }; + for _ in 0..100 { + reserve(); + } + for touched in [1, 16, 256] { + let start = std::time::Instant::now(); + for _ in 0..1000 { + for _ in 0..touched { + reserve(); + } + } + let nanos = start.elapsed().as_nanos() as f64 / (1000 * touched) as f64; + eprintln!("{entries},{touched},{nanos:.1}"); + } + owner.close().unwrap(); + } + } +} diff --git a/rs/moq-ffi/src/producer.rs b/rs/moq-ffi/src/producer.rs index 19b79e08c08..d43ed780ebf 100644 --- a/rs/moq-ffi/src/producer.rs +++ b/rs/moq-ffi/src/producer.rs @@ -78,6 +78,8 @@ pub(crate) struct BroadcastProducer { // Carries the untyped `Extra` extension so callers can attach application catalog // sections by name (the only extension shape that crosses the FFI boundary). pub(crate) catalog: moq_mux::catalog::Producer, + // Core timebases own catalog outputs, so the broadcast holds them and binding handles stay weak. + pub(crate) timebases: std::collections::HashMap>, } #[derive(uniffi::Object)] @@ -137,7 +139,11 @@ impl MoqBroadcastProducer { moq_mux::catalog::Config::default().with_catalog(moq_mux::catalog::hang::Catalog::::default()); let catalog = moq_mux::catalog::Producer::new(&mut broadcast, config)?; Ok(Self { - state: std::sync::Mutex::new(Some(BroadcastProducer { broadcast, catalog })), + state: std::sync::Mutex::new(Some(BroadcastProducer { + broadcast, + catalog, + timebases: Default::default(), + })), }) } diff --git a/sh/gh/nightly.sh b/sh/gh/nightly.sh index dd245f38d7d..8f512ea37ec 100755 --- a/sh/gh/nightly.sh +++ b/sh/gh/nightly.sh @@ -31,6 +31,9 @@ case "${1:-}" in run just rs test -p moq-archive -p moq-mux --no-fail-fast \ -E 'test(benchmark_timeline_fetch_fanout) | test(benchmark_damage_pid_fanout)' \ --run-ignored only --success-output immediate + # Codecs are irrelevant to timebase reservation, so skip building them. + run just rs test -p moq-ffi --no-default-features -E 'test(benchmark_timebase_reservation_fanout)' \ + --run-ignored only --success-output immediate # moq-gst's catalog bench shares a target name with moq-mux's, so it runs on its own. run just rs bench-gst-catalog -- --quick run just rs test -p moq-cli -E 'test(benchmark_stream_import)' --run-ignored only --success-output immediate diff --git a/swift/Sources/Moq/Media.swift b/swift/Sources/Moq/Media.swift index f2bcb18fd7e..d2d6dc47ddf 100644 --- a/swift/Sources/Moq/Media.swift +++ b/swift/Sources/Moq/Media.swift @@ -48,8 +48,41 @@ public enum Media { public typealias AudioInit = MoqAudioInit /// A video codec, its initialization bytes, label, and hints. public typealias VideoInit = MoqVideoInit - /// A container format and its leading bytes. - public typealias ContainerInit = MoqContainerInit + /// Shares one source's timestamp offset without keeping its broadcast open. + public final class Timebase: Sendable { + let ffi: MoqMediaTimebase + /// Create a shared source timebase owned by this broadcast. + public init(broadcast: BroadcastProducer) throws { ffi = try MoqMediaTimebase(broadcast: broadcast.ffi) } + } + /// A container format, its leading bytes, and an optional shared source timebase. + public struct ContainerInit: Sendable { + /// The container format. + public var format: ContainerFormat + /// The leading container bytes. + public var data: [UInt8] + /// A shared source timebase, or nil for an independent offset. + public var timebase: Timebase? + /// Configure a container's leading bytes and source timeline. + public init(format: ContainerFormat, data: [UInt8], timebase: Timebase? = nil) { + self.format = format + self.data = data + self.timebase = timebase + } + var ffi: MoqContainerInit { MoqContainerInit(format: format, data: data, timebase: timebase?.ffi) } + } + /// A byte-stream container format and an optional shared source timebase. + public struct ContainerStreamInit: Sendable { + /// The container format. + public var format: ContainerFormat + /// A shared source timebase, or nil for an independent offset. + public var timebase: Timebase? + /// Configure a container byte stream's source timeline. + public init(format: ContainerFormat, timebase: Timebase? = nil) { + self.format = format + self.timebase = timebase + } + var ffi: MoqContainerStreamInit { MoqContainerStreamInit(format: format, timebase: timebase?.ffi) } + } /// A track name, its container, and live delivery options. public typealias TrackConfig = MoqMediaTrackConfig /// A fetched group's name, sequence, container, and delivery options. @@ -257,7 +290,7 @@ public enum Media { /// Import complete container chunks into this broadcast. public convenience init(broadcast: BroadcastProducer, initData: ContainerInit) throws { - self.init(try MoqMediaContainerProducer(broadcast: broadcast.ffi, init: initData)) + self.init(try MoqMediaContainerProducer(broadcast: broadcast.ffi, init: initData.ffi)) } init(_ ffi: MoqMediaContainerProducer) { self.ffi = ffi @@ -295,8 +328,8 @@ public enum Media { let ffi: MoqMediaContainerStreamProducer /// Import a container byte stream into this broadcast. - public convenience init(broadcast: BroadcastProducer, format: ContainerFormat) throws { - self.init(try MoqMediaContainerStreamProducer(broadcast: broadcast.ffi, format: format)) + public convenience init(broadcast: BroadcastProducer, initData: ContainerStreamInit) throws { + self.init(try MoqMediaContainerStreamProducer(broadcast: broadcast.ffi, init: initData.ffi)) } init(_ ffi: MoqMediaContainerStreamProducer) { self.ffi = ffi diff --git a/swift/Tests/MoqTests/SmokeTests.swift b/swift/Tests/MoqTests/SmokeTests.swift index 710dedeaaee..4caff0d7b26 100644 --- a/swift/Tests/MoqTests/SmokeTests.swift +++ b/swift/Tests/MoqTests/SmokeTests.swift @@ -9,6 +9,17 @@ private func nextRoute(_ announced: AnnounceConsumer) async throws -> AnnounceEv } final class SmokeTests: XCTestCase { + func testContainerTimebaseBelongsToOneBroadcast() throws { + let owner = try BroadcastProducer() + let other = try BroadcastProducer() + let timebase = try Media.Timebase(broadcast: owner) + XCTAssertThrowsError(try Media.ContainerProducer(broadcast: other, initData: Media.ContainerInit(format: .fmp4, data: [], timebase: timebase))) + XCTAssertThrowsError(try Media.ContainerStreamProducer(broadcast: other, initData: Media.ContainerStreamInit(format: .fmp4, timebase: timebase))) + try owner.close() + XCTAssertThrowsError(try Media.Timebase(broadcast: owner)) + try other.close() + } + func testStreamAbortPreservesProtocolDetails() async throws { let broadcast = try BroadcastProducer() let track = try broadcast.publishTrack(name: "errors")