docs: add AudioRecorder and AudioPlayer documentation

Author: devopvoid

docs/_sidebar.md

@@ -28,6 +28,8 @@
         - [Logging](guide/logging.md)
     - Utilities
         - [Audio Converter](guide/audio_converter.md)
+        - [Audio Recorder](guide/utilities/audio_recorder.md)
+        - [Audio Player](guide/utilities/audio_player.md)
         - [Video Buffer Converter](guide/utilities/video_buffer_converter.md)
         - [Video Capture](guide/video_capturer.md)
         - [Screen Capture](guide/screen_capturer.md)

docs/guide/overview.md

@@ -38,6 +38,8 @@ This section provides detailed guides for various features of the webrtc-java li
 ## Utilities
 
 - [Audio Converter](guide/audio_converter.md) - Resample and remix 10 ms PCM frames between different rates and channel layouts
+- [Audio Recorder](guide/utilities/audio_recorder.md) - Capture microphone input and receive 10 ms PCM frames via an AudioSink
+- [Audio Player](guide/utilities/audio_player.md) - Play PCM audio to an output device by supplying frames via an AudioSource
 - [Video Buffer Converter](guide/utilities/video_buffer_converter.md) - Convert between I420 and common FourCC pixel formats (e.g., RGBA, NV12)
 - [Video Capture](guide/video_capturer.md) - Control a camera device, configure capabilities, and deliver frames to a sink
 - [Screen Capture](guide/screen_capturer.md) - Enumerate and capture full desktop screens/monitors

docs/guide/utilities/audio_player.md

@@ -0,0 +1,97 @@
+# Audio Player
+
+The AudioPlayer is a small helper that plays audio using a selected output device by pulling frames from your implementation of AudioSource. It manages a native AudioDeviceModule internally and provides idempotent start/stop.
+
+API: `dev.onvoid.webrtc.media.audio.AudioPlayer`
+
+## When to use it
+- You want to render raw PCM audio (generated or decoded by your app) to an OS output device.
+- You need a simple, high‑level start/stop wrapper around WebRTC’s audio playout.
+
+See also: [Audio Device Selection](../audio_devices.md), [Custom Audio Source](../custom_audio_source.md), [Headless Audio](../headless_audio_device_module.md).
+
+## Key concepts
+- Device selection: Provide an `AudioDevice` representing the output device (speaker) before starting.
+- Data supply: Implement `AudioSource` to provide 10 ms PCM frames on demand.
+- Lifecycle: `start()` initializes output and begins pulling; `stop()` halts playout and releases resources.
+
+## Basic usage
+
+```java
+import dev.onvoid.webrtc.media.audio.AudioPlayer;
+import dev.onvoid.webrtc.media.audio.AudioSource;
+import dev.onvoid.webrtc.media.audio.AudioDevice;
+import dev.onvoid.webrtc.media.audio.AudioDeviceModule;
+
+import java.nio.ByteBuffer;
+
+public class TonePlayerExample {
+
+    public static void main(String[] args) {
+        // Choose a playout device (speaker). Enumerate via a temporary ADM.
+        AudioDeviceModule adm = new AudioDeviceModule();
+        AudioDevice speaker = adm.getPlayoutDevices().stream()
+                .findFirst()
+                .orElseThrow(() -> new IllegalStateException("No playout device found"));
+        adm.dispose();
+
+        // Provide 10 ms frames of PCM 16‑bit audio. This example generates a sine tone.
+        final int sampleRate = 48000;
+        final int channels = 2;
+        final int bytesPerSample = channels * 2; // 16‑bit
+        final double frequency = 440.0; // A4
+        final double twoPiFDivFs = 2 * Math.PI * frequency / sampleRate;
+        final int samplesPer10msPerChannel = sampleRate / 100; // 480 samples/channel
+        final int totalSamplesPer10ms = samplesPer10msPerChannel * channels; // e.g., 960 samples
+        final double[] phase = new double[] {0.0};
+
+        AudioSource source = (audioSamples, nSamples, nBytesPerSample, nChannels, samplesPerSec) -> {
+            // Ensure caller requested matches our configuration
+            if (nBytesPerSample != bytesPerSample || nChannels != channels || samplesPerSec != sampleRate) {
+                // Fill silence if formats mismatch
+                java.util.Arrays.fill(audioSamples, (byte) 0);
+                return totalSamplesPer10ms;
+            }
+
+            // Generate interleaved stereo sine wave
+            int idx = 0;
+            for (int i = 0; i < samplesPer10msPerChannel; i++) {
+                short s = (short) (Math.sin(phase[0]) * 32767);
+                // left
+                audioSamples[idx++] = (byte) (s & 0xFF);
+                audioSamples[idx++] = (byte) ((s >> 8) & 0xFF);
+                // right
+                audioSamples[idx++] = (byte) (s & 0xFF);
+                audioSamples[idx++] = (byte) ((s >> 8) & 0xFF);
+
+                phase[0] += twoPiFDivFs;
+
+                if (phase[0] > Math.PI * 2) {
+                    phase[0] -= Math.PI * 2;
+                }
+            }
+            return totalSamplesPer10ms; // number of samples written across all channels
+        };
+
+        AudioPlayer player = new AudioPlayer();
+        player.setAudioDevice(speaker);
+        player.setAudioSource(source);
+
+        player.start();
+        // ... playout running ...
+        player.stop();
+    }
+}
+```
+
+## Data format
+- The player requests 10 ms frames as 16‑bit little‑endian PCM via `AudioSource#onPlaybackData`.
+- Return value must be the number of samples written across all channels for that 10 ms frame.
+
+## Tips
+- If your synthesis/decoder operates at a different rate or channel layout, convert using the [Audio Converter](../audio_converter.md) before writing into the output buffer.
+
+## API reference
+- `setAudioDevice(AudioDevice device)` – choose output device
+- `setAudioSource(AudioSource source)` – provide playout frames
+- `start()` / `stop()` – control the playout lifecycle

docs/guide/utilities/audio_recorder.md

@@ -0,0 +1,65 @@
+# Audio Recorder
+
+The AudioRecorder is a small helper that captures audio from a selected input device and forwards PCM frames to your implementation of AudioSink. It manages a native AudioDeviceModule internally and provides idempotent start/stop.
+
+API: `dev.onvoid.webrtc.media.audio.AudioRecorder`
+
+## When to use it
+- You want a simple way to record microphone input without wiring a full PeerConnection.
+- You need raw 16‑bit PCM frames (10 ms) delivered to your code for analysis, file writing, or custom processing.
+
+See also: [Audio Device Selection](../audio_devices.md), [Audio Processing](../audio_processing.md), [Custom Audio Source](../custom_audio_source.md).
+
+## Key concepts
+- Device selection: Provide an `AudioDevice` representing the input device (microphone) before starting.
+- Data delivery: Implement `AudioSink` to receive recorded frames.
+- Lifecycle: `start()` initializes and starts capture once; `stop()` halts and releases native resources.
+
+## Basic usage
+
+```java
+import dev.onvoid.webrtc.media.audio.AudioRecorder;
+import dev.onvoid.webrtc.media.audio.AudioSink;
+import dev.onvoid.webrtc.media.audio.AudioDevice;
+import dev.onvoid.webrtc.media.audio.AudioDeviceModule;
+
+public class MicRecorderExample {
+    public static void main(String[] args) {
+        // Pick a recording device (microphone). You can enumerate via MediaDevices.getAudioCaptureDevices()
+        AudioDevice mic = ...
+
+        // Implement a sink to receive 10 ms PCM frames
+        AudioSink sink = (audioSamples, nSamples, nBytesPerSample, nChannels, samplesPerSec, totalDelayMS, clockDrift) -> {
+            // audioSamples: little‑endian 16‑bit PCM
+            // nSamples: total samples across all channels for this 10 ms frame
+            // nBytesPerSample: typically 2 for 16‑bit
+            // nChannels: number of channels (1 = mono, 2 = stereo)
+            // samplesPerSec: sample rate (e.g., 48000)
+            // totalDelayMS, clockDrift: diagnostics
+            // TODO: write to file, analyzer, encoder, etc.
+        };
+
+        AudioRecorder recorder = new AudioRecorder();
+        recorder.setAudioDevice(mic);
+        recorder.setAudioSink(sink);
+
+        recorder.start();
+        // ... capture running ...
+        recorder.stop();
+    }
+}
+```
+
+## Data format
+- Frames are delivered every 10 ms as 16‑bit little‑endian PCM in a `byte[]`.
+- `nSamples` refers to the number of samples across all channels within the 10 ms frame. Example: 48 kHz stereo → (48000/100)×2 = 960×2 = 1920 samples.
+
+## Tips
+- Apply echo cancellation, AGC, and noise suppression via the [Audio Processing](../audio_processing.md) guide if needed.
+- If you need to resample or remix, use the [Audio Converter](../audio_converter.md).
+- Device selection details and best practices are covered in [Audio Device Selection](../audio_devices.md).
+
+## API reference
+- `setAudioDevice(AudioDevice device)` – choose input device
+- `setAudioSink(AudioSink sink)` – receive captured frames
+- `start()` / `stop()` – control the capture lifecycle

webrtc/src/main/java/dev/onvoid/webrtc/media/audio/AudioPlayer.java

@@ -18,29 +18,68 @@
 
 import java.util.concurrent.atomic.AtomicBoolean;
 
+/**
+ * High-level wrapper to control audio playout. Provides idempotent start/stop semantics
+ * around an underlying AudioDeviceModule.
+ *
+ * @author Alex Andres
+ */
 public class AudioPlayer {
 
+	/**
+	 * Indicates if the player is currently started. Used atomically to provide
+	 * a thread-safe idempotent start/stop sequence.
+	 */
 	private final AtomicBoolean playing;
 
+	/**
+	 * Underlying audio device module managing the native playout resources.
+	 * Created lazily on {@link #start()} and disposed on {@link #stop()}.
+	 */
 	private AudioDeviceModule module;
 
+	/**
+	 * The audio output device to use for playout. Should be set before calling {@link #start()}.
+	 */
 	private AudioDevice device;
 
+	/**
+	 * The audio source providing audio frames to be rendered by the device.
+	 */
 	private AudioSource source;
 
 
+	/**
+	 * Creates a new AudioPlayer instance in a non-playing state.
+	 */
 	public AudioPlayer() {
 		playing = new AtomicBoolean();
 	}
 
+	/**
+	 * Assigns the audio output device.
+	 *
+	 * @param device the target playout device (may be null to clear).
+	 */
 	public void setAudioDevice(AudioDevice device) {
 		this.device = device;
 	}
 
+	/**
+	 * Assigns the audio source supplying audio data.
+	 *
+	 * @param source the audio source (may be null to clear).
+	 */
 	public void setAudioSource(AudioSource source) {
 		this.source = source;
 	}
 
+	/**
+	 * Starts audio playout if not already running. This method is idempotent; subsequent
+	 * calls while already playing have no effect.
+	 * <p>
+	 * Initializes and configures the underlying {@link AudioDeviceModule}.
+	 */
 	public void start() {
 		if (playing.compareAndSet(false, true)) {
 			module = new AudioDeviceModule();
@@ -51,11 +90,14 @@ public void start() {
 		}
 	}
 
+	/**
+	 * Stops audio playout if currently running and releases underlying resources.
+	 * This method is idempotent; calling when already stopped has no effect.
+	 */
 	public void stop() {
 		if (playing.compareAndSet(true, false)) {
 			module.stopPlayout();
 			module.dispose();
 		}
 	}
-
 }

webrtc/src/main/java/dev/onvoid/webrtc/media/audio/AudioRecorder.java

@@ -18,29 +18,57 @@
 
 import java.util.concurrent.atomic.AtomicBoolean;
 
+/**
+ * High-level recorder that captures audio from a configured {@link AudioDevice}
+ * and forwards frames to an {@link AudioSink}. Manages the lifecycle of the
+ * underlying {@link AudioDeviceModule} and offers thread-safe start/stop control.
+ *
+ * @author Alex Andres
+ */
 public class AudioRecorder {
 
+	/** Indicates whether the recording is currently active (thread-safe). */
 	private final AtomicBoolean capturing;
 
+	/** Underlying audio device module handling the native capture. */
 	private AudioDeviceModule module;
 
+	/** The audio input device to record from. */
 	private AudioDevice device;
 
+	/** The sink receiving captured audio data. */
 	private AudioSink sink;
 
 
+	/**
+	 * Creates a new AudioRecorder with an inactive capture state.
+	 */
 	public AudioRecorder() {
 		capturing = new AtomicBoolean();
 	}
 
+	/**
+	 * Set the audio input device to be used for recording.
+	 *
+	 * @param device the recording device; may be null until set.
+	 */
 	public void setAudioDevice(AudioDevice device) {
 		this.device = device;
 	}
 
+	/**
+	 * Set the sink that will receive captured audio frames.
+	 *
+	 * @param sink the audio sink implementation.
+	 */
 	public void setAudioSink(AudioSink sink) {
 		this.sink = sink;
 	}
 
+	/**
+	 * Start recording if not already active. Initializes and starts the underlying
+	 * AudioDeviceModule.
+	 */
 	public void start() {
 		if (capturing.compareAndSet(false, true)) {
 			module = new AudioDeviceModule();
@@ -51,11 +79,13 @@ public void start() {
 		}
 	}
 
+	/**
+	 * Stop recording if active and release resources.
+	 */
 	public void stop() {
 		if (capturing.compareAndSet(true, false)) {
 			module.stopRecording();
 			module.dispose();
 		}
 	}
-
 }

webrtc/src/main/java/dev/onvoid/webrtc/media/video/VideoBufferConverter.java

@@ -43,7 +43,8 @@ public final class VideoBufferConverter {
 	 * @throws NullPointerException if {@code src} or {@code dst} is {@code null}.
 	 * @throws Exception            if the native conversion fails.
 	 */
-	public static void convertFromI420(VideoFrameBuffer src, byte[] dst, FourCC fourCC) throws Exception {
+	public static void convertFromI420(VideoFrameBuffer src, byte[] dst, FourCC fourCC)
+			throws Exception {
 		if (src == null) {
 			throw new NullPointerException("Source buffer must not be null");
 		}
@@ -76,7 +77,8 @@ public static void convertFromI420(VideoFrameBuffer src, byte[] dst, FourCC four
 	 * @throws IllegalArgumentException if {@code dst} is read-only.
 	 * @throws Exception                if the native conversion fails.
 	 */
-	public static void convertFromI420(VideoFrameBuffer src, ByteBuffer dst, FourCC fourCC) throws Exception {
+	public static void convertFromI420(VideoFrameBuffer src, ByteBuffer dst, FourCC fourCC)
+			throws Exception {
 		if (src == null) {
 			throw new NullPointerException("Source buffer must not be null");
 		}
@@ -130,7 +132,8 @@ public static void convertFromI420(VideoFrameBuffer src, ByteBuffer dst, FourCC
 	 * @throws NullPointerException if {@code src} or {@code dst} is {@code null}.
 	 * @throws Exception            if the native conversion fails.
 	 */
-	public static void convertToI420(byte[] src, I420Buffer dst, FourCC fourCC) throws Exception {
+	public static void convertToI420(byte[] src, I420Buffer dst, FourCC fourCC)
+			throws Exception {
 		if (src == null) {
 			throw new NullPointerException("Source buffer must not be null");
 		}
@@ -160,7 +163,8 @@ public static void convertToI420(byte[] src, I420Buffer dst, FourCC fourCC) thro
 	 * @throws NullPointerException if {@code src} or {@code dst} is {@code null}.
 	 * @throws Exception            if the native conversion fails.
 	 */
-	public static void convertToI420(ByteBuffer src, I420Buffer dst, FourCC fourCC) throws Exception {
+	public static void convertToI420(ByteBuffer src, I420Buffer dst, FourCC fourCC)
+			throws Exception {
 		if (src == null) {
 			throw new NullPointerException("Source buffer must not be null");
 		}