feat: device-pulled remote audio playout

docs/fresh-audio-stream.md

@@ -64,6 +64,22 @@ renderer wake stalls. A 30-minute, two-participant application run measured
 p95 scheduled age at most 50 ms and maximum 56.911 ms, with bounded queues and
 no underruns; these are development measurements on one Windows machine.
 
+## Device-pulled playout
+
+Applications with platform playout disabled can call `setExternalAudioPlayout(true)`
+and drive `pullAudioPlayout()` from one device-clocked thread every 10 ms. One pull
+serves all active Rooms: their shared `LkRuntime` owns one PeerConnectionFactory
+and synthetic ADM. Read each active `FreshAudioStream` immediately after the pull.
+No timer advances remote audio in this mode; disable it when the driver exits.
+
+The receive path is synchronous: `AudioTransportImpl::NeedMorePlayData` calls
+`AudioMixerImpl::Mix`, which pulls every receive source, then `ChannelReceive`
+decodes NetEq and calls its raw sink. `RemoteAudioSource::OnData` forwards to
+`NativeAudioSink`, which fills the fresh queue inline on the caller thread.
+A source not yet playing, or a NetEq error, can still produce no frame.
+The Rust `external_playout_delivers_remote_frames_before_return` loopback test
+checks immediate reads, sink thread identity, and internal timer resumption.
+
 ## Publisher replacement regression
 
 The remote-audio routing fixture uncovered a publisher regression with mixed

include/livekit/livekit.h

@@ -72,4 +72,16 @@ LIVEKIT_API void shutdown();
 /// sound actually heard. Process-wide; clamped to 0..1000 ms.
 LIVEKIT_API void setAudioPlayoutDelay(std::chrono::milliseconds delay);
 
+/// @brief Select application-clocked remote audio instead of the internal timer.
+/// Process-wide, for applications that disable SDK platform playout. A single
+/// caller thread must pull every 10 ms while enabled, or remote audio stalls.
+/// @param enabled True to drive playout externally; false to resume the timer.
+LIVEKIT_API void setExternalAudioPlayout(bool enabled);
+
+/// @brief Synchronously pull one 10 ms remote audio frame for all active Rooms.
+/// Track sinks complete on this caller thread before return. Read active
+/// FreshAudioStreams immediately afterwards. Use one caller thread only.
+/// @return True if pulled; false if disabled, uninitialized, or not playing.
+LIVEKIT_API bool pullAudioPlayout();
+
 } // namespace livekit