Logo Velours DevicesVelours Devices, homeOrder

Documentation

Extensions

Ready-made pages for gear and software that need more than plain MIDI, and your own code on KARL's screen. Turn one on and its pages appear by themselves.

What an extension does

With plain MIDI you build pages yourself in the configurator. An extension goes further for one product: it knows its parameters, lays them out on pages, and follows the product both ways, so turning a knob on the device moves the knob on KARL. Some talk MIDI, others OSC through the configurator.

Ableton Live works the same way. Its pages are covered in Ableton Live.

Turning one on

In the configurator's JSON tab, add the extension's name to the plugins list, for example "plugins": ["ableton", "totalmix"], then send the project. Its pages appear on KARL with keys to move between them.

Two examples

These are the first extensions. More are on the way.

RME TotalMix FX

Gain, phantom power, volume, mute and solo for the channels of an RME audio interface, with level meters. It talks to TotalMix FX over OSC: in TotalMix, under Options, Settings, OSC, turn on a remote with incoming port 7001, outgoing port 9001, host 127.0.0.1, and Send Level Data for the meters. Extension name: totalmix.

Korg microKORG XL and XL+

Every parameter of the synth, both ways, over KARL's MIDI jacks. Connect MIDI out 1 to the synth's MIDI IN and its MIDI OUT to KARL's MIDI in, and turn on MIDI FLT for system exclusive, control change and program change in its global settings. KARL finds the synth and its channel. Extension name: mkxl.

Write your own

An extension can also be your own code. It is a C++ library that KARL loads when it starts, drawing with OpenGL/OpenSceneGraph like the rest of KARL's screen. It can:

  • draw anything on the whole page, or on a part of it next to ordinary controls
  • take any knob and key, give a key its label and colour, and read every knob's exact angle
  • send MIDI and OSC, and receive MIDI
  • follow a MIDI clock, from another device or from KARL's own Clock control, or Live's transport
  • keep its own files, which survive restarts and updates

The SDK is on GitHub at velours-io/karl-sdk: one header, karl/sdk.h, that is the whole interface, and two examples, a game that takes the whole page and a 16 step sequencer on four knobs and two keys. It is short enough for an AI coding assistant to read in full, and it comes with notes for one. The SDK may only be used to make software for KARL; the extensions you write are yours.

Build

Extensions build in a Docker image that holds the same compiler and libraries as KARL, on macOS, Windows or Linux. In your extension's folder:

docker run --rm -v "$PWD":/src ghcr.io/velours-io/karl-sdk:abi1

The extension comes out as a .so file in dist.

Try it without a KARL

The same image runs KARL's app with your extension, in a browser tab at localhost:6080:

docker run --rm -it --name karl-sim -p 6080:6080 -v "$PWD":/src ghcr.io/velours-io/karl-sdk:abi1 karl-sim

Click the keys and turn the knobs with the mouse. The copper lines that cross KARL's display show in red, and the knobs as outlined discs, so you can see what the panel hides. Build again and the simulator reloads. A script or a coding assistant can press keys, turn knobs and take screenshots with karl-ctl, described in the SDK's README. It has no MIDI ports, Live or configurator, so try the extension on a KARL before you share it.

Install

KARL connected, open the configurator's Extensions, go to On this KARL and choose Install extension. KARL checks the file before it takes it, then Restart KARL loads it. The same place lists what is installed, says why a extension was refused, and removes extensions.

Then add its control to a page with Add extension, like the built-in extensions. An extension that takes part of a page asks where: click the knob where it should start, and the configurator gives it the keys next to it. Its options show in the inspector. Adding it turns the extension on for your project.

An extension runs inside KARL with the same rights, so install only code you trust. If KARL stops within seconds of starting with extensions on, the next start leaves them out and the configurator tells you, so you can remove the one at fault. After an update that changes the interface, KARL leaves out extensions built for the old one until they are rebuilt.

Asking for one

If you would like an extension for a synth, an effect or an app you use, tell us at contact@veloursdevices.com. Requests decide what we build next.