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
46 changes: 33 additions & 13 deletions packages/spf/src/publish/behaviors/dom/probe-encoder-support.ts
Original file line number Diff line number Diff line change
Expand Up @@ -14,11 +14,14 @@
* bitstream format so the avcC extradata exists to publish out-of-band —
* see `videoCandidates`) with a VP8 fallback, at the track
* resolution/framerate; Opus at the track sample rate with a 48 kHz
* fallback. A `config.{camera,screen}.codec` prepends itself to the
* ladder rather than replacing it. The screen ladder defaults to a lower
* framerate than the camera's (static degrade-screen-first tuning, per
* the multi-source design record's "Encoder budget" decision — no dynamic
* policy in v1).
* fallback. A `config.{camera,screen,audio}.codec` prepends itself to the
* ladder rather than replacing it — for audio the preferred codec probes
* at every ladder sample rate before Opus does (codec preference
* outranks rate preference), so `audio: { codec: 'mp4a.40.2' }` publishes
* AAC where the browser can encode it and falls back to Opus where it
* can't. The screen ladder defaults to a lower framerate than the
* camera's (static degrade-screen-first tuning, per the multi-source
* design record's "Encoder budget" decision — no dynamic policy in v1).
*
* Each probe is a single-positive-state reactor mirroring the acquire
* behaviors: the probe runs in the positive state's `effects:` so a
Expand Down Expand Up @@ -78,11 +81,22 @@ export interface VideoEncodeTuning {
codec?: string;
}

export interface AudioEncodeTuning {
bitrate?: number;
/**
* Preferred WebCodecs audio codec string (e.g. `'mp4a.40.2'` for
* AAC-LC). Prepended to the Opus default rather than replacing it, so
* an unsupported preference degrades to Opus instead of failing the
* kind.
*/
codec?: string;
}

/** Per-kind encode tuning (mirrors `MoqPublishEngineConfig`). */
export interface ProbeEncoderSupportConfig {
camera?: VideoEncodeTuning;
screen?: VideoEncodeTuning;
audio?: { bitrate?: number };
audio?: AudioEncodeTuning;
selectEncoderConfig?: SelectEncoderConfig;
}

Expand Down Expand Up @@ -147,14 +161,20 @@ function screenCandidates(track: CaptureTrackFacts, tuning: VideoEncodeTuning |
});
}

function audioCandidates(track: CaptureTrackFacts, audio: ProbeEncoderSupportConfig['audio']): AudioEncoderConfig[] {
function audioCandidates(track: CaptureTrackFacts, audio: AudioEncodeTuning | undefined): AudioEncoderConfig[] {
const codecs = [...new Set([...(audio?.codec ? [audio.codec] : []), DEFAULT_AUDIO_CODEC])];
const sampleRates = [...new Set([track.sampleRate ?? OPUS_SAMPLE_RATE, OPUS_SAMPLE_RATE])];
return sampleRates.map((sampleRate) => ({
codec: DEFAULT_AUDIO_CODEC,
sampleRate,
numberOfChannels: track.channelCount ?? 1,
bitrate: audio?.bitrate ?? DEFAULT_AUDIO_BITRATE,
}));
// Codec-major: the preferred codec exhausts its sample rates before the
// default gets a turn — the preference exists for egress compatibility,
// which a rate tweak can't buy back.
return codecs.flatMap((codec) =>
sampleRates.map((sampleRate) => ({
codec,
sampleRate,
numberOfChannels: track.channelCount ?? 1,
bitrate: audio?.bitrate ?? DEFAULT_AUDIO_BITRATE,
}))
);
}

/**
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,18 @@ function mockVideoEncoderSupport(supported: () => boolean): void {
}));
}

/**
* Force the audio ladder's verdict per candidate. Needed for any AAC arm:
* headless Chromium ships no AAC encoder, so the preference walk would
* always fall back to Opus under the real `isConfigSupported`.
*/
function mockAudioEncoderSupport(supported: (config: AudioEncoderConfig) => boolean): void {
vi.spyOn(AudioEncoder, 'isConfigSupported').mockImplementation(async (config) => ({
supported: supported(config),
config,
}));
}

const CAMERA_TRACK = { width: 320, height: 240, frameRate: 30 };
const SCREEN_TRACK = { width: 1920, height: 1080, frameRate: 30 };
const MIC_TRACK = { sampleRate: 48_000, channelCount: 1 };
Expand Down Expand Up @@ -129,6 +141,50 @@ describe('probeEncoderSupport', () => {
expect(state.activeEncodings.get()!.screen).toMatchObject({ framerate: 15, bitrate: 1_500_000 });
});

it('walks the audio codec preference before the Opus default (codec-major ladder)', async () => {
mockAudioEncoderSupport(() => true);
const { state } = setupProbe({ audio: { codec: 'mp4a.40.2' } });

state.micTracks.set({ sampleRate: 44_100, channelCount: 2 });

await vi.waitFor(() => {
expect(state.encoderSupport.get()?.audio).toBeDefined();
});
// The preferred codec exhausts its sample rates before Opus gets a turn.
expect(state.encoderSupport.get()!.audio!.map(({ codec, sampleRate }) => ({ codec, sampleRate }))).toEqual([
{ codec: 'mp4a.40.2', sampleRate: 44_100 },
{ codec: 'mp4a.40.2', sampleRate: 48_000 },
{ codec: 'opus', sampleRate: 44_100 },
{ codec: 'opus', sampleRate: 48_000 },
]);
expect(state.activeEncodings.get()!.audio).toMatchObject({ codec: 'mp4a.40.2', sampleRate: 44_100 });
});

it('falls back to Opus when the preferred audio codec is unsupported', async () => {
mockAudioEncoderSupport((config) => config.codec === 'opus');
const { state } = setupProbe({ audio: { codec: 'mp4a.40.2' } });

state.micTracks.set(MIC_TRACK);

await vi.waitFor(() => {
expect(state.activeEncodings.get()?.audio).toBeDefined();
});
expect(state.activeEncodings.get()!.audio).toMatchObject({ codec: 'opus', sampleRate: 48_000 });
expect(state.publishError.get()).toBeUndefined();
});

it('does not duplicate the ladder when the preferred audio codec is the default', async () => {
mockAudioEncoderSupport(() => true);
const { state } = setupProbe({ audio: { codec: 'opus' } });

state.micTracks.set(MIC_TRACK);

await vi.waitFor(() => {
expect(state.encoderSupport.get()?.audio).toBeDefined();
});
expect(state.encoderSupport.get()!.audio).toHaveLength(1);
});

it('resolves the active encodings through the selectEncoderConfig seam', async () => {
const chosen: ActiveEncodingsFacts = {};
const { state } = setupProbe({
Expand Down
5 changes: 4 additions & 1 deletion packages/spf/src/publish/engines/moq/engine.ts
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,7 @@ import type { CaptureDeviceFacts } from '../../behaviors/dom/enumerate-capture-d
import { enumerateCaptureDevices } from '../../behaviors/dom/enumerate-capture-devices';
import type {
ActiveEncodingsFacts,
AudioEncodeTuning,
EncoderSupportFacts,
SelectEncoderConfig,
VideoEncodeTuning,
Expand All @@ -48,6 +49,7 @@ import type { ConnectPublishTransport, PublishEndpoint, PublishSessionActor } fr
export type {
ActiveEncodingsFacts,
AudioEncoderActor,
AudioEncodeTuning,
CaptureDeviceFacts,
CaptureSourceKind,
CaptureStatus,
Expand Down Expand Up @@ -174,7 +176,8 @@ export interface MoqPublishEngineConfig extends ShareSignalsConfig<MoqPublishEng
video?: VideoEncodeTuning;
/** Screen-share video tuning; defaults to a lower framerate/bitrate than `camera` (static degrade-screen-first). */
screen?: VideoEncodeTuning;
audio?: { bitrate?: number };
/** Audio tuning; `codec` prepends a preference to the Opus default ladder. */
audio?: AudioEncodeTuning;
/** Resolve probed encoder support into the active encodings. */
selectEncoderConfig?: SelectEncoderConfig;
/**
Expand Down
1 change: 1 addition & 0 deletions packages/spf/src/publish/engines/moq/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@ export { MoqPublishMediaElement, MoqPublishMediaMixin, moqPublishMediaDefaultPro
export type {
ActiveEncodingsFacts,
AudioEncoderActor,
AudioEncodeTuning,
CaptureDeviceFacts,
CaptureSourceKind,
CaptureStatus,
Expand Down
Loading