From 2d7469a9a57573cdaef09024f15f9a72284e839a Mon Sep 17 00:00:00 2001 From: huangyouyi Date: Thu, 19 Nov 2026 12:23:41 -0700 Subject: [PATCH] feat: support PCMA and PCMU audio publishing --- .changeset/select-audio-codec.md | 5 + src/room/RTCEngine.ts | 27 ++- src/room/participant/LocalParticipant.ts | 170 ++++++++++--- src/room/participant/audioCodec.test.ts | 293 +++++++++++++++++++++++ src/room/track/LocalTrackPublication.ts | 5 +- src/room/track/options.ts | 27 ++- 6 files changed, 486 insertions(+), 41 deletions(-) create mode 100644 .changeset/select-audio-codec.md create mode 100644 src/room/participant/audioCodec.test.ts diff --git a/.changeset/select-audio-codec.md b/.changeset/select-audio-codec.md new file mode 100644 index 0000000000..80684f4a78 --- /dev/null +++ b/.changeset/select-audio-codec.md @@ -0,0 +1,5 @@ +--- +'livekit-client': minor +--- + +Support publishing PCMA and PCMU via `audioCodec`. diff --git a/src/room/RTCEngine.ts b/src/room/RTCEngine.ts index 04766c1ca2..68e8ea11a7 100644 --- a/src/room/RTCEngine.ts +++ b/src/room/RTCEngine.ts @@ -82,6 +82,7 @@ import { ConnectionErrorReason, NegotiationError, PublishDataError, + PublishTrackError, SignalReconnectError, TrackInvalidError, UnexpectedConnectionState, @@ -1133,10 +1134,11 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit track: LocalTrack, opts: TrackPublishOptions, encodings?: RTCRtpEncodingParameters[], + codecPreference?: RTCRtpCapabilities['codecs'][number], ) { let sender: RTCRtpSender; if (supportsTransceiver()) { - sender = await this.createTransceiverRTCRtpSender(track, opts, encodings); + sender = await this.createTransceiverRTCRtpSender(track, opts, encodings, codecPreference); } else if (supportsAddTrack()) { this.log.warn('using add-track fallback'); sender = await this.createRTCRtpSender(track.mediaStreamTrack); @@ -1225,8 +1227,10 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit track: LocalTrack, opts: TrackPublishOptions, encodings?: RTCRtpEncodingParameters[], + codecPreference?: RTCRtpCapabilities['codecs'][number], ) { - if (!this.pcManager) { + const pcManager = this.pcManager; + if (!pcManager) { throw new UnexpectedConnectionState('publisher is closed'); } @@ -1245,11 +1249,28 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit transceiverInit.sendEncodings = encodings; } // addTransceiver for react-native is async. web is synchronous, but await won't effect it. - const transceiver = await this.pcManager.addPublisherTransceiver( + const transceiver = await pcManager.addPublisherTransceiver( track.mediaStreamTrack, transceiverInit, ); + if (codecPreference) { + try { + transceiver.setCodecPreferences([codecPreference]); + } catch (cause) { + try { + pcManager.removeTrack( + transceiver.sender, + isStopTransceiverSupportedByServer(this.serverProtocol), + ); + } catch (error) { + this.log.warn('failed to remove sender after audio codec setup failed', { error }); + } + const error = new PublishTrackError(`browser rejected ${codecPreference.mimeType}`, 415); + error.cause = cause; + throw error; + } + } return transceiver.sender; } diff --git a/src/room/participant/LocalParticipant.ts b/src/room/participant/LocalParticipant.ts index f723fe5d9b..1aab49aede 100644 --- a/src/room/participant/LocalParticipant.ts +++ b/src/room/participant/LocalParticipant.ts @@ -12,6 +12,7 @@ import { ParticipantInfo, RequestResponse, RequestResponse_Reason, + SimulcastCodec, SipDTMF, TrackInfo, TrackUnpublishedResponse, @@ -51,6 +52,7 @@ import { Track } from '../track/Track'; import { createLocalTracks, getVideoCapture } from '../track/create'; import type { AudioCaptureOptions, + AudioCodecOptions, CreateLocalTracksOptions, ScreenShareCaptureOptions, TrackPublishOptions, @@ -73,6 +75,7 @@ import { isLocalTrack, isLocalVideoTrack, isPermissionDeniedError, + isStopTransceiverSupportedByServer, isVideoTrack, isWeb, sleep, @@ -764,6 +767,23 @@ export class LocalParticipant extends Participant { ...this.roomOptions.publishDefaults, ...options, }; + let g711Codec: 'pcma' | 'pcmu' | undefined; + if (track.kind === Track.Kind.Audio && opts.audioCodec) { + const selection: AudioCodecOptions = + typeof opts.audioCodec === 'string' ? { codec: opts.audioCodec } : opts.audioCodec; + opts.red = selection.codec === 'red'; + if (selection.codec === 'pcma' || selection.codec === 'pcmu') { + g711Codec = selection.codec; + opts.dtx = false; + opts.forceStereo = false; + } else { + opts.dtx = selection.dtx ?? opts.dtx; + opts.forceStereo = selection.stereo ?? opts.forceStereo; + if (selection.maxBitrate !== undefined) { + opts.audioPreset = { ...opts.audioPreset, maxBitrate: selection.maxBitrate }; + } + } + } const isStereoInput = ('channelCount' in track.mediaStreamTrack.getSettings() && // @ts-ignore `channelCount` on getSettings() is currently only available for Safari, but is generally the best way to determine a stereo track https://developer.mozilla.org/en-US/docs/Web/API/MediaTrackSettings/channelCount @@ -815,11 +835,11 @@ export class LocalParticipant extends Participant { if (publicationTimedOut) { return; } - const publication = await this.publish(track, opts, isStereo); + const publication = await this.publish(track, opts, isStereo, g711Codec); resolve(publication); } else { try { - const publication = await this.publish(track, opts, isStereo); + const publication = await this.publish(track, opts, isStereo, g711Codec); resolve(publication); } catch (e) { reject(e); @@ -834,6 +854,9 @@ export class LocalParticipant extends Participant { const publication = await publishPromise; return publication; } catch (e) { + if (g711Codec) { + track.off(TrackEvent.Ended, this.handleTrackEnded); + } if (!hasRetriedAfterNegotiationError && e instanceof NegotiationError) { this.log.warn('negotiation due to track publish failed, retrying after reconnect', { error: e, @@ -872,7 +895,12 @@ export class LocalParticipant extends Participant { return false; } - private async publish(track: LocalTrack, opts: TrackPublishOptions, isStereo: boolean) { + private async publish( + track: LocalTrack, + opts: TrackPublishOptions, + isStereo: boolean, + g711Codec?: 'pcma' | 'pcmu', + ) { if (!this.hasPermissionsToPublish(track)) { throw new PublishTrackError('failed to publish track, insufficient permissions', 403); } @@ -885,17 +913,40 @@ export class LocalParticipant extends Participant { getLogContextFromTrack(track), ); } + const g711MimeType = g711Codec && `audio/${g711Codec}`; + let audioCodecPreference: RTCRtpCapabilities['codecs'][number] | undefined; + if (g711MimeType) { + if ( + !this.engine.latestJoinResponse?.enabledPublishCodecs.some( + (codec) => codec.mime.toLowerCase() === g711MimeType && !codec.fmtpLine, + ) + ) { + throw new PublishTrackError(`server does not advertise audio codec ${g711Codec}`, 415); + } + audioCodecPreference = globalThis.RTCRtpSender?.getCapabilities?.('audio')?.codecs.find( + (codec) => codec.mimeType.toLowerCase() === g711MimeType, + ); + if ( + !audioCodecPreference || + !globalThis.RTCPeerConnection?.prototype.addTransceiver || + !globalThis.RTCRtpTransceiver?.prototype.setCodecPreferences + ) { + throw new PublishTrackError(`browser cannot publish audio codec ${g711Codec}`, 415); + } + } if (opts.stopMicTrackOnMute && isAudioTrack(track)) { track.stopOnMute = true; } - // handle track actions - track.on(TrackEvent.Muted, this.onTrackMuted); - track.on(TrackEvent.Unmuted, this.onTrackUnmuted); track.on(TrackEvent.Ended, this.handleTrackEnded); - track.on(TrackEvent.UpstreamPaused, this.onTrackUpstreamPaused); - track.on(TrackEvent.UpstreamResumed, this.onTrackUpstreamResumed); - track.on(TrackEvent.AudioTrackFeatureUpdate, this.onTrackFeatureUpdate); + const addTrackListeners = () => { + track.on(TrackEvent.Muted, this.onTrackMuted); + track.on(TrackEvent.Unmuted, this.onTrackUnmuted); + track.on(TrackEvent.UpstreamPaused, this.onTrackUpstreamPaused); + track.on(TrackEvent.UpstreamResumed, this.onTrackUpstreamResumed); + track.on(TrackEvent.AudioTrackFeatureUpdate, this.onTrackFeatureUpdate); + }; + if (!g711Codec) addTrackListeners(); const audioFeatures: AudioTrackFeature[] = []; const disableDtx = !(opts.dtx ?? true); @@ -911,7 +962,11 @@ export class LocalParticipant extends Participant { if (settings.noiseSuppression) { audioFeatures.push(AudioTrackFeature.TF_NOISE_SUPPRESSION); } - if (settings.channelCount && settings.channelCount > 1) { + const stereoFeature = + track.kind === Track.Kind.Audio && opts.audioCodec + ? isStereo + : (settings.channelCount ?? 0) > 1; + if (stereoFeature) { audioFeatures.push(AudioTrackFeature.TF_STEREO); } if (disableDtx) { @@ -946,9 +1001,12 @@ export class LocalParticipant extends Participant { if (isLocalVideoTrack(track)) { encodings = await this.requireVideoPublisher().prepare(track, opts, req); } else if (track.kind === Track.Kind.Audio) { + if (g711Codec) { + req.simulcastCodecs = [new SimulcastCodec({ codec: g711Codec, cid: req.cid })]; + } encodings = [ { - maxBitrate: opts.audioPreset?.maxBitrate, + maxBitrate: g711Codec ? undefined : opts.audioPreset?.maxBitrate, priority: opts.audioPreset?.priority ?? 'high', networkPriority: opts.audioPreset?.priority ?? 'high', }, @@ -959,12 +1017,12 @@ export class LocalParticipant extends Participant { throw new UnexpectedConnectionState('cannot publish track when not connected'); } - const negotiate = async () => { + const createSender = async () => { if (!this.engine.pcManager) { throw new UnexpectedConnectionState('pcManager is not ready'); } - track.sender = await this.engine.createSender(track, opts, encodings); + track.sender = await this.engine.createSender(track, opts, encodings, audioCodecPreference); if (isLocalVideoTrack(track)) { track.publishOptions = opts; } @@ -975,7 +1033,7 @@ export class LocalParticipant extends Participant { } if (encodings) { - if (isFireFox() && track.kind === Track.Kind.Audio) { + if (!g711Codec && isFireFox() && track.kind === Track.Kind.Audio) { /* Refer to RFC https://datatracker.ietf.org/doc/html/rfc7587#section-6.1, livekit-server uses maxaveragebitrate=510000 in the answer sdp to permit client to publish high quality audio track. But firefox always uses this value as the actual @@ -999,15 +1057,15 @@ export class LocalParticipant extends Participant { } } } - + }; + const negotiate = async () => { + await createSender(); await this.engine.negotiate(); }; - let ti: TrackInfo; - const addTrackPromise = new Promise(async (resolve, reject) => { + const addTrack = async () => { try { - ti = await this.engine.addTrack(req); - resolve(ti); + return await this.engine.addTrack(req); } catch (err) { if (track.sender && this.engine.pcManager?.publisher) { try { @@ -1030,14 +1088,46 @@ export class LocalParticipant extends Participant { ); }); } - reject(err); + throw err; } - }); - if (this.enabledPublishVideoCodecs.length > 0 && packetTrailerFeatures.length === 0) { - const rets = await Promise.all([addTrackPromise, negotiate()]); - ti = rets[0]; + }; + let ti: TrackInfo; + if (g711Codec) { + const engine = this.engine; + const transport = engine.pcManager; + // Restrict the media section before associating the codec and track ID on the SFU. + await createSender(); + try { + ti = await engine.addTrack(req); + if (ti.codecs[0]?.mimeType.toLowerCase() !== g711MimeType) { + throw new PublishTrackError(`server did not accept audio codec ${g711Codec}`, 415); + } + await engine.negotiate(); + } catch (err) { + const sender = track.sender; + track.sender = undefined; + if (sender && transport && transport === engine.pcManager) { + try { + if (!sender.track) { + this.deactivateTransceiver(sender, transport.publisher.getTransceivers()); + } + // Remove this sender without cancelling another AddTrack request for the same CID. + transport.removeTrack( + sender, + isStopTransceiverSupportedByServer(engine.serverProtocol), + ); + await engine.negotiate(); + } catch (error) { + this.log.warn('failed to remove an unpublished audio sender', { error }); + } + } + throw err; + } + addTrackListeners(); + } else if (this.enabledPublishVideoCodecs.length > 0 && packetTrailerFeatures.length === 0) { + [ti] = await Promise.all([addTrack(), negotiate()]); } else { - ti = await addTrackPromise; + ti = await addTrack(); if (isLocalVideoTrack(track)) { // the server may answer with another primary codec encodings = @@ -1056,6 +1146,10 @@ export class LocalParticipant extends Participant { // save options for when it needs to be republished again publication.options = opts; track.sid = ti.sid; + if (g711Codec) { + const muted = track.isMuted || track.isUpstreamPaused; + if (muted !== req.muted) this.onTrackMuted(track, muted); + } // keep publish options on the video track so that it can recompute encoding // parameters when the MediaStreamTrack is restarted (e.g. after switching cameras). @@ -1231,16 +1325,7 @@ export class LocalParticipant extends Participant { trackSender ) { try { - for (const transceiver of this.engine.pcManager.publisher.getTransceivers()) { - // if sender is not currently sending (after replaceTrack(null)) - // removeTrack would have no effect. - // to ensure we end up successfully removing the track, manually set - // the transceiver to inactive - if (transceiver.sender === trackSender) { - transceiver.direction = 'inactive'; - negotiationNeeded = true; - } - } + this.deactivateTransceiver(trackSender, this.engine.pcManager.publisher.getTransceivers()); try { negotiationNeeded = this.engine.removeTrack(trackSender); } catch (e) { @@ -1289,6 +1374,14 @@ export class LocalParticipant extends Participant { return publication; } + private deactivateTransceiver(sender: RTCRtpSender, transceivers: RTCRtpTransceiver[]) { + const transceiver = transceivers.find((candidate) => candidate.sender === sender); + if (transceiver) { + // removeTrack has no effect once replaceTrack(null) detaches the track. + transceiver.direction = 'inactive'; + } + } + async unpublishTracks( tracks: LocalTrack[] | MediaStreamTrack[], ): Promise { @@ -1561,7 +1654,12 @@ export class LocalParticipant extends Participant { track.source === Track.Source.ScreenShareAudio ) { this.log.debug('unpublishing local track due to TrackEnded', getLogContextFromTrack(track)); - this.unpublishTrack(track); + await this.unpublishTrack(track).catch((error) => { + this.log.warn('failed to unpublish a local track that ended', { + ...getLogContextFromTrack(track), + error, + }); + }); } else if (track.isUserProvided) { await track.mute(); } else if (isLocalAudioTrack(track) || isLocalVideoTrack(track)) { diff --git a/src/room/participant/audioCodec.test.ts b/src/room/participant/audioCodec.test.ts new file mode 100644 index 0000000000..8289f9acda --- /dev/null +++ b/src/room/participant/audioCodec.test.ts @@ -0,0 +1,293 @@ +import { + AudioTrackFeature, + JoinResponse, + ParticipantInfo, + ParticipantPermission, + TrackInfo, +} from '@livekit/protocol'; +import { afterEach, describe, expect, it, vi } from 'vitest'; +import { SignalConnectionState } from '../../api/SignalClient'; +import { CoreRoom } from '../CoreRoom'; +import type { PCTransportManager } from '../PCTransportManager'; +import { TrackEvent } from '../events'; +import LocalAudioTrack from '../track/LocalAudioTrack'; +import { Track } from '../track/Track'; +import type { TrackPublishOptions } from '../track/options'; +import { Future } from '../utils'; + +class Microphone extends EventTarget { + readonly kind = 'audio'; + + readonly id = 'mic'; + + enabled = true; + + stop = vi.fn(); + + getSettings = () => ({ channelCount: 2 }); + + getConstraints = () => ({}); +} + +function setup(publishDefaults?: TrackPublishOptions) { + const codecs = [{ mimeType: 'audio/PCMA' }, { mimeType: 'audio/PCMU' }]; + const setCodecPreferences = vi.fn(); + vi.stubGlobal('MediaStreamTrack', Microphone); + vi.stubGlobal('RTCPeerConnection', { prototype: { addTransceiver: vi.fn() } }); + vi.stubGlobal('RTCRtpTransceiver', { prototype: { setCodecPreferences } }); + vi.stubGlobal('RTCRtpSender', { getCapabilities: () => ({ codecs }) }); + + const participant = new CoreRoom({ publishDefaults }).localParticipant; + const engine = participant.engine; + engine.latestJoinResponse = new JoinResponse({ + enabledPublishCodecs: codecs.map((codec) => ({ mime: codec.mimeType })), + }); + participant.updateInfo( + new ParticipantInfo({ permission: new ParticipantPermission({ canPublish: true }) }), + ); + vi.spyOn(engine, 'isClosed', 'get').mockReturnValue(false); + vi.spyOn(engine.client, 'currentState', 'get').mockReturnValue(SignalConnectionState.CONNECTED); + + const mic = new Microphone(); + const track = mic as unknown as MediaStreamTrack; + const sender = { + track: track as MediaStreamTrack | null, + async replaceTrack(next: MediaStreamTrack | null) { + this.track = next; + }, + }; + const transceiver = { sender, setCodecPreferences, direction: 'sendonly' }; + const addPublisherTransceiver = vi.fn( + (_track: MediaStreamTrack, _init: RTCRtpTransceiverInit) => transceiver, + ); + const removeTrack = vi.fn(); + engine.pcManager = { + addPublisherTransceiver, + removeTrack, + publisher: { getTransceivers: () => [transceiver] }, + } as unknown as PCTransportManager; + const addTrack = vi.spyOn(engine, 'addTrack').mockImplementation( + async (req) => + new TrackInfo({ + sid: 'TR_mic', + stereo: req.stereo, + codecs: req.simulcastCodecs.map((c) => ({ mimeType: `audio/${c.codec}`, cid: c.cid })), + }), + ); + const negotiate = vi.spyOn(engine, 'negotiate').mockResolvedValue(); + return { + participant, + engine, + mic, + track, + sender, + transceiver, + setCodecPreferences, + addPublisherTransceiver, + addTrack, + removeTrack, + negotiate, + }; +} + +afterEach(() => { + vi.unstubAllGlobals(); + vi.restoreAllMocks(); +}); + +describe('audio codec publication', () => { + it.each([ + { codec: 'pcma', options: undefined }, + { codec: 'pcmu', options: { audioCodec: { codec: 'pcmu' } } }, + ] as const)( + 'publishes $codec with a codec-specific request and transceiver', + async ({ codec, options }) => { + const { + participant, + track, + setCodecPreferences, + addPublisherTransceiver, + addTrack, + negotiate, + } = setup({ audioCodec: 'pcma' }); + + const publication = await participant.publishTrack(track, options); + + expect(setCodecPreferences).toHaveBeenCalledExactlyOnceWith([ + { mimeType: `audio/${codec.toUpperCase()}` }, + ]); + expect(addTrack).toHaveBeenCalledExactlyOnceWith( + expect.objectContaining({ + disableDtx: true, + disableRed: true, + stereo: false, + audioFeatures: [AudioTrackFeature.TF_NO_DTX], + simulcastCodecs: [expect.objectContaining({ codec, cid: track.id })], + }), + ); + expect(setCodecPreferences.mock.invocationCallOrder[0]).toBeLessThan( + addTrack.mock.invocationCallOrder[0], + ); + expect(addTrack.mock.invocationCallOrder[0]).toBeLessThan( + negotiate.mock.invocationCallOrder[0], + ); + expect( + addPublisherTransceiver.mock.calls[0][1].sendEncodings?.[0].maxBitrate, + ).toBeUndefined(); + expect(publication.options?.audioCodec).toEqual(options?.audioCodec ?? 'pcma'); + expect(publication.getTrackFeatures()).toEqual([AudioTrackFeature.TF_NO_DTX]); + publication.track?.stop(); + }, + ); + + it.each(['opus', 'red'] as const)('uses the existing %s settings', async (codec) => { + const { participant, track, setCodecPreferences, addPublisherTransceiver, addTrack } = setup({ + audioCodec: 'pcmu', + }); + + const publication = await participant.publishTrack(track, { + audioCodec: { codec, dtx: false, stereo: true, maxBitrate: 96000 }, + }); + + expect(addTrack).toHaveBeenCalledExactlyOnceWith( + expect.objectContaining({ + disableDtx: true, + disableRed: codec === 'opus', + stereo: true, + simulcastCodecs: [], + }), + ); + expect(addPublisherTransceiver.mock.calls[0][1].sendEncodings?.[0].maxBitrate).toBe(96000); + expect(setCodecPreferences).not.toHaveBeenCalled(); + publication.track?.stop(); + }); + + it('uses normal negotiation when audioCodec is omitted', async () => { + const { participant, track, setCodecPreferences, addTrack } = setup(); + vi.stubGlobal('RTCRtpSender', undefined); + + const publication = await participant.publishTrack(track); + + expect(addTrack).toHaveBeenCalledExactlyOnceWith( + expect.objectContaining({ disableDtx: false, disableRed: false, simulcastCodecs: [] }), + ); + expect(setCodecPreferences).not.toHaveBeenCalled(); + publication.track?.stop(); + }); + + it.each(['browser', 'server'])( + 'rejects G.711 unavailable on the %s before creating a sender', + async (source) => { + const { participant, engine, track, addTrack, addPublisherTransceiver } = setup(); + if (source === 'browser') { + vi.stubGlobal('RTCRtpSender', undefined); + } else { + engine.latestJoinResponse = new JoinResponse(); + } + + await expect(participant.publishTrack(track, { audioCodec: 'pcma' })).rejects.toMatchObject({ + name: 'PublishTrackError', + status: 415, + message: expect.stringContaining(source), + }); + expect(addTrack).not.toHaveBeenCalled(); + expect(addPublisherTransceiver).not.toHaveBeenCalled(); + }, + ); + + it('unpublishes G.711 screen audio that ends before the publish confirmation', async () => { + const { participant, mic, track, addTrack } = setup(); + const requestSent = new Future(); + const confirmation = new Future(); + addTrack.mockImplementationOnce(() => { + requestSent.resolve(); + return confirmation.promise; + }); + + const publishing = participant.publishTrack(track, { + audioCodec: 'pcma', + source: Track.Source.ScreenShareAudio, + }); + await requestSent.promise; + mic.dispatchEvent(new Event('ended')); + confirmation.resolve(new TrackInfo({ sid: 'TR_mic', codecs: [{ mimeType: 'audio/pcma' }] })); + + const publication = await publishing; + publication.track?.stop(); + expect(participant.trackPublications.size).toBe(0); + }); + + it('detaches the Ended listener when the engine closes before creating a sender', async () => { + const { participant, engine, track, addPublisherTransceiver } = setup(); + const localTrack = new LocalAudioTrack(track); + vi.spyOn(engine, 'isClosed', 'get').mockReturnValue(true); + + await expect(participant.publishTrack(localTrack, { audioCodec: 'pcma' })).rejects.toThrow( + 'cannot publish track when not connected', + ); + expect(localTrack.listenerCount(TrackEvent.Ended)).toBe(0); + expect(addPublisherTransceiver).not.toHaveBeenCalled(); + }); + + it('removes the unpublished sender if the server chooses another codec', async () => { + const { participant, mic, track, sender, addTrack, removeTrack, negotiate } = setup(); + const localTrack = new LocalAudioTrack(track); + addTrack.mockImplementationOnce(async () => { + mic.dispatchEvent(new Event('ended')); + return new TrackInfo({ codecs: [{ mimeType: 'audio/opus' }] }); + }); + + await expect( + participant.publishTrack(localTrack, { + audioCodec: 'pcma', + source: Track.Source.ScreenShareAudio, + }), + ).rejects.toMatchObject({ + name: 'PublishTrackError', + status: 415, + message: 'server did not accept audio codec pcma', + }); + expect(removeTrack).toHaveBeenCalledExactlyOnceWith(sender, false); + expect(negotiate).toHaveBeenCalledOnce(); + expect(removeTrack.mock.invocationCallOrder[0]).toBeLessThan( + negotiate.mock.invocationCallOrder[0], + ); + expect(participant.trackPublications.size).toBe(0); + expect(localTrack.listenerCount(TrackEvent.Ended)).toBe(0); + expect(mic.stop).not.toHaveBeenCalled(); + }); + + it('deactivates a paused G.711 sender if publication fails', async () => { + const { participant, track, addTrack, sender, transceiver, removeTrack } = setup(); + vi.spyOn(navigator, 'userAgent', 'get').mockReturnValue('Chrome/156.0.0.0'); + const localTrack = new LocalAudioTrack(track); + addTrack.mockImplementationOnce(async () => { + await localTrack.pauseUpstream(); + return new TrackInfo({ codecs: [{ mimeType: 'audio/opus' }] }); + }); + + await expect( + participant.publishTrack(localTrack, { audioCodec: 'pcma' }), + ).rejects.toMatchObject({ + status: 415, + }); + expect(sender.track).toBeNull(); + expect(transceiver.direction).toBe('inactive'); + expect(removeTrack).toHaveBeenCalledExactlyOnceWith(sender, false); + }); + + it('signals a G.711 track muted while publication is pending', async () => { + const { participant, engine, track, addTrack } = setup(); + const localTrack = new LocalAudioTrack(track); + const updateMuteStatus = vi.spyOn(engine, 'updateMuteStatus').mockImplementation(() => {}); + addTrack.mockImplementationOnce(async () => { + await localTrack.mute(); + return new TrackInfo({ sid: 'TR_mic', codecs: [{ mimeType: 'audio/pcma' }] }); + }); + + await participant.publishTrack(localTrack, { audioCodec: 'pcma' }); + + expect(updateMuteStatus).toHaveBeenCalledExactlyOnceWith('TR_mic', true); + localTrack.stop(); + }); +}); diff --git a/src/room/track/LocalTrackPublication.ts b/src/room/track/LocalTrackPublication.ts index 3b9e3a8f5a..a8882d89ed 100644 --- a/src/room/track/LocalTrackPublication.ts +++ b/src/room/track/LocalTrackPublication.ts @@ -102,7 +102,10 @@ export default class LocalTrackPublication extends TrackPublication { if (settings.noiseSuppression) { features.add(AudioTrackFeature.TF_NOISE_SUPPRESSION); } - if (settings.channelCount && settings.channelCount > 1) { + const stereo = this.options?.audioCodec + ? this.trackInfo?.stereo + : (settings.channelCount ?? 0) > 1; + if (stereo) { features.add(AudioTrackFeature.TF_STEREO); } if (!this.options?.dtx) { diff --git a/src/room/track/options.ts b/src/room/track/options.ts index cb608d2027..3c78081db5 100644 --- a/src/room/track/options.ts +++ b/src/room/track/options.ts @@ -49,6 +49,15 @@ export interface TrackPublishDefaults { */ videoCodec?: VideoCodec; + /** + * Audio codec selection. A per-track selection overrides `RoomOptions.publishDefaults`. + * `'opus'` disables RED and `'red'` enables Opus redundancy when supported. + * Opus and RED accept `dtx`, `stereo` and `maxBitrate`. PCMA and PCMU use mono G.711 + * and require browser codec preferences and support for the codec on the server. + * Omit this option at both levels to keep normal audio negotiation. + */ + audioCodec?: AudioCodec | AudioCodecOptions; + /** * which audio preset should be used for publishing (audio) tracks * defaults to [[AudioPresets.music]] @@ -57,16 +66,19 @@ export interface TrackPublishDefaults { /** * dtx (Discontinuous Transmission of audio), enabled by default for mono tracks. + * @deprecated Use the `dtx` option of an Opus or RED `audioCodec`. */ dtx?: boolean; /** * red (Redundant Audio Data), enabled by default for mono tracks. + * @deprecated Use `audioCodec: 'red'` or `audioCodec: 'opus'`. */ red?: boolean; /** * publish track in stereo mode (or set to false to disable). defaults determined by capture channel count. + * @deprecated Use the `stereo` option of an Opus or RED `audioCodec`. */ forceStereo?: boolean; @@ -421,10 +433,23 @@ export interface AudioPreset { } // `red` is not technically a codec, but treated as one in signalling protocol -export const audioCodecs = ['opus', 'red'] as const; +export const audioCodecs = ['opus', 'red', 'pcma', 'pcmu'] as const; export type AudioCodec = (typeof audioCodecs)[number]; +interface OpusParams { + dtx?: boolean; + stereo?: boolean; + /** Maximum encoder bitrate in bits per second. */ + maxBitrate?: number; +} + +export type AudioCodecOptions = + | ({ codec: 'opus' } & OpusParams) + | ({ codec: 'red' } & OpusParams) + | { codec: 'pcma' } + | { codec: 'pcmu' }; + const backupVideoCodecs = ['vp8', 'h264'] as const; export const videoCodecs = ['vp8', 'h264', 'vp9', 'av1', 'h265'] as const;