Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 6 additions & 3 deletions doc/lib/rs/moq-audio.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,8 +34,10 @@ policy. Decoding likewise separates low-level `decode::Config`, PCM
| `aec` | Acoustic echo cancellation (a port of WebRTC's), so a laptop with no headset doesn't feed itself back |

`decode` picks a backend per track the way `moq-video` does: a platform decoder
first, then software. `decode::Config::kind` forces one (`Kind::Software`, or
`Kind::Named` with a name below), and `Decoder::name()` reports what opened.
first, then software. `decode::Config::kind` narrows it: `Kind::Software` skips
the platform tier, and `Kind::Named` requires the track to be a codec, by its
name (`"opus"`, `"pcm"`, or `"aac"`), and refuses any other. Backends are never
named; `Decoder::name()` reports which one opened.

| Backend | Decodes | Hosts |
| --- | --- | --- |
Expand All @@ -57,7 +59,8 @@ catalog with neither. A description that is present but malformed (truncated,
wrong signature, a new major version, or a channel count its mapping family
forbids) is refused rather than falling back to the catalog's fields.

`encode` selects the same way, through `encode::Settings::kind`, and
`encode` selects the same way, through `encode::Settings::kind`, where
`Kind::Named` requires `Settings::codec` to match the codec name, and
`Encoder::name()` reports what opened.

| Backend | Encodes | Hosts |
Expand Down
1 change: 0 additions & 1 deletion quest/m1/audio-codecs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,6 @@ its own decode and encode quest so verification stays per host.

## Required

- [Named codecs](/quest/m1/audio-codecs/named-codecs.md) - `decode::Kind::Named` keeps the published codec names and picks backends internally; must land before the line merges
- [AudioToolbox decode](/quest/m1/audio-codecs/decode-audiotoolbox.md) - macOS and iOS decode HE-AAC, multichannel AAC, and what else the framework offers
- [HE-AAC catalog output](/quest/m1/audio-codecs/he-aac-catalog-output.md) - HE-AAC catalog entries name the output rate and layout, not the LC core
- [TS Opus export refusals](/quest/m1/audio-codecs/ts-opus-export-refusals.md) - the TS exporter refuses Opus heads its channel code cannot describe instead of mislabeling them
Expand Down
27 changes: 0 additions & 27 deletions quest/m1/audio-codecs/named-codecs.md

This file was deleted.

124 changes: 54 additions & 70 deletions rs/moq-audio/src/decode/backend/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,8 @@
//!
//! [`open`] tries the platform decoders before the software ones, skipping any
//! that does not advertise the catalog codec, and refuses when none opens the
//! track. The software tier is libopus for Opus, a passthrough for PCM, and
//! track. [`Kind::Named`] names the codec, not a backend, so which backend
//! decodes it stays the library's choice. The software tier is libopus for Opus, a passthrough for PCM, and
//! symphonia for AAC-LC mono and stereo (behind the `aac` feature). No platform
//! decoder is wired in yet.

Expand Down Expand Up @@ -42,7 +43,8 @@ pub(crate) trait Backend: Send {
0
}

/// The stable lowercase name [`Kind::Named`] selects this backend by.
/// The stable lowercase name of this backend, as [`Decoder::name`](super::Decoder::name)
/// reports it. Callers never select by it.
fn name(&self) -> &str;
}

Expand Down Expand Up @@ -80,9 +82,28 @@ const SOFTWARE: &[Candidate] = &[
},
];

/// The name [`Kind::Named`] uses for a catalog codec, `None` for one this crate has no name for.
fn codec_name(codec: &AudioCodec) -> Option<&'static str> {
match codec {
AudioCodec::Opus => Some("opus"),
AudioCodec::Pcm => Some("pcm"),
AudioCodec::AAC(_) => Some("aac"),
_ => None,
}
}

/// Open the first backend that advertises the catalog codec and accepts the track.
pub(crate) fn open(catalog: &AudioConfig, config: &Config) -> Result<Box<dyn Backend>, Error> {
select(catalog, &config.kind, candidates(&config.kind, PLATFORM, SOFTWARE))
if let Kind::Named(requested) = &config.kind
&& codec_name(&catalog.codec) != Some(requested)
{
return Err(Error::Unsupported(format!(
"audio decoder {requested:?} is unavailable for {}",
catalog.codec
)));
}

select(catalog, candidates(&config.kind, PLATFORM, SOFTWARE))
}

/// The candidates `kind` allows, in the order to try them.
Expand All @@ -91,13 +112,13 @@ pub(crate) fn open(catalog: &AudioConfig, config: &Config) -> Result<Box<dyn Bac
/// this host compiles in.
fn candidates<'a>(kind: &Kind, platform: &'a [Candidate], software: &'a [Candidate]) -> Vec<&'a Candidate> {
match kind {
Kind::Auto => platform.iter().chain(software).collect(),
Kind::Software => software.iter().collect(),
Kind::Named(name) => platform.iter().chain(software).filter(|c| c.name == name).collect(),
// `open` has already checked that a name matches the codec.
Kind::Auto | Kind::Named(_) => platform.iter().chain(software).collect(),
}
}

fn select(catalog: &AudioConfig, kind: &Kind, candidates: Vec<&Candidate>) -> Result<Box<dyn Backend>, Error> {
fn select(catalog: &AudioConfig, candidates: Vec<&Candidate>) -> Result<Box<dyn Backend>, Error> {
let codec = &catalog.codec;
let mut refused = Vec::new();

Expand All @@ -122,21 +143,7 @@ fn select(catalog: &AudioConfig, kind: &Kind, candidates: Vec<&Candidate>) -> Re
return Err(Error::Unsupported(reasons.join(", ")));
}

match kind {
Kind::Named(name) => {
let available: Vec<&str> = PLATFORM
.iter()
.chain(SOFTWARE)
.filter(|c| (c.supports)(codec))
.map(|c| c.name)
.collect();
Err(Error::Unsupported(format!(
"no audio decoder named {name:?} for {codec} (this build has: {})",
available.join(", ")
)))
}
_ => Err(Error::Unsupported(format!("unsupported audio codec: {codec}"))),
}
Err(Error::Unsupported(format!("unsupported audio codec: {codec}")))
}

#[cfg(test)]
Expand Down Expand Up @@ -204,7 +211,7 @@ mod tests {
}

fn pick(kind: Kind, platform: &[Candidate], software: &[Candidate]) -> Result<String, Error> {
let backend = select(&opus(), &kind, candidates(&kind, platform, software))?;
let backend = select(&opus(), candidates(&kind, platform, software))?;
Ok(backend.name().to_owned())
}

Expand All @@ -226,22 +233,11 @@ mod tests {
assert_eq!(name, "software");
}

/// A codec name is not a backend selector: it tries the same tiers as `Auto`.
#[test]
fn named_forces_one() {
let name = pick(
Kind::Named("software".into()),
&[PLATFORM_STUB],
&[PCM_ONLY, SOFTWARE_STUB],
)
.unwrap();
assert_eq!(name, "software");
}

/// A named backend that refuses the track is the answer: nothing else is tried.
#[test]
fn named_refusal_does_not_fall_back() {
let err = pick(Kind::Named("refusing".into()), &[REFUSING], &[SOFTWARE_STUB]).unwrap_err();
assert!(err.to_string().contains("not this track"), "{err}");
fn named_codec_picks_like_auto() {
let name = pick(Kind::Named("opus".into()), &[PLATFORM_STUB], &[SOFTWARE_STUB]).unwrap();
assert_eq!(name, "platform");
}

#[test]
Expand All @@ -259,45 +255,33 @@ mod tests {
);
}

/// An unknown name says what this build has for the codec instead.
#[test]
fn unknown_name_lists_the_alternatives() {
let err = open(
&opus(),
&Config {
kind: Kind::Named("opus".into()),
},
)
.err()
.expect("no backend is named after its codec");
let message = err.to_string();
assert!(
message.contains("\"opus\"") && message.contains(libopus::NAME),
"{message}"
);
fn named(name: &str) -> Config {
Config {
kind: Kind::Named(name.into()),
}
}

/// Asking for a real backend that does not decode the codec is refused, not
/// quietly swapped for one that does.
/// The codec names published moq-audio accepts still open their codec.
#[test]
fn named_backend_for_another_codec_is_refused() {
let config = Config {
kind: Kind::Named(pcm::NAME.into()),
};
assert!(matches!(open(&opus(), &config), Err(Error::Unsupported(_))));
fn codec_names_open_their_codec() {
let pcm = AudioConfig::new(AudioCodec::Pcm, 48_000, 2);
assert_eq!(open(&pcm, &named("pcm")).unwrap().name(), pcm::NAME);
assert_eq!(open(&opus(), &named("opus")).unwrap().name(), libopus::NAME);
}

/// A name for another codec is refused, not quietly swapped for one that decodes.
#[test]
fn software_backends_open_by_name() {
let pcm = AudioConfig::new(AudioCodec::Pcm, 48_000, 2);
let config = Config {
kind: Kind::Named(pcm::NAME.into()),
};
assert_eq!(open(&pcm, &config).unwrap().name(), pcm::NAME);
fn another_codecs_name_is_refused() {
assert!(matches!(open(&opus(), &named("pcm")), Err(Error::Unsupported(_))));
}

let config = Config {
kind: Kind::Named(libopus::NAME.into()),
};
assert_eq!(open(&opus(), &config).unwrap().name(), libopus::NAME);
/// Backend names are internal: asking for one is refused like any unknown name.
#[test]
fn backend_names_are_refused() {
let message = open(&opus(), &named(libopus::NAME))
.err()
.expect("libopus is a backend, not a codec")
.to_string();
assert!(message.contains("\"libopus\"") && message.contains("opus"), "{message}");
}
}
23 changes: 21 additions & 2 deletions rs/moq-audio/src/decode/decoder.rs
Original file line number Diff line number Diff line change
Expand Up @@ -17,8 +17,9 @@ pub enum Kind {
Auto,
/// Require a software backend.
Software,
/// Require a backend by its stable lowercase name: `"libopus"`, `"pcm"`, or
/// `"symphonia"`.
/// Require the track to be this codec, by its lowercase name: `"opus"`,
/// `"pcm"`, or `"aac"`. Any other codec is refused. The library still picks
/// the backend, platform first.
Named(String),
}

Expand Down Expand Up @@ -371,6 +372,24 @@ pub(crate) mod tests {
));
}

/// Published moq-audio accepts the codec's name, not a backend's.
#[cfg(feature = "aac")]
#[test]
fn named_aac_decodes_aac() {
let config = Config {
kind: Kind::Named("aac".into()),
};
assert!(Decoder::new(&aac_catalog(), &config).is_ok());

let config = Config {
kind: Kind::Named("opus".into()),
};
assert!(matches!(
Decoder::new(&aac_catalog(), &config),
Err(Error::Unsupported(_))
));
}

#[test]
fn refuses_unavailable_backend() {
let catalog = hang::catalog::AudioConfig::new(hang::catalog::AudioCodec::Pcm, 48_000, 2);
Expand Down
Loading
Loading