Realtime Engine
The real-time engine uses the system IO and can access the microphone and render to the device speaker.
- Android
- iOS
- Desktop
Configuration
graph
Type: Graph Config
The audio graph the engine runs.
microphoneEnabled
Type: Boolean. Default: false.
Whether the engine opens an input stream.
inputPreset
Type: String. Default: "GENERIC".
Android equivalent: AAudioStreamBuilder_setInputPreset().
What kind of capture this is, which decides the microphone used and the preprocessing applied.
Takes a MediaRecorder.AudioSource
constant name. VOICE_COMMUNICATION is the one that asks for
echo cancellation.
outputUsage
Type: String. Default: "USAGE_MEDIA".
Android equivalent: AAudioStreamBuilder_setUsage().
Why you are playing audio, which drives the volume stream and routing. Takes an
AudioAttributes USAGE_*
constant name.
performanceMode
Type: String. Default: "AAUDIO_PERFORMANCE_MODE_NONE".
Android equivalent: AAudioStreamBuilder_setPerformanceMode().
Trades latency against buffer size and battery. Takes an
aaudio_performance_mode_t constant name.
audioManagerMode
Type: String. Default: unset — the audio mode is not touched.
Android equivalent: AudioManager.setMode().
Set when the engine starts. Takes an AudioManager MODE_* constant name;
MODE_IN_COMMUNICATION is what arms the hardware echo canceller on most devices.
Needs MODIFY_AUDIO_SETTINGS
and an application context — see Requirements. Without them the key is
ignored and a warning is logged.
speakerphoneOn
Type: Boolean. Default: unset — the route is not touched.
Android equivalent: AudioManager.setCommunicationDevice()
on API 31 and above, setSpeakerphoneOn() below it.
Routes to the loudspeaker rather than the earpiece. Applied after audioManagerMode and before the
streams open, the only point the platform accepts it.
Needs MODIFY_AUDIO_SETTINGS
and an application context — see Requirements. Without them the key is
ignored and a warning is logged.
graph
Type: Graph Config
The audio graph the engine runs.
microphoneEnabled
Type: Boolean. Default: false.
Whether the engine opens an input stream.
voiceProcessingEnabled
Type: Boolean. Default: false.
Enables Apple's voice processing IO, which applies acoustic echo cancellation and automatic gain control to the microphone input. This is the device canceller, handled by the platform rather than by a node in your graph — for the software alternative, see the AEC node.
{
"type": "Switchboard.Realtime",
"config": {
"microphoneEnabled": true,
"voiceProcessingEnabled": true,
"graph": { }
}
}
Voice processing changes the output path, so it comes with constraints:
- Only mono audio output is supported.
- Various filters are applied to the output signal.
- The user cannot set the volume to zero.
allowBluetoothA2DP
Type: Boolean. Default: false.
Whether Bluetooth A2DP may be used when the microphone is enabled.
iOS supports two Bluetooth profiles: A2DP is one-directional with up to two channels of high-quality audio, while HFP carries both microphone and output but is mono and typically below 24 kHz. With the microphone enabled the default is HFP; setting this flag selects A2DP instead, in which case the device's built-in microphone is used and the headset's microphone cannot be read.
When the microphone is not enabled, A2DP is used automatically and this flag is not needed.
Properties
Inherits properties from its parent, Engine.
Every configuration key the platform accepts is also readable.
Configuration keys are readable as well. The enum keys return their constant name as a string, not the integer the platform uses internally.
graph
Type: Graph Config
The configuration of the graph that is set in the engine.
isRunning (Read only)
Type: Boolean
Whether the engine is currently running.
inputLatency / outputLatency (Read only)
Type: Double
Current input and output latency in milliseconds. -1 when the device does not report stream
timestamps, which is what the engine's latency detection is built on.
graph
Type: Graph Config
The configuration of the graph that is set in the engine.
isRunning (Read only)
Type: Boolean
Whether the engine is currently running.
graph
Type: Graph Config
The configuration of the graph that is set in the engine.
isRunning (Read only)
Type: Boolean
Whether the engine is currently running.
inputDevices / outputDevices (Read only)
Type: Object Array
The capture and render devices the system reports. Each entry carries id, name,
inputChannels, outputChannels, isDefaultInput, isDefaultOutput, sampleRates,
currentSampleRate and preferredSampleRate. Entries in outputDevices also carry
isUsedAsPrimaryOutput and isUsedAsSecondaryOutput.
secondaryOutputs (Read only)
Type: Object Array
The devices currently added as secondary outputs, in the same shape as outputDevices.
Actions
Inherits actions from its parent, Engine.
start
Starts the audio engine.
Parameters
None.
Return Value
None.
stop
Stops the audio engine.
Parameters
None.
Return Value
None.
addSecondaryOutput
Adds a secondary output, so the engine renders to more than one device at once.
Parameters
| Name | Type | Description |
|---|---|---|
device | Object | The device to add, matched on its id. |
numberOfChannels | Int | How many channels to use on that device. |
Return Value
The ID of the secondary output that was added.
removeSecondaryOutput
Removes one secondary output.
Parameters
| Name | Type | Description |
|---|---|---|
id | Int | The ID of the secondary output to remove. |
Return Value
None.
clearSecondaryOutputs
Removes every secondary output.
Parameters
None.
Return Value
None.
Events
Inherits events from its parent, Engine.