Skip to content

Commit a7d1829

Browse files
PlatformAudio: integration and unit tests
1 parent 245d55c commit a7d1829

10 files changed

Lines changed: 960 additions & 19 deletions

File tree

‎AGENTS.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -60,6 +60,7 @@ All `RoomDelegate` callbacks and stream handler callbacks (e.g., `registerTextSt
6060
| `SubscriptionThreadDispatcher` | Yes | Internal `std::mutex` protects registrations and active readers. Thread joins happen outside the lock. |
6161
| `AudioStream` / `VideoStream` / `DataTrackStream` | Yes | Internal `std::mutex` + `condition_variable` coordinate the FFI producer thread and the consumer reader thread. |
6262
| `AudioSource::captureFrame` | No | Not safe to call concurrently from multiple threads. |
63+
| `PlatformAudio` / `PlatformAudioSource` | Yes | Thin `sendRequest` wrappers over immutable FFI handle state; destruction and move operations must be externally synchronized. |
6364
| `VideoSource::captureFrame` | No | Not safe to call concurrently from multiple threads. |
6465
| `LocalAudioTrack` / `LocalVideoTrack` | No | Thin `sendRequest` wrappers with no internal synchronization. |
6566
| `LocalDataTrack::tryPush` | No | Thin `sendRequest` wrapper with no internal synchronization. |

‎CMakeLists.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -385,6 +385,7 @@ add_library(livekit SHARED
385385
src/logging.cpp
386386
src/local_audio_track.cpp
387387
src/local_data_track.cpp
388+
src/platform_audio.cpp
388389
src/remote_audio_track.cpp
389390
src/remote_data_track.cpp
390391
src/room.cpp

‎include/livekit/livekit.h‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,7 @@
2828
#include "livekit/local_video_track.h"
2929
#include "livekit/logging.h"
3030
#include "livekit/participant.h"
31+
#include "livekit/platform_audio.h"
3132
#include "livekit/remote_participant.h"
3233
#include "livekit/remote_track_publication.h"
3334
#include "livekit/room.h"
@@ -60,4 +61,4 @@ LIVEKIT_API bool initialize(const LogLevel& level = LogLevel::Info);
6061
/// After shutdown, you may call initialize() again.
6162
LIVEKIT_API void shutdown();
6263

63-
} // namespace livekit
64+
} // namespace livekit

‎include/livekit/local_audio_track.h‎

Lines changed: 40 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -31,12 +31,15 @@ class OwnedTrack;
3131
}
3232

3333
class AudioSource;
34+
class PlatformAudioSource;
3435

3536
/// Represents a user-provided audio track sourced from the local device.
3637
///
37-
/// `LocalAudioTrack` is used to publish microphone audio (or any custom
38-
/// audio source) to a LiveKit room. It wraps a platform-specific audio
39-
/// source and exposes simple controls such as `mute()` and `unmute()`.
38+
/// `LocalAudioTrack` is used to publish microphone audio or any custom audio
39+
/// source to a LiveKit room. It wraps a platform-specific audio
40+
/// source and exposes simple controls such as `mute()` and `unmute()`.
41+
/// Muting a local audio track stops transmitting audio to the room, but
42+
/// the underlying source may continue capturing depending on platform behavior.
4043
///
4144
/// Typical usage:
4245
///
@@ -52,6 +55,8 @@ class AudioSource;
5255
///
5356
/// The track name provided during creation is visible to remote
5457
/// participants and can be used for debugging or UI display.
58+
/// @note Thread-safety: Not thread-safe. This is a thin FFI wrapper with no
59+
/// internal synchronization.
5560
class LIVEKIT_API LocalAudioTrack : public Track {
5661
public:
5762
/// Creates a new local audio track backed by the given `AudioSource`.
@@ -63,30 +68,55 @@ class LIVEKIT_API LocalAudioTrack : public Track {
6368
/// directly for frame capture.
6469
///
6570
/// @return A shared pointer to the newly constructed `LocalAudioTrack`.
71+
/// @throws std::invalid_argument If \p source is null.
72+
/// @throws std::runtime_error If the FFI request fails.
6673
static std::shared_ptr<LocalAudioTrack> createLocalAudioTrack(const std::string& name,
6774
const std::shared_ptr<AudioSource>& source);
6875

76+
/// Creates a new local audio track backed by the given `PlatformAudioSource`.
77+
///
78+
/// @param name Human-readable name for the track. This may appear to
79+
/// remote participants and in analytics/debug logs.
80+
/// @param source The platform source that captures microphone audio
81+
/// automatically through WebRTC's Audio Device Module.
82+
///
83+
/// @return A shared pointer to the newly constructed `LocalAudioTrack`.
84+
/// @throws std::invalid_argument If \p source is null.
85+
/// @throws std::runtime_error If the FFI request fails.
86+
///
87+
/// @note Thread-safety: Not thread-safe. This is a thin FFI wrapper with no
88+
/// internal synchronization.
89+
static std::shared_ptr<LocalAudioTrack> createLocalAudioTrack(const std::string& name,
90+
const std::shared_ptr<PlatformAudioSource>& source);
91+
6992
/// Mutes the audio track.
7093
///
7194
/// A muted track stops sending audio to the room, but the track remains
7295
/// published and can be unmuted later without renegotiation.
96+
///
97+
/// @throws std::runtime_error If the FFI request fails.
7398
void mute();
7499

75-
/// Unmutes the audio track and resumes sending audio to the room.
100+
/// Unmute the audio track.
101+
///
102+
/// Resumes sending audio to the room.
103+
///
104+
/// @throws std::runtime_error If the FFI request fails.
76105
void unmute();
77106

78-
/// Returns a human-readable string representation of the track,
79-
/// including its SID and name. Useful for debugging and logging.
107+
/// Return a human-readable string representation of the track.
108+
///
109+
/// @return String containing the track SID and name.
80110
std::string toString() const;
81111

82112
/// Returns the publication that owns this track, or nullptr if the track is
83113
/// not published.
84114
std::shared_ptr<LocalTrackPublication> publication() const noexcept { return local_publication_; }
85115

86-
/// Sets the publication that owns this track.
87-
/// Note: std::move on a const& silently falls back to a copy, so we assign
88-
/// directly. Changing the virtual signature to take by value would enable
89-
/// a true move but is an API-breaking change hence left for a future revision.
116+
/// Set the publication that owns this track.
117+
///
118+
/// @param publication Publication that owns this track, or nullptr to clear
119+
/// the association.
90120
void setPublication(const std::shared_ptr<LocalTrackPublication>& publication) noexcept override {
91121
local_publication_ = publication;
92122
}

‎include/livekit/platform_audio.h‎

Lines changed: 269 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,269 @@
1+
/*
2+
* Copyright 2026 LiveKit
3+
*
4+
* Licensed under the Apache License, Version 2.0 (the "License");
5+
* you may not use this file except in compliance with the License.
6+
* You may obtain a copy of the License at
7+
*
8+
* http://www.apache.org/licenses/LICENSE-2.0
9+
*
10+
* Unless required by applicable law or agreed to in writing, software
11+
* distributed under the License is distributed on an "AS IS" BASIS,
12+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
* See the License for the specific language governing permissions and
14+
* limitations under the License.
15+
*/
16+
17+
#pragma once
18+
19+
#include <cstdint>
20+
#include <memory>
21+
#include <stdexcept>
22+
#include <string>
23+
#include <vector>
24+
25+
#include "livekit/ffi_handle.h"
26+
#include "livekit/visibility.h"
27+
28+
namespace livekit {
29+
30+
/// Internal shared state for platform audio handles.
31+
///
32+
/// This forward declaration is exposed only so public wrapper types can hold a
33+
/// shared implementation pointer.
34+
///
35+
/// @note Thread-safety: Thread-safe. Instances are managed internally by
36+
/// PlatformAudio.
37+
struct PlatformAudioState;
38+
39+
/// Information about a platform audio device.
40+
///
41+
/// Device indices may change when audio hardware is added or removed. Prefer
42+
/// the stable `id` value when selecting a device.
43+
///
44+
/// @note Thread-safety: Thread-safe. This is an aggregate value type with no
45+
/// internal shared state.
46+
struct AudioDeviceInfo {
47+
/// Current device index.
48+
std::uint32_t index = 0;
49+
50+
/// Device name reported by the operating system.
51+
std::string name;
52+
53+
/// Platform-specific stable device identifier.
54+
std::string id;
55+
};
56+
57+
/// Audio processing options for platform microphone capture.
58+
///
59+
/// The default values enable WebRTC's voice processing path for typical
60+
/// microphone publishing.
61+
///
62+
/// @note Thread-safety: Thread-safe. This is an aggregate value type with no
63+
/// internal shared state.
64+
struct PlatformAudioOptions {
65+
/// Enable acoustic echo cancellation.
66+
bool echo_cancellation = true;
67+
68+
/// Enable background noise suppression.
69+
bool noise_suppression = true;
70+
71+
/// Enable automatic gain control.
72+
bool auto_gain_control = true;
73+
74+
/// Prefer hardware audio processing when the platform provides it.
75+
bool prefer_hardware = false;
76+
};
77+
78+
/// Error raised when platform audio setup or device operations fail.
79+
///
80+
/// @note Thread-safety: Thread-safe. Instances are immutable after
81+
/// construction.
82+
class LIVEKIT_API PlatformAudioError : public std::runtime_error {
83+
public:
84+
/// Create a platform audio error.
85+
///
86+
/// @param message Human-readable error message.
87+
///
88+
/// @note Thread-safety: Thread-safe. Instances are immutable after
89+
/// construction.
90+
explicit PlatformAudioError(const std::string& message) : std::runtime_error(message) {}
91+
};
92+
93+
/// Audio source backed by WebRTC's platform Audio Device Module.
94+
///
95+
/// A PlatformAudioSource captures microphone audio automatically. Unlike
96+
/// AudioSource, callers do not push frames with captureFrame().
97+
///
98+
/// @note Thread-safety: Thread-safe. The source owns an immutable FFI handle
99+
/// and keeps the shared PlatformAudio state alive.
100+
class LIVEKIT_API PlatformAudioSource {
101+
public:
102+
/// Copy construction is disabled.
103+
///
104+
/// @param other Source to copy from.
105+
///
106+
/// @note Thread-safety: Not thread-safe. This operation is deleted.
107+
PlatformAudioSource(const PlatformAudioSource& other) = delete;
108+
109+
/// Copy assignment is disabled.
110+
///
111+
/// @param other Source to copy from.
112+
/// @return Reference to this source.
113+
///
114+
/// @note Thread-safety: Not thread-safe. This operation is deleted.
115+
PlatformAudioSource& operator=(const PlatformAudioSource& other) = delete;
116+
117+
/// Move the platform audio source.
118+
///
119+
/// @param other Source to move from.
120+
///
121+
/// @note Thread-safety: Not thread-safe. The moved-from and moved-to objects
122+
/// must not be accessed concurrently during the move.
123+
PlatformAudioSource(PlatformAudioSource&& other) noexcept = default;
124+
125+
/// Move-assign the platform audio source.
126+
///
127+
/// @param other Source to move from.
128+
/// @return Reference to this source.
129+
///
130+
/// @note Thread-safety: Not thread-safe. The moved-from and moved-to objects
131+
/// must not be accessed concurrently during the move.
132+
PlatformAudioSource& operator=(PlatformAudioSource&& other) noexcept = default;
133+
134+
/// Return the underlying FFI handle ID used in FFI requests.
135+
///
136+
/// @note Thread-safety: Thread-safe. Reads immutable handle state.
137+
std::uint64_t ffiHandleId() const noexcept { return static_cast<std::uint64_t>(handle_.get()); }
138+
139+
private:
140+
friend class PlatformAudio;
141+
142+
PlatformAudioSource(FfiHandle handle, std::shared_ptr<PlatformAudioState> platform_audio) noexcept;
143+
144+
FfiHandle handle_;
145+
std::shared_ptr<PlatformAudioState> platform_audio_;
146+
};
147+
148+
/// Platform audio device manager backed by WebRTC's Audio Device Module.
149+
///
150+
/// Use PlatformAudio for normal microphone publishing when built-in echo
151+
/// cancellation, noise suppression, automatic gain control, and speaker playout
152+
/// are desired. Use AudioSource instead when the application needs direct access
153+
/// to raw PCM frames or custom audio generation.
154+
///
155+
/// @note Thread-safety: Thread-safe. Methods send independent FFI requests and
156+
/// share immutable handle state.
157+
class LIVEKIT_API PlatformAudio {
158+
public:
159+
/// Create a platform audio manager.
160+
///
161+
/// Enables WebRTC's platform Audio Device Module for microphone capture and
162+
/// speaker playout.
163+
///
164+
/// @throws PlatformAudioError If the FFI response is malformed or the
165+
/// platform Audio Device Module cannot be created.
166+
///
167+
/// @note Thread-safety: Thread-safe. Sends an independent FFI request.
168+
PlatformAudio();
169+
170+
/// Copy the platform audio manager.
171+
///
172+
/// The copy shares the same underlying platform audio handle.
173+
///
174+
/// @param other Manager to copy from.
175+
///
176+
/// @note Thread-safety: Not thread-safe. The source object must not be
177+
/// concurrently moved or assigned while copying.
178+
PlatformAudio(const PlatformAudio& other) = default;
179+
180+
/// Copy-assign the platform audio manager.
181+
///
182+
/// The assigned instance shares the same underlying platform audio handle.
183+
///
184+
/// @param other Manager to copy from.
185+
/// @return Reference to this manager.
186+
///
187+
/// @note Thread-safety: Not thread-safe. The assigned object and source
188+
/// object must not be accessed concurrently during assignment.
189+
PlatformAudio& operator=(const PlatformAudio& other) = default;
190+
191+
/// Move the platform audio manager.
192+
///
193+
/// @param other Manager to move from.
194+
///
195+
/// @note Thread-safety: Not thread-safe. The moved-from and moved-to objects
196+
/// must not be accessed concurrently during the move.
197+
PlatformAudio(PlatformAudio&& other) noexcept = default;
198+
199+
/// Move-assign the platform audio manager.
200+
///
201+
/// @param other Manager to move from.
202+
/// @return Reference to this manager.
203+
///
204+
/// @note Thread-safety: Not thread-safe. The moved-from and moved-to objects
205+
/// must not be accessed concurrently during the move.
206+
PlatformAudio& operator=(PlatformAudio&& other) noexcept = default;
207+
208+
/// Return the number of recording devices reported when this instance was created.
209+
///
210+
/// @note Thread-safety: Thread-safe. Reads immutable handle state.
211+
std::int32_t recordingDeviceCount() const noexcept;
212+
213+
/// Return the number of playout devices reported when this instance was created.
214+
///
215+
/// @note Thread-safety: Thread-safe. Reads immutable handle state.
216+
std::int32_t playoutDeviceCount() const noexcept;
217+
218+
/// Enumerate available microphones.
219+
///
220+
/// @return List of available recording devices.
221+
/// @throws PlatformAudioError If the FFI response is malformed or device
222+
/// enumeration fails.
223+
///
224+
/// @note Thread-safety: Thread-safe. Sends an independent FFI request.
225+
std::vector<AudioDeviceInfo> recordingDevices() const;
226+
227+
/// Enumerate available speakers/headphones.
228+
///
229+
/// @return List of available playout devices.
230+
/// @throws PlatformAudioError If the FFI response is malformed or device
231+
/// enumeration fails.
232+
///
233+
/// @note Thread-safety: Thread-safe. Sends an independent FFI request.
234+
std::vector<AudioDeviceInfo> playoutDevices() const;
235+
236+
/// Select the microphone by device ID.
237+
///
238+
/// @param device_id Stable device identifier from AudioDeviceInfo::id.
239+
/// @throws PlatformAudioError If the FFI response is malformed or device
240+
/// selection fails.
241+
///
242+
/// @note Thread-safety: Thread-safe. Sends an independent FFI request.
243+
void setRecordingDevice(const std::string& device_id) const;
244+
245+
/// Select the speaker/headphones by device ID.
246+
///
247+
/// @param device_id Stable device identifier from AudioDeviceInfo::id.
248+
/// @throws PlatformAudioError If the FFI response is malformed or device
249+
/// selection fails.
250+
///
251+
/// @note Thread-safety: Thread-safe. Sends an independent FFI request.
252+
void setPlayoutDevice(const std::string& device_id) const;
253+
254+
/// Create an automatically captured microphone source for LocalAudioTrack.
255+
///
256+
/// @param options Audio processing options for the platform microphone path.
257+
/// @return Platform-backed audio source suitable for LocalAudioTrack.
258+
/// @throws PlatformAudioError If the FFI response is malformed or source
259+
/// creation fails.
260+
///
261+
/// @note Thread-safety: Thread-safe. Sends an independent FFI request and
262+
/// returns a source that keeps the shared PlatformAudio state alive.
263+
std::shared_ptr<PlatformAudioSource> createAudioSource(const PlatformAudioOptions& options = {}) const;
264+
265+
private:
266+
std::shared_ptr<PlatformAudioState> state_;
267+
};
268+
269+
} // namespace livekit

0 commit comments

Comments
 (0)