Disclaimer : this project moved to the protocol0 monorepo

Protocol0 script backend and audio libraries

This monolithic repo is the backend of my (Ableton control surface script)

I created it because the python environment in the control surface script executes in ableton and is limited in several ways (cannot use threading, asyncio, python3, a bunch of system libraries etc ...)

This repo has none of these limitations and exposes an API to the protocol0 script while also being able to do the opposite : calling the script by dispatching script RPC commands.

I used python 3.7
I'm on windows 10 (So a some library code is relative to windows (in particular windows and keyboard management))

legend:

script: the ableton control surface script

backend : this repo

I didn't work on a real architecture for the backend so it's not as clean as the one for the script.

It is composed of the following packages:

./api

The user facing APIs for the backend

./api/midi_server

A MIDI server exposing the backend API for consumption by the the control surface script (the script communicates only via MIDI)

Also includes client code for

accessing the backend API from the script (python2)
accessing the backend API from python3 (needed to access the Backend from outside the MIDI server, see http_server below)
- NB : due to windows limitations on MIDI ports (only one connection possible), "talking" to the script is only possible from the midi server
- That means that sending a command to the script from outside the server, we first need to call the server that will forward the command to the script.
Calling the script from the backend (server push)

NB : the backend API is not exposed in the same way as the script API (this should be fixed)

The backend clients are generated using open API tools. They generate a python client that has a method per exposed backend Route method. It's nice to do code generation but replacing the Route class by Command objects would be simpler
The script client uses RPC and dispatches script Command objects over MIDI. It's simpler (even though it creates a hard dependency on the script. but it's ok they are both on the same machine)

./api/http_server

I've also setup a minimal http server using FastAPI. This server is there as a gateway to the midi server, for clients that cannot use MIDI It serves two clients :

ahk hotkeys : that's because hitting an API is considerably faster than executing scripts with python.
my stream deck. The server pushes song state changes to the stream deck via a websocket endpoint

It's run independently from the midi server.

./gui

Code used to create notifications and dialog boxes that are displayed on top of ableton interface.

I'm using PySimpleGui based on Tkinter
Instead of managing threads (Tkinter is picky about thread management) I chose a simpler setup by displaying each window in a celery worker process.
Now I need to launch celery on startup but at least there is no threading problems and it's easier to stop workers by using celery features than threads.

./lib

This is the 'monolithic' common backend library used by most backend components.

./scripts

Mainly used from the windows system (logon / logoff) or as a way to start the components.

Spawning processes is slow so I'm usually using the http server when I want to hit the backend.

In this package, we have the following sub packages :

ahk

I've setup a few Auto Hotkey (AHK) hotkeys. Mostly they are a way to call the backend. Even though some will simply execute a python script (e.g. display the log window)

Doing hotkey detection in python didn't work as well, that's why I kept this (windows) dependency.

In the 'standard' way of executing backend code via ahk, we usually follow these steps :

hotkey pressed
ahk dispatches a GET request to the gateway http server
the gateway route calls the backend (over MIDI)
the backend code executes, potentially forwarding the command to the script
In this last case the ahk will in the end trigger a script command (like 'ToggleSceneLoopCommand') (a bit complex but fast)

powershell

Startup command for my terminal

cli.py

A few cli commands that I run from the terminal / windows task scheduler

tail_protocol0_logs.py

A script tailing the ableton log file and applying filtering / formatting / colouring to show only the script information.

./sr

Sidekick project : control ableton via vocal commands.

Sounds crazy but it actually works quite well !
I stopped using it because well .. it was also a bit stupid ^^. I thought it would liberate me from some button clicking but having to talk to the software is a bit boring in the end + it really works only with headphones etc ..
I set this up using kaldi offline recognition (fastest solution)
It works by generating before hand a kaldi dictionary
On identifying a dictionary word it sends it to the script that matches it to a specific action (like arm, solo ..)
Been working with rxpy with some success on this. It's great to process a stream of sound / words and filter / process it.
It's not connected to the script anymore but could be put back quite easily

Installation

This script is more here to showcase development techniques and is not ready for distribution / installation but you can try.

Install python 3.7 on windows
py -m venv venv
activate virtual env
pip install -r 'requirements.txt'
On windows check python-rtmidi is installed else install MSVC 14 or above
Add to your PYTHON_PATH (you can create a .pth file in venv sites-packages) : your remote scripts folder and this folder
Some commands / libraries are specific to windows, adapt to mac if necessary
Create the abletonVersion env var and set it the full version number (e.g. 10.1.43)

Install other dependencies

Open Api generator to generate the sdk for the backend api
make
AHK if you're on windows

Generate the backend api client

install java
make sdk

Setup the midi ports

Create LoopMidi virtual ports (P0_IN and P0_OUT)
configure ableton midi as so :

Makefile

most commands I run from the terminal are gathered here (starting processes, sdk generation, tests and lint)

Start the backend server

make celery
make midi_server
make http_server

I'm using watchmedo to watch file changes for the midi server and celery. The http server is watched by fastAPI itself.

Development

make check

lebrunthibault/Protocol0-Backend