2727
2828namespace livekit {
2929
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.
3037struct PlatformAudioState ;
3138
32- /* *
33- * Information about a platform audio device.
34- */
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.
3546struct AudioDeviceInfo {
36- /* * Current device index. Indices may change when devices are added or removed. */
47+ // / Current device index.
3748 std::uint32_t index = 0 ;
3849
39- /* * Device name reported by the operating system. */
50+ // / Device name reported by the operating system.
4051 std::string name;
4152
42- /* * Platform-specific stable device identifier. Prefer this over index for selection. */
53+ // / Platform-specific stable device identifier.
4354 std::string id;
4455};
4556
46- /* *
47- * Audio processing options for platform microphone capture.
48- */
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.
4964struct PlatformAudioOptions {
50- /* * Enable acoustic echo cancellation. */
65+ // / Enable acoustic echo cancellation.
5166 bool echo_cancellation = true ;
5267
53- /* * Enable background noise suppression. */
68+ // / Enable background noise suppression.
5469 bool noise_suppression = true ;
5570
56- /* * Enable automatic gain control. */
71+ // / Enable automatic gain control.
5772 bool auto_gain_control = true ;
5873
59- /* * Prefer hardware audio processing when the platform provides it. */
74+ // / Prefer hardware audio processing when the platform provides it.
6075 bool prefer_hardware = false ;
6176};
6277
63- /* *
64- * Error raised when platform audio setup or device operations fail.
65- */
78+ // / Error raised when platform audio setup or device operations fail.
79+ // /
80+ // / @note Thread-safety: Thread-safe. Instances are immutable after
81+ // / construction.
6682class LIVEKIT_API PlatformAudioError : public std::runtime_error {
6783public:
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.
6890 explicit PlatformAudioError (const std::string& message) : std::runtime_error(message) {}
6991};
7092
71- /* *
72- * Audio source backed by WebRTC's platform Audio Device Module.
73- *
74- * A PlatformAudioSource captures microphone audio automatically. Unlike
75- * AudioSource, callers do not push frames with captureFrame().
76- */
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.
77100class LIVEKIT_API PlatformAudioSource {
78101public:
102+ // / Destroy the platform audio source and release its FFI handle.
103+ // /
104+ // / @note Thread-safety: Not thread-safe. Do not destroy the source while
105+ // / another thread is using it.
79106 ~PlatformAudioSource () = default ;
80107
81- PlatformAudioSource (const PlatformAudioSource&) = delete ;
82- PlatformAudioSource& operator =(const PlatformAudioSource&) = delete ;
83- PlatformAudioSource (PlatformAudioSource&&) noexcept = default ;
84- PlatformAudioSource& operator =(PlatformAudioSource&&) noexcept = default ;
108+ // / Copy construction is disabled.
109+ // /
110+ // / @param other Source to copy from.
111+ // /
112+ // / @note Thread-safety: Not thread-safe. This operation is deleted.
113+ PlatformAudioSource (const PlatformAudioSource& other) = delete ;
114+
115+ // / Copy assignment is disabled.
116+ // /
117+ // / @param other Source to copy from.
118+ // / @return Reference to this source.
119+ // /
120+ // / @note Thread-safety: Not thread-safe. This operation is deleted.
121+ PlatformAudioSource& operator =(const PlatformAudioSource& other) = delete ;
122+
123+ // / Move the platform audio source.
124+ // /
125+ // / @param other Source to move from.
126+ // /
127+ // / @note Thread-safety: Not thread-safe. The moved-from and moved-to objects
128+ // / must not be accessed concurrently during the move.
129+ PlatformAudioSource (PlatformAudioSource&& other) noexcept = default ;
85130
86- // / Underlying FFI handle ID used in FFI requests.
131+ // / Move-assign the platform audio source.
132+ // /
133+ // / @param other Source to move from.
134+ // / @return Reference to this source.
135+ // /
136+ // / @note Thread-safety: Not thread-safe. The moved-from and moved-to objects
137+ // / must not be accessed concurrently during the move.
138+ PlatformAudioSource& operator =(PlatformAudioSource&& other) noexcept = default ;
139+
140+ // / Return the underlying FFI handle ID used in FFI requests.
141+ // /
142+ // / @note Thread-safety: Thread-safe. Reads immutable handle state.
87143 std::uint64_t ffiHandleId () const noexcept { return static_cast <std::uint64_t >(handle_.get ()); }
88144
89145private:
@@ -95,43 +151,127 @@ class LIVEKIT_API PlatformAudioSource {
95151 std::shared_ptr<PlatformAudioState> platform_audio_;
96152};
97153
98- /* *
99- * Platform audio device manager backed by WebRTC's Audio Device Module.
100- *
101- * Use PlatformAudio for normal microphone publishing when built-in echo
102- * cancellation, noise suppression, automatic gain control, and speaker playout
103- * are desired. Use AudioSource instead when the application needs direct access
104- * to raw PCM frames or custom audio generation.
105- */
154+ // / Platform audio device manager backed by WebRTC's Audio Device Module.
155+ // /
156+ // / Use PlatformAudio for normal microphone publishing when built-in echo
157+ // / cancellation, noise suppression, automatic gain control, and speaker playout
158+ // / are desired. Use AudioSource instead when the application needs direct access
159+ // / to raw PCM frames or custom audio generation.
160+ // /
161+ // / @note Thread-safety: Thread-safe. Methods send independent FFI requests and
162+ // / share immutable handle state.
106163class LIVEKIT_API PlatformAudio {
107164public:
165+ // / Create a platform audio manager.
166+ // /
167+ // / Enables WebRTC's platform Audio Device Module for microphone capture and
168+ // / speaker playout.
169+ // /
170+ // / @throws PlatformAudioError If the FFI response is malformed or the
171+ // / platform Audio Device Module cannot be created.
172+ // /
173+ // / @note Thread-safety: Thread-safe. Sends an independent FFI request.
108174 PlatformAudio ();
175+
176+ // / Destroy the platform audio manager and release its FFI handle.
177+ // /
178+ // / @note Thread-safety: Not thread-safe. Do not destroy the manager while
179+ // / another thread is using it.
109180 ~PlatformAudio () = default ;
110181
111- PlatformAudio (const PlatformAudio&) = default ;
112- PlatformAudio& operator =(const PlatformAudio&) = default ;
113- PlatformAudio (PlatformAudio&&) noexcept = default ;
114- PlatformAudio& operator =(PlatformAudio&&) noexcept = default ;
182+ // / Copy the platform audio manager.
183+ // /
184+ // / The copy shares the same underlying platform audio handle.
185+ // /
186+ // / @param other Manager to copy from.
187+ // /
188+ // / @note Thread-safety: Not thread-safe. The source object must not be
189+ // / concurrently moved or assigned while copying.
190+ PlatformAudio (const PlatformAudio& other) = default ;
191+
192+ // / Copy-assign the platform audio manager.
193+ // /
194+ // / The assigned instance shares the same underlying platform audio handle.
195+ // /
196+ // / @param other Manager to copy from.
197+ // / @return Reference to this manager.
198+ // /
199+ // / @note Thread-safety: Not thread-safe. The assigned object and source
200+ // / object must not be accessed concurrently during assignment.
201+ PlatformAudio& operator =(const PlatformAudio& other) = default ;
202+
203+ // / Move the platform audio manager.
204+ // /
205+ // / @param other Manager to move from.
206+ // /
207+ // / @note Thread-safety: Not thread-safe. The moved-from and moved-to objects
208+ // / must not be accessed concurrently during the move.
209+ PlatformAudio (PlatformAudio&& other) noexcept = default ;
210+
211+ // / Move-assign the platform audio manager.
212+ // /
213+ // / @param other Manager to move from.
214+ // / @return Reference to this manager.
215+ // /
216+ // / @note Thread-safety: Not thread-safe. The moved-from and moved-to objects
217+ // / must not be accessed concurrently during the move.
218+ PlatformAudio& operator =(PlatformAudio&& other) noexcept = default ;
115219
116- // / Number of recording devices reported when this instance was created.
220+ // / Return the number of recording devices reported when this instance was created.
221+ // /
222+ // / @note Thread-safety: Thread-safe. Reads immutable handle state.
117223 std::int32_t recordingDeviceCount () const noexcept ;
118224
119- // / Number of playout devices reported when this instance was created.
225+ // / Return the number of playout devices reported when this instance was created.
226+ // /
227+ // / @note Thread-safety: Thread-safe. Reads immutable handle state.
120228 std::int32_t playoutDeviceCount () const noexcept ;
121229
122230 // / Enumerate available microphones.
231+ // /
232+ // / @return List of available recording devices.
233+ // / @throws PlatformAudioError If the FFI response is malformed or device
234+ // / enumeration fails.
235+ // /
236+ // / @note Thread-safety: Thread-safe. Sends an independent FFI request.
123237 std::vector<AudioDeviceInfo> recordingDevices () const ;
124238
125239 // / Enumerate available speakers/headphones.
240+ // /
241+ // / @return List of available playout devices.
242+ // / @throws PlatformAudioError If the FFI response is malformed or device
243+ // / enumeration fails.
244+ // /
245+ // / @note Thread-safety: Thread-safe. Sends an independent FFI request.
126246 std::vector<AudioDeviceInfo> playoutDevices () const ;
127247
128- // / Select the microphone by AudioDeviceInfo::id.
248+ // / Select the microphone by device ID.
249+ // /
250+ // / @param device_id Stable device identifier from AudioDeviceInfo::id.
251+ // / @throws PlatformAudioError If the FFI response is malformed or device
252+ // / selection fails.
253+ // /
254+ // / @note Thread-safety: Thread-safe. Sends an independent FFI request.
129255 void setRecordingDevice (const std::string& device_id) const ;
130256
131- // / Select the speaker/headphones by AudioDeviceInfo::id.
257+ // / Select the speaker/headphones by device ID.
258+ // /
259+ // / @param device_id Stable device identifier from AudioDeviceInfo::id.
260+ // / @throws PlatformAudioError If the FFI response is malformed or device
261+ // / selection fails.
262+ // /
263+ // / @note Thread-safety: Thread-safe. Sends an independent FFI request.
132264 void setPlayoutDevice (const std::string& device_id) const ;
133265
134266 // / Create an automatically captured microphone source for LocalAudioTrack.
267+ // /
268+ // / @param options Audio processing options for the platform microphone path.
269+ // / @return Platform-backed audio source suitable for LocalAudioTrack.
270+ // / @throws PlatformAudioError If the FFI response is malformed or source
271+ // / creation fails.
272+ // /
273+ // / @note Thread-safety: Thread-safe. Sends an independent FFI request and
274+ // / returns a source that keeps the shared PlatformAudio state alive.
135275 std::shared_ptr<PlatformAudioSource> createAudioSource (const PlatformAudioOptions& options = {}) const ;
136276
137277private:
0 commit comments