JSON IPC Mechanism

IPC Mechanism for Front-end / Back-end Communication

Anklang employs a WebSocket-based Inter-Process Communication (IPC) mechanism to facilitate interaction between its web browser based front-end and the multi-threaded real-time back-end implemented in C++20 within the AnklangSynthEngine process. This section provides an overview of Anklang's IPC mechanism:

Front-end / back-end Communication: The primary communication channel between the web browser based front-end and the multi-threaded back-end is established through a WebSocket connection. The front-end sends method calls marshalled as JSON messages to the back-end, which are handled by the main thread in the AnklangSynthEngine process by calling into C++ methods of the exposed interface classes. The back-end responds with call results marshalled into JSON that are sent back as responses through the web socket.

API Introspection: The internal API of AnklangSynthEngine is provided in ase/api.hh as a set of abstract C++ classes. These classes are parsed by castxml, a Clang-based C++ parser that generates XML descriptions of the class interfaces. This XML is then processed by the Python script jsonipc/cxxjip.py to generate some C++ code that instantiates JsonIPC classes, which describe the API's abstract classes and their exposed methods through a generic introspection interface that supports call marshalling to and from JSON strings.

JsonIPC Classes: The generated JsonIPC template class instantiations provide introspection information about the C++ classes from ase/api.hh, including their inheritance relationships, methods, and the method parameters. These classes enable the conversion (or demarshalling + invocation + marshalling) of JSON messages to and from C++ API calls and results.

Websocket Connection: The browser front-end establishes a WebSocket connection to the AnklangSynthEngine process. This connection is used to send JSON method calls from the front-end to the back-end, as well as receive method call results as JSON messages from the back-end.

Javascript ASE Bindings: Based on the JsonIPC classes, code for a thin layer of Javascript proxy classes is generated via AnklangSynthEngine --js-api. These Javascript proxy classes are used in the browser to marshal remote method calls into the web socket connection to a running AnklangSynthEngine process.

Asynchronous Communication: To allow remote calls into another process from the JavaScript main loop of a running browser session, all remote calls are sent through the web socket and the JavaScript methods implementing the calls return a JavaScript Promise. The invocation results can be obtained via await Promise or more idiomatically result = await remote_object.remote_method().

Callback Registration: The browser front-end can register callback functions with the front-end JavaScript proxy classes, which allows the back-end to emit notifications from C++ into JavaScript. These are implemented by sending callback related JSON messages to the front-end. This enables the execution of specific JavaScript code in response to events or changes in the audio synthesis process.