Skip to content

feat: let the audio codecs of a factory be limited and ordered - #340

Open
devopvoid wants to merge 1 commit into
mainfrom
feat/audio-codec-factories
Open

devopvoid wants to merge 1 commit into
mainfrom
feat/audio-codec-factories

Conversation

@devopvoid

Copy link
Copy Markdown
Owner

The audio counterpart of the video codec factories (#303), as far as the Android SDK goes: Android's setAudioEncoderFactoryFactory/setAudioDecoderFactoryFactory only take native factories, in practice the built-in ones. This lets a PeerConnectionFactory limit and order WebRTC's built-in audio codecs; Java audio codecs are left out.

API

New package dev.onvoid.webrtc.media.audio.codec:

  • BuiltinAudioEncoderFactory(String... codecNames) and BuiltinAudioDecoderFactory(String... codecNames): without names, all of WebRTC's built-in codecs (Opus, G722, PCMU, PCMA), as before. With names, only those codecs, in that order of preference. Names are compared ignoring case and de-duplicated; an unknown name throws an IllegalArgumentException that lists the built-in codecs.
  • getSupportedCodecs() returns the resulting AudioCodecInfo list: name, clock rate, channels and format parameters.
  • AudioEncoderFactory / AudioDecoderFactory: abstract classes with package-private constructors, so the built-in factories are their only implementations for now, while Java audio codecs could be added later without changing the builder.

PeerConnectionFactory.Builder gains setAudioEncoderFactory() and setAudioDecoderFactory():

PeerConnectionFactory factory = PeerConnectionFactory.builder()
        .setAudioEncoderFactory(new BuiltinAudioEncoderFactory("opus"))
        .setAudioDecoderFactory(new BuiltinAudioDecoderFactory("opus", "PCMU"))
        .build();

WebRTC still adds the auxiliary codecs by itself, depending on the selected ones: telephone-event at the 8000 and 48000 Hz clock rates (so DTMF keeps working), CN next to 8000 Hz codecs, and red next to Opus. The javadoc and guide say so.

Native

  • FilteredAudioEncoderFactory / FilteredAudioDecoderFactory wrap the built-in factories: they list the selected codecs ordered by name (AudioCodecSelection, the same algorithm as the Java side), and refuse to query or create the others.
  • AudioCodecFactories builds the native factory from the Java object, reading its canonical codec names; no factory or no names means the built-in factory itself, unchanged.
  • PeerConnectionFactory.initialize takes the two factories; the existing constructors pass null.
  • New sources live in media/audio/codec/, with its own glob in CMakeLists.txt.

Docs

A new "Audio Codecs" guide (docs/guide/advanced/audio-codecs.md), linked from the sidebar and the guide index.

Tests

AudioCodecFactoryTests: the built-in list and Opus's clock rate and channels, ordering and case-insensitive de-duplication, unknown names, which codecs a factory's sender and receiver capabilities list (including telephone-event), the codec order of an actual offer, and a call that negotiates the only selected codec.

The full webrtc suite passes on Windows (267 run, 0 failures, 2 skipped); before the rebase onto the current main, also under -Pjni-check with no JNI errors.

PeerConnectionFactory.Builder gains setAudioEncoderFactory and
setAudioDecoderFactory, which take the new BuiltinAudioEncoderFactory
and BuiltinAudioDecoderFactory of dev.onvoid.webrtc.media.audio.codec.
Without codec names they are WebRTC's built-in factories, as before.
With names they offer only those codecs, in that order, for example
only Opus; an unknown name throws and lists the built-in codecs.
getSupportedCodecs() returns the resulting AudioCodecInfo list.

Natively, FilteredAudioEncoderFactory and FilteredAudioDecoderFactory
wrap the built-in factories, selecting and ordering by name the same way
the Java side does, and refusing to create codecs that were not
selected. WebRTC still adds telephone-event, CN and red by itself.

The factory classes are abstract with package-private constructors, so
that Java audio codecs can be added later without changing the builder.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant