Controlling Sushi using gRPC#

gRPC is a remote proceduce call framework that enables processes to communicate, either over the network or locally, on the same machine. It supports most common programming languages and can even be used from a web browser. As such it’s an ideal framework for controlling Sushi from a remote application, either on the same Elk device or over the network. Sushi exposes a rich API over gRPC. We also provide up-to-date examples of programs which use gRPC to communicate with Sushi.

All these examples are written in Python, and use our elkpy Python library, which greatly simplifies controlling Sushi over gRPC. The elkpy library has comprehensive comments, and is also documented here. For controlling Sushi from a C++ application we also provide a corresponding wrapper library for C++ elkcpp library

The heart of the gRPC integration, is the API definition in sushi_rpc.proto file. Which defines all endpoints and their respective types.

Since Sushi 1.3, the API is versioned. The expected version is defined in api_version.proto, and a client can compare it with the value returned by SystemController.GetSushiApiVersion to check that it matches the Sushi instance it is controlling.

One way to quickly interact directly with the gRPC API during development is to use an API tool that has support for gRPC, for example [Postman](https://www.postman.com/). You can find more on how to load Sushi’s .proto definition into Postman [here](https://learning.postman.com/docs/sending-requests/grpc/grpc-request-interface/).

Though we recommend you to start with one of our wrapper libraries: elkpy or elkcpp, depending on your choice of programming language. This way you do not need to use gRPC directly, and can just read the documentation for the respective library.

High-level Overview of Sushi’s gRPC API#

Given Sushi’s complexity, the gRPC API has been split into specific controllers, each of which controls one subsystem of Sushi.

These are:

  • AudioGraphController

  • ParameterController

  • AudioRoutingController

  • MidiController

  • CvGateController

  • KeyboardController

  • ProgramController

  • OscController

  • TransportController

  • SystemController

  • TimingController

  • SessionController

  • NotificationController

All except NotificationController, define methods the GUI can invoke to query Sushi on its state, and issue commands to modify that state.

Methods that modify Sushi’s state return a CommandResponse, with a status and a command id. Some commands are completed asynchronously by Sushi. In that case the status is ASYNC_RESPONSE, and the final result is sent later through the NotificationController, with the same id.

For the details on the methods that can be invoked from each controller, please refer to the .proto file, and elkpy library documentation. Here we’ll only present a high-level overview of what each is for, without too much detail of how it is used.

AudioGraphController#

Allows adding/moving/removeing tracks and processors (plugins) at runtime and querying the current tracks and plugins in the engine.

ParameterController#

Allows the querying of all Track and Processor (plugin) parameters and properties and setting them to new values.

AudioRoutingController#

Allows connecting audio input and output to and from tracks, and query the current connections. When a track is added, routings are not automatically created, but have to be explicitly connected in order to process and output sound to/from Sushi’s inputs and outputs.

MidiController#

MidiController allows connecting MIDI input and output to and from tracks, mapping CC messages to parameter and querying the current connections. When a track is added, MIDI connections are not automatically created, but have to be explicity added in order to process and output MIDI to/from Sushi’s inputs and outputs.

CvGateController#

Enables the connection/disconnection of Control Voltage (CV) and Gate signals to and from processor parameters. It also allows querying existing connections.

* Note that in the current release version of Sushi, while the .proto file API for creating and destroying is defined, it is not yet functional.

KeyboardController#

KeyboardController allows sending keyboard events to tracks - e.g. Note On/Off messages, pitch bend, modulation, etc.

ProgramController#

For querying, loading and storing programs (pre-sets) for processors (plugins).

OscController#

OscController allows querying the state of the Open Sound Control broadcasting from Sushi, and selectively enable/disable which parameters will broadcast their state. Also used to fetch the IP and ports which Sushi uses for OSC.

TransportController#

Enables querying and setting the state of the global Sushi transport - start/stop, time signature, tempo and tempo synchronisation methods.

SystemController#

Allows querying static information about the running Sushi instance: the Sushi version, the gRPC API version, build information (build options, audio buffer size, commit hash and date) and the number of audio input and output channels.

TimingController#

Allows the generation and querying of CPU timing information for the engine, individual tracks or processors. When Sushi runs with multicore processing, the engine timings also include the timings of each audio thread.

SessionController#

Allows for saving and restoring the full state of Sushi including tracks, loaded plugins, audio and control routing.

Sushi gRPC Notifications#

NotificationController is different in that using it the GUI can subscribe to notifications of events happening in Sushi: for example if a plugin is added/removed, a track is added/removed, the transport state is changed, or a plugin’s internal parameter has changed value.

Since Sushi 1.3, clients can also subscribe to SubscribeToAsyncCommandUpdates to receive the result of commands that are completed asynchronously.

Controlling Sushi using ZeroMQ#

Since version 1.4, Sushi exposes the same controllers and methods through ZeroMQ, over the local IPC sockets ipc:///tmp/sushi_ipc.sock (commands) and ipc:///tmp/sushi_pub.sock (notifications). The messages are the same ones defined in sushi_rpc.proto.

The ZeroMQ API is only available to applications running on the same machine as Sushi. The Sushi web UI included in Elk Audio OS 1.4.0 uses it by default. The ZeroMQ server is enabled by default, and you can disable it by starting Sushi with the –no-zmq flag.