diff --git a/c/moq/MIGRATE.md b/c/moq/MIGRATE.md index 8426aaa067a..a880800ee85 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`. 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 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 c70c4979916..64741d2fcf5 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`. 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)) `moq::JsonSnapshotProducer::update`, `moq::JsonStreamProducer::append`, and `moq::JsonWindowProducer::push` and `pop` take a required `moq::Timestamp` instead of an optional one. Stamp it from `moq::MediaCatalogProducer::now()`, the broadcast clock every track shares. Their constructors refuse a track created without a `timescale`. 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..16ad9730569 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,23 @@ 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); + // 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"; @@ -1295,11 +1295,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 a7e864393df..55789a0a84a 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`. 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)) `json.SnapshotProducer.update`, `json.StreamProducer.append`, and `json.WindowProducer.push` / `pop` take a `required MoqTimestamp timestamp` on the broadcast clock instead of an optional one. Read it with `MoqMediaCatalogProducer(broadcast: broadcast).now()`. Their track needs a timescale, such as `MoqTrackInfo(timescale: 1000)`; one without is refused. diff --git a/dart/moq_ffi/MIGRATE.md b/dart/moq_ffi/MIGRATE.md index 612358bb729..1f0d514839c 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`. 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 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 b056600b94c..aff33b413d1 100644 --- a/dart/moq_ffi/lib/src/moq.dart +++ b/dart/moq_ffi/lib/src/moq.dart @@ -5765,6 +5765,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, @@ -6930,6 +6936,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) { @@ -22449,7 +22493,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) { @@ -22535,7 +22579,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 603e47b56a4..46017ac2560 100644 --- a/doc/lib/c/index.md +++ b/doc/lib/c/index.md @@ -113,7 +113,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. Stamp media frames and JSON writes from `moq_publish_catalog_now()`, the broadcast clock every track in the broadcast shares; media on a timeline of its own advertises the gap to the JSON tracks as catalog `delay`. JSON writes are converted to their track's milliseconds. A NULL timestamp on any JSON write (snapshot update, stream append, window push or pop) fails with `MOQ_ERROR_INVALID_POINTER` and publishes nothing. 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 a2084da6629..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. +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 dc260668597..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. +- **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 48cb6e19484..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. +- **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 386e1324e70..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. +- **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 ee895a4116d..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. +- **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 5d17d2bc21b..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. +- **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 e2553c8cb0f..d3188ea7fff 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`. 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)) `json.SnapshotProducer.Update`, `json.StreamProducer.Append`, and `json.WindowProducer.Push` / `Pop` take a `moq.Timestamp` instead of a `*moq.Timestamp`, so there is no untimed write. Stamp it from `media.CatalogProducer.Now()`, the broadcast clock every track shares. Their track needs a `TrackInfo.Timescale`; one without is refused. 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..9525d9ce6a6 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`. 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 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 010cf0a3b0e..cef72975bb2 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`. 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)) `json.SnapshotProducer.update(value, timestamp)`, `json.StreamProducer.append(value, timestamp)`, and `json.WindowProducer.push(value, timestamp)` / `pop(count, timestamp)` require a `Timestamp` on the broadcast clock instead of defaulting to null, for both the typed and the `String` overloads. Read it with `media.CatalogProducer(broadcast).now()`. Their track needs a timescale, such as `TrackInfo(timescale = 1_000uL)`; one without is refused. diff --git a/py/moq-ffi/MIGRATE.md b/py/moq-ffi/MIGRATE.md index 677af200662..042afc06407 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`. 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 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 ff25c5e2161..a85cd9a2c75 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`. 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)) `json.SnapshotProducer.update(value, timestamp)`, `json.StreamProducer.append(value, timestamp)`, and `json.WindowProducer.push(value, timestamp)` / `pop(count, timestamp)` require a `Timestamp` on the broadcast clock instead of an optional `timestamp=` keyword. Read it with `media.CatalogProducer(broadcast).now()`. Their track needs a timescale, such as `TrackInfo(timescale=1_000)`; one without is refused. 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 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. diff --git a/rs/moq-audio/MIGRATE.md b/rs/moq-audio/MIGRATE.md index 74684822b4b..a915e51cf99 100644 --- a/rs/moq-audio/MIGRATE.md +++ b/rs/moq-audio/MIGRATE.md @@ -4,6 +4,12 @@ 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, 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 Open `capture::Producer::open(config).await?` once and create a consumer with 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/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 6ebd41e014e..764576e8429 100644 --- a/rs/moq-audio/src/decode/consumer.rs +++ b/rs/moq-audio/src/decode/consumer.rs @@ -179,12 +179,20 @@ impl Consumer { name: impl Into, options: Options, ) -> Result { - let decoder = Decoder::new(catalog, &options.decoder)?; + // 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, + }; + 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())); diff --git a/rs/moq-audio/src/error.rs b/rs/moq-audio/src/error.rs index c81cc457c74..cb428fa2bcc 100644 --- a/rs/moq-audio/src/error.rs +++ b/rs/moq-audio/src/error.rs @@ -5,10 +5,16 @@ #[derive(Clone, Debug, thiserror::Error)] #[non_exhaustive] pub enum Error { + /// 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), @@ -36,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/audio.rs b/rs/moq-c/src/audio.rs index db120d8b4ae..776cb18a604 100644 --- a/rs/moq-c/src/audio.rs +++ b/rs/moq-c/src/audio.rs @@ -523,6 +523,10 @@ pub extern "C" fn moq_encode_audio_finish(producer: u32) -> i32 { /// model. TODO: a future API will pick the right rendition /// automatically (ABR). /// +/// 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. /// /// `on_read` is called with a positive read id per decoded frame, gap, or encoder @@ -561,7 +565,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(|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 067e5229226..f9a59d5ea19 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'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. #[repr(C)] @@ -193,6 +195,10 @@ pub type Status = i32; #[derive(Debug, thiserror::Error, Clone)] #[non_exhaustive] pub enum Error { + /// The rendition's codec, layout, or description was refused 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), @@ -374,13 +380,19 @@ 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)), + } } } 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 +526,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 +544,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::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); + 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 f1b5ee56b7e..b28fde7454e 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`. 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)) `MoqJsonSnapshotProducer::update`, `MoqJsonStreamProducer::append`, and `MoqJsonWindowProducer::push` and `pop` take a required `MoqTimestamp` instead of an optional one that defaulted to null. Stamp it on the broadcast clock, read with `MoqMediaCatalogProducer::now`, so the data shares the media's epoch. diff --git a/rs/moq-ffi/src/audio.rs b/rs/moq-ffi/src/audio.rs index adc29cff582..dc867e1d910 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 @@ -648,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)?; @@ -660,7 +663,13 @@ 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(|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() { @@ -734,10 +743,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 +762,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..096ac68e331 100644 --- a/rs/moq-ffi/src/error.rs +++ b/rs/moq-ffi/src/error.rs @@ -401,6 +401,13 @@ pub enum MoqError { /// The catalog version this build cannot read. version: u64, }, + /// 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. + reason: String, + }, } impl From for MoqError { @@ -493,8 +500,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(), + }, } } } @@ -502,8 +512,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 ce26709fa0f..a0d8bfa4fba 100644 --- a/rs/moq-ffi/src/test.rs +++ b/rs/moq-ffi/src/test.rs @@ -9191,3 +9191,148 @@ 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), + // 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), + ] { + 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 { + let error = result.err(); + assert!( + matches!(&error, Some(MoqError::UnsupportedConfig { .. })), + "{codec}/{channels}: {error:?}" + ); + } + } + // 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 + .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: Some(Duration::from_millis(20)), + max: None, + }), + ..audio_output() + }, + ) + .await; + assert!(matches!(retained, 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 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), + ("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 708e9a97214..c0e5d0f165a 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..fe66bda0f28 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 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)) `decode::Options::max_delay: Duration` is `delay: decode::Delay` (`moq_net::track::Delay`). 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 d2af94d4697..9beda54c1bf 100644 --- a/rs/moq-video/src/decode/consumer.rs +++ b/rs/moq-video/src/decode/consumer.rs @@ -312,7 +312,12 @@ 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 { + // 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))?; let mut subscriber = track 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 378ac2d32bb..6a4af0f9ecd 100644 --- a/rs/moq-video/src/error.rs +++ b/rs/moq-video/src/error.rs @@ -2,13 +2,20 @@ #[derive(Debug, thiserror::Error)] #[non_exhaustive] pub enum Error { + /// 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), + /// 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})")] 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), @@ -38,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/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(_)))); + } +} diff --git a/swift/MIGRATE.md b/swift/MIGRATE.md index bff6d545884..de2bfe1db11 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`. 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)) `Json.SnapshotProducer.update(_:timestamp:)`, `Json.StreamProducer.append(_:timestamp:)`, and `Json.WindowProducer.push(_:timestamp:)` / `pop(_:timestamp:)` require a `Timestamp` on the broadcast clock instead of defaulting to `nil`. Read it with `Media.CatalogProducer(broadcast:).now()`. Their track needs a timescale, such as `TrackInfo(timescale: 1000)`; one without is refused.