Merge branch 'main' of github.com:livekit-examples/cpp-example-collection into feature/token_source_examples

Author: alan-george-lk

CMakeLists.txt

@@ -90,8 +90,7 @@ add_subdirectory(logging_levels/basic_usage logging_levels_basic_usage)
 add_subdirectory(logging_levels/custom_sinks logging_levels_custom_sinks)
 add_subdirectory(hello_livekit/sender hello_livekit_sender)
 add_subdirectory(hello_livekit/receiver hello_livekit_receiver)
-add_subdirectory(simple_joystick/sender simple_joystick_sender)
-add_subdirectory(simple_joystick/receiver simple_joystick_receiver)
+add_subdirectory(platform_audio)
 add_subdirectory(ping_pong/ping ping_pong_ping)
 add_subdirectory(ping_pong/pong ping_pong_pong)
 add_subdirectory(user_timestamped_video)

README.md

@@ -73,11 +73,21 @@ For example:
 ./build/basic_room/basic_room --url <ws-url> --token <token>
 ```
 
+### PlatformAudio
+
+The `platform_audio` examples show microphone capture and speaker playout using
+WebRTC's platform Audio Device Module:
+
+```bash
+./build/platform_audio/player/PlatformAudioPlayer <ws-url> <player-token>
+./build/platform_audio/sender/PlatformAudioSender <ws-url> <sender-token>
+```
+
 ### Supported platforms
 
 Prebuilt SDKs are downloaded automatically for:
 * Windows: x64
 * macOS: x64, arm64 (Apple Silicon)
 * Linux: x64
 
-If no matching SDK is available for your platform, CMake configuration will fail with a clear error.
+If no matching SDK is available for your platform, CMake configuration will fail with a clear error.

basic_room/main.cpp

@@ -132,7 +132,9 @@ int main(int argc, char* argv[]) {
 
   std::shared_ptr<LocalTrackPublication> audioPub;
   try {
-    room->localParticipant()->publishTrack(audioTrack, audioOpts);
+    auto lp = room->localParticipant().lock();
+    if (!lp) throw std::runtime_error("local participant unavailable");
+    lp->publishTrack(audioTrack, audioOpts);
     audioPub = audioTrack->publication();
     std::cout << "Published audio: sid=" << audioPub->sid() << "\n";
   } catch (const std::exception& e) {
@@ -151,7 +153,9 @@ int main(int argc, char* argv[]) {
 
   std::shared_ptr<LocalTrackPublication> videoPub;
   try {
-    room->localParticipant()->publishTrack(videoTrack, videoOpts);
+    auto lp = room->localParticipant().lock();
+    if (!lp) throw std::runtime_error("local participant unavailable");
+    lp->publishTrack(videoTrack, videoOpts);
     videoPub = videoTrack->publication();
     std::cout << "Published video: sid=" << videoPub->sid() << "\n";
   } catch (const std::exception& e) {
@@ -179,8 +183,10 @@ int main(int argc, char* argv[]) {
 
   // Best-effort unpublish
   try {
-    if (audioPub) room->localParticipant()->unpublishTrack(audioPub->sid());
-    if (videoPub) room->localParticipant()->unpublishTrack(videoPub->sid());
+    if (auto lp = room->localParticipant().lock()) {
+      if (audioPub) lp->unpublishTrack(audioPub->sid());
+      if (videoPub) lp->unpublishTrack(videoPub->sid());
+    }
   } catch (...) {
   }
 

hello_livekit/receiver/main.cpp

@@ -25,11 +25,11 @@
 ///   LIVEKIT_URL, LIVEKIT_RECEIVER_TOKEN, LIVEKIT_SENDER_IDENTITY
 
 #include <atomic>
-#include <cassert>
 #include <chrono>
 #include <csignal>
 #include <cstdlib>
 #include <iostream>
+#include <stdexcept>
 #include <thread>
 
 #include "livekit/livekit.h"
@@ -83,8 +83,10 @@ int main(int argc, char* argv[]) {
     return 1;
   }
 
-  LocalParticipant* lp = room->localParticipant();
-  assert(lp);
+  auto lp = room->localParticipant().lock();
+  if (!lp) {
+    throw std::runtime_error("[receiver] local participant is null");
+  }
 
   std::cout << "[info] [receiver] Connected as identity='" << lp->identity() << "' room='" << room->roomInfo().name
             << "'; subscribing to sender identity='" << sender_identity << "'\n";

hello_livekit/sender/main.cpp

@@ -24,13 +24,13 @@
 ///   LIVEKIT_URL, LIVEKIT_SENDER_TOKEN
 
 #include <atomic>
-#include <cassert>
 #include <chrono>
 #include <csignal>
 #include <cstdlib>
 #include <iomanip>
 #include <iostream>
 #include <sstream>
+#include <stdexcept>
 #include <thread>
 
 #include "livekit/livekit.h"
@@ -84,27 +84,33 @@ int main(int argc, char* argv[]) {
     return 1;
   }
 
-  LocalParticipant* lp = room->localParticipant();
-  assert(lp);
+  std::shared_ptr<LocalDataTrack> data_track;
+  std::shared_ptr<LocalVideoTrack> video_track;
+  std::shared_ptr<VideoSource> video_source;
+  {
+    auto lp = room->localParticipant().lock();
+    if (!lp) {
+      throw std::runtime_error("[sender] local participant is null");
+    }
 
-  std::cout << "[info] [sender] Connected as identity='" << lp->identity() << "' room='" << room->roomInfo().name
-            << "' — pass this identity to HelloLivekitReceiver\n";
+    std::cout << "[info] [sender] Connected as identity='" << lp->identity() << "' room='" << room->roomInfo().name
+              << "' — pass this identity to HelloLivekitReceiver\n";
 
-  auto video_source = std::make_shared<VideoSource>(kWidth, kHeight);
+    video_source = std::make_shared<VideoSource>(kWidth, kHeight);
 
-  std::shared_ptr<LocalVideoTrack> video_track =
-      lp->publishVideoTrack(kVideoTrackName, video_source, TrackSource::SOURCE_CAMERA);
+    video_track = lp->publishVideoTrack(kVideoTrackName, video_source, TrackSource::SOURCE_CAMERA);
 
-  auto publish_result = lp->publishDataTrack(kDataTrackName);
-  if (!publish_result) {
-    const auto& error = publish_result.error();
-    std::cerr << "[error] Failed to publish data track: code=" << static_cast<std::uint32_t>(error.code)
-              << " message=" << error.message << "\n";
-    room.reset();
-    livekit::shutdown();
-    return 1;
+    auto publish_result = lp->publishDataTrack(kDataTrackName);
+    if (!publish_result) {
+      const auto& error = publish_result.error();
+      std::cerr << "[error] Failed to publish data track: code=" << static_cast<std::uint32_t>(error.code)
+                << " message=" << error.message << "\n";
+      room.reset();
+      livekit::shutdown();
+      return 1;
+    }
+    data_track = publish_result.value();
   }
-  std::shared_ptr<LocalDataTrack> data_track = publish_result.value();
 
   const auto t0 = std::chrono::steady_clock::now();
   std::uint64_t count = 0;

ping_pong/ping/main.cpp

@@ -19,14 +19,14 @@
 /// identity is `ping`.
 
 #include <atomic>
-#include <cassert>
 #include <csignal>
 #include <cstdint>
 #include <exception>
 #include <iostream>
 #include <memory>
 #include <mutex>
 #include <optional>
+#include <stdexcept>
 #include <string>
 #include <thread>
 #include <unordered_map>
@@ -98,24 +98,29 @@ int main(int argc, char* argv[]) {
     return 1;
   }
 
-  LocalParticipant* local_participant = room->localParticipant();
-  assert(local_participant);
+  std::shared_ptr<LocalDataTrack> ping_track;
+  {
+    auto local_participant = room->localParticipant().lock();
+    if (!local_participant) {
+      throw std::runtime_error("[ping] local participant is null");
+    }
 
-  std::cout << "[info] ping connected as identity='" << local_participant->identity() << "' room='"
-            << room->roomInfo().name << "'\n";
+    std::cout << "[info] ping connected as identity='" << local_participant->identity() << "' room='"
+              << room->roomInfo().name << "'\n";
 
-  auto publish_result = local_participant->publishDataTrack(ping_pong::kPingTrackName);
-  if (!publish_result) {
-    const auto& error = publish_result.error();
-    std::cerr << "[error] Failed to publish ping data track: code=" << static_cast<std::uint32_t>(error.code)
-              << " message=" << error.message << "\n";
-    room->setDelegate(nullptr);
-    room.reset();
-    livekit::shutdown();
-    return 1;
+    auto publish_result = local_participant->publishDataTrack(ping_pong::kPingTrackName);
+    if (!publish_result) {
+      const auto& error = publish_result.error();
+      std::cerr << "[error] Failed to publish ping data track: code=" << static_cast<std::uint32_t>(error.code)
+                << " message=" << error.message << "\n";
+      room->setDelegate(nullptr);
+      room.reset();
+      livekit::shutdown();
+      return 1;
+    }
+    ping_track = publish_result.value();
   }
 
-  std::shared_ptr<LocalDataTrack> ping_track = publish_result.value();
   std::unordered_map<std::uint64_t, ping_pong::PingMessage> sent_messages;
   std::mutex sent_messages_mutex;
 

ping_pong/pong/main.cpp

@@ -18,13 +18,13 @@
 /// on the "pong" data track. Use a token whose identity is `pong`.
 
 #include <atomic>
-#include <cassert>
 #include <csignal>
 #include <cstdint>
 #include <exception>
 #include <iostream>
 #include <memory>
 #include <optional>
+#include <stdexcept>
 #include <string>
 #include <thread>
 #include <vector>
@@ -77,25 +77,30 @@ int main(int argc, char* argv[]) {
     return 1;
   }
 
-  LocalParticipant* local_participant = room->localParticipant();
-  assert(local_participant);
-
-  std::cout << "[info] pong connected as identity='" << local_participant->identity() << "' room='"
-            << room->roomInfo().name << "'\n";
-
-  auto publish_result = local_participant->publishDataTrack(ping_pong::kPongTrackName);
-  if (!publish_result) {
-    const auto& error = publish_result.error();
-    std::cerr << "[error] Failed to publish pong data track: code=" << static_cast<std::uint32_t>(error.code)
-              << " message=" << error.message << "\n";
-    room->setDelegate(nullptr);
-    room.reset();
-    livekit::shutdown();
-    return 1;
+  std::shared_ptr<LocalDataTrack> pong_track;
+  {
+    // limit the scope of the local participant
+    auto local_participant = room->localParticipant().lock();
+    if (!local_participant) {
+      throw std::runtime_error("[pong] local participant is null");
+    }
+
+    std::cout << "[info] pong connected as identity='" << local_participant->identity() << "' room='"
+              << room->roomInfo().name << "'\n";
+
+    auto publish_result = local_participant->publishDataTrack(ping_pong::kPongTrackName);
+    if (!publish_result) {
+      const auto& error = publish_result.error();
+      std::cerr << "[error] Failed to publish pong data track: code=" << static_cast<std::uint32_t>(error.code)
+                << " message=" << error.message << "\n";
+      room->setDelegate(nullptr);
+      room.reset();
+      livekit::shutdown();
+      return 1;
+    }
+    pong_track = publish_result.value();
   }
 
-  std::shared_ptr<LocalDataTrack> pong_track = publish_result.value();
-
   const auto callback_id = room->addOnDataFrameCallback(
       ping_pong::kPingParticipantIdentity, ping_pong::kPingTrackName,
       [pong_track](const std::vector<std::uint8_t>& payload, std::optional<std::uint64_t> /*user_timestamp*/) {

platform_audio/CMakeLists.txt

@@ -0,0 +1,16 @@
+# Copyright 2026 LiveKit, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+add_subdirectory(sender)
+add_subdirectory(player)

platform_audio/README.md

@@ -0,0 +1,44 @@
+# PlatformAudio
+
+These examples demonstrate the platform Audio Device Module path:
+
+- `PlatformAudioSender`: publishes microphone audio with echo cancellation, noise suppression, and auto gain control.
+- `PlatformAudioPlayer`: joins the same room and plays subscribed remote audio through the platform output device.
+
+Build the collection, then run the player and sender with different participant tokens for the same room:
+
+```bash
+./build/platform_audio/player/PlatformAudioPlayer <ws-url> <player-token>
+./build/platform_audio/sender/PlatformAudioSender <ws-url> <sender-token>
+```
+
+Environment fallbacks:
+
+```bash
+export LIVEKIT_URL=wss://your-livekit-host
+export LIVEKIT_PLAYER_TOKEN=<player-token>
+export LIVEKIT_SENDER_TOKEN=<sender-token>
+```
+
+## Test environments
+
+The sender captures the mic and runs the AEC/NS/AGC front-end; the player drives
+hardware playout. The acoustic echo cancellation (AEC) reference is per Audio
+Device Module (ADM), so the sender can only cancel playout from *its own* ADM.
+Pick an environment based on what you want to prove out.
+
+| Environment | What it proves | Notes |
+|-------------|----------------|-------|
+| **Two machines** (sender on A, player on B) | End-to-end capture → publish → subscribe → hardware playout over the network, like a real call. | Closest to a real LiveKit call. For full duplex (both apps on both boxes), use headphones or separate rooms to avoid feedback. |
+| **One machine + headphones** | Mic capture and ADM playout both work on one box, with no acoustic feedback path. | Best for confirming device selection and round-trip latency in isolation. |
+| **Noise suppression (NS)** | Steady background noise is attenuated while speech passes. | Add a fan / AC hum / typing near the mic. A/B by setting `noise_suppression = false` in `sender/main.cpp`. |
+| **Auto gain control (AGC)** | Quiet vs. loud / near vs. far speech is normalized on the player side. | A/B by setting `auto_gain_control = false` in `sender/main.cpp`. |
+| **`prefer_hardware = true`** | Platform hardware voice processing engages (e.g. macOS voice-processing I/O). | Set in the sender options; compare CPU and audio character vs. the software path. |
+| **Device / hot-plug sanity** | `recordingDevices()` / `playoutDevices()` reflect attached hardware and route correctly. | Plug/unplug a USB or Bluetooth mic/headset before launch and check the startup device logs. |
+
+> **AEC caveat:** these split sender/player apps cannot demonstrate AEC against
+> each other on one machine over open speakers — the sender's AEC has no
+> reference to the player's separate ADM, so the speaker output is treated as
+> external sound and you get an echo/feedback loop. Genuine AEC requires a
+> single application that both plays remote audio and captures the mic through
+> the *same* ADM. Use headphones to avoid feedback with these examples.

simple_joystick/sender/CMakeLists.txt platform_audio/player/CMakeLists.txtsimple_joystick/sender/CMakeLists.txt renamed to platform_audio/player/CMakeLists.txt

@@ -12,21 +12,11 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-add_library(simple_joystick_sender_support STATIC
-  json_utils.cpp
-  json_utils.h
-  utils.cpp
-  utils.h
-)
-
-target_include_directories(simple_joystick_sender_support PUBLIC ${CMAKE_CURRENT_SOURCE_DIR})
-target_link_libraries(simple_joystick_sender_support PUBLIC nlohmann_json::nlohmann_json)
-
-add_executable(SimpleJoystickSender
+add_executable(PlatformAudioPlayer
   main.cpp
 )
 
-target_include_directories(SimpleJoystickSender PRIVATE ${CMAKE_CURRENT_SOURCE_DIR})
-target_link_libraries(SimpleJoystickSender PRIVATE simple_joystick_sender_support ${LIVEKIT_CORE_TARGET})
+target_include_directories(PlatformAudioPlayer PRIVATE ${CMAKE_CURRENT_SOURCE_DIR})
+target_link_libraries(PlatformAudioPlayer PRIVATE ${LIVEKIT_CORE_TARGET})
 
-livekit_copy_windows_runtime_dlls(SimpleJoystickSender)
+livekit_copy_windows_runtime_dlls(PlatformAudioPlayer)