Switchboard Objects

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.

In the Switchboard 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	Used to create the object and may sometimes be immutable after creation.
Properties	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.

Hierarchy and Lifecycle of Objects

The SDK Instance serves as the top-level object, managing both Engine objects and Extension objects. When the SDK is deinitialized, the SDK instance automatically destroys all engines and unloads all extensions, ensuring proper resource cleanup.

Each Engine object manages one or more Graph objects. Destroying an engine will also destroy all graphs it owns.

A Graph object, in turn, manages its own set of Node objects. When a graph is destroyed, all nodes within that graph are also destroyed.

This hierarchical ownership model ensures that resources are managed efficiently and that objects are cleaned up in the correct order.

Using the SDK Instance

To begin working with the SDK, you must first initialize the SDK Instance. This is typically done by calling the initialize method.

For more details about the SDK Instance object, see the SDK Instance documentation.

Creating and Destroying Engines

Switchboard engines are created and destroyed using dedicated API methods, allowing you to manage audio processing engines dynamically.

C++

// Creating an engine
auto createResult = Switchboard::createEngine(engineConfig);

// Destroying an engine
auto destroyResult = Switchboard::destroyEngine(objectID);

For more information about engines, refer to the Engines documentation.

Getting and Setting Properties

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

C++

// Getting the value of a property
auto volume = Switchboard::getValue("gainNode", "gain");

// Setting the value of a property
auto setResult = Switchboard::setValue("gainNode", "gain", 0.8);

Properties 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 = Switchboard::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
Switchboard::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
Switchboard::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.