nixo
/
midizap
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Formatting changes.

master
Albert Graef 2018-08-12 11:59:44 +02:00
parent 201e3055d8
commit abd85f4931
1 changed files with 11 additions and 11 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

22
README.md
View File

@ -7,14 +7,14 @@ This is a version of Eric Messick's [ShuttlePRO][nanosyzygy/ShuttlePRO] program
ShuttlePRO was originally written in 2013 by Eric Messick. This version of the program is based on Albert Graef's [fork][agraef/ShuttlePRO] of the program, so it has all of the translation features of the original program, but also offers Jack MIDI support and various other useful improvements, such as additional command line options and the ability to detect applications using their `WM_CLASS` property (in addition to window titles).
midizap provides you with a way to hook up just about any MIDI controller and use it to translate MIDI input to X keyboard and mouse events in order to control your favorite multimedia applications, such as audio and video editors, digital audio workstation (DAW) programs and the like. Moreover, midizap can also be used to output translated MIDI data, which is useful, e.g., if the target application supports MIDI, but can't work directly with your controller because of protocol incompatibilities. In other words, as long as the target application can be controlled with simple keyboard shortcuts and/or MIDI commands, `midizap` should be able to make it work with your controller.
midizap provides you with a way to hook up just about any MIDI controller and use it to translate MIDI input to X keyboard and mouse events in order to control your favorite multimedia applications, such as audio and video editors, digital audio workstation (DAW) programs and the like. Moreover, midizap can also be used to output translated MIDI data, which is useful, e.g., if the target application supports MIDI, but can't work directly with your controller because of protocol incompatibilities. In other words, as long as the target application can be controlled with simple keyboard shortcuts and/or MIDI commands, midizap should be able to make it work with your controller.
[nanosyzygy/ShuttlePRO]: https://github.com/nanosyzygy/ShuttlePRO
[agraef/ShuttlePRO]: https://github.com/agraef/ShuttlePRO
## Description
The `midizap` program translates Jack MIDI input into X keystrokes, mouse button presses, scroll wheel events, or, as an option, MIDI output. It does this by matching the `WM_CLASS` and `WM_NAME` properties of the window that has the keyboard focus against the regular expressions for each application section in its configuration (midizaprc) file. If a regex matches, the corresponding set of translations is used. Otherwise the program falls back to a set of translations in a default section at the end of the file, if available.
The midizap program translates Jack MIDI input into X keystrokes, mouse button presses, scroll wheel events, or, as an option, MIDI output. It does this by matching the `WM_CLASS` and `WM_NAME` properties of the window that has the keyboard focus against the regular expressions for each application section in its configuration (midizaprc) file. If a regex matches, the corresponding set of translations is used. Otherwise the program falls back to a set of translations in a default section at the end of the file, if available.
By these means incoming MIDI messages can be translated to sequences of multiple mouse actions and keystrokes, including the pressing and releasing of modifier keys. In addition, MIDI messages can be generated and output using Jack MIDI.
@ -26,7 +26,7 @@ First, make sure that you have the required dependencies installed. The program
sudo apt install build-essential libx11-dev libxtst-dev libjack-dev
Then just run `make` and `sudo make install`. This installs the example.midizaprc file as /etc/midizaprc, and the `midizap` program in the default install location. Usually this will be /usr/local/bin, but the installation prefix can be changed with the `prefix` variable in the Makefile. Also, package maintainers can use the `DESTDIR` variable as usual to install into a staging directory for packaging purposes.
Then just run `make` and `sudo make install`. This installs the example.midizaprc file as /etc/midizaprc, and the midizap program in the default install location. Usually this will be /usr/local/bin, but the installation prefix can be changed with the `prefix` variable in the Makefile. Also, package maintainers can use the `DESTDIR` variable as usual to install into a staging directory for packaging purposes.
## Configuration File
@ -34,15 +34,15 @@ After installation the system-wide default configuration file will be in /etc/mi
cp /etc/midizaprc ~/.midizaprc
The ~/.midizaprc file, if it exists, takes priority over /etc/midizaprc, so it becomes your personal `midizap` configuration. You can edit this file as you see fit, in order to customize existing or add your own application configurations for the MIDI controller that you have. (If you create any new configurations which might be useful to other users of this program, please consider submitting them so that they can be included in future releases.)
The ~/.midizaprc file, if it exists, takes priority over /etc/midizaprc, so it becomes your personal midizap configuration. You can edit this file as you see fit, in order to customize existing or add your own application configurations for the MIDI controller that you have. (If you create any new configurations which might be useful to other users of this program, please consider submitting them so that they can be included in future releases.)
**NOTE:** The program automatically reloads the midizaprc file whenever it notices that the file has been changed. Thus you can edit the file while the program keeps running, and have the changes take effect immediately without having to restart the program. When working on new translations, you may want to run the program in a terminal, and employ some or all of the debugging options explained below to see exactly how your translations are being processed.
## Basic Usage
The `midizap` program is a command line application, so you typically run it from the terminal, but of course it is also possible to invoke it from your desktop environment's startup files once you've set up everything to your liking.
The midizap program is a command line application, so you typically run it from the terminal, but of course it is also possible to invoke it from your desktop environment's startup files once you've set up everything to your liking.
`midizap` uses [Jack][] for doing all its MIDI input and output, so you need to be able to run Jack and connect the Jack MIDI inputs and outputs of the program. While it's possible to do all of that from the command line as well, we recommend using a Jack front-end and patchbay program like [QjackCtl][] to manage Jack and to set up the MIDI connections. In QJackCtl's setup, make sure that you have selected `seq` as the MIDI driver. This exposes the ALSA sequencer ports of your MIDI hardware and other non-Jack ALSA MIDI applications as Jack MIDI ports, so that they can easily be connected using QjackCtl.
midizap uses [Jack][] for doing all its MIDI input and output, so you need to be able to run Jack and connect the Jack MIDI inputs and outputs of the program. While it's possible to do all of that from the command line as well, we recommend using a Jack front-end and patchbay program like [QjackCtl][] to manage Jack and to set up the MIDI connections. In QJackCtl's setup, make sure that you have selected `seq` as the MIDI driver. This exposes the ALSA sequencer ports of your MIDI hardware and other non-Jack ALSA MIDI applications as Jack MIDI ports, so that they can easily be connected using QjackCtl.
(Here and in the following, we're assuming that you're using Jack1. Jack2 works in a very similar way, but may require some more fiddling; in particular, you may have to use [a2jmidid][] as a separate ALSA-Jack MIDI bridge in order to have the ALSA MIDI devices show properly as Jack MIDI devices.)
@ -96,7 +96,7 @@ More information about the available configurations and on how to actually creat
## MIDI Output
As already mentioned, the `midizap` program can also be used to translate MIDI input to MIDI output. To these ends, MIDI messages can be translated to sequences of other MIDI messages.
As already mentioned, the midizap program can also be used to translate MIDI input to MIDI output. To these ends, MIDI messages can be translated to sequences of other MIDI messages.
You enable MIDI output by running the program as `midizap -o`. This will equip the `midizap` Jack MIDI client with an additional output port named `midi_out` (visible on the left side of QJackCtl's Connection window).
@ -122,7 +122,7 @@ Note the `-10` suffix on the output messages in the above example, which indicat
E.g., the input note `C4` is mapped to `C3-10`, the note C in the third MIDI octave, which on channel 10 will produce the sound of a bass drum, at least on GM compatible synthesizers like Fluidsynth. The binding for the volume controller (`CC7`) at the end of the entry sends volume changes to the same drum channel (`CC7-10`), so that you can use the volume control on your keyboard to dial in the volume on the drum channel that you want. The program keeps track of the values of both input and output controllers on all MIDI channels internally, so with the translations above all that happens automagically.
Besides MIDI notes and control change (`CC`) messages, the `midizap` program also supports receiving and sending program change (`PC`) and pitch bend (`PB`) messages. This should cover most common use cases. Other messages (in particular, aftertouch and system messages) are not supported right now, but may be added in the future. Again, please refer to the example.midizaprc file and the comments in the readconfig.c for further details.
Besides MIDI notes and control change (`CC`) messages, the midizap program also supports receiving and sending program change (`PC`) and pitch bend (`PB`) messages. This should cover most common use cases. Other messages (in particular, aftertouch and system messages) are not supported right now, but may be added in the future. Again, please refer to the example.midizaprc file and the comments in the readconfig.c for further details.
## Octave Numbering and Other Options
@ -138,7 +138,7 @@ This is useful, in particular, if you use some external MIDI monitoring software
Finally, there are some additional directives (and corresponding command line options) to set midizap's Jack client name and the number of input and output ports it uses. (If both the command line options and directives in the midizaprc file are used, the former take priority, so that it's always possible to override the options from the midizaprc file from the command line.)
Firstly, there's the `-j` option and the `JACK_NAME` directive which change the Jack client name from the default (`midizap`) to whatever you want it to be. To use this option, simply invoke `midizap` as `midizap -j client-name`, or put the following directive into your midizaprc file:
Firstly, there's the `-j` option and the `JACK_NAME` directive which change the Jack client name from the default (`midizap`) to whatever you want it to be. To use this option, simply invoke midizap as `midizap -j client-name`, or put the following directive into your midizaprc file:
~~~
JACK_NAME "client-name"
@ -152,10 +152,10 @@ Secondly, we've already seen the `-o` option which is used to equip the Jack cli
JACK_PORTS 1
~~~
You may want to place this directive directly into a configuration file, if the configuration is primarily used for doing MIDI translations, so you want to have the MIDI output enabled by default. Typically, such configurations will include just a default `[MIDI]` section and little else. (As explained below, it's also possible to have *two* pairs of input and output ports, in order to deal with controller feedback from the application. This is achieved by either invoking `midizap` with the `-o2` option, or by employing the `JACK_PORTS 2` directive in the configuration file.)
You may want to place this directive directly into a configuration file, if the configuration is primarily used for doing MIDI translations, so you want to have the MIDI output enabled by default. Typically, such configurations will include just a default `[MIDI]` section and little else. (As explained below, it's also possible to have *two* pairs of input and output ports, in order to deal with controller feedback from the application. This is achieved by either invoking midizap with the `-o2` option, or by employing the `JACK_PORTS 2` directive in the configuration file.)
## Secondary MIDI Ports
Some MIDI controllers need a more elaborate setup than what we've seen so far, because they have motor faders, LEDs and similar controls requiring feedback from the application. To accommodate these, you can use the `-o2` option of `midizap`, or the `JACK_PORTS 2` directive in the midizaprc file, to create a second pair of MIDI input and output ports, named `midi_input2` and `midi_output2`. Use of this option also activates a second MIDI default section in the midizaprc file, labeled `[MIDI2]`, which is used exclusively for translating MIDI from the second input port and sending the resulting MIDI data to the second output port. Typically, the translations in the `[MIDI2]` section will be the inverse of those in the `[MIDI]` section, or whatever it takes to translate the MIDI feedback from the application back to MIDI data which the controller understands.
Some MIDI controllers need a more elaborate setup than what we've seen so far, because they have motor faders, LEDs and similar controls requiring feedback from the application. To accommodate these, you can use the `-o2` option of midizap, or the `JACK_PORTS 2` directive in the midizaprc file, to create a second pair of MIDI input and output ports, named `midi_input2` and `midi_output2`. Use of this option also activates a second MIDI default section in the midizaprc file, labeled `[MIDI2]`, which is used exclusively for translating MIDI from the second input port and sending the resulting MIDI data to the second output port. Typically, the translations in the `[MIDI2]` section will be the inverse of those in the `[MIDI]` section, or whatever it takes to translate the MIDI feedback from the application back to MIDI data which the controller understands.
You then wire up the controller to the `midi_input` port of midizap and the `midi_output` port to the application as before, but in addition you also connect the application back to midizap's `midi_input2` port, and the `midi_output2` port to the controller. This reverse path is what is needed to translate the feedback from the application and send it back to the controller. Please check the example.midizaprc file for a simple example illustrating this kind of setup.