Skip to content

Using the engine Control API

The engine exposes a public Control API that lets your app configure pipelines, manage routing, and subscribe to events. There are a few ways to talk to it.

  • gRPC — the primary API. Works from any language.
  • REST — an HTTP/JSON alternative, currently in development.
  • Client libraries — convenient wrappers around gRPC, available for several languages.

Pick whichever fits your stack.

gRPC

gRPC is an industry-standard remote procedure call (RPC) framework built on top of HTTP/2 and Protocol Buffers. The engine provides a .proto file with the full API specification. Your app generates a client from it and calls remote methods as if they were local functions.

We chose gRPC for a few reasons:

  • Interoperability — Works with any language: C++, Python, Go, C#, Java, Node.js, Rust, and more. Everyone talks to the same schema.
  • Efficiency — Binary encoding over HTTP/2 keeps overhead and latency low. That matters for responsive, real-time control.
  • Compatibility — The schema is versioned. API can evolve without breaking existing clients, so old and new versions keep working together.
  • Strong typing — Requests and responses are typed and validated. You catch mistakes at compile time, not at runtime.

Generating a client

To use the gRPC service, you generate a client from the spec for your language.

The general process is the same in every language:

  1. Get the engine's .proto file (part of the SDK).
  2. Run the Protocol Buffers compiler (protoc) with the gRPC plugin for your language.
  3. It produces client code — types for every message and a stub with a method per RPC.
  4. Import the generated code, connect to the engine, and call methods like any other class.

Most ecosystems have their own tooling around this (build plugins, package managers), so the exact commands vary. The gRPC documentation covers setup for each supported language, and the Protocol Buffers guide explains the schema format.

Tip

Prefer a ready-made client for your language? See Client libraries below — they save you the generation step.

For the full list of services, methods, and messages, see the Control RPC reference.

REST

In development

The REST API is currently under development. Feel free to contact us if you're interested.

REST will be an alternative to gRPC, exposing the same functionality over plain HTTP/JSON.

It's meant to simplify usage from environments where gRPC is awkward — for example, Node.js or the browser — and to let you integrate without a code generation step.

Client libraries

For some languages we ship client libraries that wrap the generated gRPC client and expose the Control API as an idiomatic interface.

They're not strictly necessary — you can always use the raw gRPC client directly. But they're convenient and can smooth over some rough edges.

A client library typically gives you:

  • Engine discovery — Locate installed engines and connect to the default one.
  • Connection handling — Set up the channel, manage sessions, and reconnect.
  • Idiomatic methods — Each RPC as a natural method with nice DTOs instead of raw protobuf messages.
  • Idiomatic errors — Failures mapped to first-class errors you can inspect and categorize.

Available libraries:

Language Source Documentation
.NET ViveSound.Sdk.Ctl .NET client library
Go vsctl Go client library