feat(spf): add an audio codec preference to the publish encoder ladder

Merged
MM
3mo ago
+94-14

Closes #36

Summary

probeEncoderSupport hardcoded Opus as the only audio codec, so every browser publish was Opus unconditionally — and RTMP/FLV re-publish and LL-HLS egress (both structurally unable to carry Opus) went video-only. This adds the audio.codec seam the issue asks for, as a preference walk with an Opus fallback.

Changes

  • MoqPublishEngineConfig.audio (and ProbeEncoderSupportConfig.audio) gains a codec field — a new exported AudioEncodeTuning type — with the same semantics as the existing camera/screen codec seam: the preferred WebCodecs codec string prepends to the Opus default ladder rather than replacing it, so audio: { codec: 'mp4a.40.2' } publishes AAC where the browser can encode it and degrades to Opus where it can't (e.g. headless Chromium).
  • The audio ladder is now a codec-major cross product over the existing sample-rate ladder — the preferred codec exhausts its sample rates before Opus gets a turn, since the preference exists for egress compatibility, which a rate tweak can't buy back.
  • No catalog or packaging changes needed, as the issue predicted: deriveCatalog already gates mp4a.* on its AudioSpecificConfig init data and only special-cases Opus's 48 kHz sample-rate rewrite, and the audio encoder actor already rides decoderConfig.description on every frame in the LOC Audio Config property.

Testing

  • New tests: the codec-major preference walk (mocked AudioEncoder.isConfigSupported — headless Chromium ships no AAC encoder), the Opus fallback when the preference is unsupported, and ladder dedup when the preference is the default.
  • pnpm -F @videojs/spf test src/publish — 247 passed; spf build + full pnpm typecheck clean.
  • Codex CLI review of the branch diff: no findings.

🤖 Generated with Claude Code


Summary by cubic

Adds an audio codec preference to the publish encoder ladder so browsers that can encode AAC publish AAC; others fall back to Opus. Previously, audio was always Opus, causing RTMP/FLV re-publish and LL‑HLS egress to drop audio.

Review and rollout

  • Adds and exports AudioEncodeTuning; MoqPublishEngineConfig.audio and ProbeEncoderSupportConfig.audio now accept { bitrate?, codec? }.
  • Builds the audio ladder codec-major: the preferred audio.codec is tried across sample rates before Opus; unsupported preferences degrade to Opus.
  • No catalog or packaging changes; existing behavior is unchanged when no audio.codec is set.
  • Tests cover the preference walk, Opus fallback, and ladder dedup when the preference is Opus.
  • Migration: set audio: { codec: 'mp4a.40.2' } to publish AAC where supported; no changes required otherwise.