Skip to main content

C++ API

The Switchboard SDK is implemented in C++, so this is the native call surface. Every other language wraps these calls.

The whole API lives on switchboard::Switchboard and is built around object URIs — the SDK singleton itself ("switchboard"), engines, nodes, and extensions are all identified by a URI string. The same handful of calls (callAction, setValue, getValue, addEventListener) drives every object.

All calls return switchboard::Result<T>. Check result.isError() before using result.value().

Initialize SDK​

Initializes the SDK with a config map. Returns the SDK instance's object URI (always "switchboard").

static Result<ObjectURI> initialize(const SBAnyMap& config);
auto result = switchboard::Switchboard::initialize({
    {"appID", "your-app-id"},
    {"appSecret", "your-app-secret"},
});
if (result.isError()) {
    std::cerr << result.error().message << std::endl;
    return 1;
}

Deinitialize SDK​

Releases all SDK-owned resources. Call before the process exits if you want a clean shutdown.

static Result<void> deinitialize();
switchboard::Switchboard::deinitialize();

Create Engine​

Creates an engine from a JSON-shaped config map describing the audio graph. Returns the engine's object ID, which you pass to the runtime calls below.

static Result<ObjectURI> createEngine(const SBAnyMap& config);
auto createResult = switchboard::Switchboard::createEngine(engineConfig);
if (createResult.isError()) { /* handle */ }
auto engineID = createResult.value();

Destroy Engine​

Destroys an engine previously returned by createEngine. Any object owned by the engine (nodes, sub-graphs) is destroyed with it.

static Result<void> destroyEngine(const ObjectURI& engineURI);
switchboard::Switchboard::destroyEngine(engineID);

Call Action​

Invokes a named action on any Switchboard object — start an engine, play a player, load a file, etc. Returns whatever the action returns (often empty).

static Result<SBAny> callAction(
    const ObjectURI& objectURI,
    const std::string& actionName,
    const SBAnyMap& params = {}
);
// Start the engine
switchboard::Switchboard::callAction(engineID, "start");

// Load a file into a player node
switchboard::Switchboard::callAction("playerNode", "load", {
    {"audioFilePath", "AudioFiles/speech-mono-48k.wav"},
});

Set Value​

Writes a value to a key on a Switchboard object. Used for runtime configuration — gain, loop flags, BPM, etc.

static Result<void> setValue(
    const ObjectURI& objectURI,
    const std::string& key,
    const SBAny& value
);
switchboard::Switchboard::setValue("playerNode", "isLoopingEnabled", true);
switchboard::Switchboard::setValue("gainNode", "gain", 0.5f);

Get Value​

Reads a value from a key on a Switchboard object.

static Result<SBAny> getValue(const ObjectURI& objectURI, const std::string& key);
auto framesResult = switchboard::Switchboard::getValue("recorderNode", "framesRecorded");
if (framesResult.isSuccess()) {
    auto frames = framesResult.value();
    // ...
}

Add Event Listener​

Subscribes to a named event on an object. Returns a numeric listener ID that you pass to removeEventListener.

static Result<unsigned int> addEventListener(
    const ObjectURI& objectURI,
    const std::string& eventName,
    const std::function<void(const Event&)>& callback
);
auto listenerResult = switchboard::Switchboard::addEventListener(
    "playerNode",
    "playbackProgress",
    [](const switchboard::Event& event) {
        // ...
    }
);
auto listenerID = listenerResult.value();

Remove Event Listener​

Unsubscribes a listener previously registered with addEventListener.

static Result<void> removeEventListener(const ObjectURI& objectURI, unsigned int listenerID);
switchboard::Switchboard::removeEventListener("playerNode", listenerID);

Full Reference​

Open C++ API Reference (Doxygen) — every class, every overload, every type.