Overview

The Switchboard SDK is a powerful tool for building and managing audio processing engines. It allows developers to design complex audio workflows using simple JSON configurations, enabling rapid prototyping and deployment. Once the audio engine is set up, its state can be dynamically modified with just a few API calls, providing flexibility and control for real-time audio applications.

Switchboard Objects

In the Switchboard V3 API, everything is a Switchboard Object:

Object Type	Description
SDK Instance	The main entry point for interacting with the Switchboard SDK.
Engine	Audio processing engine that can run graphs.
Graph	Managing and connecting nodes together.
Nodes	Individual components within the graph that perform specific tasks.

Switchboard objects share a common behavior model that includes:

Feature	Description
Configuration parameters	Used to create the object and may sometimes be immutable after creation.
Values	Attributes of the object that can be either read-only or read-write.
Actions	Functions that you can invoke to perform specific operations on the object.
Events	Notifications that you can subscribe to, allowing you to react to changes or actions.

Using the SDK

Creating and Destroying Objects

To work with Switchboard Objects, you typically create and destroy them using provided API methods.

C++

// Creating an object
auto createResult = SwitchboardV3::createEngine(engineConfig);
// Destroying an object
auto destroyResult = SwitchboardV3::destroyObject(objectID);

Read-write values, which can be configured through the provided configuration parameters. These parameters allow you to define the initial state of the object and specify attributes that can be dynamically updated during runtime.

Getting and Setting Values

Switchboard Objects have attributes called Values that can be either read-only or read-write. You can retrieve or modify these values using the provided API methods.

C++

// Getting a value
auto volume = SwitchboardV3::getValue("gainNode", "gain");

// Setting a value
auto setResult = SwitchboardV3::setValue("gainNode", "gain", 0.8);

Values allow you to configure and query the state of objects dynamically, enabling flexible control over your audio processing pipeline.

Calling Actions

Switchboard Objects support Actions, which are functions you can invoke to perform specific operations. Actions allow you to trigger behaviors or processes on an object dynamically.

C++

// Calling an action
auto result = SwitchboardV3::callAction("ttsNode", "synthesize", { { "text", text } });

In the example above, the callAction method is used to invoke the synthesize action on a Text-to-Speech (TTS) node, passing the required parameters as a key-value map. This enables you to interact with objects in a flexible and extensible way.

Subscribing to Events

Switchboard Objects emit Events that you can subscribe to in order to react to changes or specific actions. Events provide a mechanism for asynchronous communication, enabling you to handle updates dynamically.

C++

// Subscribing to an event
SwitchboardV3::addEventListener("sttNode", "transcription", [](const std::any& data) {
    const auto text = std::any_cast<std::string>(data);
    std::cout << "STT node transcribed: " << text << std::endl;
});

// Unsubscribing from an event
SwitchboardV3::removeEventListener("sttNode", "transcription");

In the example above, the addEventListener method is used to subscribe to the transcription event on a Speech-to-Text (STT) node. The callback function processes the event data, allowing you to handle the transcription results. To stop receiving updates, you can use the removeEventListener method.

List of Objects

Engines

Type	Description
Real-time	Runs a graph in real-time using the system audio I/O.
Offline	Processes a graph with audio file inputs and outputs.
Manual	Manually processing audio buffers.
WebSocket	Processing audio coming on a WebSocket channel.

Graphs

There is only a single implementation of AudioGraph which you can read about here.

Nodes

Type	Description
AudioPlayer	Plays audio from a buffer or file source, functioning as a basic audio source.
BusSelect	Selects a specific audio bus from a multi-bus stream for further processing.
BusSplitter	Splits an incoming audio signal into individual bus outputs.
ChannelSplitter	Divides a multi-channel audio signal into separate single-channel outputs.
ClippingDetector	Detects when an audio signal exceeds the maximum level, potentially causing distortion.
Discard	Discards incoming audio without processing or forwarding it.
Gain	A node that adjusts the amplitude of the audio signal, effectively controlling its volume.
Mixer	Combines multiple audio inputs into a single output mix.
MonoBusMerger	Merges several mono audio buses into a single bus multi-channel output.
MonoToMultiChannel	Converts a mono signal into a multi-channel output by duplicating the input.
MultiChannelToMono	Mixes multiple channels down into a single mono signal.
MusicDucking	Lowers background music volume when another signal, like voice, is detected.
Mute	Silences the audio signal without stopping the stream.
NoiseGate	Suppresses signals below a certain threshold, reducing background noise.
Passthrough	Forwards audio without modification, useful for routing or diagnostics.
Recorder	Captures incoming audio and stores it for playback or export.
ResampedSink	Receives audio and resamples it to a different sample rate for an embedded audio node.
ResampledSource	Outputs audio that has been resampled from another sample rate of an embedded audio node.
Resampler	Changes the sample rate of the audio stream.
Silence	Generates a silent audio signal, typically used for timing or control.
SineGenerator	A node that generates a sine wave signal, often used for testing or as a basic audio source.
StereoBusMerger	Merges multiple stereo buses into a unified stereo bus output.
StereoPanner	Adjusts the left-right stereo balance of the audio signal.
SubgraphProcessor	Processes audio using a subgraph, allowing for modular and reusable signal chains.
SubgraphSink	Audio sink that embeds another audio graph.
SubgraphSource	Audio source that embeds another audio graph.
SynchronizedAudioPlayer	Plays audio in sync with a timeline or other synchronized events.
Timeline	Manages time-based events and synchronization within an audio graph.
TimelineQuantizedTrigger	Triggers actions aligned to timeline quantization points, useful for music timing.
VoiceActivityDetector	Detects the presence of voice in an audio stream for use in gating or ducking.
VUMeter	Measures audio signal levels for monitoring purposes.
WhiteNoiseGenerator	Produces a white noise signal, often used for testing or audio masking.

Extensions

The list of available nodes can be expanded by implementing a custom Switchboard SDK extension. For more details on how to create your own extension, please contact us.