Engines

To run your audio graph, you need to place it inside an audio engine. The engine is responsible for managing audio I/O, scheduling, and processing, and determines how and where your audio graph runs.

Switchboard SDK provides several types of engines, each suited for different use cases:

Engine Type	Description
Realtime	Runs your audio graph in real time, connecting to the system's audio input/output (e.g., mic, speakers). Ideal for interactive apps, live audio, and music production.
Offline	Processes audio graphs using audio files as input and output. Useful for rendering, exporting, or batch processing audio.
Manual	Gives you full control to process audio buffers step-by-step, ideal for custom workflows, testing, or integration with other engines.
WebSocket	Processes audio buffers received over a network connection, enabling remote audio processing and streaming scenarios.

You can find the full list of available engines and their documentation on the List of Objects page.

---

Choosing the Right Engine

• Realtime Engine:
  Use this when you want to process live audio from the microphone, play audio to speakers, or build interactive audio apps. The engine handles low-latency, real-time audio I/O for you.

• Offline Engine:
  Use this for non-realtime tasks like rendering audio files, exporting mixes, or running batch audio processing jobs. The engine processes audio as fast as possible, independent of real-time constraints.

• Manual Engine:
  Use this if you want to process audio buffers manually, for example, when integrating with another audio engine or for advanced testing and debugging.

• WebSocket Engine: Use this to process audio data sent and received over a network, such as in collaborative or distributed audio applications.

---

Creating Engines from JSON

Switchboard engines can be created from JSON configuration, allowing you to define your entire audio processing pipeline declaratively. This makes it easy to design audio graphs in the Switchboard Editor and load them directly into your application.

JSON Structure

The engine JSON configuration contains:

• Engine type - Specifies which engine to use (e.g., RealTimeGraphRenderer, OfflineGraphRenderer)
• Engine config - Engine-specific settings (e.g., microphone enabled, audio I/O settings)
• Graph definition - The audio graph containing nodes and their connections

Example JSON Configuration

Here's a complete example of a real-time engine with a voice processing pipeline:

{
  "type": "RealTimeGraphRenderer",
  "config": {
    "microphoneEnabled": true,
    "graph": {
      "config": {
        "sampleRate": 16000,
        "bufferSize": 512
      },
      "nodes": [
        {
          "id": "multiChannelToMonoNode",
          "type": "MultiChannelToMono"
        },
        {
          "id": "reverbNode",
          "type": "Superpowered.Reverb",
          "config": {
            "mix": 0.5,
            "roomSize": 0.7
          }
        }
      ],
      "connections": [
        {
          "sourceNode": "inputNode",
          "destinationNode": "multiChannelToMonoNode"
        },
        {
          "sourceNode": "multiChannelToMonoNode",
          "destinationNode": "reverbNode"
        },
        {
          "sourceNode": "reverbNode",
          "destinationNode": "outputNode"
        }
      ]
    }
  }
}

Graph Components

The graph object contains:

• config - Graph-level settings like sample rate and buffer size
• nodes - Array of audio nodes, each with:
  • id - Unique identifier for the node
  • type - Node type (e.g., MultiChannelToMono, Superpowered.Reverb)
  • config - (Optional) Node-specific configuration parameters
• connections - Array of connections defining the audio routing:
  • sourceNode - ID of the source node (or action like vadNode.end)
  • destinationNode - ID of the destination node (or action like sttNode.transcribe)

Loading the Engine from JSON

Swift (iOS/macOS)

import SwitchboardSDK

func createEngine() {
    // Read JSON file from bundle
    guard let filePath = Bundle.main.path(forResource: "AudioGraph", ofType: "json"),
          let jsonString = try? String(contentsOfFile: filePath, encoding: .utf8)
    else {
        print("Error reading JSON file")
        return
    }

    // Parse JSON string to dictionary
    guard let jsonData = jsonString.data(using: .utf8),
          let config = try? JSONSerialization.jsonObject(with: jsonData) as? [String: Any]
    else {
        print("Error parsing JSON")
        return
    }

    // Create engine from configuration
    let createEngineResult = Switchboard.createEngine(withConfig: config)

    if let engineID = createEngineResult.value as? String {
        print("Engine created: \(engineID)")

        // Start the engine
        let _ = Switchboard.callAction(engineID, actionName: "start", params: [:])
    }
}

Kotlin (Android)

import com.synervoz.switchboard.sdk.Switchboard
import org.json.JSONObject

fun createEngine(context: Context) {
    // Read JSON from assets
    val jsonString = context.assets.open("AudioGraph.json")
        .bufferedReader()
        .use { it.readText() }

    // Parse JSON
    val jsonObject = JSONObject(jsonString)

    // Create engine from configuration
    val engineResult = Switchboard.createEngine(jsonObject)

    if (engineResult.isSuccess) {
        val engineID = engineResult.value as String
        println("Engine created: $engineID")

        // Start the engine
        Switchboard.callAction(engineID, "start", JSONObject())
    }
}

C++

#include <switchboard/Switchboard.hpp>
#include <switchboard/SBAny.hpp>
#include <fstream>
#include <nlohmann/json.hpp>

void createEngine() {
    // Read JSON file
    std::ifstream file("AudioGraph.json");
    nlohmann::json json;
    file >> json;

    // Convert JSON to SBAnyMap
    switchboard::SBAnyMap config = convertJSONToSBAnyMap(json);

    // Create engine from configuration
    auto result = switchboard::Switchboard::createEngine(config);

    if (result.isSuccess()) {
        std::string engineURI = switchboard::SBAny::convert<std::string>(result.value());
        std::cout << "Engine created: " << engineURI << std::endl;

        // Start the engine
        switchboard::Switchboard::callAction(engineURI, "start", {});
    }
}

Benefits of JSON Configuration

• Visual Design - Create and test your audio graph in the Switchboard Editor
• Declarative - Define your entire audio pipeline in a readable format
• Portable - Share the same JSON configuration across iOS, Android, Web, and Desktop
• Version Control - Track changes to your audio pipeline in version control
• Dynamic Loading - Load different audio graphs at runtime without code changes
• Debugging - Easily inspect and modify the audio graph structure

---