|
| 1 | +# Headless Audio Device Module |
| 2 | + |
| 3 | +The `HeadlessAudioDeviceModule` is a convenience implementation of the `AudioDeviceModule` that uses WebRTC's dummy audio layer. It avoids touching real OS audio devices while still enabling the WebRTC audio pipeline to pull and render audio frames (headless playout) and to simulate capture (recording path). |
| 4 | + |
| 5 | +This is ideal for: |
| 6 | +- Server-side or CI environments without audio hardware |
| 7 | +- Automated tests where deterministic, no-op audio IO is desired |
| 8 | +- Receive-only applications that should render audio via the WebRTC pipeline without producing audible output |
| 9 | +- Applications that implement custom audio ingestion but do not want to interact with system devices |
| 10 | + |
| 11 | +## Key characteristics |
| 12 | +- Uses dummy audio drivers; no real system devices are opened |
| 13 | +- Exposes at least one dummy playout and recording device to allow initialization |
| 14 | +- Supports playout and recording initialization and start/stop lifecycle |
| 15 | +- Intended primarily for headless scenarios where you want the WebRTC audio pipelines to run without touching physical devices |
| 16 | + |
| 17 | +--- |
| 18 | + |
| 19 | +## Playout path |
| 20 | + |
| 21 | +Create the module and pass it to the PeerConnectionFactory. This ensures your peer connection stack uses a headless (dummy) audio backend. |
| 22 | + |
| 23 | +```java |
| 24 | +import dev.onvoid.webrtc.PeerConnectionFactory; |
| 25 | +import dev.onvoid.webrtc.media.audio.HeadlessAudioDeviceModule; |
| 26 | + |
| 27 | +// Create the headless ADM |
| 28 | +HeadlessAudioDeviceModule audioModule = new HeadlessAudioDeviceModule(); |
| 29 | + |
| 30 | +// Initialize and start playout |
| 31 | +audioModule.initPlayout(); |
| 32 | +audioModule.startPlayout(); |
| 33 | + |
| 34 | +// Create a factory that uses the headless ADM |
| 35 | +PeerConnectionFactory factory = new PeerConnectionFactory(audioModule); |
| 36 | + |
| 37 | +// ... use the factory to build peer connections ... |
| 38 | + |
| 39 | +// Cleanup |
| 40 | +try { |
| 41 | + audioModule.stopPlayout(); |
| 42 | +} |
| 43 | +catch (Throwable e) { |
| 44 | + // Ignore errors during stopPlayout() |
| 45 | +} |
| 46 | +finally { |
| 47 | + audioModule.dispose(); |
| 48 | + factory.dispose(); |
| 49 | +} |
| 50 | +``` |
| 51 | + |
| 52 | +Notes: |
| 53 | +- Calling startPlayout without a prior initPlayout will throw an error. Always call initPlayout first. |
| 54 | +- If you only need the audio pipeline to be ready when remote audio arrives, you may delay playout initialization until after creating your RTCPeerConnection. |
| 55 | + |
| 56 | +--- |
| 57 | + |
| 58 | +## Recording path (capture) |
| 59 | + |
| 60 | +The headless module also implements a recording path that simulates a microphone. When started, it periodically pulls 10 ms of PCM from the registered AudioTransport (your Java audio source) and feeds it into WebRTC’s capture pipeline. This is particularly useful in tests or server-side senders. |
| 61 | + |
| 62 | +Typical steps: |
| 63 | + |
| 64 | +```java |
| 65 | +HeadlessAudioDeviceModule adm = new HeadlessAudioDeviceModule(); |
| 66 | + |
| 67 | +// Initialize and start the recording pipeline (capture) |
| 68 | +adm.initRecording(); |
| 69 | +adm.startRecording(); |
| 70 | + |
| 71 | +PeerConnectionFactory factory = new PeerConnectionFactory(adm); |
| 72 | + |
| 73 | +// Use a custom or built-in AudioSource to provide audio frames |
| 74 | +CustomAudioSource source = new CustomAudioSource(); |
| 75 | +AudioTrack senderTrack = factory.createAudioTrack("audio0", source); |
| 76 | +peerConnection.addTrack(senderTrack, Collections.singletonList("stream0")); |
| 77 | + |
| 78 | +// Push PCM frames into the CustomAudioSource (10 ms chunks work well) |
| 79 | +byte[] pcm = new byte[480 /* frames */ * 2 /* ch */ * 2 /* bytes */]; |
| 80 | +source.pushAudio(pcm, 16, 48000, 2, 480); |
| 81 | + |
| 82 | +// ... later, stop |
| 83 | +adm.stopRecording(); |
| 84 | +adm.dispose(); |
| 85 | +factory.dispose(); |
| 86 | +``` |
| 87 | + |
| 88 | +Details: |
| 89 | +- Initialization order matters: call `initRecording()` before `startRecording()`. |
| 90 | +- The module exposes one virtual recording device; selection calls succeed with index 0. |
| 91 | +- Stereo can be enabled/disabled via the standard ADM methods; by default 1 channel is used. |
| 92 | +- If no AudioTransport is registered (no source), silence is injected to keep timings consistent. |
| 93 | + |
| 94 | +--- |
| 95 | + |
| 96 | +## When to use HeadlessAudioDeviceModule vs. dummy audio layer on AudioDeviceModule |
| 97 | + |
| 98 | +- Prefer `HeadlessAudioDeviceModule` when you need to receive remote audio frames in a headless environment and consume them via `AudioTrack.addSink(AudioSink)`, or when you need to send audio from a custom source without touching physical devices. The headless module drives both playout and recording pipelines while no real system audio device is opened. |
| 99 | +- Using a standard `AudioDeviceModule` with `AudioLayer.kDummyAudio` disables actual audio I/O; the audio pipeline is not started for playout and sinks will typically not receive audio frame callbacks. Use this only when you intentionally do not want any audio delivery (e.g., video‑only or fully custom audio). |
| 100 | + |
| 101 | +Related guides: |
| 102 | +- [Audio Device Selection](audio_devices.md) |
| 103 | +- [Custom Audio Source](custom_audio_source.md) |
| 104 | + |
| 105 | +--- |
| 106 | + |
| 107 | +## Limitations and notes |
| 108 | +- No real audio is played or captured; playout frames are pulled from the render pipeline and discarded, and capture frames are pulled from your source (or zeroed) and delivered into WebRTC. |
| 109 | +- Always follow the lifecycles: `initPlayout()` before `startPlayout()`, and `initRecording()` before `startRecording()`. Stop before dispose. |
| 110 | +- The library handles native loading internally; instantiate and use the module as shown above. |
0 commit comments