Previous: , Up: Getting Started   [Contents][Index]

2.2 Tutorial

The best way to introduce Librekontrol is to dive right in with an example.

Here we will be configuring the Audio Kontrol 1 (AK1) USB sound card from Native Instruments. This device has several knobs and buttons on its face that directly control the internal electronics. The top of the device also has three buttons and a large knob, which send input events to the computer.

By default, these controls aren’t very useful. The three buttons (let’s call them “left”, “middle”, and “right”) send the a, b, and c keyboard events, respectively. That is, if you have a text editor open and you press the left button, the letter ‘a’ would be typed. Similarly, turning the knob results in the mouse cursor moving left and right2.

Furthermore, each of these four controls has an associated LED under them that should light up when the control is used, however this does not happen on its own.

Let’s say that we want to use the AK1 to control the audio software Ardour. We want the left and right buttons to move the current playing position to the start and the end of the song, respectively. We want the middle button to toggle the current playing state (play/pause). Finally, we want the big knob to scroll the editor window left and right.

Ardour allows all of these functions to be mapped to whatever key you want, so theoretically we could just map the above functions to the a, b and c keys and be done with it. However, a) not all programs offer this flexibility, b) sometimes changing keybindings in large programs creates conflicts that you don’t anticipate (this is a simple example, so it’s not a big problem here), and b) controls on some devices send input events that are beyond the normal range of a standard keyboard and might not be recognized by the software. Not to mention, the LEDs will just remain lifeless.

So, we’ll stick with the default keybindings in Ardour for the buttons: the HOME/END keys to move the current playing position to the start/end of the song and SPC to play/pause. Scrolling the editor is not initially bound to any keys, so we’ll bind them (in Ardour) to Shift-{ and Shift-}.

With all that in mind, here is our AK1 configuration in Librekontrol:

(use-modules (librekontrol core)
             (librekontrol device)
             (librekontrol input)
             (librekontrol alsa)
             ((librekontrol devices ni-ak1) #:prefix ak1:))

 #:alsa-name ak1:alsa-name
 #:input-name ak1:input-name
 #:remap-events (list (make-input-event ev-key key-home)
                      (make-input-event ev-key key-end)
                      (make-input-event ev-key key-space)
                      (make-input-event ev-key key-leftbrace)
                      (make-input-event ev-key key-rightbrace)
                      (make-input-event ev-key key-leftshift))
 #:controls (list (list ak1:left remap-button
                        #:event-code key-home)
                  (list ak1:middle (make-remap-button-toggle)
                        #:event-code key-space)
                  (list ak1:right remap-button
                        #:event-code key-end)
                  (list ak1:knob (make-abs-knob-to-button)
                        #:neg-event-code key-leftbrace
                        #:pos-event-code key-rightbrace
                        #:neg-mod-keys (list key-leftshift)
                        #:pos-mod-keys (list key-leftshift)
                        #:knob-max (ak1:knob-max)
                        #:invert #t))
 #:init (list (lambda ()
                 (map control-alsa-ctl
                      (list ak1:left ak1:middle ak1:right ak1:knob)))))
 #:exit-hooks (list (lambda ()
                       (map control-alsa-ctl
                            (list ak1:left ak1:middle ak1:right ak1:knob))))))

This is an example of Librekontrol’s high-level configuration. The eventual goal is to make configuring a device to do common tasks possible without having to think (much) about the fact that you’re actually configuring it within a programming language. We’re not quite there yet, but this is much simpler than using the underlying, low-level programming interface.

You would stick that code in your Librekontrol initialization script, which is usually located at $HOME/.config/librekontrol/init.scm, and then you would run the librekontrol command to start using the device. See Invoking Librekontrol.

We’ll take a look at this example in chunks in the following sections:



Actually, some system configurations suppress these events, so you might not see these results yourself

Previous: , Up: Getting Started   [Contents][Index]