From 0ec579d7eb3191da25027961d52167981023d7ad Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 3 Nov 2026 03:23:32 -0800 Subject: [PATCH 1/6] chore(quest): claim quest/m1/ffi-unsupported-config.md Quest-Claim: 8c96e18fd7c473ab From a686ce3c41d04eef6c102944d41024bb1c22b40e Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 3 Nov 2026 03:36:59 -0800 Subject: [PATCH 2/6] feat(ffi): type media decoder setup refusals Co-Authored-By: GPT-6.1 Sol --- quest/m1/README.md | 1 - quest/m1/ffi-unsupported-config.md | 33 ------------------------------ 2 files changed, 34 deletions(-) delete mode 100644 quest/m1/ffi-unsupported-config.md diff --git a/quest/m1/README.md b/quest/m1/README.md index 360826fa74b..750c67f5bf4 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -191,7 +191,6 @@ per-frame CPU growth since #5926. - [Authored tracks default to a 30 s max-age](/quest/m1/max-age-defaults.md) - raw and media tracks advertise 30 s unless their author chooses otherwise, with explicit unlimited in every binding - [HLS export lists a same-codec reconfigure's first group under the new init](/quest/m1/hls-reinit-same-codec.md) - the hand-over pick, whichever of the catalog and the records arrives first, after the catalog `hls` removal is planned - [A cancelled MoqTrackDemand wait never loses the next change](/quest/m1/demand-cancel-race.md) - cancelling a `MoqTrackDemand::wanted_changed` call, from any binding, never consumes a demand change -- [moq-ffi reports an unsupported media configuration as a typed error](/quest/m1/ffi-unsupported-config.md) - `MoqAudioConsumer::subscribe` and the matching video subscribe fail with a typed "unsupported configuration" error - [A live keyframe interval change never outruns the declared HLS duration](/quest/m1/js-hls-keyframe-duration.md) - raising a live keyframe interval, even to infinite, never pushes a segment past the declared HLS target duration, and the browser interop cell asserts the catalog `hls` field - [A request stream that opens after its deadline is aborted once and never sends](/quest/m1/js-request-deadline.md) - A `@moq/net` IETF request whose stream finishes opening only after its deadline fired is aborted exactly once, through its `RequestStream`, and never writes its request - [One Ed25519 public key type with one z-base-32 codec](/quest/m1/mesh-key-codec.md) - `moq_auth::mesh::EndpointId` is merged into `moq_sign::PublicKey` diff --git a/quest/m1/ffi-unsupported-config.md b/quest/m1/ffi-unsupported-config.md deleted file mode 100644 index a84c9998a07..00000000000 --- a/quest/m1/ffi-unsupported-config.md +++ /dev/null @@ -1,33 +0,0 @@ -# [S] moq-ffi reports an unsupported media configuration as a typed error - -## Goal - -`MoqAudioConsumer::subscribe` and the matching video subscribe fail with a -typed "unsupported configuration" error (a distinct `MoqError` variant, not a -reason string) when moq-audio or moq-video refuses a rendition's codec, -layout, or description. The OBS source falls through to the next ranked -rendition on that error and drops its copy of moq-audio's codec checks. - -## Plan - -Decided 2026-10-31 (user, /quest-plan of the follow-ups from the 2026-10-31 -/quest-complete run), from -[moq-dev/moq#7331](https://github.com/moq-dev/moq/pull/7331). - -Milestone: ✅ m1 (moved from m2). Not chosen: m2. - -- [moq-dev/moq#7331](https://github.com/moq-dev/moq/pull/7331) (merged) gates audio in OBS with `moq_source_audio_decodes` (opus, pcm, mono - or stereo AAC-LC), mirroring moq-audio's rules, because moq-ffi reports a - setup refusal only as an async `MoqError::Audio { reason }` - (`rs/moq-ffi/src/error.rs:235`; video at `:243`). A configuration moq-audio - refuses under a supported codec string, such as an AAC description that - declares SBR, still discards the candidate without trying the next. -- Add the typed variant, raised from `subscribe` (`rs/moq-ffi/src/audio.rs:645`, - `video.rs:1293` at be39188000) wherever moq-audio or moq-video refuses the - config before decoding starts. Mirror it in moq-c and the wrappers. -- In OBS, fall through on the typed error and delete the mirrored gate and - its tests. -- Not in scope: falling through after a later async failure (subscribe - rejected by the peer, first decode fails), which [moq-dev/moq#7331](https://github.com/moq-dev/moq/pull/7331) also listed. - -Public API: adds a `MoqError` variant (bindings and moq-c). Wire: none. From 858bc2fb44661459ec4e5313968ab9e97fcfea21 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 3 Nov 2026 03:37:06 -0800 Subject: [PATCH 3/6] feat(ffi): expose typed configuration refusals and OBS rendition fallback Co-Authored-By: GPT-6.1 Sol --- c/moq/MIGRATE.md | 6 ++ cpp/moq/MIGRATE.md | 4 + cpp/obs/src/moq-source.cpp | 58 +++++++------- cpp/obs/test/moq-source-test.cpp | 34 ++++----- dart/moq/MIGRATE.md | 4 + dart/moq_ffi/MIGRATE.md | 4 + dart/moq_ffi/lib/src/moq.dart | 48 +++++++++++- doc/bin/obs.md | 2 +- doc/lib/c/index.md | 2 +- doc/lib/cpp/index.md | 2 +- doc/lib/dart/index.md | 2 +- doc/lib/go/index.md | 2 +- doc/lib/kt/index.md | 2 +- doc/lib/py/index.md | 2 +- doc/lib/swift/index.md | 2 +- go/wrapper/MIGRATE.md | 4 + go/wrapper/errors.go | 2 + go/wrapper/errors_test.go | 1 + kt/moq-ffi/MIGRATE.md | 4 + kt/moq/MIGRATE.md | 4 + py/moq-ffi/MIGRATE.md | 4 + py/moq-rs/MIGRATE.md | 4 + rs/moq-c/src/audio.rs | 10 ++- rs/moq-c/src/error.rs | 36 ++++++++- rs/moq-c/src/video.rs | 5 +- rs/moq-ffi/MIGRATE.md | 4 + rs/moq-ffi/src/audio.rs | 43 +++++++---- rs/moq-ffi/src/error.rs | 23 +++++- rs/moq-ffi/src/test.rs | 113 ++++++++++++++++++++++++++++ rs/moq-ffi/src/video.rs | 20 +++-- rs/moq-video/MIGRATE.md | 4 + rs/moq-video/src/decode/consumer.rs | 6 +- rs/moq-video/src/error.rs | 4 + swift/MIGRATE.md | 4 + 34 files changed, 383 insertions(+), 86 deletions(-) diff --git a/c/moq/MIGRATE.md b/c/moq/MIGRATE.md index e2a9d73e5cd..76ad065ead2 100644 --- a/c/moq/MIGRATE.md +++ b/c/moq/MIGRATE.md @@ -2,6 +2,12 @@ How to update your code for each breaking change, newest first. +## Unreleased + +### Media setup refusals are typed + +Audio and video subscribe setup now reports `MOQ_ERROR_UNSUPPORTED_CONFIG` when the decoder refuses a codec, layout, or description. Handle this variant to try another rendition instead of inspecting an audio/video error message or `Unsupported`. Later peer and decode failures keep their existing errors. Regenerate bindings and rebuild the matching native library together. + ## moq-c 0.7, the hand-written ABI The hand-written crate never published as moq-c: a libmoq 0.6 user applies these entries before moving to the generated API. diff --git a/cpp/moq/MIGRATE.md b/cpp/moq/MIGRATE.md index d561d680531..942031f8b62 100644 --- a/cpp/moq/MIGRATE.md +++ b/cpp/moq/MIGRATE.md @@ -2,6 +2,10 @@ ## Unreleased +### Media setup refusals are typed + +Audio and video subscribe setup now reports `moq::Error::kUnsupportedConfig` when the decoder refuses a codec, layout, or description. Handle this variant to try another rendition instead of inspecting an audio/video error message or `Unsupported`. Later peer and decode failures keep their existing errors. Regenerate bindings and rebuild the matching native library together. + ### Announcement captures are required ([#7484](https://github.com/moq-dev/moq/pull/7484)) `moq::Announce.captures` is `std::vector` instead of an optional vector. Remove optional checks and dereferences; an empty vector means the filter has no wildcards. Regenerate bindings and rebuild with the matching native library. diff --git a/cpp/obs/src/moq-source.cpp b/cpp/obs/src/moq-source.cpp index 626f96e3b6e..3669a55ab47 100644 --- a/cpp/obs/src/moq-source.cpp +++ b/cpp/obs/src/moq-source.cpp @@ -119,6 +119,12 @@ struct AudioLayout { uint32_t sample_rate = 0; }; +// Own the ranked snapshot while setup asynchronously tries each rendition once. +struct AudioSelection { + std::vector> candidates; + size_t next = 0; +}; + // One subscribed track: what it is, the consumer once subscribed, and the pending // call that subscribes or reads its next frame. Dropping it cancels that call. struct Track { @@ -140,6 +146,7 @@ struct Track { // Video reads encoded frames to decode here; audio reads PCM moq-audio decoded. std::shared_ptr consumer; std::shared_ptr audio_consumer; + std::shared_ptr audio_selection; std::optional call; }; @@ -229,6 +236,8 @@ static void moq_source_subscribe_video(struct moq_source *ctx, const std::shared static void moq_source_clear_audio_locked(struct moq_source *ctx); static void moq_source_subscribe_audio(struct moq_source *ctx, const std::shared_ptr &conn, const moq::Catalog &catalog); +static void moq_source_try_audio(struct moq_source *ctx, const std::shared_ptr &conn, + const std::shared_ptr &selection); static Sent moq_source_send_packet(VideoDecoder &decoder, const moq::MediaFrame &frame_data); static Decoded moq_source_receive_frame(VideoDecoder &decoder); @@ -865,32 +874,16 @@ static void moq_source_on_audio_subscribed(struct moq_source *ctx, const std::sh if (!result) { LOG_ERROR("Failed to subscribe to Audio track: %s", result.error().to_string().c_str()); moq_source_discard_candidate(conn, track); + if (std::holds_alternative(result.error().get_variant())) + moq_source_try_audio(ctx, conn, track->audio_selection); return; } + track->audio_selection.reset(); track->audio_consumer = *result; LOG_INFO("Subscribed to Audio track successfully"); moq_source_read_audio(ctx, conn, track); } -// Whether moq-audio decodes the rendition: Opus, PCM, or mono or stereo AAC-LC (the one AAC -// profile and the layouts it has). moq-ffi reports a refusal only once the subscribe fails, -// as an audio error with no kind, so check here to let an unsupported rendition fall through. -// A configuration moq-audio still refuses, such as a malformed OpusHead, discards the -// candidate when it subscribes. -static bool moq_source_audio_decodes(const moq::Audio &config) -{ - const auto &codec = config.codec; - if (codec == "opus" || codec == "pcm") - return true; - // hang reads the AAC profile as a decimal, so `mp4a.40.02` is AAC-LC too. - const std::string aac = "mp4a.40."; - if (codec.rfind(aac, 0) != 0) - return false; - const auto profile = codec.find_first_not_of('0', aac.size()); - return profile != std::string::npos && codec.compare(profile, std::string::npos, "2") == 0 && - (config.channel_count == 1 || config.channel_count == 2); -} - // The channels moq-audio should remix a rendition to, and where OBS puts them. A count // names moq-audio's default layout by the WAVE convention: 3 is 2.1, 4 quad, 5 5.0, 6 5.1, // 7 6.1, 8 7.1. OBS has no quad, 5.0, or 6.1 (its 4.0 and 4.1 put a center where quad has @@ -1029,22 +1022,32 @@ static void moq_source_subscribe_audio(struct moq_source *ctx, const std::shared return; } - for (const auto *rendition : candidates) { + auto selection = std::make_shared(); + selection->candidates.reserve(candidates.size()); + for (const auto *rendition : candidates) + selection->candidates.emplace_back(rendition->first, rendition->second); + moq_source_try_audio(ctx, conn, selection); +} + +static void moq_source_try_audio(struct moq_source *ctx, const std::shared_ptr &conn, + const std::shared_ptr &selection) +{ + while (selection->next < selection->candidates.size()) { + const auto *rendition = &selection->candidates[selection->next++]; const auto &id = rendition->first; const auto &config = rendition->second; if (moq_source_same_audio(conn->audio.get(), id, config) && conn->audio->instance == conn->instance) { conn->pending_audio.reset(); return; } - if (moq_source_same_audio(conn->pending_audio.get(), id, config)) + if (moq_source_same_audio(conn->pending_audio.get(), id, config)) { + // Keep the in-flight setup, but fall through against the newest catalog if it refuses. + if (!conn->pending_audio->audio_consumer) + conn->pending_audio->audio_selection = selection; return; - - // A codec moq-audio can't decode, or a layout OBS can't place, falls through to the next rendition. - if (!moq_source_audio_decodes(config)) { - LOG_ERROR("Unsupported audio codec '%s' with %u channels in rendition %s", config.codec.c_str(), - config.channel_count, id.c_str()); - continue; } + + // OBS's speaker layout is independent of the decoder's capabilities. auto layout = moq_source_audio_layout(config.channel_count); if (!layout) { LOG_ERROR("Unsupported audio channel count %u in rendition %s: OBS has no layout for it", @@ -1063,6 +1066,7 @@ static void moq_source_subscribe_audio(struct moq_source *ctx, const std::shared track->instance = conn->instance; track->audio_config = config; track->audio_layout = *layout; + track->audio_selection = selection; conn->pending_audio = track; moq::AudioDecoderOutput output{}; diff --git a/cpp/obs/test/moq-source-test.cpp b/cpp/obs/test/moq-source-test.cpp index 425b6b1a124..7f8a86422d5 100644 --- a/cpp/obs/test/moq-source-test.cpp +++ b/cpp/obs/test/moq-source-test.cpp @@ -1205,23 +1205,6 @@ int main() CHECK((names(moq_source_candidates(moq_source_ranked_audio(audios), held)) == std::vector{"c-low"})); CHECK(moq_source_candidates(moq_source_ranked_audio(audios), none).empty()); - - // The codecs moq-audio decodes, with AAC-LC in either spelling hang parses. - const auto decodes = [&](const char *codec, uint32_t channels) { - auto config = base_audio; - config.codec = codec; - config.channel_count = channels; - return moq_source_audio_decodes(config); - }; - for (const char *codec : {"opus", "pcm", "mp4a.40.2", "mp4a.40.02"}) - CHECK(decodes(codec, 2)); - for (const char *codec : {"flac", "mp4a.40.5", "mp4a.40.20", "mp4a.40.", "mp4a.40.0"}) - CHECK(!decodes(codec, 2)); - // moq-audio decodes AAC only in mono or stereo, unlike Opus and PCM. - CHECK(decodes("mp4a.40.2", 1)); - CHECK(!decodes("mp4a.40.2", 6)); - CHECK(decodes("opus", 6)); - CHECK(decodes("pcm", 6)); } report("renditions rank like hang"); @@ -1273,6 +1256,17 @@ int main() he_aac_audio.description.reset(); he_aac_audio.bitrate = 5500000; catalog.audio.emplace("he-aac", he_aac_audio); + // A recognized codec with a malformed description is also a setup refusal. + auto malformed_audio = audio; + malformed_audio.description = std::vector{}; + malformed_audio.bitrate = 5600000; + catalog.audio.emplace("malformed", malformed_audio); + // AAC-LC by name, but its description declares SBR, which moq-audio refuses. + auto sbr_audio = audio; + sbr_audio.codec = "mp4a.40.2"; + sbr_audio.description = std::vector{0x12, 0x10, 0x56, 0xe5, 0x98}; + sbr_audio.bitrate = 5400000; + catalog.audio.emplace("sbr", sbr_audio); // 5.1 AAC-LC: OBS has the layout, but moq-audio decodes AAC only in mono or stereo. auto surround_aac_audio = audio; surround_aac_audio.codec = "mp4a.40.2"; @@ -1295,11 +1289,15 @@ int main() moq_source_subscribe_video(ctx, conn, catalog); moq_source_subscribe_audio(ctx, conn, catalog); CHECK(conn->pending_video && conn->pending_video->id == "c"); - CHECK(conn->pending_audio && conn->pending_audio->id == "c"); + // Selection continues asynchronously when setup refuses a rendition. // The playing tracks stay until the replacement delivers. CHECK(conn->video && conn->video->id == video_id); CHECK(conn->audio && conn->audio->id == audio_id); } + CHECK(publisher.WriteUntil([&] { + std::lock_guard lock(ctx->mutex); + return ctx->connection->audio && ctx->connection->audio->id == "c"; + })); destroySource(source); } report("disabled and undecodable renditions fall through"); diff --git a/dart/moq/MIGRATE.md b/dart/moq/MIGRATE.md index f6279a8e838..f38243a082e 100644 --- a/dart/moq/MIGRATE.md +++ b/dart/moq/MIGRATE.md @@ -4,6 +4,10 @@ How to update your code for each breaking change, newest first. ## Unreleased +### Media setup refusals are typed + +Audio and video subscribe setup now reports `UnsupportedConfigMoqException` when the decoder refuses a codec, layout, or description. Handle this variant to try another rendition instead of inspecting an audio/video error message or `Unsupported`. Later peer and decode failures keep their existing errors. Regenerate bindings and rebuild the matching native library together. + ### `Transport.iroh` is removed ([#7345](https://github.com/moq-dev/moq/pull/7345)) Native sessions no longer arrive over iroh, so `Transport` loses its `iroh` value. Drop the case, and regenerate bindings and rebuild with the matching native library. diff --git a/dart/moq_ffi/MIGRATE.md b/dart/moq_ffi/MIGRATE.md index 612358bb729..337a486424e 100644 --- a/dart/moq_ffi/MIGRATE.md +++ b/dart/moq_ffi/MIGRATE.md @@ -2,6 +2,10 @@ ## Unreleased +### Media setup refusals are typed + +Audio and video subscribe setup now reports `UnsupportedConfigMoqException` when the decoder refuses a codec, layout, or description. Handle this variant to try another rendition instead of inspecting an audio/video error message or `Unsupported`. Later peer and decode failures keep their existing errors. Regenerate bindings and rebuild the matching native library together. + ### Follow the core API migration guide These bindings are generated from moq-ffi. Apply every change in the diff --git a/dart/moq_ffi/lib/src/moq.dart b/dart/moq_ffi/lib/src/moq.dart index afad90c9868..78b15250985 100644 --- a/dart/moq_ffi/lib/src/moq.dart +++ b/dart/moq_ffi/lib/src/moq.dart @@ -5763,6 +5763,12 @@ class FfiConverterMoqException { lifted.value, lifted.bytesRead - subview.offsetInBytes + 4, ); + case 34: + final lifted = UnsupportedConfigMoqException.read(subview); + return LiftRetVal( + lifted.value, + lifted.bytesRead - subview.offsetInBytes + 4, + ); default: throw UniffiInternalError( UniffiInternalError.unexpectedEnumCase, @@ -6928,6 +6934,44 @@ class UnsupportedCatalogMoqException extends MoqException { } } +class UnsupportedConfigMoqException extends MoqException { + final String reason; + UnsupportedConfigMoqException(String this.reason); + UnsupportedConfigMoqException._(String this.reason); + static LiftRetVal read(Uint8List buf) { + int new_offset = buf.offsetInBytes; + final reason_lifted = FfiConverterString.read( + Uint8List.view(buf.buffer, new_offset), + ); + final reason = reason_lifted.value; + new_offset += reason_lifted.bytesRead; + return LiftRetVal(UnsupportedConfigMoqException._(reason), new_offset); + } + + @override + RustBuffer lower() { + final buf = Uint8List(allocationSize()); + write(buf); + return toRustBuffer(buf); + } + + @override + int allocationSize() { + return FfiConverterString.allocationSize(reason) + 4; + } + + @override + int write(Uint8List buf) { + buf.buffer.asByteData(buf.offsetInBytes).setInt32(0, 34); + int new_offset = buf.offsetInBytes + 4; + new_offset += FfiConverterString.write( + reason, + Uint8List.view(buf.buffer, new_offset), + ); + return new_offset; + } +} + class MoqExceptionErrorHandler extends UniffiRustCallStatusErrorHandler { @override Exception lift(RustBuffer errorBuf) { @@ -22422,7 +22466,7 @@ void _checkApiChecksums() { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } if (uniffi_moq_ffi_checksum_constructor_moqaudioconsumer_subscribe() != - 10630) { + 42847) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } if (uniffi_moq_ffi_checksum_constructor_moqaudioencoder_new() != 52616) { @@ -22509,7 +22553,7 @@ void _checkApiChecksums() { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } if (uniffi_moq_ffi_checksum_constructor_moqvideoconsumer_subscribe() != - 15507) { + 20518) { throw UniffiInternalError.panicked("UniFFI API checksum mismatch"); } if (uniffi_moq_ffi_checksum_constructor_moqvideoencoder_new() != 22531) { diff --git a/doc/bin/obs.md b/doc/bin/obs.md index bb2bbe2128d..b91e8ea8992 100644 --- a/doc/bin/obs.md +++ b/doc/bin/obs.md @@ -17,7 +17,7 @@ reconnects keep the same instance. A stop/start, or an OBS auto-reconnect after the client gives up, republishes the broadcast under a new instance, which viewers see as a new stream. -MoQ Source plays the best enabled audio and video rendition it can decode and place. It follows catalog changes while keeping the current audio and video playing until a replacement produces decoded output. A failed replacement leaves the current rendition playing. Disabling every rendition of a media kind keeps the one already playing; removing the media kind from the catalog clears it. It also follows a restarted or replaced publisher, including a sibling broadcast the catalog points at, playing the new one from its first keyframe. +MoQ Source plays the best enabled audio and video rendition it can decode and place. It follows catalog changes while keeping the current audio and video playing until a replacement produces decoded output. A decoder setup refusal tries the next ranked rendition, including when a supported codec name carries a description the decoder cannot use. A later peer or decode failure leaves the current rendition playing. Disabling every rendition of a media kind keeps the one already playing; removing the media kind from the catalog clears it. It also follows a restarted or replaced publisher, including a sibling broadcast the catalog points at, playing the new one from its first keyframe. The source plays Opus, AAC-LC (mono or stereo), and PCM audio. A channel count names its speakers by the WAVE convention: 1, 2, 3 (2.1), 6 (5.1), and 8 (7.1) play on the matching OBS layout, while quad and 5.0 are upmixed to 5.1 and 6.1 to 7.1, which OBS lacks. Other counts are refused. diff --git a/doc/lib/c/index.md b/doc/lib/c/index.md index a9b5d6533cc..4c8adbf5863 100644 --- a/doc/lib/c/index.md +++ b/doc/lib/c/index.md @@ -110,7 +110,7 @@ inside. The header is the reference: each function carries a doc comment. - **Timestamps.** A `moq_timestamp` is exact: `value` units at `scale` units per second, so a 90 kHz tick survives a read and republish. Frames, datagrams, and JSON values point `timestamp` at theirs, NULL on an untimed track and valid as long as the payload. Tracks moq-c creates are timed, so their raw writes need one. JSON writes, including window pushes and pops, take one too, converted to their track's milliseconds; NULL stamps the broadcast clock's current time. A zero scale or an out-of-range value fails with `MOQ_ERROR_TIMESTAMP_OVERFLOW`. - **JSON values.** `moq_consume_json_value` fills `moq_json_value` with the document and its frame's timestamp. A snapshot consumer's callback fires for each state in order, but a group superseded before it is read is skipped. - **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. +- **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. - **Stats.** `moq_session_stats()` fills `moq_connection_stats` with `rtt_us`, `estimated_send_rate_bps`, and the byte and packet counters (`bytes_sent`, `bytes_received`, `bytes_lost`, `packets_sent`, `packets_received`, `packets_lost`). Each has a `_valid` flag, false when the transport does not report it, which is not the same as zero. `moq_session_snapshot()` adds the negotiated `protocol`. A failed dial or dropped connection reaches the session's `on_state` with its `failure` code, and `moq_error()` gives the reason during that callback. Hold the handle returned by `moq_session_recv_bandwidth()` to request receive estimates. `moq_bandwidth_consumer_peek()` reads the estimate and `moq_bandwidth_consumer_changed()` waits for a change. `moq_bandwidth_consumer_close()` releases demand; the last consumer stops PROBE. Stats snapshots do not request it. - **Demand.** A watcher from `moq_publish_track_demand()` (or the media, video, and audio variants) calls back `MOQ_DEMAND_WANTED` or `MOQ_DEMAND_UNWANTED`, again whenever the wanted group moves. `moq_publish_demand_wanted()` reads that group: start a new one once it passes your largest. Set `refresh` in `moq_track_info` to have a joining subscriber ask for a new group once the newest has grown past `refresh` times its first frame. A producer publishes everything you write, subscribed or not, so a late subscriber can fetch the recent past. Capturing only while the watcher reports `MOQ_DEMAND_WANTED` is an opt-in that saves the encode but leaves nothing from before the first subscriber. - **Disabled renditions.** A rendition with `enabled: false` has no frames coming until its publisher re-enables it. Query the latest catalog with `moq_consume_audio_enabled` or `moq_consume_video_enabled` before selecting a rendition and opening a decoder. Keep one already playing while every rendition of its kind is disabled: the convenience decoders accept a disabled configuration, and a re-enable, such as an unmute, then plays without a resubscribe. Among the video renditions you can decode, prefer the highest `preference`; `0` is the default and `-1` marks a compatibility transcode. diff --git a/doc/lib/cpp/index.md b/doc/lib/cpp/index.md index 4b139d69663..0f41dae3e37 100644 --- a/doc/lib/cpp/index.md +++ b/doc/lib/cpp/index.md @@ -207,7 +207,7 @@ future completed, which is the executor thread. ## Disabled renditions -A rendition with `enabled: false` has no frames coming until its publisher re-enables it. Select an enabled rendition from the latest catalog before opening a decoder. Keep one already playing while every rendition of its kind is disabled: the convenience decoders accept a disabled configuration, and a re-enable, such as an unmute, then plays without a resubscribe. Among the video renditions you can decode, prefer the highest `preference`; `0` is the default and `-1` marks a compatibility transcode. +A rendition with `enabled: false` has no frames coming until its publisher re-enables it. Select an enabled rendition from the latest catalog before opening a decoder. Keep one already playing while every rendition of its kind is disabled: the convenience decoders accept a disabled configuration, and a re-enable, such as an unmute, then plays without a resubscribe. Among the video renditions you can decode, prefer the highest `preference`; `0` is the default and `-1` marks a compatibility transcode. Audio and video subscribe setup returns `moq::Error::kUnsupportedConfig` when the decoder refuses the codec, layout, or description; a player can then try its next ranked rendition. Later peer or decode failures do not report that setup refusal. ## Bandwidth estimates diff --git a/doc/lib/dart/index.md b/doc/lib/dart/index.md index 106c767cb72..ac3f254e1e1 100644 --- a/doc/lib/dart/index.md +++ b/doc/lib/dart/index.md @@ -158,7 +158,7 @@ shows which module holds each. - **Authorization.** On `moq-lite-07-wip` (opt in with `ConnectOptions(versions: ...)`) and on moq-transport draft-18+ with the [MoQ Auth extension](/draft/moq-auth), listen to `moq.grants().updates()` for the `Grant` the relay sent back and each change, `null` until it answers and while a client session reconnects. - **Tokens.** Pass `ConnectOptions(tokens: [...])` instead of putting the credential in the URL. The first is the connection credential, sent in SETUP and, while an offered version can't carry it there (lite before 07), as the URL's `?jwt=`; each other token widens the grant over AUTH. `moq.tokens().set_(tokens: [...])` replaces them before they expire: the next dial presents them, a live AUTH session at once, and after an authorization refusal the session redials only if they changed. `await tokens().answered()` returns once the relay accepts them and throws its refusal with the relay's code. A `?jwt=` already in the URL stays the connection credential, which is how to reach a relay older than this release. - **Errors.** Read diagnostic payloads from `reason` and structured protocol failures from `details`. -- **Disabled renditions.** A rendition with `enabled: false` has no frames coming until its publisher re-enables it. Select an enabled rendition from the latest catalog before opening a decoder. Keep one already playing while every rendition of its kind is disabled: the convenience decoders accept a disabled configuration, and a re-enable, such as an unmute, then plays without a resubscribe. Among the video renditions you can decode, prefer the highest `preference`; `0` is the default and `-1` marks a compatibility transcode. +- **Disabled renditions.** A rendition with `enabled: false` has no frames coming until its publisher re-enables it. Select an enabled rendition from the latest catalog before opening a decoder. Keep one already playing while every rendition of its kind is disabled: the convenience decoders accept a disabled configuration, and a re-enable, such as an unmute, then plays without a resubscribe. Among the video renditions you can decode, prefer the highest `preference`; `0` is the default and `-1` marks a compatibility transcode. Audio and video subscribe setup returns `UnsupportedConfigMoqException` when the decoder refuses the codec, layout, or description; a player can then try its next ranked rendition. Later peer or decode failures do not report that setup refusal. - **Subscription defaults.** `defaultSubscription()` returns moq-net's defaults, whose zero `maxDelay` skips a superseded group at once; passing no subscription means the same. A `Subscription()` leaves `maxDelay` null, which sets no subscriber limit, so pass `maxDelay: Duration.zero` when building one to match. - **Track demand.** Obtain a dynamic track request’s `demand()` before accepting it to watch subscribers through the handoff to its producer. The watch does not keep the track alive and ends when the track closes or the request is rejected. A producer publishes everything you write, subscribed or not, so a late subscriber can fetch the recent past. Capturing only while a producer's `demand()` reports a subscriber is an opt-in that saves the encode but leaves nothing from before the first one. diff --git a/doc/lib/go/index.md b/doc/lib/go/index.md index 5ad9e4eb92e..0b1c773bed9 100644 --- a/doc/lib/go/index.md +++ b/doc/lib/go/index.md @@ -140,7 +140,7 @@ shows which module holds each. - **Authorization.** On `moq-lite-07-wip` (opt in with `ClientConfig.Versions`) and on moq-transport draft-18+ with the [MoQ Auth extension](/draft/moq-auth), `Session().Grants()` returns a `GrantConsumer`: `Grant()` is the `Grant` the relay sent back, nil until it answers and while a client session reconnects, and `Changed(ctx)` waits for the next one. `Close()` it when done. - **Tokens.** Set `ClientConfig.Tokens` instead of putting the credential in the URL. The first is the connection credential, sent in SETUP and, while an offered version can't carry it there (lite before 07), as the URL's `?jwt=`; each other token widens the grant over AUTH. `Session().Tokens().Set(...)` replaces a client session's tokens before they expire: the next dial presents them, a live AUTH session at once, and after an authorization refusal the session redials only if they changed. `Answered(ctx)` returns nil once the relay accepts them, or its refusal with the relay's code. A `?jwt=` already in the URL stays the connection credential, which is how to reach a relay older than this release. - **Errors.** Read diagnostic payloads from `Reason` and structured protocol failures from `Details`. -- **Disabled renditions.** A rendition with `enabled: false` has no frames coming until its publisher re-enables it. Select an enabled rendition from the latest catalog before opening a decoder. Keep one already playing while every rendition of its kind is disabled: the convenience decoders accept a disabled configuration, and a re-enable, such as an unmute, then plays without a resubscribe. Among the video renditions you can decode, prefer the highest `Preference`; `0` is the default and `-1` marks a compatibility transcode. +- **Disabled renditions.** A rendition with `enabled: false` has no frames coming until its publisher re-enables it. Select an enabled rendition from the latest catalog before opening a decoder. Keep one already playing while every rendition of its kind is disabled: the convenience decoders accept a disabled configuration, and a re-enable, such as an unmute, then plays without a resubscribe. Among the video renditions you can decode, prefer the highest `Preference`; `0` is the default and `-1` marks a compatibility transcode. Audio and video subscribe setup returns `moq.ErrUnsupportedConfig` when the decoder refuses the codec, layout, or description; a player can then try its next ranked rendition. Later peer or decode failures do not report that setup refusal. - **Subscription defaults.** `moq.DefaultSubscription()` returns moq-net's defaults, whose zero `MaxDelay` skips a superseded group at once; a nil `*Subscription` means the same. Change its fields rather than starting from `Subscription{}`, whose nil `MaxDelay` sets no subscriber limit. - **Track demand.** Obtain a dynamic track request’s `Demand()` before accepting it to watch subscribers through the handoff to its producer. The watch does not keep the track alive and ends when the track closes or the request is rejected. A producer publishes everything you write, subscribed or not, so a late subscriber can fetch the recent past. Capturing only while a producer's `Demand()` reports a subscriber is an opt-in that saves the encode but leaves nothing from before the first one. diff --git a/doc/lib/kt/index.md b/doc/lib/kt/index.md index d7c33fb9fe5..2d78554ece0 100644 --- a/doc/lib/kt/index.md +++ b/doc/lib/kt/index.md @@ -113,7 +113,7 @@ shows which module holds each. - **Authorization.** On `moq-lite-07-wip` (opt in with `ClientConfig(versions = ...)`) and on moq-transport draft-18+ with the [MoQ Auth extension](/draft/moq-auth), collect `moq.grants().updates()` for the `Grant` the relay sent back and each change, `null` until it answers and while a client session reconnects. Ending the collection cancels the consumer. - **Tokens.** Pass `ClientConfig(tokens = listOf(...))` instead of putting the credential in the URL. The first is the connection credential, sent in SETUP and, while an offered version can't carry it there (lite before 07), as the URL's `?jwt=`; each other token widens the grant over AUTH. `moq.tokens().set(listOf(...))` replaces them before they expire: the next dial presents them, a live AUTH session at once, and after an authorization refusal the session redials only if they changed. Suspending `tokens().answered()` returns once the relay accepts them and throws its refusal with the relay's code. A `?jwt=` already in the URL stays the connection credential, which is how to reach a relay older than this release. - **Errors.** Read diagnostic payloads from `reason` and structured protocol failures from `details`. -- **Disabled renditions.** A rendition with `enabled: false` has no frames coming until its publisher re-enables it. Select an enabled rendition from the latest catalog before opening a decoder. Keep one already playing while every rendition of its kind is disabled: the convenience decoders accept a disabled configuration, and a re-enable, such as an unmute, then plays without a resubscribe. Among the video renditions you can decode, prefer the highest `preference`; `0` is the default and `-1` marks a compatibility transcode. +- **Disabled renditions.** A rendition with `enabled: false` has no frames coming until its publisher re-enables it. Select an enabled rendition from the latest catalog before opening a decoder. Keep one already playing while every rendition of its kind is disabled: the convenience decoders accept a disabled configuration, and a re-enable, such as an unmute, then plays without a resubscribe. Among the video renditions you can decode, prefer the highest `preference`; `0` is the default and `-1` marks a compatibility transcode. Audio and video subscribe setup returns `MoqException.UnsupportedConfig` when the decoder refuses the codec, layout, or description; a player can then try its next ranked rendition. Later peer or decode failures do not report that setup refusal. - **Subscription defaults.** `Subscription.default()` returns moq-net's defaults, whose zero `maxDelay` skips a superseded group at once; passing no subscription means the same. `copy` it to change a field; building a `Subscription(...)` must name `maxDelay`, where null sets no subscriber limit. - **Track demand.** Obtain a dynamic track request’s `demand()` before accepting it to watch subscribers through the handoff to its producer. The watch does not keep the track alive and ends when the track closes or the request is rejected. A producer publishes everything you write, subscribed or not, so a late subscriber can fetch the recent past. Capturing only while a producer's `demand()` reports a subscriber is an opt-in that saves the encode but leaves nothing from before the first one. diff --git a/doc/lib/py/index.md b/doc/lib/py/index.md index 3f1a8d5ae3f..4ddda28233b 100644 --- a/doc/lib/py/index.md +++ b/doc/lib/py/index.md @@ -128,7 +128,7 @@ shows which module holds each. - **Authorization.** On `moq-lite-07-wip` (opt in with `versions=`) and on moq-transport draft-18+ with the [MoQ Auth extension](/draft/moq-auth), `async for grant in session.grants()` yields the `Grant` the relay sent back and each change, `None` until it answers and while a client session reconnects. `grants().grant()` reads it once; cancelling or leaving an `async with` releases the wait. - **Tokens.** Pass `tokens=[...]` instead of putting the credential in the URL. The first is the connection credential, sent in SETUP and, while an offered version can't carry it there (lite before 07), as the URL's `?jwt=`; each other token widens the grant over AUTH. `session.tokens().set([...])` replaces a client session's tokens before they expire: the next dial presents them, a live AUTH session at once, and after an authorization refusal the session redials only if they changed. `await tokens.answered()` returns once the relay accepts them and raises its refusal with the relay's code. A `?jwt=` already in the URL stays the connection credential, which is how to reach a relay older than this release. - **Errors.** Read diagnostic payloads from `reason` and structured protocol failures from `details`. -- **Disabled renditions.** A rendition with `enabled: false` has no frames coming until its publisher re-enables it. Select an enabled rendition from the latest catalog before opening a decoder. Keep one already playing while every rendition of its kind is disabled: the convenience decoders accept a disabled configuration, and a re-enable, such as an unmute, then plays without a resubscribe. Among the video renditions you can decode, prefer the highest `preference`; `0` is the default and `-1` marks a compatibility transcode. +- **Disabled renditions.** A rendition with `enabled: false` has no frames coming until its publisher re-enables it. Select an enabled rendition from the latest catalog before opening a decoder. Keep one already playing while every rendition of its kind is disabled: the convenience decoders accept a disabled configuration, and a re-enable, such as an unmute, then plays without a resubscribe. Among the video renditions you can decode, prefer the highest `preference`; `0` is the default and `-1` marks a compatibility transcode. Audio and video subscribe setup returns `moq.Error.UnsupportedConfig` when the decoder refuses the codec, layout, or description; a player can then try its next ranked rendition. Later peer or decode failures do not report that setup refusal. - **Subscription defaults.** `moq.Subscription.default()` returns moq-net's defaults, whose zero `max_delay` skips a superseded group at once; passing no subscription means the same. A bare `moq.Subscription()` has the same defaults; an explicit `max_delay=None` sets no subscriber limit. - **Track demand.** Obtain a dynamic track request’s `demand()` before accepting it to watch subscribers through the handoff to its producer. The watch does not keep the track alive and ends when the track closes or the request is rejected. A producer publishes everything you write, subscribed or not, so a late subscriber can fetch the recent past. Capturing only while a producer's `demand()` reports a subscriber is an opt-in that saves the encode but leaves nothing from before the first one. diff --git a/doc/lib/swift/index.md b/doc/lib/swift/index.md index ec0ae5b804a..2878cc111fa 100644 --- a/doc/lib/swift/index.md +++ b/doc/lib/swift/index.md @@ -113,7 +113,7 @@ shows which module holds each. - **Authorization.** On `moq-lite-07-wip` (opt in with `Client(versions:)`) and on moq-transport draft-18+ with the [MoQ Auth extension](/draft/moq-auth), `for try await grant in session.grants()` yields the `Grant` the relay sent back and each change, `nil` until it answers and while a client session reconnects. Cancelling the iterating task cancels the native wait. - **Tokens.** Pass `Client(tokens: [...])` instead of putting the credential in the URL. The first is the connection credential, sent in SETUP and, while an offered version can't carry it there (lite before 07), as the URL's `?jwt=`; each other token widens the grant over AUTH. `try session.tokens()?.set([...])` replaces them before they expire: the next dial presents them, a live AUTH session at once, and after an authorization refusal the session redials only if they changed. `try await tokens.answered()` returns once the relay accepts them and throws its refusal with the relay's code. A `?jwt=` already in the URL stays the connection credential, which is how to reach a relay older than this release. - **Errors.** Diagnostic cases use the `reason:` argument label; match their associated value to inspect it. Protocol errors carry `details`. -- **Disabled renditions.** A rendition with `enabled: false` has no frames coming until its publisher re-enables it. Select an enabled rendition from the latest catalog before opening a decoder. Keep one already playing while every rendition of its kind is disabled: the convenience decoders accept a disabled configuration, and a re-enable, such as an unmute, then plays without a resubscribe. Among the video renditions you can decode, prefer the highest `preference`; `0` is the default and `-1` marks a compatibility transcode. +- **Disabled renditions.** A rendition with `enabled: false` has no frames coming until its publisher re-enables it. Select an enabled rendition from the latest catalog before opening a decoder. Keep one already playing while every rendition of its kind is disabled: the convenience decoders accept a disabled configuration, and a re-enable, such as an unmute, then plays without a resubscribe. Among the video renditions you can decode, prefer the highest `preference`; `0` is the default and `-1` marks a compatibility transcode. Audio and video subscribe setup returns `MoqError.UnsupportedConfig` when the decoder refuses the codec, layout, or description; a player can then try its next ranked rendition. Later peer or decode failures do not report that setup refusal. - **Subscription defaults.** `Subscription.default` holds moq-net's defaults, whose `maxDelay` of 0 skips a superseded group at once; passing no subscription means the same. Copy it to change a field; building a `Subscription(...)` must name `maxDelay`, where `nil` sets no subscriber limit. - **Track demand.** Obtain a dynamic track request’s `demand()` before accepting it to watch subscribers through the handoff to its producer. The watch does not keep the track alive and ends when the track closes or the request is rejected. A producer publishes everything you write, subscribed or not, so a late subscriber can fetch the recent past. Capturing only while a producer's `demand()` reports a subscriber is an opt-in that saves the encode but leaves nothing from before the first one. diff --git a/go/wrapper/MIGRATE.md b/go/wrapper/MIGRATE.md index 8f0b8385259..9889a52f180 100644 --- a/go/wrapper/MIGRATE.md +++ b/go/wrapper/MIGRATE.md @@ -4,6 +4,10 @@ How to update your code for each breaking change, newest first. ## Unreleased +### Media setup refusals are typed + +Audio and video subscribe setup now reports `ErrUnsupportedConfig` when the decoder refuses a codec, layout, or description. Handle this variant to try another rendition instead of inspecting an audio/video error message or `Unsupported`. Later peer and decode failures keep their existing errors. Regenerate bindings and rebuild the matching native library together. + ### `media.VideoInit` is a struct `media.VideoInit` is its own struct rather than an alias of the generated record, so its new `Lower` field takes a `*media.TrackProducer`. A composite literal with `Format`, `Data`, `Label`, and `Hint` compiles unchanged; build one that way where you converted a generated `MoqVideoInit`. diff --git a/go/wrapper/errors.go b/go/wrapper/errors.go index 540949c3bf9..022bd5d3d98 100644 --- a/go/wrapper/errors.go +++ b/go/wrapper/errors.go @@ -75,6 +75,8 @@ var ( ErrNotFound = ffi.ErrMoqErrorNotFound // ErrUnsupported is returned when the requested operation is not supported by this build or peer, however it is asked for. 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 = ffi.ErrMoqErrorAlreadyCommitted // ErrInvalidInstance is returned when an instance is empty. diff --git a/go/wrapper/errors_test.go b/go/wrapper/errors_test.go index be1a090efd8..4cb2e38cd22 100644 --- a/go/wrapper/errors_test.go +++ b/go/wrapper/errors_test.go @@ -95,6 +95,7 @@ func TestErrorSentinels(t *testing.T) { {"Expired", ffi.NewMoqErrorExpired(), moq.ErrExpired}, {"NotFound", ffi.NewMoqErrorNotFound(), moq.ErrNotFound}, {"Unsupported", ffi.NewMoqErrorUnsupported(), moq.ErrUnsupported}, + {"UnsupportedConfig", ffi.NewMoqErrorUnsupportedConfig("description"), moq.ErrUnsupportedConfig}, {"InvalidPattern", ffi.NewMoqErrorInvalidPattern(""), moq.ErrInvalidPattern}, {"InvalidInstance", ffi.NewMoqErrorInvalidInstance(""), moq.ErrInvalidInstance}, {"UnresolvableBroadcast", ffi.NewMoqErrorUnresolvableBroadcast(""), moq.ErrUnresolvableBroadcast}, diff --git a/kt/moq-ffi/MIGRATE.md b/kt/moq-ffi/MIGRATE.md index adf9c765ad6..deffe2c09a6 100644 --- a/kt/moq-ffi/MIGRATE.md +++ b/kt/moq-ffi/MIGRATE.md @@ -2,6 +2,10 @@ ## Unreleased +### Media setup refusals are typed + +Audio and video subscribe setup now reports `MoqException.UnsupportedConfig` when the decoder refuses a codec, layout, or description. Handle this variant to try another rendition instead of inspecting an audio/video error message or `Unsupported`. Later peer and decode failures keep their existing errors. Regenerate bindings and rebuild the matching native library together. + ### Follow the core API migration guide These bindings are generated from moq-ffi. Apply every change in the diff --git a/kt/moq/MIGRATE.md b/kt/moq/MIGRATE.md index ecb3c831ba8..2401d12bdaa 100644 --- a/kt/moq/MIGRATE.md +++ b/kt/moq/MIGRATE.md @@ -4,6 +4,10 @@ How to update your code for each breaking change, newest first. ## Unreleased +### Media setup refusals are typed + +Audio and video subscribe setup now reports `MoqException.UnsupportedConfig` when the decoder refuses a codec, layout, or description. Handle this variant to try another rendition instead of inspecting an audio/video error message or `Unsupported`. Later peer and decode failures keep their existing errors. Regenerate bindings and rebuild the matching native library together. + ### Announcement captures are required ([#7484](https://github.com/moq-dev/moq/pull/7484)) `Announce.captures` is `List` instead of `List?`. Remove null checks and pass `captures = emptyList()` when constructing an announcement for a filter without wildcards. Rebuild with the matching generated bindings and native library. diff --git a/py/moq-ffi/MIGRATE.md b/py/moq-ffi/MIGRATE.md index 677af200662..6d9b6618a00 100644 --- a/py/moq-ffi/MIGRATE.md +++ b/py/moq-ffi/MIGRATE.md @@ -2,6 +2,10 @@ ## Unreleased +### Media setup refusals are typed + +Audio and video subscribe setup now reports `UnsupportedConfig` when the decoder refuses a codec, layout, or description. Handle this variant to try another rendition instead of inspecting an audio/video error message or `Unsupported`. Later peer and decode failures keep their existing errors. Regenerate bindings and rebuild the matching native library together. + ### Follow the core API migration guide These bindings are generated from moq-ffi. Apply every change in the diff --git a/py/moq-rs/MIGRATE.md b/py/moq-rs/MIGRATE.md index af31a32d54a..533ce8ec89a 100644 --- a/py/moq-rs/MIGRATE.md +++ b/py/moq-rs/MIGRATE.md @@ -4,6 +4,10 @@ How to update your code for each breaking change, newest first. ## Unreleased +### Media setup refusals are typed + +Audio and video subscribe setup now reports `UnsupportedConfig` when the decoder refuses a codec, layout, or description. Handle this variant to try another rendition instead of inspecting an audio/video error message or `Unsupported`. Later peer and decode failures keep their existing errors. Regenerate bindings and rebuild the matching native library together. + ### Announcement captures are required ([#7484](https://github.com/moq-dev/moq/pull/7484)) `Announce.captures` is `list[str]` instead of `list[str] | None`. Remove `None` checks and pass `captures=[]` when constructing an announcement for a filter without wildcards. Rebuild with the matching generated bindings and native library. diff --git a/rs/moq-c/src/audio.rs b/rs/moq-c/src/audio.rs index db120d8b4ae..48b319e9917 100644 --- a/rs/moq-c/src/audio.rs +++ b/rs/moq-c/src/audio.rs @@ -270,7 +270,9 @@ impl Audio { |close| async move { driver .watch(async move { - let consumer = moq_audio::decode::Consumer::new(&broadcast, &catalog, name, config).await?; + let consumer = moq_audio::decode::Consumer::new(&broadcast, &catalog, name, config) + .await + .map_err(Error::audio_subscribe)?; Self::run(on_frame, consumer, close).await }) .await @@ -523,6 +525,9 @@ pub extern "C" fn moq_encode_audio_finish(producer: u32) -> i32 { /// model. TODO: a future API will pick the right rendition /// automatically (ABR). /// +/// A codec, layout, or description refused during setup reports +/// [`MOQ_ERROR_UNSUPPORTED_CONFIG`](crate::MOQ_ERROR_UNSUPPORTED_CONFIG) on the terminal callback. +/// /// Returns a non-zero handle on success or a negative error code. /// /// `on_read` is called with a positive read id per decoded frame, gap, or encoder @@ -561,7 +566,8 @@ pub unsafe extern "C" fn moq_decode_audio( config.output.sample_rate = zeroable(raw.sample_rate); config.output.layout = zeroable(raw.channels) .map(moq_audio::Layout::from_channels) - .transpose()?; + .transpose() + .map_err(Error::audio_subscribe)?; config.delay = raw.delay.into(); let on_read = unsafe { OnStatus::new(user_data, on_read)? }; diff --git a/rs/moq-c/src/error.rs b/rs/moq-c/src/error.rs index 067e5229226..88efb9fad6c 100644 --- a/rs/moq-c/src/error.rs +++ b/rs/moq-c/src/error.rs @@ -82,6 +82,8 @@ pub const MOQ_ERROR_UNRESOLVABLE_BROADCAST: i32 = -41; pub const MOQ_ERROR_EXPIRED: i32 = -42; /// The catalog requires a newer moq-hang version than this build supports. pub const MOQ_ERROR_UNSUPPORTED_CATALOG: i32 = -43; +/// The rendition or decoder output was refused during setup; another configuration may work. +pub const MOQ_ERROR_UNSUPPORTED_CONFIG: i32 = -44; /// Whether a protocol code is from the session or stream registry. #[repr(C)] @@ -193,6 +195,10 @@ pub type Status = i32; #[derive(Debug, thiserror::Error, Clone)] #[non_exhaustive] pub enum Error { + /// The rendition or decoder output could not be configured before decoding started. + #[error("unsupported configuration: {0}")] + UnsupportedConfig(String), + /// Error from the underlying MoQ protocol layer. #[error("moq error: {0}")] Moq(#[from] moq_net::Error), @@ -343,6 +349,15 @@ pub enum Error { UnresolvableBroadcast(String), } +impl Error { + pub(crate) fn audio_subscribe(err: moq_audio::Error) -> Self { + match err { + moq_audio::Error::Unsupported(reason) => Self::UnsupportedConfig(reason), + err => err.into(), + } + } +} + impl From for Error { fn from(err: moq_json::Error) -> Self { match err { @@ -380,7 +395,10 @@ impl From for Error { impl From for Error { fn from(err: moq_video::Error) -> Self { - Error::Video(Arc::new(err)) + match err { + moq_video::Error::UnsupportedConfig(reason) => Error::UnsupportedConfig(reason), + err => Error::Video(Arc::new(err)), + } } } @@ -514,6 +532,7 @@ impl ffi::ReturnCode for Error { Error::FrameNotFound => MOQ_ERROR_FRAME_NOT_FOUND, Error::Mux(_) => MOQ_ERROR_MUX, Error::Audio(_) => MOQ_ERROR_AUDIO, + Error::UnsupportedConfig(_) => MOQ_ERROR_UNSUPPORTED_CONFIG, Error::BufferNotConsumed => MOQ_ERROR_BUFFER_NOT_CONSUMED, Error::GroupNotFound => MOQ_ERROR_GROUP_NOT_FOUND, Error::Native(moq_tokio::Error::Panic) => MOQ_ERROR_PANIC, @@ -531,6 +550,21 @@ impl ffi::ReturnCode for Error { #[cfg(test)] mod tests { + #[test] + fn setup_refusals_are_distinct_from_later_codec_failures() { + use crate::ffi::ReturnCode; + let setup = super::Error::audio_subscribe(moq_audio::Error::Unsupported("layout".into())); + assert_eq!(setup.code(), super::MOQ_ERROR_UNSUPPORTED_CONFIG); + let later = super::Error::from(moq_audio::Error::Unsupported("duration".into())); + assert_eq!(later.code(), super::MOQ_ERROR_AUDIO); + let decode = super::Error::from(moq_audio::Error::Decode("packet".into())); + assert_eq!(decode.code(), super::MOQ_ERROR_AUDIO); + let setup = super::Error::from(moq_video::Error::UnsupportedConfig("description".into())); + assert_eq!(setup.code(), super::MOQ_ERROR_UNSUPPORTED_CONFIG); + let gone = super::Error::from(moq_video::Error::CodecGone("worker".into())); + assert_eq!(gone.code(), super::MOQ_ERROR_VIDEO); + } + #[test] fn unsupported_catalog_has_its_own_code() { use crate::ffi::ReturnCode; diff --git a/rs/moq-c/src/video.rs b/rs/moq-c/src/video.rs index 99ba0c12a73..f4755ae5b11 100644 --- a/rs/moq-c/src/video.rs +++ b/rs/moq-c/src/video.rs @@ -1159,8 +1159,9 @@ pub extern "C" fn moq_encode_video_finish(producer: u32) -> i32 { /// CPU pixel format and size (see [`moq_video_decoder_output`]). /// /// The catalog `index` selects which video rendition to subscribe to, matching -/// the existing `moq_consume_video` selection model. Only H.264 is -/// supported; a non-H.264 rendition fails on the terminal callback. +/// the existing `moq_consume_video` selection model. A codec or description the native +/// decoders cannot open reports [`MOQ_ERROR_UNSUPPORTED_CONFIG`](crate::MOQ_ERROR_UNSUPPORTED_CONFIG) +/// on the terminal callback, before any decoded reads. /// /// An unknown `output->format` or an invalid `output->width`/`height` fails /// here, before subscribing. Each frame is produced in the requested layout by diff --git a/rs/moq-ffi/MIGRATE.md b/rs/moq-ffi/MIGRATE.md index 943c1c7e8f6..ca928426812 100644 --- a/rs/moq-ffi/MIGRATE.md +++ b/rs/moq-ffi/MIGRATE.md @@ -5,6 +5,10 @@ These are the UniFFI names; each language wrapper has its own `MIGRATE.md` in it ## Unreleased +### Media setup refusals are typed + +Audio and video subscribe setup now reports `UnsupportedConfig` when the decoder refuses a codec, layout, or description. Handle this variant to try another rendition instead of inspecting an audio/video error message or `Unsupported`. Later peer and decode failures keep their existing errors. Regenerate bindings and rebuild the matching native library together. + ### `MoqTransport::Iroh` is removed ([#7345](https://github.com/moq-dev/moq/pull/7345)) moq-tokio no longer accepts iroh sessions, so `MoqTransport` loses its `Iroh` variant and the later variants renumber; Go loses `TransportIroh`. diff --git a/rs/moq-ffi/src/audio.rs b/rs/moq-ffi/src/audio.rs index 6570e536f31..89f04298e6a 100644 --- a/rs/moq-ffi/src/audio.rs +++ b/rs/moq-ffi/src/audio.rs @@ -605,15 +605,17 @@ impl MoqAudioConsumer { } fn audio_config(catalog_audio: crate::media::MoqAudio) -> Result { - let codec = catalog_audio.codec.parse().map_err(|_| MoqError::Unsupported)?; - // What moq-audio's decoder opens. It rejects the rest itself, so this is only - // here to report an unusable rendition as a plain Unsupported rather than a - // wrapped codec error. - if !matches!( - &codec, - hang::catalog::AudioCodec::Opus | hang::catalog::AudioCodec::AAC(_) | hang::catalog::AudioCodec::Pcm - ) { - return Err(MoqError::Unsupported); + let codec = catalog_audio + .codec + .parse::() + .map_err(|err| MoqError::UnsupportedConfig { + reason: err.to_string(), + })?; + + if matches!(codec, hang::catalog::AudioCodec::Unknown(_)) { + return Err(MoqError::UnsupportedConfig { + reason: format!("unknown audio codec: {codec}"), + }); } let mut config = hang::catalog::AudioConfig::new(codec, catalog_audio.sample_rate, catalog_audio.channel_count); @@ -631,7 +633,8 @@ impl MoqAudioConsumer { /// Subscribe to an audio track. `catalog_audio_config` comes from /// the catalog (see /// [`MoqMediaCatalogConsumer::next`](crate::media::MoqMediaCatalogConsumer::next)); - /// the codec is inferred from it. Only Opus, AAC-LC, and PCM are supported. + /// the codec is inferred from it. A codec, layout, or description the decoder cannot open + /// returns [`MoqError::UnsupportedConfig`], so a player can try another rendition. /// /// A [disabled](crate::media::MoqAudio::enabled) rendition subscribes too, and decodes once its /// publisher re-enables it: a muted speaker's listener stays subscribed, so the unmute plays @@ -660,7 +663,11 @@ impl MoqAudioConsumer { let mut config = moq_audio::decode::Options::default(); config.output.format = output.format.into(); config.output.sample_rate = output.sample_rate; - config.output.layout = output.channels.map(moq_audio::Layout::from_channels).transpose()?; + config.output.layout = output + .channels + .map(moq_audio::Layout::from_channels) + .transpose() + .map_err(MoqError::audio_subscribe)?; config.delay = output.delay.map(Into::into).unwrap_or_default(); config.estimate = output.estimate; config.start = match output.start.unwrap_or_default() { @@ -670,7 +677,11 @@ impl MoqAudioConsumer { let consumer = broadcast .driver - .watch(async { Ok(moq_audio::decode::Consumer::new(&resolved, &cfg, id, config).await?) }) + .watch(async { + moq_audio::decode::Consumer::new(&resolved, &cfg, id, config) + .await + .map_err(MoqError::audio_subscribe) + }) .await?; let delay = Arc::new(AtomicU64::new(nanos(consumer.delay()))); @@ -734,10 +745,10 @@ mod tests { } #[test] - fn audio_config_rejects_a_codec_the_decoder_lacks() { + fn audio_config_preserves_a_codec_the_decoder_checks() { // In the catalog, and decodable in a browser, but not by moq-audio. - let error = audio_config(catalog_audio("flac")).unwrap_err(); - assert!(matches!(error, MoqError::Unsupported)); + let config = audio_config(catalog_audio("flac")).unwrap(); + assert!(matches!(config.codec, hang::catalog::AudioCodec::Flac)); } /// The advertised jitter floors the estimated playout delay, so it must survive the trip @@ -753,7 +764,7 @@ mod tests { #[test] fn audio_config_rejects_unknown_codec() { let error = audio_config(catalog_audio("unknown")).unwrap_err(); - assert!(matches!(error, MoqError::Unsupported)); + assert!(matches!(error, MoqError::UnsupportedConfig { .. })); } #[tokio::test(start_paused = true)] diff --git a/rs/moq-ffi/src/error.rs b/rs/moq-ffi/src/error.rs index eadcf7e74c5..1dfa9c0e573 100644 --- a/rs/moq-ffi/src/error.rs +++ b/rs/moq-ffi/src/error.rs @@ -401,6 +401,22 @@ pub enum MoqError { /// The catalog version this build cannot read. version: u64, }, + /// The rendition or decoder output was refused during setup; another configuration may work. + #[error("unsupported configuration: {reason}")] + UnsupportedConfig { + /// A diagnostic message describing the refusal. + reason: String, + }, +} + +impl MoqError { + #[cfg(feature = "audio")] + pub(crate) fn audio_subscribe(err: moq_audio::Error) -> Self { + match err { + moq_audio::Error::Unsupported(reason) => Self::UnsupportedConfig { reason }, + err => err.into(), + } + } } impl From for MoqError { @@ -502,8 +518,11 @@ impl From for MoqError { #[cfg(feature = "video")] impl From for MoqError { fn from(err: moq_video::Error) -> Self { - Self::Video { - reason: err.to_string(), + match err { + moq_video::Error::UnsupportedConfig(reason) => Self::UnsupportedConfig { reason }, + err => Self::Video { + reason: err.to_string(), + }, } } } diff --git a/rs/moq-ffi/src/test.rs b/rs/moq-ffi/src/test.rs index c055599ad6b..93e9e879d90 100644 --- a/rs/moq-ffi/src/test.rs +++ b/rs/moq-ffi/src/test.rs @@ -9154,3 +9154,116 @@ fn shutdown_waits_for_a_polled_call() { let parked = parked.join().unwrap(); assert!(matches!(parked, Err(MoqError::Cancelled)), "{parked:?}"); } + +/// Setup, rather than the first packet, decides whether a rendition is usable. +#[cfg(feature = "audio")] +#[tokio::test] +async fn audio_subscribe_configuration_boundary() { + use crate::audio::MoqAudioConsumer; + let broadcast = MoqBroadcastProducer::new().unwrap(); + let _track = broadcast.publish_track("audio".into(), None).unwrap(); + let consumer = broadcast.consume().unwrap(); + // The names alone cannot decide: the AAC-LC description may declare SBR, + // and a present, malformed OpusHead must never be replaced by catalog fields. + for (codec, description, channels, supported) in [ + ("opus", None, 2, true), + ("opus", Some(opus_head()), 2, true), + ("opus", Some(vec![]), 2, false), + ("opus", Some(opus_head()[..18].to_vec()), 2, false), + ("opus", None, 6, false), + ("pcm", None, 6, true), + ("pcm", Some(vec![]), 2, false), + ("flac", None, 2, false), + ("unknown", None, 2, false), + ("mp4a.40.bad", None, 2, false), + ("mp4a.40.2", Some(vec![0x11, 0x90]), 2, true), + ("mp4a.40.2", Some(vec![0x12, 0x10, 0x56, 0xe5, 0x98]), 2, false), + ("mp4a.40.2", Some(vec![0x11]), 2, false), + ("mp4a.40.2", None, 6, false), + ("mp4a.40.5", None, 2, false), + ] { + let mut config = sibling_audio(""); + config.codec = codec.into(); + config.description = description; + config.channel_count = channels; + let result = MoqAudioConsumer::subscribe(&consumer, "audio".into(), config, audio_output()).await; + if supported { + result.unwrap().cancel(); + } else { + assert!( + matches!(result, Err(MoqError::UnsupportedConfig { .. })), + "{codec}/{channels}" + ); + } + } + // Output refusals are setup errors too; a missing track is not. + for output in [ + crate::audio::MoqAudioDecoderOutput { + sample_rate: Some(0), + ..audio_output() + }, + crate::audio::MoqAudioDecoderOutput { + channels: Some(0), + ..audio_output() + }, + ] { + assert!(matches!( + MoqAudioConsumer::subscribe(&consumer, "audio".into(), sibling_audio(""), output).await, + Err(MoqError::UnsupportedConfig { .. }) + )); + } + let missing = MoqAudioConsumer::subscribe(&consumer, "missing".into(), sibling_audio(""), audio_output()).await; + assert!(matches!(missing, Err(MoqError::Audio { .. }))); + broadcast.close().unwrap(); +} + +#[cfg(feature = "video")] +#[tokio::test] +async fn video_subscribe_configuration_boundary() { + use crate::video::{MoqVideoConsumer, MoqVideoDecoderOutput}; + let broadcast = MoqBroadcastProducer::new().unwrap(); + let _track = broadcast.publish_track("video".into(), None).unwrap(); + let consumer = broadcast.consume().unwrap(); + for (codec, description, supported) in [ + ("avc1.42001e", None, true), + ("avc1.42001e", Some(vec![]), false), + ("avc1.42001e", Some(vec![1, 0x42, 0, 0x1e]), false), + ("hvc1.1.6.L93.B0", None, false), + ("vp09.02.10.10", None, false), + ("avc1.invalid", None, false), + ("unknown", None, false), + ] { + let config = MoqVideo { + codec: codec.into(), + description, + enabled: true, + container: MoqContainer::Legacy, + preference: 0, + label: None, + broadcast: None, + instance: None, + track: None, + coded: None, + display_aspect: None, + bitrate: None, + framerate: None, + }; + let result = MoqVideoConsumer::subscribe( + &consumer, + "video".into(), + config.clone(), + MoqVideoDecoderOutput::default(), + ) + .await; + if supported { + result.unwrap().cancel(); + let missing = + MoqVideoConsumer::subscribe(&consumer, "missing".into(), config, MoqVideoDecoderOutput::default()) + .await; + assert!(matches!(missing, Err(MoqError::Video { .. }))); + } else { + assert!(matches!(result, Err(MoqError::UnsupportedConfig { .. })), "{codec}"); + } + } + broadcast.close().unwrap(); +} diff --git a/rs/moq-ffi/src/video.rs b/rs/moq-ffi/src/video.rs index e5e43380d16..84d8fb95f84 100644 --- a/rs/moq-ffi/src/video.rs +++ b/rs/moq-ffi/src/video.rs @@ -1231,11 +1231,17 @@ impl MoqVideoConsumer { /// is rejected here; a recognized one the native backends can't open is rejected when the decoder /// opens, which is still before the first frame. fn video_config(catalog_video: crate::media::MoqVideo) -> Result { - let codec: hang::catalog::VideoCodec = catalog_video.codec.parse().map_err(|_| MoqError::Unsupported)?; - // Parsing is total: an unrecognized name becomes `Unknown` rather than failing. Reject it here - // so a typo in the catalog is an error at subscribe, not an opaque backend failure later. + let codec = catalog_video + .codec + .parse::() + .map_err(|err| MoqError::UnsupportedConfig { + reason: format!("{err}"), + })?; + if matches!(codec, hang::catalog::VideoCodec::Unknown(_)) { - return Err(MoqError::Unsupported); + return Err(MoqError::UnsupportedConfig { + reason: format!("unknown video codec: {codec}"), + }); } let mut config = hang::catalog::VideoConfig::new(codec); @@ -1278,8 +1284,8 @@ impl MoqVideoConsumer { /// /// `catalog_video` comes from the catalog (see /// [`MoqMediaCatalogConsumer::next`](crate::media::MoqMediaCatalogConsumer::next)); the codec is read - /// from it. Errors if no native backend handles that codec, rather than failing on the first - /// frame. Also fails with [`MoqError::Unsupported`] when + /// from it. A codec or description no native backend can open returns + /// [`MoqError::UnsupportedConfig`] before decoding starts. Also fails with [`MoqError::Unsupported`] when /// [`surface`](MoqVideoDecoderOutput::surface) is set on a platform with no surface to expose. /// /// A [disabled](crate::media::MoqVideo::enabled) rendition subscribes too, and decodes once its @@ -1372,7 +1378,7 @@ mod decode_tests { #[test] fn video_config_rejects_an_unknown_codec() { let error = video_config(catalog_video("nope")).unwrap_err(); - assert!(matches!(error, MoqError::Unsupported)); + assert!(matches!(error, MoqError::UnsupportedConfig { .. })); } } diff --git a/rs/moq-video/MIGRATE.md b/rs/moq-video/MIGRATE.md index 55ef582a900..5f8ff5204f8 100644 --- a/rs/moq-video/MIGRATE.md +++ b/rs/moq-video/MIGRATE.md @@ -4,6 +4,10 @@ How to update your code for each breaking change, newest first. ## Unreleased +### Consumer decoder setup refusals are typed + +`decode::Consumer::new` reports `Error::UnsupportedConfig` for a codec, description, or decoder output it cannot open. Direct `decode::Decoder::new` retains its detailed setup errors. Subscription failures and codec worker failures keep their existing errors. + ### `decode::Options::max_delay` is `delay` ([#7311](https://github.com/moq-dev/moq/pull/7311), [#7597](https://github.com/moq-dev/moq/pull/7597)) `decode::Options::max_delay: Duration` is `delay: decode::Delay` (`moq_net::track::Delay`). diff --git a/rs/moq-video/src/decode/consumer.rs b/rs/moq-video/src/decode/consumer.rs index d2af94d4697..e6b7a8d5af3 100644 --- a/rs/moq-video/src/decode/consumer.rs +++ b/rs/moq-video/src/decode/consumer.rs @@ -312,7 +312,11 @@ impl Reader { delay: Delay, lookback: u64, ) -> Result { - let decoder = Sink::open(catalog, &options.decoder).await?; + let decoder = Sink::open(catalog, &options.decoder).await.map_err(|err| match err { + // A worker that disappeared is an infrastructure failure, not a capability refusal. + err @ Error::CodecGone(_) => err, + err => Error::UnsupportedConfig(err.to_string()), + })?; let track = broadcast.track(hang::catalog::Reference::track(catalog, name))?; let mut subscriber = track diff --git a/rs/moq-video/src/error.rs b/rs/moq-video/src/error.rs index 378ac2d32bb..5116198c4aa 100644 --- a/rs/moq-video/src/error.rs +++ b/rs/moq-video/src/error.rs @@ -2,6 +2,10 @@ #[derive(Debug, thiserror::Error)] #[non_exhaustive] pub enum Error { + /// The rendition or decoder output could not be configured before decoding started. + #[error("unsupported video configuration: {0}")] + UnsupportedConfig(String), + /// No encoder matching the requested codec / hardware preference could be /// opened (none compiled in, or none available on this machine). #[error("no usable video encoder found (tried: {0})")] diff --git a/swift/MIGRATE.md b/swift/MIGRATE.md index 3ff5db0b9d9..40fdd9a4d6b 100644 --- a/swift/MIGRATE.md +++ b/swift/MIGRATE.md @@ -4,6 +4,10 @@ How to update your code for each breaking change, newest first. ## Unreleased +### Media setup refusals are typed + +Audio and video subscribe setup now reports `UnsupportedConfig` when the decoder refuses a codec, layout, or description. Handle this variant to try another rendition instead of inspecting an audio/video error message or `Unsupported`. Later peer and decode failures keep their existing errors. Regenerate bindings and rebuild the matching native library together. + ### Announcement captures are required ([#7484](https://github.com/moq-dev/moq/pull/7484)) `Announce.captures` is `[String]` instead of `[String]?`. Remove optional checks and pass `captures: []` when constructing an announcement for a filter without wildcards. Rebuild with the matching MoqFFI package and native library. From 96e2064a3af62638ce5619171d06ef63eab9cd1f Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 3 Nov 2026 03:51:08 -0800 Subject: [PATCH 4/6] fix(media): separate setup refusals from peer and worker failures Co-Authored-By: GPT-6.1 Sol --- rs/moq-audio/MIGRATE.md | 4 ++++ rs/moq-audio/src/decode/consumer.rs | 13 ++++++++++--- rs/moq-audio/src/error.rs | 4 ++++ rs/moq-c/src/audio.rs | 9 ++++----- rs/moq-c/src/error.rs | 16 +++++----------- rs/moq-ffi/src/audio.rs | 14 ++++++-------- rs/moq-ffi/src/error.rs | 17 +++++------------ rs/moq-ffi/src/test.rs | 26 ++++++++++++++++++++++++++ rs/moq-video/MIGRATE.md | 2 +- rs/moq-video/src/worker.rs | 17 +++++++++++++---- 10 files changed, 78 insertions(+), 44 deletions(-) diff --git a/rs/moq-audio/MIGRATE.md b/rs/moq-audio/MIGRATE.md index 99511d6fab9..86516e82082 100644 --- a/rs/moq-audio/MIGRATE.md +++ b/rs/moq-audio/MIGRATE.md @@ -4,6 +4,10 @@ How to update your code for each breaking change, newest first. ## Unreleased +### Consumer decoder setup refusals are typed + +`decode::Consumer::new` reports `Error::UnsupportedConfig` for a codec, layout, description, or decoder output it cannot open. Direct `decode::Decoder::new` retains its detailed setup errors. Subscription conditions, including a playout delay beyond the track's retention, keep their existing errors. + ### `decode::Options` takes a `Delay` and `estimate` ([#7311](https://github.com/moq-dev/moq/pull/7311), [#7597](https://github.com/moq-dev/moq/pull/7597)) `decode::Options::max_delay: Duration` and the playout `delay: Option` are one `delay: decode::Delay` (`moq_net::track::Delay`) plus `estimate: bool`. diff --git a/rs/moq-audio/src/decode/consumer.rs b/rs/moq-audio/src/decode/consumer.rs index 6ebd41e014e..e691e0d2ae1 100644 --- a/rs/moq-audio/src/decode/consumer.rs +++ b/rs/moq-audio/src/decode/consumer.rs @@ -179,15 +179,22 @@ impl Consumer { name: impl Into, options: Options, ) -> Result { - let decoder = Decoder::new(catalog, &options.decoder)?; + // Only the local decoder/output setup is a capability refusal. Conditions learned + // from the subscription, such as retention, keep their original errors. + let setup = |err| match err { + Error::Unsupported(reason) => Error::UnsupportedConfig(reason), + err => err, + }; + let decoder = Decoder::new(catalog, &options.decoder).map_err(setup)?; let sample_rate = options.output.sample_rate.unwrap_or_else(|| decoder.sample_rate()); let layout = options.output.layout.unwrap_or_else(|| decoder.layout()); let remix = (decoder.layout() != layout) .then(|| Remix::new(decoder.layout(), layout)) - .transpose()?; + .transpose() + .map_err(setup)?; if sample_rate == 0 { - return Err(Error::Unsupported("output sample rate must be > 0".into())); + return Err(Error::UnsupportedConfig("output sample rate must be > 0".into())); } let name = name.into(); diff --git a/rs/moq-audio/src/error.rs b/rs/moq-audio/src/error.rs index c81cc457c74..ff96391db15 100644 --- a/rs/moq-audio/src/error.rs +++ b/rs/moq-audio/src/error.rs @@ -5,6 +5,10 @@ #[derive(Clone, Debug, thiserror::Error)] #[non_exhaustive] pub enum Error { + /// The rendition or decoder output was refused before subscribing to its track. + #[error("unsupported audio configuration: {0}")] + UnsupportedConfig(String), + /// The requested configuration is outside what the codec or device supports, /// e.g. a sample rate, channel count, or frame duration Opus can't encode, or a /// capture format the microphone can't deliver. The diff --git a/rs/moq-c/src/audio.rs b/rs/moq-c/src/audio.rs index 48b319e9917..776cb18a604 100644 --- a/rs/moq-c/src/audio.rs +++ b/rs/moq-c/src/audio.rs @@ -270,9 +270,7 @@ impl Audio { |close| async move { driver .watch(async move { - let consumer = moq_audio::decode::Consumer::new(&broadcast, &catalog, name, config) - .await - .map_err(Error::audio_subscribe)?; + let consumer = moq_audio::decode::Consumer::new(&broadcast, &catalog, name, config).await?; Self::run(on_frame, consumer, close).await }) .await @@ -525,8 +523,9 @@ pub extern "C" fn moq_encode_audio_finish(producer: u32) -> i32 { /// model. TODO: a future API will pick the right rendition /// automatically (ABR). /// -/// A codec, layout, or description refused during setup reports +/// A rendition's codec, layout, or description refused during setup reports /// [`MOQ_ERROR_UNSUPPORTED_CONFIG`](crate::MOQ_ERROR_UNSUPPORTED_CONFIG) on the terminal callback. +/// An unsupported output channel count returns that code directly, without a callback. /// /// Returns a non-zero handle on success or a negative error code. /// @@ -567,7 +566,7 @@ pub unsafe extern "C" fn moq_decode_audio( config.output.layout = zeroable(raw.channels) .map(moq_audio::Layout::from_channels) .transpose() - .map_err(Error::audio_subscribe)?; + .map_err(|err| Error::UnsupportedConfig(err.to_string()))?; config.delay = raw.delay.into(); let on_read = unsafe { OnStatus::new(user_data, on_read)? }; diff --git a/rs/moq-c/src/error.rs b/rs/moq-c/src/error.rs index 88efb9fad6c..cf3f77e6007 100644 --- a/rs/moq-c/src/error.rs +++ b/rs/moq-c/src/error.rs @@ -349,15 +349,6 @@ pub enum Error { UnresolvableBroadcast(String), } -impl Error { - pub(crate) fn audio_subscribe(err: moq_audio::Error) -> Self { - match err { - moq_audio::Error::Unsupported(reason) => Self::UnsupportedConfig(reason), - err => err.into(), - } - } -} - impl From for Error { fn from(err: moq_json::Error) -> Self { match err { @@ -389,7 +380,10 @@ impl From for Error { impl From for Error { fn from(err: moq_audio::Error) -> Self { - Error::Audio(Arc::new(err)) + match err { + moq_audio::Error::UnsupportedConfig(reason) => Error::UnsupportedConfig(reason), + err => Error::Audio(Arc::new(err)), + } } } @@ -553,7 +547,7 @@ mod tests { #[test] fn setup_refusals_are_distinct_from_later_codec_failures() { use crate::ffi::ReturnCode; - let setup = super::Error::audio_subscribe(moq_audio::Error::Unsupported("layout".into())); + let setup = super::Error::from(moq_audio::Error::UnsupportedConfig("layout".into())); assert_eq!(setup.code(), super::MOQ_ERROR_UNSUPPORTED_CONFIG); let later = super::Error::from(moq_audio::Error::Unsupported("duration".into())); assert_eq!(later.code(), super::MOQ_ERROR_AUDIO); diff --git a/rs/moq-ffi/src/audio.rs b/rs/moq-ffi/src/audio.rs index 89f04298e6a..9399b73c356 100644 --- a/rs/moq-ffi/src/audio.rs +++ b/rs/moq-ffi/src/audio.rs @@ -651,8 +651,8 @@ impl MoqAudioConsumer { catalog_audio: crate::media::MoqAudio, output: MoqAudioDecoderOutput, ) -> Result, MoqError> { - // Reject the codec before resolving: resolving reaches the origin, which can invoke a - // dynamic handler and open an upstream subscription we would immediately drop. + // Reject malformed or unknown codec names before resolving the broadcast reference. + // Decoder setup checks recognized codecs after resolution, without a second codec gate. let reference = catalog_audio.broadcast.clone(); let instance = catalog_audio.instance.clone(); let cfg = audio_config(catalog_audio)?; @@ -667,7 +667,9 @@ impl MoqAudioConsumer { .channels .map(moq_audio::Layout::from_channels) .transpose() - .map_err(MoqError::audio_subscribe)?; + .map_err(|err| MoqError::UnsupportedConfig { + reason: err.to_string(), + })?; config.delay = output.delay.map(Into::into).unwrap_or_default(); config.estimate = output.estimate; config.start = match output.start.unwrap_or_default() { @@ -677,11 +679,7 @@ impl MoqAudioConsumer { let consumer = broadcast .driver - .watch(async { - moq_audio::decode::Consumer::new(&resolved, &cfg, id, config) - .await - .map_err(MoqError::audio_subscribe) - }) + .watch(async { Ok(moq_audio::decode::Consumer::new(&resolved, &cfg, id, config).await?) }) .await?; let delay = Arc::new(AtomicU64::new(nanos(consumer.delay()))); diff --git a/rs/moq-ffi/src/error.rs b/rs/moq-ffi/src/error.rs index 1dfa9c0e573..73d51ea393a 100644 --- a/rs/moq-ffi/src/error.rs +++ b/rs/moq-ffi/src/error.rs @@ -409,16 +409,6 @@ pub enum MoqError { }, } -impl MoqError { - #[cfg(feature = "audio")] - pub(crate) fn audio_subscribe(err: moq_audio::Error) -> Self { - match err { - moq_audio::Error::Unsupported(reason) => Self::UnsupportedConfig { reason }, - err => err.into(), - } - } -} - impl From for MoqError { fn from(err: moq_net::Error) -> Self { match err { @@ -509,8 +499,11 @@ impl From for MoqError { #[cfg(feature = "audio")] impl From for MoqError { fn from(err: moq_audio::Error) -> Self { - Self::Audio { - reason: err.to_string(), + match err { + moq_audio::Error::UnsupportedConfig(reason) => Self::UnsupportedConfig { reason }, + err => Self::Audio { + reason: err.to_string(), + }, } } } diff --git a/rs/moq-ffi/src/test.rs b/rs/moq-ffi/src/test.rs index 93e9e879d90..cf1b88d7b36 100644 --- a/rs/moq-ffi/src/test.rs +++ b/rs/moq-ffi/src/test.rs @@ -9214,6 +9214,32 @@ async fn audio_subscribe_configuration_boundary() { } let missing = MoqAudioConsumer::subscribe(&consumer, "missing".into(), sibling_audio(""), audio_output()).await; assert!(matches!(missing, Err(MoqError::Audio { .. }))); + let _limited = broadcast + .publish_track( + "limited".into(), + Some(MoqTrackInfo { + priority: 0, + max_age: Some(Duration::from_millis(10)), + refresh: None, + timescale: None, + compress: false, + }), + ) + .unwrap(); + let retained = MoqAudioConsumer::subscribe( + &consumer, + "limited".into(), + sibling_audio(""), + crate::audio::MoqAudioDecoderOutput { + delay: Some(MoqDelay { + min: Duration::from_millis(20), + max: None, + }), + ..audio_output() + }, + ) + .await; + assert!(matches!(retained, Err(MoqError::Audio { .. }))); broadcast.close().unwrap(); } diff --git a/rs/moq-video/MIGRATE.md b/rs/moq-video/MIGRATE.md index 5f8ff5204f8..796bded3188 100644 --- a/rs/moq-video/MIGRATE.md +++ b/rs/moq-video/MIGRATE.md @@ -6,7 +6,7 @@ How to update your code for each breaking change, newest first. ### Consumer decoder setup refusals are typed -`decode::Consumer::new` reports `Error::UnsupportedConfig` for a codec, description, or decoder output it cannot open. Direct `decode::Decoder::new` retains its detailed setup errors. Subscription failures and codec worker failures keep their existing errors. +`decode::Consumer::new` reports `Error::UnsupportedConfig` for a codec, description, or decoder output it cannot open. Direct `decode::Decoder::new` retains its detailed setup errors. Subscription failures keep their existing errors. A codec worker that cannot start or exits during initialization reports `Error::CodecGone`, like a worker lost after initialization, rather than `Error::Codec`. ### `decode::Options::max_delay` is `delay` ([#7311](https://github.com/moq-dev/moq/pull/7311), [#7597](https://github.com/moq-dev/moq/pull/7597)) diff --git a/rs/moq-video/src/worker.rs b/rs/moq-video/src/worker.rs index f290bb2652b..aa56c394887 100644 --- a/rs/moq-video/src/worker.rs +++ b/rs/moq-video/src/worker.rs @@ -71,7 +71,7 @@ impl Worker { let handle = std::thread::Builder::new() .name(thread_name.into()) .spawn(move || run(Ready(ready_tx), req_rx)) - .map_err(|err| Error::Codec(anyhow::anyhow!("failed to spawn the {thread_name} thread: {err}")))?; + .map_err(|err| Error::CodecGone(format!("failed to spawn the {thread_name} thread: {err}")))?; match ready_rx.await { Ok(Ok(info)) => Ok(Self { @@ -83,9 +83,7 @@ impl Worker { Ok(Err(err)) => Err(err), Err(_) => { let _ = handle.join(); - Err(Error::Codec(anyhow::anyhow!( - "{thread_name} thread exited before opening" - ))) + Err(Error::CodecGone(format!("{thread_name} thread exited before opening"))) } } } @@ -149,3 +147,14 @@ fn gone() -> Error { fn abandoned() -> Error { Error::CodecGone("a cancelled call left the codec ahead of this stream".to_owned()) } + +#[cfg(test)] +mod tests { + use super::*; + + #[tokio::test] + async fn an_init_that_drops_its_reply_is_a_worker_failure() { + let result = Worker::<(), ()>::open("test-codec", |_, _| {}).await; + assert!(matches!(result, Err(Error::CodecGone(_)))); + } +} From b53b5430bd094f8b11949d3998564cae162da574 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 3 Nov 2026 04:19:26 -0800 Subject: [PATCH 5/6] fix(audio): type malformed AAC setup refusals and record open policy Co-Authored-By: GPT-6.1 Sol --- cpp/obs/test/moq-source-test.cpp | 6 +++++ quest/m1/README.md | 1 + quest/m1/ffi-unsupported-config.md | 43 ++++++++++++++++++++++++++++++ rs/moq-audio/src/aac.rs | 3 ++- rs/moq-audio/src/error.rs | 6 +++-- rs/moq-ffi/src/test.rs | 8 ++++-- 6 files changed, 62 insertions(+), 5 deletions(-) create mode 100644 quest/m1/ffi-unsupported-config.md diff --git a/cpp/obs/test/moq-source-test.cpp b/cpp/obs/test/moq-source-test.cpp index 7f8a86422d5..16ad9730569 100644 --- a/cpp/obs/test/moq-source-test.cpp +++ b/cpp/obs/test/moq-source-test.cpp @@ -1267,6 +1267,12 @@ int main() sbr_audio.description = std::vector{0x12, 0x10, 0x56, 0xe5, 0x98}; sbr_audio.bitrate = 5400000; catalog.audio.emplace("sbr", sbr_audio); + // Two bytes can still be malformed: this ASC promises a missing explicit sample rate. + auto truncated_aac_audio = audio; + truncated_aac_audio.codec = "mp4a.40.2"; + truncated_aac_audio.description = std::vector{0x17, 0x90}; + truncated_aac_audio.bitrate = 5450000; + catalog.audio.emplace("truncated-aac", truncated_aac_audio); // 5.1 AAC-LC: OBS has the layout, but moq-audio decodes AAC only in mono or stereo. auto surround_aac_audio = audio; surround_aac_audio.codec = "mp4a.40.2"; diff --git a/quest/m1/README.md b/quest/m1/README.md index 750c67f5bf4..360826fa74b 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -191,6 +191,7 @@ per-frame CPU growth since #5926. - [Authored tracks default to a 30 s max-age](/quest/m1/max-age-defaults.md) - raw and media tracks advertise 30 s unless their author chooses otherwise, with explicit unlimited in every binding - [HLS export lists a same-codec reconfigure's first group under the new init](/quest/m1/hls-reinit-same-codec.md) - the hand-over pick, whichever of the catalog and the records arrives first, after the catalog `hls` removal is planned - [A cancelled MoqTrackDemand wait never loses the next change](/quest/m1/demand-cancel-race.md) - cancelling a `MoqTrackDemand::wanted_changed` call, from any binding, never consumes a demand change +- [moq-ffi reports an unsupported media configuration as a typed error](/quest/m1/ffi-unsupported-config.md) - `MoqAudioConsumer::subscribe` and the matching video subscribe fail with a typed "unsupported configuration" error - [A live keyframe interval change never outruns the declared HLS duration](/quest/m1/js-hls-keyframe-duration.md) - raising a live keyframe interval, even to infinite, never pushes a segment past the declared HLS target duration, and the browser interop cell asserts the catalog `hls` field - [A request stream that opens after its deadline is aborted once and never sends](/quest/m1/js-request-deadline.md) - A `@moq/net` IETF request whose stream finishes opening only after its deadline fired is aborted exactly once, through its `RequestStream`, and never writes its request - [One Ed25519 public key type with one z-base-32 codec](/quest/m1/mesh-key-codec.md) - `moq_auth::mesh::EndpointId` is merged into `moq_sign::PublicKey` diff --git a/quest/m1/ffi-unsupported-config.md b/quest/m1/ffi-unsupported-config.md new file mode 100644 index 00000000000..81053fb0d95 --- /dev/null +++ b/quest/m1/ffi-unsupported-config.md @@ -0,0 +1,43 @@ +# [S] Settle native decoder setup refusal policy + +## Goal + +Settle which native decoder-open failures are an unsupported media configuration, +and whether that setup must precede resolving a rendition's foreign broadcast, +then finish [moq-dev/moq#7730](https://github.com/moq-dev/moq/pull/7730). +The typed binding error, wrapper support, and OBS ranked fallback are implemented; +later async peer or decode failures remain outside this quest. + +## Plan + +The user chose a distinct `MoqError` variant returned by audio/video subscribe, +mirrored in moq-c and the wrappers, with OBS falling through on that error and +removing its duplicated audio codec gate (2026-10-31). + +The current implementation tags decoder/output setup at the Rust consumer boundary. +Peer retention refusals and worker startup/loss retain separate errors. A malformed +AAC AudioSpecificConfig is a setup refusal regardless of how many decoder backends +are available. OBS owns one ranked catalog snapshot per selection and tries each +candidate once; it does not permanently cache refusals across catalog updates. + +Local review exposed two choices the existing error/API shapes cannot distinguish. +`moq-video`'s backend selector aggregates unavailable capabilities and device/resource +failures into `NoDecoder`; classifying only static unsupported configurations requires +preserving that distinction before aggregation. `MoqAudioConsumer::subscribe` resolves +before opening its decoder, so an unsupported configuration referencing an unannounced +foreign broadcast can wait before the decoder gets to refuse it. The current broadcast +is already pinned, and rejected local configurations never subscribe to a media track. +A disposable synchronous probe would open a decoder twice; a prepared decoder handle +could establish support once and be reused after resolution, but adds public API. + +Public API: adds `MoqError::UnsupportedConfig`, matching Rust consumer errors and +binding variants, plus moq-c's typed status. Wire: none. + +## Waiting + +- Maintainer: Choose the decoder-open failure boundary. (1) Keep the attempt-scoped `UnsupportedConfig` for local codec/backend-open refusals, preserving peer and worker failures (recommended, the current implementation). (2) Reserve it for known unsupported codec/layout/description and keep device/resource failures distinct; this needs a typed backend error taxonomy before `NoDecoder` aggregation. Record the choice on [moq-dev/moq#7730](https://github.com/moq-dev/moq/pull/7730), then adjust code and review against it. +- Maintainer: Choose whether local setup must precede foreign broadcast resolution. (1) Keep subscribe's existing resolve-then-open shape with one authoritative decoder open (recommended for this quest's current scope). (2) Split preparation from subscription using a reusable decoder handle, so unsupported foreign renditions fail before any origin request. Settle that public shape before implementing it; avoid a separate check that opens a throwaway decoder and then opens it again. + +## Related + +- [moq-dev/moq#7331](https://github.com/moq-dev/moq/pull/7331) introduced OBS's duplicated audio codec gate. diff --git a/rs/moq-audio/src/aac.rs b/rs/moq-audio/src/aac.rs index d30d3b78eef..b16668b9360 100644 --- a/rs/moq-audio/src/aac.rs +++ b/rs/moq-audio/src/aac.rs @@ -88,7 +88,8 @@ pub(crate) fn description(catalog: &hang::catalog::AudioConfig, profile: u8) -> } }; - let parsed = moq_mux::codec::aac::Config::parse(&mut description.as_ref()).map_err(moq_mux::Error::from)?; + let parsed = moq_mux::codec::aac::Config::parse(&mut description.as_ref()) + .map_err(|err| Error::Unsupported(format!("invalid AAC description: {err}")))?; validate(&parsed)?; // HE-AAC has two spellings. `validate` catches the one that leads with SBR or diff --git a/rs/moq-audio/src/error.rs b/rs/moq-audio/src/error.rs index ff96391db15..ff0b09e9676 100644 --- a/rs/moq-audio/src/error.rs +++ b/rs/moq-audio/src/error.rs @@ -5,14 +5,16 @@ #[derive(Clone, Debug, thiserror::Error)] #[non_exhaustive] pub enum Error { - /// The rendition or decoder output was refused before subscribing to its track. - #[error("unsupported audio configuration: {0}")] + /// An audio consumer's decoder or output setup was refused before subscribing to its track. + #[error("audio decoder setup refused: {0}")] UnsupportedConfig(String), /// The requested configuration is outside what the codec or device supports, /// e.g. a sample rate, channel count, or frame duration Opus can't encode, or a /// capture format the microphone can't deliver. The /// caller asked for something impossible; picking different settings fixes it. + /// This also covers a playout delay beyond the subscribed track's retention; + /// consumer decoder setup is tagged as [`Self::UnsupportedConfig`] instead. #[error("unsupported audio configuration: {0}")] Unsupported(String), diff --git a/rs/moq-ffi/src/test.rs b/rs/moq-ffi/src/test.rs index cf1b88d7b36..6d1b4978a6c 100644 --- a/rs/moq-ffi/src/test.rs +++ b/rs/moq-ffi/src/test.rs @@ -9179,6 +9179,8 @@ async fn audio_subscribe_configuration_boundary() { ("mp4a.40.2", Some(vec![0x11, 0x90]), 2, true), ("mp4a.40.2", Some(vec![0x12, 0x10, 0x56, 0xe5, 0x98]), 2, false), ("mp4a.40.2", Some(vec![0x11]), 2, false), + // Frequency index 15 promises a 24-bit rate that is absent from these two bytes. + ("mp4a.40.2", Some(vec![0x17, 0x90]), 2, false), ("mp4a.40.2", None, 6, false), ("mp4a.40.5", None, 2, false), ] { @@ -9190,9 +9192,10 @@ async fn audio_subscribe_configuration_boundary() { if supported { result.unwrap().cancel(); } else { + let error = result.err(); assert!( - matches!(result, Err(MoqError::UnsupportedConfig { .. })), - "{codec}/{channels}" + matches!(&error, Some(MoqError::UnsupportedConfig { .. })), + "{codec}/{channels}: {error:?}" ); } } @@ -9254,6 +9257,7 @@ async fn video_subscribe_configuration_boundary() { ("avc1.42001e", None, true), ("avc1.42001e", Some(vec![]), false), ("avc1.42001e", Some(vec![1, 0x42, 0, 0x1e]), false), + // hvc1 requires hvcC before any backend is opened, even on HEVC-capable hosts. ("hvc1.1.6.L93.B0", None, false), ("vp09.02.10.10", None, false), ("avc1.invalid", None, false), From a960f3721f1a372d48c85737fc0e9e6cb833d123 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 3 Nov 2026 14:10:45 -0800 Subject: [PATCH 6/6] fix(ffi): refuse only known-unsupported decoder setups Return UnsupportedConfig only for a codec, layout, or description the decoder knows it cannot handle, per the maintainer's decision. Backend faults keep typed errors of their own: libopus allocation and internal failures become moq_audio::Error::Codec, a multi-backend audio refusal reports a fault instead of folding it into Unsupported, and moq_video::Error::NoDecoder now means only that every compiled-in decoder failed to open. Missing or malformed avcC/hvcC descriptions and codecs with no compiled-in decoder are UnsupportedCodec. A zero output sample rate stays a caller error. The quest is finished, so delete it. Co-Authored-By: Claude Opus 5.5 --- c/moq/MIGRATE.md | 2 +- cpp/moq/MIGRATE.md | 2 +- dart/moq/MIGRATE.md | 2 +- dart/moq_ffi/MIGRATE.md | 2 +- doc/lib/cpp/index.md | 2 +- doc/lib/dart/index.md | 2 +- doc/lib/go/index.md | 2 +- doc/lib/kt/index.md | 2 +- doc/lib/py/index.md | 2 +- doc/lib/swift/index.md | 2 +- go/wrapper/MIGRATE.md | 2 +- kt/moq-ffi/MIGRATE.md | 2 +- kt/moq/MIGRATE.md | 2 +- py/moq-ffi/MIGRATE.md | 2 +- py/moq-rs/MIGRATE.md | 2 +- quest/m1/README.md | 1 - quest/m1/ffi-unsupported-config.md | 43 -------------------------- rs/moq-audio/MIGRATE.md | 4 ++- rs/moq-audio/src/decode/backend/mod.rs | 25 +++++++++++++-- rs/moq-audio/src/decode/consumer.rs | 7 +++-- rs/moq-audio/src/error.rs | 6 ++++ rs/moq-audio/src/opus.rs | 28 ++++++++++++++++- rs/moq-c/src/error.rs | 4 +-- rs/moq-ffi/MIGRATE.md | 2 +- rs/moq-ffi/src/error.rs | 3 +- rs/moq-ffi/src/test.rs | 36 +++++++++++---------- rs/moq-video/MIGRATE.md | 2 +- rs/moq-video/src/decode/backend/mod.rs | 9 ++++-- rs/moq-video/src/decode/consumer.rs | 7 +++-- rs/moq-video/src/decode/decoder.rs | 25 ++++++++------- rs/moq-video/src/error.rs | 12 ++++--- swift/MIGRATE.md | 2 +- 32 files changed, 136 insertions(+), 110 deletions(-) delete mode 100644 quest/m1/ffi-unsupported-config.md diff --git a/c/moq/MIGRATE.md b/c/moq/MIGRATE.md index 2429053e0db..a880800ee85 100644 --- a/c/moq/MIGRATE.md +++ b/c/moq/MIGRATE.md @@ -6,7 +6,7 @@ How to update your code for each breaking change, newest first. ### Media setup refusals are typed -Audio and video subscribe setup now reports `MOQ_ERROR_UNSUPPORTED_CONFIG` when the decoder refuses a codec, layout, or description. Handle this variant to try another rendition instead of inspecting an audio/video error message or `Unsupported`. Later peer and decode failures keep their existing errors. Regenerate bindings and rebuild the matching native library together. +Audio and video subscribe setup now reports `MOQ_ERROR_UNSUPPORTED_CONFIG` when the decoder refuses a codec, layout, or description. Handle this variant to try another rendition instead of inspecting an audio/video error message or `Unsupported`. Decoder faults, such as a backend that fails to open, and later peer and decode failures keep their existing errors. Regenerate bindings and rebuild the matching native library together. ## moq-c 0.7, the hand-written ABI diff --git a/cpp/moq/MIGRATE.md b/cpp/moq/MIGRATE.md index aa495f10f4b..64741d2fcf5 100644 --- a/cpp/moq/MIGRATE.md +++ b/cpp/moq/MIGRATE.md @@ -4,7 +4,7 @@ ### Media setup refusals are typed -Audio and video subscribe setup now reports `moq::Error::kUnsupportedConfig` when the decoder refuses a codec, layout, or description. Handle this variant to try another rendition instead of inspecting an audio/video error message or `Unsupported`. Later peer and decode failures keep their existing errors. Regenerate bindings and rebuild the matching native library together. +Audio and video subscribe setup now reports `moq::Error::kUnsupportedConfig` when the decoder refuses a codec, layout, or description. Handle this variant to try another rendition instead of inspecting an audio/video error message or `Unsupported`. Decoder faults, such as a backend that fails to open, and later peer and decode failures keep their existing errors. Regenerate bindings and rebuild the matching native library together. ### JSON writes take a broadcast-clock timestamp ([#7691](https://github.com/moq-dev/moq/pull/7691)) diff --git a/dart/moq/MIGRATE.md b/dart/moq/MIGRATE.md index b592b166053..55789a0a84a 100644 --- a/dart/moq/MIGRATE.md +++ b/dart/moq/MIGRATE.md @@ -6,7 +6,7 @@ How to update your code for each breaking change, newest first. ### Media setup refusals are typed -Audio and video subscribe setup now reports `UnsupportedConfigMoqException` when the decoder refuses a codec, layout, or description. Handle this variant to try another rendition instead of inspecting an audio/video error message or `Unsupported`. Later peer and decode failures keep their existing errors. Regenerate bindings and rebuild the matching native library together. +Audio and video subscribe setup now reports `UnsupportedConfigMoqException` when the decoder refuses a codec, layout, or description. Handle this variant to try another rendition instead of inspecting an audio/video error message or `Unsupported`. Decoder faults, such as a backend that fails to open, and later peer and decode failures keep their existing errors. Regenerate bindings and rebuild the matching native library together. ### JSON writes take a broadcast-clock timestamp ([#7691](https://github.com/moq-dev/moq/pull/7691)) diff --git a/dart/moq_ffi/MIGRATE.md b/dart/moq_ffi/MIGRATE.md index 337a486424e..1f0d514839c 100644 --- a/dart/moq_ffi/MIGRATE.md +++ b/dart/moq_ffi/MIGRATE.md @@ -4,7 +4,7 @@ ### Media setup refusals are typed -Audio and video subscribe setup now reports `UnsupportedConfigMoqException` when the decoder refuses a codec, layout, or description. Handle this variant to try another rendition instead of inspecting an audio/video error message or `Unsupported`. Later peer and decode failures keep their existing errors. Regenerate bindings and rebuild the matching native library together. +Audio and video subscribe setup now reports `UnsupportedConfigMoqException` when the decoder refuses a codec, layout, or description. Handle this variant to try another rendition instead of inspecting an audio/video error message or `Unsupported`. Decoder faults, such as a backend that fails to open, and later peer and decode failures keep their existing errors. Regenerate bindings and rebuild the matching native library together. ### Follow the core API migration guide diff --git a/doc/lib/cpp/index.md b/doc/lib/cpp/index.md index 0f81a1ca781..f10a48386b8 100644 --- a/doc/lib/cpp/index.md +++ b/doc/lib/cpp/index.md @@ -207,7 +207,7 @@ future completed, which is the executor thread. ## Disabled renditions -A rendition with `enabled: false` has no frames coming until its publisher re-enables it. Select an enabled rendition from the latest catalog before opening a decoder. Keep one already playing while every rendition of its kind is disabled: the convenience decoders accept a disabled configuration, and a re-enable, such as an unmute, then plays without a resubscribe. Among the video renditions you can decode, prefer the highest `preference`; `0` is the default and `-1` marks a compatibility transcode. Audio and video subscribe setup returns `moq::Error::kUnsupportedConfig` when the decoder refuses the codec, layout, or description; a player can then try its next ranked rendition. Later peer or decode failures do not report that setup refusal. +A rendition with `enabled: false` has no frames coming until its publisher re-enables it. Select an enabled rendition from the latest catalog before opening a decoder. Keep one already playing while every rendition of its kind is disabled: the convenience decoders accept a disabled configuration, and a re-enable, such as an unmute, then plays without a resubscribe. Among the video renditions you can decode, prefer the highest `preference`; `0` is the default and `-1` marks a compatibility transcode. Audio and video subscribe setup returns `moq::Error::kUnsupportedConfig` when the decoder refuses the codec, layout, or description; a player can then try its next ranked rendition. Decoder faults and later peer or decode failures do not report that setup refusal. ## Bandwidth estimates diff --git a/doc/lib/dart/index.md b/doc/lib/dart/index.md index dccb0417325..672e698798c 100644 --- a/doc/lib/dart/index.md +++ b/doc/lib/dart/index.md @@ -159,7 +159,7 @@ shows which module holds each. - **Authorization.** On `moq-lite-07-wip` (opt in with `ConnectOptions(versions: ...)`) and on moq-transport draft-18+ with the [MoQ Auth extension](/draft/moq-auth), listen to `moq.grants().updates()` for the `Grant` the relay sent back and each change, `null` until it answers and while a client session reconnects. - **Tokens.** Pass `ConnectOptions(tokens: [...])` instead of putting the credential in the URL. The first is the connection credential, sent in SETUP and, while an offered version can't carry it there (lite before 07), as the URL's `?jwt=`; each other token widens the grant over AUTH. `moq.tokens().set_(tokens: [...])` replaces them before they expire: the next dial presents them, a live AUTH session at once, and after an authorization refusal the session redials only if they changed. `await tokens().answered()` returns once the relay accepts them and throws its refusal with the relay's code. A `?jwt=` already in the URL stays the connection credential, which is how to reach a relay older than this release. - **Errors.** Read diagnostic payloads from `reason` and structured protocol failures from `details`. -- **Disabled renditions.** A rendition with `enabled: false` has no frames coming until its publisher re-enables it. Select an enabled rendition from the latest catalog before opening a decoder. Keep one already playing while every rendition of its kind is disabled: the convenience decoders accept a disabled configuration, and a re-enable, such as an unmute, then plays without a resubscribe. Among the video renditions you can decode, prefer the highest `preference`; `0` is the default and `-1` marks a compatibility transcode. Audio and video subscribe setup returns `UnsupportedConfigMoqException` when the decoder refuses the codec, layout, or description; a player can then try its next ranked rendition. Later peer or decode failures do not report that setup refusal. +- **Disabled renditions.** A rendition with `enabled: false` has no frames coming until its publisher re-enables it. Select an enabled rendition from the latest catalog before opening a decoder. Keep one already playing while every rendition of its kind is disabled: the convenience decoders accept a disabled configuration, and a re-enable, such as an unmute, then plays without a resubscribe. Among the video renditions you can decode, prefer the highest `preference`; `0` is the default and `-1` marks a compatibility transcode. Audio and video subscribe setup returns `UnsupportedConfigMoqException` when the decoder refuses the codec, layout, or description; a player can then try its next ranked rendition. Decoder faults and later peer or decode failures do not report that setup refusal. - **Subscription defaults.** A bare `Subscription()`, passing no subscription, and `defaultSubscription()` all mean moq-net's defaults, whose zero `delay` starts at the newest group and skips a superseded one at once. `Delay` defaults both bounds to zero: pass `max: null` for no subscriber limit, or `min: null` to leave the target latency unstated. Decoders take the same `Delay`. - **Track demand.** Obtain a dynamic track request’s `demand()` before accepting it to watch subscribers through the handoff to its producer. The watch does not keep the track alive and ends when the track closes or the request is rejected. A producer publishes everything you write, subscribed or not, so a late subscriber can fetch the recent past. Capturing only while a producer's `demand()` reports a subscriber is an opt-in that saves the encode but leaves nothing from before the first one. diff --git a/doc/lib/go/index.md b/doc/lib/go/index.md index 61921f5ad36..3e162edc3c8 100644 --- a/doc/lib/go/index.md +++ b/doc/lib/go/index.md @@ -140,7 +140,7 @@ shows which module holds each. - **Authorization.** On `moq-lite-07-wip` (opt in with `ClientConfig.Versions`) and on moq-transport draft-18+ with the [MoQ Auth extension](/draft/moq-auth), `Session().Grants()` returns a `GrantConsumer`: `Grant()` is the `Grant` the relay sent back, nil until it answers and while a client session reconnects, and `Changed(ctx)` waits for the next one. `Close()` it when done. - **Tokens.** Set `ClientConfig.Tokens` instead of putting the credential in the URL. The first is the connection credential, sent in SETUP and, while an offered version can't carry it there (lite before 07), as the URL's `?jwt=`; each other token widens the grant over AUTH. `Session().Tokens().Set(...)` replaces a client session's tokens before they expire: the next dial presents them, a live AUTH session at once, and after an authorization refusal the session redials only if they changed. `Answered(ctx)` returns nil once the relay accepts them, or its refusal with the relay's code. A `?jwt=` already in the URL stays the connection credential, which is how to reach a relay older than this release. - **Errors.** Read diagnostic payloads from `Reason` and structured protocol failures from `Details`. -- **Disabled renditions.** A rendition with `enabled: false` has no frames coming until its publisher re-enables it. Select an enabled rendition from the latest catalog before opening a decoder. Keep one already playing while every rendition of its kind is disabled: the convenience decoders accept a disabled configuration, and a re-enable, such as an unmute, then plays without a resubscribe. Among the video renditions you can decode, prefer the highest `Preference`; `0` is the default and `-1` marks a compatibility transcode. Audio and video subscribe setup returns `moq.ErrUnsupportedConfig` when the decoder refuses the codec, layout, or description; a player can then try its next ranked rendition. Later peer or decode failures do not report that setup refusal. +- **Disabled renditions.** A rendition with `enabled: false` has no frames coming until its publisher re-enables it. Select an enabled rendition from the latest catalog before opening a decoder. Keep one already playing while every rendition of its kind is disabled: the convenience decoders accept a disabled configuration, and a re-enable, such as an unmute, then plays without a resubscribe. Among the video renditions you can decode, prefer the highest `Preference`; `0` is the default and `-1` marks a compatibility transcode. Audio and video subscribe setup returns `moq.ErrUnsupportedConfig` when the decoder refuses the codec, layout, or description; a player can then try its next ranked rendition. Decoder faults and later peer or decode failures do not report that setup refusal. - **Subscription defaults.** A zero `moq.Subscription{}`, a nil `*Subscription`, and `moq.DefaultSubscription()` all mean moq-net's defaults, whose zero `Delay` starts at the newest group and skips a superseded one at once. Set `Delay.MaxUnlimited` for no subscriber limit, and `Delay.MinUnstated` to leave the target latency unstated. Decoders take the same `moq.Delay`. - **Track demand.** Obtain a dynamic track request’s `Demand()` before accepting it to watch subscribers through the handoff to its producer. The watch does not keep the track alive and ends when the track closes or the request is rejected. A producer publishes everything you write, subscribed or not, so a late subscriber can fetch the recent past. Capturing only while a producer's `Demand()` reports a subscriber is an opt-in that saves the encode but leaves nothing from before the first one. diff --git a/doc/lib/kt/index.md b/doc/lib/kt/index.md index 16f0fa1b261..0b9d467fc99 100644 --- a/doc/lib/kt/index.md +++ b/doc/lib/kt/index.md @@ -114,7 +114,7 @@ shows which module holds each. - **Authorization.** On `moq-lite-07-wip` (opt in with `ClientConfig(versions = ...)`) and on moq-transport draft-18+ with the [MoQ Auth extension](/draft/moq-auth), collect `moq.grants().updates()` for the `Grant` the relay sent back and each change, `null` until it answers and while a client session reconnects. Ending the collection cancels the consumer. - **Tokens.** Pass `ClientConfig(tokens = listOf(...))` instead of putting the credential in the URL. The first is the connection credential, sent in SETUP and, while an offered version can't carry it there (lite before 07), as the URL's `?jwt=`; each other token widens the grant over AUTH. `moq.tokens().set(listOf(...))` replaces them before they expire: the next dial presents them, a live AUTH session at once, and after an authorization refusal the session redials only if they changed. Suspending `tokens().answered()` returns once the relay accepts them and throws its refusal with the relay's code. A `?jwt=` already in the URL stays the connection credential, which is how to reach a relay older than this release. - **Errors.** Read diagnostic payloads from `reason` and structured protocol failures from `details`. -- **Disabled renditions.** A rendition with `enabled: false` has no frames coming until its publisher re-enables it. Select an enabled rendition from the latest catalog before opening a decoder. Keep one already playing while every rendition of its kind is disabled: the convenience decoders accept a disabled configuration, and a re-enable, such as an unmute, then plays without a resubscribe. Among the video renditions you can decode, prefer the highest `preference`; `0` is the default and `-1` marks a compatibility transcode. Audio and video subscribe setup returns `MoqException.UnsupportedConfig` when the decoder refuses the codec, layout, or description; a player can then try its next ranked rendition. Later peer or decode failures do not report that setup refusal. +- **Disabled renditions.** A rendition with `enabled: false` has no frames coming until its publisher re-enables it. Select an enabled rendition from the latest catalog before opening a decoder. Keep one already playing while every rendition of its kind is disabled: the convenience decoders accept a disabled configuration, and a re-enable, such as an unmute, then plays without a resubscribe. Among the video renditions you can decode, prefer the highest `preference`; `0` is the default and `-1` marks a compatibility transcode. Audio and video subscribe setup returns `MoqException.UnsupportedConfig` when the decoder refuses the codec, layout, or description; a player can then try its next ranked rendition. Decoder faults and later peer or decode failures do not report that setup refusal. - **Subscription defaults.** `Subscription.default()` returns moq-net's defaults, whose zero `delay` starts at the newest group and skips a superseded one at once; passing no subscription means the same. `copy` it to change a field; building a `Subscription(...)` must name its `Delay(min, max)`, where a null `max` sets no subscriber limit and a null `min` leaves the target latency unstated. Decoders take the same `Delay`. - **Track demand.** Obtain a dynamic track request’s `demand()` before accepting it to watch subscribers through the handoff to its producer. The watch does not keep the track alive and ends when the track closes or the request is rejected. A producer publishes everything you write, subscribed or not, so a late subscriber can fetch the recent past. Capturing only while a producer's `demand()` reports a subscriber is an opt-in that saves the encode but leaves nothing from before the first one. diff --git a/doc/lib/py/index.md b/doc/lib/py/index.md index 11c2adb8957..9525af5ecc0 100644 --- a/doc/lib/py/index.md +++ b/doc/lib/py/index.md @@ -128,7 +128,7 @@ shows which module holds each. - **Authorization.** On `moq-lite-07-wip` (opt in with `versions=`) and on moq-transport draft-18+ with the [MoQ Auth extension](/draft/moq-auth), `async for grant in session.grants()` yields the `Grant` the relay sent back and each change, `None` until it answers and while a client session reconnects. `grants().grant()` reads it once; cancelling or leaving an `async with` releases the wait. - **Tokens.** Pass `tokens=[...]` instead of putting the credential in the URL. The first is the connection credential, sent in SETUP and, while an offered version can't carry it there (lite before 07), as the URL's `?jwt=`; each other token widens the grant over AUTH. `session.tokens().set([...])` replaces a client session's tokens before they expire: the next dial presents them, a live AUTH session at once, and after an authorization refusal the session redials only if they changed. `await tokens.answered()` returns once the relay accepts them and raises its refusal with the relay's code. A `?jwt=` already in the URL stays the connection credential, which is how to reach a relay older than this release. - **Errors.** Read diagnostic payloads from `reason` and structured protocol failures from `details`. -- **Disabled renditions.** A rendition with `enabled: false` has no frames coming until its publisher re-enables it. Select an enabled rendition from the latest catalog before opening a decoder. Keep one already playing while every rendition of its kind is disabled: the convenience decoders accept a disabled configuration, and a re-enable, such as an unmute, then plays without a resubscribe. Among the video renditions you can decode, prefer the highest `preference`; `0` is the default and `-1` marks a compatibility transcode. Audio and video subscribe setup returns `moq.Error.UnsupportedConfig` when the decoder refuses the codec, layout, or description; a player can then try its next ranked rendition. Later peer or decode failures do not report that setup refusal. +- **Disabled renditions.** A rendition with `enabled: false` has no frames coming until its publisher re-enables it. Select an enabled rendition from the latest catalog before opening a decoder. Keep one already playing while every rendition of its kind is disabled: the convenience decoders accept a disabled configuration, and a re-enable, such as an unmute, then plays without a resubscribe. Among the video renditions you can decode, prefer the highest `preference`; `0` is the default and `-1` marks a compatibility transcode. Audio and video subscribe setup returns `moq.Error.UnsupportedConfig` when the decoder refuses the codec, layout, or description; a player can then try its next ranked rendition. Decoder faults and later peer or decode failures do not report that setup refusal. - **Subscription defaults.** A bare `moq.Subscription()`, passing no subscription, and `moq.Subscription.default()` all mean moq-net's defaults, whose zero `delay` starts at the newest group and skips a superseded one at once. Pass `delay=moq.Delay(max=None)` for no subscriber limit, or `min=None` to leave the target latency unstated. Decoders take the same `moq.Delay`. - **Track demand.** Obtain a dynamic track request’s `demand()` before accepting it to watch subscribers through the handoff to its producer. The watch does not keep the track alive and ends when the track closes or the request is rejected. A producer publishes everything you write, subscribed or not, so a late subscriber can fetch the recent past. Capturing only while a producer's `demand()` reports a subscriber is an opt-in that saves the encode but leaves nothing from before the first one. diff --git a/doc/lib/swift/index.md b/doc/lib/swift/index.md index 4265e6eb2f8..2a965b9c834 100644 --- a/doc/lib/swift/index.md +++ b/doc/lib/swift/index.md @@ -114,7 +114,7 @@ shows which module holds each. - **Authorization.** On `moq-lite-07-wip` (opt in with `Client(versions:)`) and on moq-transport draft-18+ with the [MoQ Auth extension](/draft/moq-auth), `for try await grant in session.grants()` yields the `Grant` the relay sent back and each change, `nil` until it answers and while a client session reconnects. Cancelling the iterating task cancels the native wait. - **Tokens.** Pass `Client(tokens: [...])` instead of putting the credential in the URL. The first is the connection credential, sent in SETUP and, while an offered version can't carry it there (lite before 07), as the URL's `?jwt=`; each other token widens the grant over AUTH. `try session.tokens()?.set([...])` replaces them before they expire: the next dial presents them, a live AUTH session at once, and after an authorization refusal the session redials only if they changed. `try await tokens.answered()` returns once the relay accepts them and throws its refusal with the relay's code. A `?jwt=` already in the URL stays the connection credential, which is how to reach a relay older than this release. - **Errors.** Diagnostic cases use the `reason:` argument label; match their associated value to inspect it. Protocol errors carry `details`. -- **Disabled renditions.** A rendition with `enabled: false` has no frames coming until its publisher re-enables it. Select an enabled rendition from the latest catalog before opening a decoder. Keep one already playing while every rendition of its kind is disabled: the convenience decoders accept a disabled configuration, and a re-enable, such as an unmute, then plays without a resubscribe. Among the video renditions you can decode, prefer the highest `preference`; `0` is the default and `-1` marks a compatibility transcode. Audio and video subscribe setup returns `MoqError.UnsupportedConfig` when the decoder refuses the codec, layout, or description; a player can then try its next ranked rendition. Later peer or decode failures do not report that setup refusal. +- **Disabled renditions.** A rendition with `enabled: false` has no frames coming until its publisher re-enables it. Select an enabled rendition from the latest catalog before opening a decoder. Keep one already playing while every rendition of its kind is disabled: the convenience decoders accept a disabled configuration, and a re-enable, such as an unmute, then plays without a resubscribe. Among the video renditions you can decode, prefer the highest `preference`; `0` is the default and `-1` marks a compatibility transcode. Audio and video subscribe setup returns `MoqError.UnsupportedConfig` when the decoder refuses the codec, layout, or description; a player can then try its next ranked rendition. Decoder faults and later peer or decode failures do not report that setup refusal. - **Subscription defaults.** `Subscription.default` holds moq-net's defaults, whose zero `delay` starts at the newest group and skips a superseded one at once; passing no subscription means the same. Copy it to change a field; building a `Subscription(...)` must name its `Delay(min:max:)`, where a `nil` `max` sets no subscriber limit and a `nil` `min` leaves the target latency unstated. Decoders take the same `Delay`. - **Track demand.** Obtain a dynamic track request’s `demand()` before accepting it to watch subscribers through the handoff to its producer. The watch does not keep the track alive and ends when the track closes or the request is rejected. A producer publishes everything you write, subscribed or not, so a late subscriber can fetch the recent past. Capturing only while a producer's `demand()` reports a subscriber is an opt-in that saves the encode but leaves nothing from before the first one. diff --git a/go/wrapper/MIGRATE.md b/go/wrapper/MIGRATE.md index 40ff830bbf2..d3188ea7fff 100644 --- a/go/wrapper/MIGRATE.md +++ b/go/wrapper/MIGRATE.md @@ -6,7 +6,7 @@ How to update your code for each breaking change, newest first. ### Media setup refusals are typed -Audio and video subscribe setup now reports `ErrUnsupportedConfig` when the decoder refuses a codec, layout, or description. Handle this variant to try another rendition instead of inspecting an audio/video error message or `Unsupported`. Later peer and decode failures keep their existing errors. Regenerate bindings and rebuild the matching native library together. +Audio and video subscribe setup now reports `ErrUnsupportedConfig` when the decoder refuses a codec, layout, or description. Handle this variant to try another rendition instead of inspecting an audio/video error message or `Unsupported`. Decoder faults, such as a backend that fails to open, and later peer and decode failures keep their existing errors. Regenerate bindings and rebuild the matching native library together. ### JSON writes take a broadcast-clock timestamp ([#7691](https://github.com/moq-dev/moq/pull/7691)) diff --git a/kt/moq-ffi/MIGRATE.md b/kt/moq-ffi/MIGRATE.md index deffe2c09a6..9525d9ce6a6 100644 --- a/kt/moq-ffi/MIGRATE.md +++ b/kt/moq-ffi/MIGRATE.md @@ -4,7 +4,7 @@ ### Media setup refusals are typed -Audio and video subscribe setup now reports `MoqException.UnsupportedConfig` when the decoder refuses a codec, layout, or description. Handle this variant to try another rendition instead of inspecting an audio/video error message or `Unsupported`. Later peer and decode failures keep their existing errors. Regenerate bindings and rebuild the matching native library together. +Audio and video subscribe setup now reports `MoqException.UnsupportedConfig` when the decoder refuses a codec, layout, or description. Handle this variant to try another rendition instead of inspecting an audio/video error message or `Unsupported`. Decoder faults, such as a backend that fails to open, and later peer and decode failures keep their existing errors. Regenerate bindings and rebuild the matching native library together. ### Follow the core API migration guide diff --git a/kt/moq/MIGRATE.md b/kt/moq/MIGRATE.md index 2ecc6cc483c..cef72975bb2 100644 --- a/kt/moq/MIGRATE.md +++ b/kt/moq/MIGRATE.md @@ -6,7 +6,7 @@ How to update your code for each breaking change, newest first. ### Media setup refusals are typed -Audio and video subscribe setup now reports `MoqException.UnsupportedConfig` when the decoder refuses a codec, layout, or description. Handle this variant to try another rendition instead of inspecting an audio/video error message or `Unsupported`. Later peer and decode failures keep their existing errors. Regenerate bindings and rebuild the matching native library together. +Audio and video subscribe setup now reports `MoqException.UnsupportedConfig` when the decoder refuses a codec, layout, or description. Handle this variant to try another rendition instead of inspecting an audio/video error message or `Unsupported`. Decoder faults, such as a backend that fails to open, and later peer and decode failures keep their existing errors. Regenerate bindings and rebuild the matching native library together. ### JSON writes take a broadcast-clock timestamp ([#7691](https://github.com/moq-dev/moq/pull/7691)) diff --git a/py/moq-ffi/MIGRATE.md b/py/moq-ffi/MIGRATE.md index 6d9b6618a00..042afc06407 100644 --- a/py/moq-ffi/MIGRATE.md +++ b/py/moq-ffi/MIGRATE.md @@ -4,7 +4,7 @@ ### Media setup refusals are typed -Audio and video subscribe setup now reports `UnsupportedConfig` when the decoder refuses a codec, layout, or description. Handle this variant to try another rendition instead of inspecting an audio/video error message or `Unsupported`. Later peer and decode failures keep their existing errors. Regenerate bindings and rebuild the matching native library together. +Audio and video subscribe setup now reports `UnsupportedConfig` when the decoder refuses a codec, layout, or description. Handle this variant to try another rendition instead of inspecting an audio/video error message or `Unsupported`. Decoder faults, such as a backend that fails to open, and later peer and decode failures keep their existing errors. Regenerate bindings and rebuild the matching native library together. ### Follow the core API migration guide diff --git a/py/moq-rs/MIGRATE.md b/py/moq-rs/MIGRATE.md index 73ad9025f53..a85cd9a2c75 100644 --- a/py/moq-rs/MIGRATE.md +++ b/py/moq-rs/MIGRATE.md @@ -6,7 +6,7 @@ How to update your code for each breaking change, newest first. ### Media setup refusals are typed -Audio and video subscribe setup now reports `UnsupportedConfig` when the decoder refuses a codec, layout, or description. Handle this variant to try another rendition instead of inspecting an audio/video error message or `Unsupported`. Later peer and decode failures keep their existing errors. Regenerate bindings and rebuild the matching native library together. +Audio and video subscribe setup now reports `UnsupportedConfig` when the decoder refuses a codec, layout, or description. Handle this variant to try another rendition instead of inspecting an audio/video error message or `Unsupported`. Decoder faults, such as a backend that fails to open, and later peer and decode failures keep their existing errors. Regenerate bindings and rebuild the matching native library together. ### JSON writes take a broadcast-clock timestamp ([#7691](https://github.com/moq-dev/moq/pull/7691)) diff --git a/quest/m1/README.md b/quest/m1/README.md index 9a44dfb4f23..10dd5ced34e 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -179,7 +179,6 @@ per-frame CPU growth since #5926. - [Authored tracks default to a 30 s max-age](/quest/m1/max-age-defaults.md) - raw and media tracks advertise 30 s unless their author chooses otherwise, with explicit unlimited in every binding - [HLS export lists a same-codec reconfigure's first group under the new init](/quest/m1/hls-reinit-same-codec.md) - the hand-over pick, whichever of the catalog and the records arrives first, after the catalog `hls` removal is planned - [A cancelled MoqTrackDemand wait never loses the next change](/quest/m1/demand-cancel-race.md) - cancelling a `MoqTrackDemand::wanted_changed` call, from any binding, never consumes a demand change -- [moq-ffi reports an unsupported media configuration as a typed error](/quest/m1/ffi-unsupported-config.md) - `MoqAudioConsumer::subscribe` and the matching video subscribe fail with a typed "unsupported configuration" error - [A live keyframe interval change never outruns the declared HLS duration](/quest/m1/js-hls-keyframe-duration.md) - raising a live keyframe interval, even to infinite, never pushes a segment past the declared HLS target duration, and the browser interop cell asserts the catalog `hls` field - [One Ed25519 public key type with one z-base-32 codec](/quest/m1/mesh-key-codec.md) - `moq_auth::mesh::EndpointId` is merged into `moq_crypto::sign::PublicKey` - [moqsink reports track demand only once the track is in the catalog](/quest/m1/moqsink-demand-catalog.md) - A `moqsink` request pad's `track-demand` stays null until its track is listed in the published catalog, and only then reports `wanted` diff --git a/quest/m1/ffi-unsupported-config.md b/quest/m1/ffi-unsupported-config.md deleted file mode 100644 index 81053fb0d95..00000000000 --- a/quest/m1/ffi-unsupported-config.md +++ /dev/null @@ -1,43 +0,0 @@ -# [S] Settle native decoder setup refusal policy - -## Goal - -Settle which native decoder-open failures are an unsupported media configuration, -and whether that setup must precede resolving a rendition's foreign broadcast, -then finish [moq-dev/moq#7730](https://github.com/moq-dev/moq/pull/7730). -The typed binding error, wrapper support, and OBS ranked fallback are implemented; -later async peer or decode failures remain outside this quest. - -## Plan - -The user chose a distinct `MoqError` variant returned by audio/video subscribe, -mirrored in moq-c and the wrappers, with OBS falling through on that error and -removing its duplicated audio codec gate (2026-10-31). - -The current implementation tags decoder/output setup at the Rust consumer boundary. -Peer retention refusals and worker startup/loss retain separate errors. A malformed -AAC AudioSpecificConfig is a setup refusal regardless of how many decoder backends -are available. OBS owns one ranked catalog snapshot per selection and tries each -candidate once; it does not permanently cache refusals across catalog updates. - -Local review exposed two choices the existing error/API shapes cannot distinguish. -`moq-video`'s backend selector aggregates unavailable capabilities and device/resource -failures into `NoDecoder`; classifying only static unsupported configurations requires -preserving that distinction before aggregation. `MoqAudioConsumer::subscribe` resolves -before opening its decoder, so an unsupported configuration referencing an unannounced -foreign broadcast can wait before the decoder gets to refuse it. The current broadcast -is already pinned, and rejected local configurations never subscribe to a media track. -A disposable synchronous probe would open a decoder twice; a prepared decoder handle -could establish support once and be reused after resolution, but adds public API. - -Public API: adds `MoqError::UnsupportedConfig`, matching Rust consumer errors and -binding variants, plus moq-c's typed status. Wire: none. - -## Waiting - -- Maintainer: Choose the decoder-open failure boundary. (1) Keep the attempt-scoped `UnsupportedConfig` for local codec/backend-open refusals, preserving peer and worker failures (recommended, the current implementation). (2) Reserve it for known unsupported codec/layout/description and keep device/resource failures distinct; this needs a typed backend error taxonomy before `NoDecoder` aggregation. Record the choice on [moq-dev/moq#7730](https://github.com/moq-dev/moq/pull/7730), then adjust code and review against it. -- Maintainer: Choose whether local setup must precede foreign broadcast resolution. (1) Keep subscribe's existing resolve-then-open shape with one authoritative decoder open (recommended for this quest's current scope). (2) Split preparation from subscription using a reusable decoder handle, so unsupported foreign renditions fail before any origin request. Settle that public shape before implementing it; avoid a separate check that opens a throwaway decoder and then opens it again. - -## Related - -- [moq-dev/moq#7331](https://github.com/moq-dev/moq/pull/7331) introduced OBS's duplicated audio codec gate. diff --git a/rs/moq-audio/MIGRATE.md b/rs/moq-audio/MIGRATE.md index a6c38c85b35..a915e51cf99 100644 --- a/rs/moq-audio/MIGRATE.md +++ b/rs/moq-audio/MIGRATE.md @@ -6,7 +6,9 @@ How to update your code for each breaking change, newest first. ### Consumer decoder setup refusals are typed -`decode::Consumer::new` reports `Error::UnsupportedConfig` for a codec, layout, description, or decoder output it cannot open. Direct `decode::Decoder::new` retains its detailed setup errors. Subscription conditions, including a playout delay beyond the track's retention, keep their existing errors. +`decode::Consumer::new` reports `Error::UnsupportedConfig` for a codec, layout, or description it refuses, where `decode::Decoder::new` reports `Error::Unsupported`. Codec faults, an output sample rate of zero, and subscription conditions such as a playout delay beyond the track's retention keep their own errors. + +A libopus allocation, internal, or state failure is the new `Error::Codec` instead of `Error::Unsupported`, which now means only a configuration libopus refuses. When several decoder backends fail, a fault is reported instead of being folded into `Unsupported`. ### Capture is one producer with independent consumers diff --git a/rs/moq-audio/src/decode/backend/mod.rs b/rs/moq-audio/src/decode/backend/mod.rs index 32c359facb5..588622600da 100644 --- a/rs/moq-audio/src/decode/backend/mod.rs +++ b/rs/moq-audio/src/decode/backend/mod.rs @@ -117,12 +117,20 @@ fn select(catalog: &AudioConfig, candidates: Vec<&Candidate>) -> Result = refused.iter().map(|(name, err)| format!("{name}: {err}")).collect(); return Err(Error::Unsupported(reasons.join(", "))); @@ -232,4 +240,17 @@ mod tests { "{message}" ); } + + /// A backend fault is not a refusal of the track, so it is never folded into one. + #[test] + fn a_fault_outranks_refusals() { + const FAULTY: Candidate = Candidate { + name: "faulty", + supports: |codec| matches!(codec, AudioCodec::Opus), + open: |_| Err(Error::Codec("allocation failed".into())), + }; + + let err = pick(Kind::Auto, &[REFUSING], &[FAULTY]).unwrap_err(); + assert!(matches!(err, Error::Codec(_)), "{err:?}"); + } } diff --git a/rs/moq-audio/src/decode/consumer.rs b/rs/moq-audio/src/decode/consumer.rs index e691e0d2ae1..764576e8429 100644 --- a/rs/moq-audio/src/decode/consumer.rs +++ b/rs/moq-audio/src/decode/consumer.rs @@ -179,8 +179,9 @@ impl Consumer { name: impl Into, options: Options, ) -> Result { - // Only the local decoder/output setup is a capability refusal. Conditions learned - // from the subscription, such as retention, keep their original errors. + // Only a codec, layout, or description the decoder refuses is a capability refusal. + // Codec faults and conditions learned from the subscription, such as retention, + // keep their original errors. let setup = |err| match err { Error::Unsupported(reason) => Error::UnsupportedConfig(reason), err => err, @@ -194,7 +195,7 @@ impl Consumer { .map_err(setup)?; if sample_rate == 0 { - return Err(Error::UnsupportedConfig("output sample rate must be > 0".into())); + return Err(Error::Unsupported("output sample rate must be > 0".into())); } let name = name.into(); diff --git a/rs/moq-audio/src/error.rs b/rs/moq-audio/src/error.rs index ff0b09e9676..cb428fa2bcc 100644 --- a/rs/moq-audio/src/error.rs +++ b/rs/moq-audio/src/error.rs @@ -42,6 +42,12 @@ pub enum Error { #[error("audio resource already in use: {0}")] Busy(String), + /// The codec library failed for a reason the configuration does not explain, + /// such as an allocation or internal error. Other settings are no more likely + /// to work; the codec itself is at fault. + #[error("audio codec: {0}")] + Codec(String), + /// A packet could not be decoded: truncated, corrupt, or using a codec /// feature this build doesn't implement. The stream itself may be fine, so a /// consumer can log this one and read the next packet. diff --git a/rs/moq-audio/src/opus.rs b/rs/moq-audio/src/opus.rs index ae12c28d203..3ae4bf20c9a 100644 --- a/rs/moq-audio/src/opus.rs +++ b/rs/moq-audio/src/opus.rs @@ -68,8 +68,17 @@ pub(crate) fn frame_size(sample_rate: u32, duration: Duration) -> Result Error { - Error::Unsupported(format!("libopus {context} failed (code {code})")) + let message = format!("libopus {context} failed (code {code})"); + match code { + unsafe_libopus::OPUS_BAD_ARG | unsafe_libopus::OPUS_UNIMPLEMENTED => Error::Unsupported(message), + _ => Error::Codec(message), + } } /// A failed decode call, split by whose fault it is. @@ -329,6 +338,23 @@ pub(crate) fn bitrate_floor(sample_rate: u32, frame_size: usize) -> u64 { mod tests { use super::*; + #[test] + fn only_argument_failures_are_unsupported() { + assert!(matches!( + error(unsafe_libopus::OPUS_BAD_ARG, "ctx"), + Error::Unsupported(_) + )); + assert!(matches!( + error(unsafe_libopus::OPUS_UNIMPLEMENTED, "ctx"), + Error::Unsupported(_) + )); + assert!(matches!(error(unsafe_libopus::OPUS_ALLOC_FAIL, "ctx"), Error::Codec(_))); + assert!(matches!( + error(unsafe_libopus::OPUS_INTERNAL_ERROR, "ctx"), + Error::Codec(_) + )); + } + #[test] fn rate_picker_snaps_up() { assert_eq!(pick_rate(44_100), 48_000); diff --git a/rs/moq-c/src/error.rs b/rs/moq-c/src/error.rs index cf3f77e6007..f9a59d5ea19 100644 --- a/rs/moq-c/src/error.rs +++ b/rs/moq-c/src/error.rs @@ -82,7 +82,7 @@ pub const MOQ_ERROR_UNRESOLVABLE_BROADCAST: i32 = -41; pub const MOQ_ERROR_EXPIRED: i32 = -42; /// The catalog requires a newer moq-hang version than this build supports. pub const MOQ_ERROR_UNSUPPORTED_CATALOG: i32 = -43; -/// The rendition or decoder output was refused during setup; another configuration may work. +/// The rendition's codec, layout, or description was refused during setup; another rendition may work. pub const MOQ_ERROR_UNSUPPORTED_CONFIG: i32 = -44; /// Whether a protocol code is from the session or stream registry. @@ -195,7 +195,7 @@ pub type Status = i32; #[derive(Debug, thiserror::Error, Clone)] #[non_exhaustive] pub enum Error { - /// The rendition or decoder output could not be configured before decoding started. + /// The rendition's codec, layout, or description was refused before decoding started. #[error("unsupported configuration: {0}")] UnsupportedConfig(String), diff --git a/rs/moq-ffi/MIGRATE.md b/rs/moq-ffi/MIGRATE.md index 342c367fbed..b28fde7454e 100644 --- a/rs/moq-ffi/MIGRATE.md +++ b/rs/moq-ffi/MIGRATE.md @@ -7,7 +7,7 @@ These are the UniFFI names; each language wrapper has its own `MIGRATE.md` in it ### Media setup refusals are typed -Audio and video subscribe setup now reports `UnsupportedConfig` when the decoder refuses a codec, layout, or description. Handle this variant to try another rendition instead of inspecting an audio/video error message or `Unsupported`. Later peer and decode failures keep their existing errors. Regenerate bindings and rebuild the matching native library together. +Audio and video subscribe setup now reports `UnsupportedConfig` when the decoder refuses a codec, layout, or description. Handle this variant to try another rendition instead of inspecting an audio/video error message or `Unsupported`. Decoder faults, such as a backend that fails to open, and later peer and decode failures keep their existing errors. Regenerate bindings and rebuild the matching native library together. ### JSON writes take a broadcast-clock timestamp ([#7691](https://github.com/moq-dev/moq/pull/7691)) diff --git a/rs/moq-ffi/src/error.rs b/rs/moq-ffi/src/error.rs index 73d51ea393a..096ac68e331 100644 --- a/rs/moq-ffi/src/error.rs +++ b/rs/moq-ffi/src/error.rs @@ -401,7 +401,8 @@ pub enum MoqError { /// The catalog version this build cannot read. version: u64, }, - /// The rendition or decoder output was refused during setup; another configuration may work. + /// The rendition's codec, layout, or description was refused during setup; another rendition may work. + /// Decoder faults keep [`MoqError::Audio`] or [`MoqError::Video`]. #[error("unsupported configuration: {reason}")] UnsupportedConfig { /// A diagnostic message describing the refusal. diff --git a/rs/moq-ffi/src/test.rs b/rs/moq-ffi/src/test.rs index a88770774af..a0d8bfa4fba 100644 --- a/rs/moq-ffi/src/test.rs +++ b/rs/moq-ffi/src/test.rs @@ -9236,22 +9236,24 @@ async fn audio_subscribe_configuration_boundary() { ); } } - // Output refusals are setup errors too; a missing track is not. - for output in [ - crate::audio::MoqAudioDecoderOutput { - sample_rate: Some(0), - ..audio_output() - }, - crate::audio::MoqAudioDecoderOutput { - channels: Some(0), - ..audio_output() - }, - ] { - assert!(matches!( - MoqAudioConsumer::subscribe(&consumer, "audio".into(), sibling_audio(""), output).await, - Err(MoqError::UnsupportedConfig { .. }) - )); - } + // An output layout the decoder cannot produce is refused too. A zero output rate + // is a caller error no rendition avoids, and a missing track is not a refusal. + let layout = crate::audio::MoqAudioDecoderOutput { + channels: Some(0), + ..audio_output() + }; + assert!(matches!( + MoqAudioConsumer::subscribe(&consumer, "audio".into(), sibling_audio(""), layout).await, + Err(MoqError::UnsupportedConfig { .. }) + )); + let rate = crate::audio::MoqAudioDecoderOutput { + sample_rate: Some(0), + ..audio_output() + }; + assert!(matches!( + MoqAudioConsumer::subscribe(&consumer, "audio".into(), sibling_audio(""), rate).await, + Err(MoqError::Audio { .. }) + )); let missing = MoqAudioConsumer::subscribe(&consumer, "missing".into(), sibling_audio(""), audio_output()).await; assert!(matches!(missing, Err(MoqError::Audio { .. }))); let _limited = broadcast @@ -9272,7 +9274,7 @@ async fn audio_subscribe_configuration_boundary() { sibling_audio(""), crate::audio::MoqAudioDecoderOutput { delay: Some(MoqDelay { - min: Duration::from_millis(20), + min: Some(Duration::from_millis(20)), max: None, }), ..audio_output() diff --git a/rs/moq-video/MIGRATE.md b/rs/moq-video/MIGRATE.md index 796bded3188..fe66bda0f28 100644 --- a/rs/moq-video/MIGRATE.md +++ b/rs/moq-video/MIGRATE.md @@ -6,7 +6,7 @@ How to update your code for each breaking change, newest first. ### Consumer decoder setup refusals are typed -`decode::Consumer::new` reports `Error::UnsupportedConfig` for a codec, description, or decoder output it cannot open. Direct `decode::Decoder::new` retains its detailed setup errors. Subscription failures keep their existing errors. A codec worker that cannot start or exits during initialization reports `Error::CodecGone`, like a worker lost after initialization, rather than `Error::Codec`. +`decode::Consumer::new` reports `Error::UnsupportedConfig` for a codec or description this build cannot decode, where `decode::Decoder::new` reports `Error::UnsupportedCodec`. That now includes a missing or malformed avcC or hvcC description (previously `Error::Codec` or `Error::Mux`) and a codec no compiled-in decoder handles (previously `Error::NoDecoder`). `Error::NoDecoder` now means only that every decoder for the codec failed to open. Backend faults, scale-hint errors, and subscription failures keep their own errors. A codec worker that cannot start or exits during initialization reports `Error::CodecGone`, like a worker lost after initialization, rather than `Error::Codec`. ### `decode::Options::max_delay` is `delay` ([#7311](https://github.com/moq-dev/moq/pull/7311), [#7597](https://github.com/moq-dev/moq/pull/7597)) diff --git a/rs/moq-video/src/decode/backend/mod.rs b/rs/moq-video/src/decode/backend/mod.rs index 46643b71388..00ce3c35051 100644 --- a/rs/moq-video/src/decode/backend/mod.rs +++ b/rs/moq-video/src/decode/backend/mod.rs @@ -320,7 +320,8 @@ fn select(codec: Codec, attempts: Vec, config: &Config) -> Result, config: &Config) -> Result Err(Error::NoDecoder(format!( + kind => Err(Error::UnsupportedCodec(format!( "nothing compiled in for {} at {kind:?} (this build has: {})", codec.label(), available.join(", "), ))), }; } + // Every candidate that decodes the codec failed to open: missing drivers, no + // device, or a library fault. Those are faults, not a property of the track. Err(Error::NoDecoder(tried.join(", "))) } @@ -456,7 +459,7 @@ mod tests { fn disabled_software_backend_is_not_selected() { let mut config = Config::new(); config.kind = Kind::Software; - assert!(matches!(open(Codec::H264, &config), Err(Error::NoDecoder(_)))); + assert!(matches!(open(Codec::H264, &config), Err(Error::UnsupportedCodec(_)))); config.kind = Kind::Named("openh264".to_owned()); assert!(matches!(open(Codec::H264, &config), Err(Error::UnknownDecoder { .. }))); diff --git a/rs/moq-video/src/decode/consumer.rs b/rs/moq-video/src/decode/consumer.rs index e6b7a8d5af3..9beda54c1bf 100644 --- a/rs/moq-video/src/decode/consumer.rs +++ b/rs/moq-video/src/decode/consumer.rs @@ -313,9 +313,10 @@ impl Reader { lookback: u64, ) -> Result { let decoder = Sink::open(catalog, &options.decoder).await.map_err(|err| match err { - // A worker that disappeared is an infrastructure failure, not a capability refusal. - err @ Error::CodecGone(_) => err, - err => Error::UnsupportedConfig(err.to_string()), + // Only a codec or description this build cannot decode is a refusal of the + // rendition. Backend and worker faults keep their own variants. + Error::UnsupportedCodec(reason) => Error::UnsupportedConfig(reason), + err => err, })?; let track = broadcast.track(hang::catalog::Reference::track(catalog, name))?; diff --git a/rs/moq-video/src/decode/decoder.rs b/rs/moq-video/src/decode/decoder.rs index 61ea8f88242..b82346c0265 100644 --- a/rs/moq-video/src/decode/decoder.rs +++ b/rs/moq-video/src/decode/decoder.rs @@ -163,8 +163,11 @@ pub struct Decoder { } impl Decoder { - /// Build a decoder for the catalog's video config. Errors if the codec is - /// not supported by the native backends. + /// Build a decoder for the catalog's video config. + /// + /// A codec or description this build cannot decode is + /// [`Error::UnsupportedCodec`]. A backend that exists for the codec but fails to + /// open is [`Error::NoDecoder`], a fault rather than a property of the track. pub fn new(catalog: &VideoConfig, config: &Config) -> Result { // CMAF samples are length-prefixed whatever the sample entry; Legacy and LOC // carry Annex-B exactly when the parameter sets are in band. @@ -174,7 +177,8 @@ impl Decoder { let conversion = match (cmaf || !h264.inline, catalog.description.as_ref()) { (false, _) => Conversion::Passthrough, (true, Some(avcc)) => { - let params = h264::Avcc::parse(avcc).map_err(moq_mux::Error::from)?; + let params = h264::Avcc::parse(avcc) + .map_err(|err| Error::UnsupportedCodec(format!("invalid avcC description: {err}")))?; let keyframe_prefix = annexb::build_prefix(params.sps.iter().chain(params.pps.iter())); Conversion::LengthPrefixed { length_size: params.length_size, @@ -182,9 +186,9 @@ impl Decoder { } } (true, None) if cmaf => { - return Err(Error::Codec(anyhow::anyhow!( - "CMAF H.264 track is missing its avcC description" - ))); + return Err(Error::UnsupportedCodec( + "CMAF H.264 track is missing its avcC description".into(), + )); } (true, None) => { tracing::warn!("avc1 track has no avcC description; reading it as Annex-B"); @@ -198,11 +202,10 @@ impl Decoder { Conversion::Passthrough } else { let hvcc = catalog.description.as_ref().ok_or_else(|| { - Error::Codec(anyhow::anyhow!( - "length-prefixed H.265 track is missing its hvcC description" - )) + Error::UnsupportedCodec("length-prefixed H.265 track is missing its hvcC description".into()) })?; - let params = h265::Hvcc::parse(hvcc).map_err(moq_mux::Error::from)?; + let params = h265::Hvcc::parse(hvcc) + .map_err(|err| Error::UnsupportedCodec(format!("invalid hvcC description: {err}")))?; let keyframe_prefix = annexb::build_prefix(params.vps.iter().chain(params.sps.iter()).chain(params.pps.iter())); Conversion::LengthPrefixed { @@ -911,7 +914,7 @@ mod tests { let Err(err) = super::Decoder::new(&catalog, &config) else { panic!("software AV1 decode unexpectedly opened"); }; - assert!(matches!(err, crate::Error::NoDecoder(_))); + assert!(matches!(err, crate::Error::UnsupportedCodec(_)), "{err:?}"); } #[test] diff --git a/rs/moq-video/src/error.rs b/rs/moq-video/src/error.rs index 5116198c4aa..6a4af0f9ecd 100644 --- a/rs/moq-video/src/error.rs +++ b/rs/moq-video/src/error.rs @@ -2,7 +2,9 @@ #[derive(Debug, thiserror::Error)] #[non_exhaustive] pub enum Error { - /// The rendition or decoder output could not be configured before decoding started. + /// A [`decode::Consumer`](crate::decode::Consumer) refused the rendition before + /// subscribing: its codec, codec parameters, or description is + /// [unsupported](Self::UnsupportedCodec). Backend faults keep their own variants. #[error("unsupported video configuration: {0}")] UnsupportedConfig(String), @@ -11,8 +13,9 @@ pub enum Error { #[error("no usable video encoder found (tried: {0})")] NoEncoder(String), - /// No decoder matching the requested codec / hardware preference could be - /// opened (none compiled in, or none available on this machine). + /// Every decoder this build has for the requested codec and hardware preference + /// failed to open on this machine: missing drivers, no device, or a library + /// fault. A codec this build has no decoder for is [`UnsupportedCodec`](Self::UnsupportedCodec). #[error("no usable video decoder found (tried: {0})")] NoDecoder(String), @@ -42,7 +45,8 @@ pub enum Error { available: String, }, - /// A track's codec is not supported by the native decoders. + /// A track's codec, codec parameters, or description is not supported by the + /// native decoders this build has. #[error("unsupported codec for native decode: {0}")] UnsupportedCodec(String), diff --git a/swift/MIGRATE.md b/swift/MIGRATE.md index 59dab01d58d..de2bfe1db11 100644 --- a/swift/MIGRATE.md +++ b/swift/MIGRATE.md @@ -6,7 +6,7 @@ How to update your code for each breaking change, newest first. ### Media setup refusals are typed -Audio and video subscribe setup now reports `UnsupportedConfig` when the decoder refuses a codec, layout, or description. Handle this variant to try another rendition instead of inspecting an audio/video error message or `Unsupported`. Later peer and decode failures keep their existing errors. Regenerate bindings and rebuild the matching native library together. +Audio and video subscribe setup now reports `UnsupportedConfig` when the decoder refuses a codec, layout, or description. Handle this variant to try another rendition instead of inspecting an audio/video error message or `Unsupported`. Decoder faults, such as a backend that fails to open, and later peer and decode failures keep their existing errors. Regenerate bindings and rebuild the matching native library together. ### JSON writes take a broadcast-clock timestamp ([#7691](https://github.com/moq-dev/moq/pull/7691))