A simple wrapper for controlling sushi over gRPC via a python script.
If you are running your Python program on a device running Elk Audio OS, the latest elkpy should already be installed.
But, if you use elkpy on another system, e.g. macOS, you can either copy the module folder to the directory where it will be used, or install it locally with pip3 install -e elkpy or similar.
elkpy is also available on Pypi: pip install elkpy.
First import the sushicontroller package, e.g.:
from elkpy import sushicontroller as scThen create an instance of the SushiController object:
controller = sc.SushiController()The default gRPC address is localhost:51051.
To connect to another address, pass it as an argument to the constructor of the controller with the format ip-address:port.
To use the controller simply use the methods of the controller objects different sections. For example:
# To make sure all the sub-controllers of SushiController close properly, you can wrap them in a try except block:
try:
# Get a list of the tracks available in sushi
list_of_tracks = controller.audio_graph.get_tracks()
# Get the parameters of the track with the id passed to the method
track_id = 0
list_of_processors = controller.parameters.get_track_parameters(track_id)
# Send a note on message to a track in sushi
track_id = 0
channel = 0
note = 65
velocity = 0.8
controller.keyboard.send_note_on(track_id, channel, note, velocity)
# To ensure proper closing of SushiController, close() should be called on your instance when you're done using it
except KeyboardInterrupt:
controller.close()For full documentation on all available methods, use:
pydoc3 elkpy.sushicontroller.SushiControllerOn the terminal where the elkpy folder is located.
In Sushi, get requests are processed synchronously, while set requests are scheduled asynchronously. The former will return the requested data, but the latter can only return a confirmation that the command has been registered.
This can lead to situations where a user could for instance try to set a parameter on a processor that has not yet been created by Sushi, even though the call to create_processor_on_track had been made.
To alleviate this burden for simple use-cases, elkpy adopts the following behavior:
Commands that edit the audio graph:
- create_track
- delete_track
- create_processor_on_track
- create_processor_on_track
- ...
return a SushiCommandResponse: an asyncio.Event that will be set by elkpy whenever the corresponding notification is emitted by Sushi.
An asyncio user can elect to await SushiCommandResponse.wait() to ensure that the command has been properly carried out before carrying on with further rpcs.
Ignoring the event is also a valid option for cases where absolute confirmation is not critical.
If an error has occurred in grpc, wait() will raise a SushiUnknownError.
elkpy uses an asyncio.EventLoop to run its notification monitoring. In asyncio programs, it will simply get the current running loop. And if that fails (for instance if you are writing a synchronous program), it will starts a new loop in a separate thread.
You MUST therefore be careful when you instantiate the main SushiController class when writing asyncio applications. Make sure that a loop is already running, for instance by instantiating a SushiController inside your async def main().
If you fail to do that, you will end up with 2 running loops: one in the main thread and one in an elkpy thread. And that will break the SushiCommandResponse system, because asyncio.Events are not thread-safe!
Synchronous programs may also leverage SushiCommandResponse but in a different way. The object waiting on such events can not wait() for them but MUST check their event.is_set() method instead. This
will return True once elkpy has set the event.
For more information about asyncio.Event: [https://docs.python.org/3/library/asyncio-sync.html]
Elkpy also ships an AsyncSushiController for asyncio applications to allow for asyncio-specific techniques, like asyncio.gather() a bunch of grpc calls.
The examples subdirectory contains examples of how elkpy can be used.
This demonstrates instantiating 3 processors onto Sushi started with an “empty” config, subscribing to notifications to wait for their instantiation, and then setting their parameters once they're available.
To run:
- Ensure you have a Python environment set up where the packages described in requirements.txt are available, globally or in a
venv. - Start Sushi with the provided "sushi_control_example_config.json", and the '--base-plugin-path' set to point to where
mda-vst.vst3plugins are available:
$ ./sushi --portaudio \
--config-file /path/to/elkpy/examples/sushi_control_example_config.json \
--base-plugin-path=/path/to/sushi/build/debug/VST3/Debug/
If you've built Sushi from source, the plugins are built and accessible in the above path relative to the sushi binary.
- Start
sushi_control_example.py:
python3 ./sushi_control_example.py --protofile "/path/to/sushi/rpc_interface/protos/sushi_rpc.proto"
The --protofile argument points elkpy to the protocol buffer file used by Sushi.
You should hear Sushi play a familiar theme tune.
An example passive monitor app using elkpy. It connects to a sushi instance, subscribes to notifications and displays all the parameter, transport and audio graph changes that Sushi broadcasts.
Ensure there is a Sushi instance running on the same computer.
Then run:
export SUSHI_GRPC_ELKPY_PROTO=./sushi_rpc.proto
python3 examples/sushi_monitor.py
Before running unit tests with the unittest command-line interface, you need to export the environment variable SUSHI_GRPC_ELKPY_PROTO, pointing to the Sushi's .proto definition file.
Example:
export SUSHI_GRPC_ELKPY_PROTO=./sushi_rpc.proto
python3 -m unittest discover -s tests -p '*_test.py'