From 4986f07b5c2f071e871ea809be0823e15c450943 Mon Sep 17 00:00:00 2001
From: Alex Andres <andres.alex@protonmail.com>
Date: Thu, 29 Oct 2026 19:35:34 +0100
Subject: [PATCH] docs: a microphone track hands no audio to sinks

WebRTC's LocalAudioSource ignores AddSink, so VoiceActivityExample attached to a microphone track hears nothing. Say which tracks feed a sink, and point to AudioRecorder for the microphone.
---
 docs/tools/audio/voice-activity-detector.md           | 11 ++++++++---
 .../onvoid/webrtc/examples/VoiceActivityExample.java  |  5 +++--
 2 files changed, 11 insertions(+), 5 deletions(-)

diff --git a/docs/tools/audio/voice-activity-detector.md b/docs/tools/audio/voice-activity-detector.md
index b658c84b4..4e9aa8c17 100644
--- a/docs/tools/audio/voice-activity-detector.md
+++ b/docs/tools/audio/voice-activity-detector.md
@@ -147,9 +147,9 @@ peer.onTrack(track -> {
 });
 ```
 
-The client API has no audio subscription on a local track. To detect speech at
-the microphone, attach the adapter as an `AudioTrackSink` to an `AudioTrack` of
-the native API:
+An `AudioTrack` of the native API takes the adapter as an `AudioTrackSink`, as
+long as the track's source hands its audio to sinks. A remote track and a track
+over a `CustomAudioSource` do:
 
 ```java
 VoiceActivityExample sink = new VoiceActivityExample(speech -> {
@@ -165,6 +165,11 @@ finally {
 }
 ```
 
+A microphone track does not: WebRTC passes captured audio from the audio device
+module straight to the senders, and the source of the track hands nothing to
+sinks. An [`AudioRecorder`](/tools/audio/audio-recorder) captures a microphone
+on its own, apart from any peer connection.
+
 The adapter invokes the consumer on the thread that delivers the audio: a thread
 of the `onAudio` subscription, or the audio callback thread of a sink. Keep work
 there short. A subscription that falls behind loses the oldest audio beyond its
diff --git a/webrtc-examples/src/main/java/dev/onvoid/webrtc/examples/VoiceActivityExample.java b/webrtc-examples/src/main/java/dev/onvoid/webrtc/examples/VoiceActivityExample.java
index 90c03fbe6..53b4c6bb9 100644
--- a/webrtc-examples/src/main/java/dev/onvoid/webrtc/examples/VoiceActivityExample.java
+++ b/webrtc-examples/src/main/java/dev/onvoid/webrtc/examples/VoiceActivityExample.java
@@ -31,8 +31,9 @@
 /**
  * With the client API, subscribe it to a remote track with
  * {@link RemoteAudio#onAudio(Consumer)}, then close the {@link Subscription}
- * before close(). An AudioTrack of the native API, such as a microphone's,
- * takes it with addSink(), then removeSink() before close().
+ * before close(). An AudioTrack of the native API takes it with addSink(),
+ * then removeSink() before close(), if its source hands audio to sinks: that
+ * of a remote track or a CustomAudioSource does, a microphone's does not.
  * Buffers arbitrary chunk lengths into 10 ms frames and converts interleaved
  * signed 16-bit PCM to 16 kHz mono, including input at 44.1 kHz. The consumer runs
  * on the thread that delivers the audio and should return promptly. It receives raw