PlatformAudio

[stephen-derosa]

Overview

Implement PlatformAudio over ffi

Examples

https://github.com/livekit-examples/cpp-example-collection/compare/sderosa/BOT-377-platform-audio?expand=1

[Copilot]

Pull request overview

This PR introduces a new PlatformAudio API to expose WebRTC platform audio (ADM-backed capture/playout with voice processing) through the C++ SDK’s FFI layer, and wires it into LocalAudioTrack creation, with docs and unit coverage.

Changes:

• Add public PlatformAudio / PlatformAudioSource API and FFI-backed implementation.
• Add LocalAudioTrack::createLocalAudioTrack overload for PlatformAudioSource.
• Add README documentation and new unit tests for platform audio behavior.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
src/tests/unit/test_platform_audio.cpp	Adds unit tests covering default options, device info fields, and creating a track from a platform source.
src/platform_audio.cpp	Implements PlatformAudio and PlatformAudioSource over synchronous FFI requests.
src/local_audio_track.cpp	Adds shared helper for track creation and an overload accepting PlatformAudioSource.
README.md	Documents recommended usage of PlatformAudio vs AudioSource, with a C++ example.
include/livekit/platform_audio.h	Adds the public PlatformAudio API surface, options, device info, and error type with Doxygen docs.
include/livekit/local_audio_track.h	Adds forward declaration + new overload and expands/updates Doxygen docs.
include/livekit/livekit.h	Exposes platform_audio.h from the umbrella header.
CMakeLists.txt	Adds src/platform_audio.cpp to the shared library build.
AGENTS.md	Updates threading-model docs and adds PlatformAudio to the thread-safety table.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[xianshijing-lk]

one question, it looks pretty good from a quick look.

[xianshijing-lk]

I wonder if getAudioSource is better than createAudioSource ?

Literally, PlatformAudio should have one source as it is a process global webrtc adm.

I think on Rust, we have something like
platform_audio.rtc_source() ?
wondering if we should have something similar to rust.

[alan-george-lk]

Agree, but FWIW we tend to use create...() in this SDK for other things

[stephen-derosa]

yeah i went with create...() to match the rest of the SDK.

If it is the case that the user can not create/get more than one audio source, than i think here getAudioSource or even rtcAudioSource would make sense

[alan-george-lk]

These feel a little verbose -- maybe just

/// @note This operation is not thread-safe.

and in the inverse

/// @note This operation is thread-safe.

If you agree let's change and update AGENTS.md. If you prefer the verbosity I won't hold anything up over it

[alan-george-lk]

General question about doc comments -- how much does the user need to know about the FFI layer? I wonder if something like this is more clean:

/// @throws std::runtime_error If the operation fails.

[stephen-derosa]

good question. We mention the ffi quite a bit in a lot of public API docs. I fear that "if the operation fails" could be misleading to the reason why.