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

Text changes.

master
Albert Graef 2018-09-04 07:53:18 +02:00
parent 5d8dae58dd
commit 803dd48b6e
2 changed files with 49 additions and 35 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

21
README.md
View File

@ -174,23 +174,26 @@ PB output # pitch bend
The `#` character at the beginning of a line and after whitespace is special; it indicates that the rest of the line is a comment, which is skipped by the parser. Empty lines and lines containing nothing but whitespace are also ignored.
Lines beginning with a `[`*name*`]` header are also special. Each such line introduces a translation class *name*, which may be followed by a basic regular expression *regex* (see the regex(7) manual page) to be matched against the X11 window class and title (in that order). Note that *everything* following the `[`*name*`]` header is taken verbatim here; the *regex* part is the entire rest of the line, ignoring leading and trailing whitespace, but including embedded whitespace or `#` characters (so you can't place a comment on such lines).
Lines beginning with a `[`*name*`]` header are also special. Each such line introduces a translation class *name*, which may be followed by a basic regular expression *regex* (see the regex(7) manual page) to be matched against window class and title. Note that *everything* following the `[`*name*`]` header on the same line is taken verbatim; the *regex* part is the entire rest of the line, ignoring leading and trailing whitespace, but including embedded whitespace and `#` characters (so you can't place a comment on such lines).
The sections are matched against the window with the keyboard focus in the order in which they are listed in the configuration file. The first class which matches the window class or title determines the translations to be used for that window. An empty *regex* for the last class will always match, allowing default translations. If a translation cannot be found in the matched section, it will be loaded from the default section if possible. In addition, there are two special default sections labeled `[MIDI]` and `[MIDI2]` which are used specifically for MIDI translations, please see the *MIDI Output* and *MIDI Feedback* sections for details. If these sections are present, they should precede the main default section. All other sections, including the main default section, can be named any way you like; the given *name* is only used for debugging output and diagnostics, and needn't be unique.
To find a set of eligible translations, midizap matches class and title of the window with the keyboard focus against each section, in the order in which they are listed in the configuration file. For each section, midizap first tries to match the window class (the `WM_CLASS` property; this usually provides the better clues for identifying an application), then the window title (the `WM_NAME` property). The first section which matches determines the translations to be used for that window. An empty *regex* for the last class will always match, allowing default translations. If a translation cannot be found in the matched section, it will be loaded from the default section if possible. In addition, there are two special default sections labeled `[MIDI]` and `[MIDI2]` which are used specifically for MIDI translations, please see the *MIDI Output* and *MIDI Feedback* sections for details. If these sections are present, they should precede the main default section. All other sections, including the main default section, can be named any way you like; the given *name* is only used for debugging output and diagnostics, and needn't be unique.
The translations define what output should be produced for the given MIDI input. Each translation must be on a line by itself. The left-hand side (first token) of the translation denotes the MIDI message to be translated. The corresponding right-hand side (the rest of the line) is a sequence of zero or more tokens, separated by whitespace, indicating either MIDI messages or X11 keyboard and mouse events to be output. The output sequence may be empty, or just the special token `NOP` (which doesn't produce any output), to indicate that the translation outputs nothing at all. This suppresses any default translation for this input.
The translations define what output should be produced for the given MIDI input. Each translation must be on a line by itself. The left-hand side (first token) of the translation denotes the MIDI message to be translated. The corresponding right-hand side (the rest of the line) is a sequence of zero or more tokens, separated by whitespace, indicating either MIDI messages or X11 keyboard and mouse events to be output. The output sequence may be empty, or just the special token `NOP` (which doesn't produce any output), to indicate that the translation outputs nothing at all; this suppresses the default translation for this input. Translation classes may be empty as well (i.e., not provide any translations), in which case *only* the default translations are active, even if a later non-default section matches the same window.
Example:
~~~
[Konsole] ^konsole$
G5 XK_Up
A5 XK_Down
[Terminal] ^.*-terminal.*\|konsole\|xterm$
F5 XK_Up
F#5 "pwd"
G5 XK_Down
G#5 "ls"
A5 XK_Return
~~~
This binds the G and A keys in the middle octave of your MIDI keyboard to the X11 cursor up and down keys, in a section named `Konsole` which matches KDE terminal windows by their class name `konsole`. So the bindings in this translation class will let you cycle through the command history of the shell when the keyboard focus is on a Konsole window.
This binds a few keys in the middle octave to the Up, Down and Return keys as well as some frequently used shell commands, in a section named `Terminal` which matches some common types of terminal windows by their class names. The bindings in this translation class will let you operate the shell from your MIDI keyboard when the keyboard focus is on a terminal window.
**NOTE:** Translations *must be determined uniquely* in each translation class, i.e., each input message may be bound to at most one output sequence in each section. Otherwise, the parser will print an error message, and the extra translations will be ignored. This restriction makes it easier to detect inconsistencies, and it also ensures that midizap's operation is completely *deterministic*. That is, for each input sequence on a given window the program will always generate exactly the same output sequence.
**NOTE:** Translations may be listed in any order, but they *must be determined uniquely*, i.e., each input message may be bound to at most one output sequence in each translation class. Otherwise, the parser will print an error message, and the extra translations will be ignored. This restriction makes it easier to detect inconsistencies, and it also ensures that midizap's operation is completely *deterministic*. That is, for each input sequence on a given window the program will always generate exactly the same output sequence.
## MIDI Message Notation
@ -693,7 +696,7 @@ The [Bome MIDI Translator][] seems to be a popular MIDI and keystroke mapping to
# Authors, License and Credits
midizap is free and open source software licensed under the GPLv3, see the LICENSE file for details.
midizap is free and open source software licensed under the GPLv3, please see the LICENSE file in the distribution for details.
Copyright 2013 Eric Messick (FixedImagePhoto.com/Contact)
Copyright 2018 Albert Graef (<aggraef@gmail.com>)

63
midizap.1
View File

@ -471,18 +471,23 @@ Lines beginning with a \f[C][\f[]\f[I]name\f[]\f[C]]\f[] header are also
special.
Each such line introduces a translation class \f[I]name\f[], which may
be followed by a basic regular expression \f[I]regex\f[] (see the
regex(7) manual page) to be matched against the X11 window class and
title (in that order).
regex(7) manual page) to be matched against window class and title.
Note that \f[I]everything\f[] following the
\f[C][\f[]\f[I]name\f[]\f[C]]\f[] header is taken verbatim here; the
\f[I]regex\f[] part is the entire rest of the line, ignoring leading and
trailing whitespace, but including embedded whitespace or \f[C]#\f[]
characters (so you can't place a comment on such lines).
\f[C][\f[]\f[I]name\f[]\f[C]]\f[] header on the same line is taken
verbatim; the \f[I]regex\f[] part is the entire rest of the line,
ignoring leading and trailing whitespace, but including embedded
whitespace and \f[C]#\f[] characters (so you can't place a comment on
such lines).
.PP
The sections are matched against the window with the keyboard focus in
the order in which they are listed in the configuration file.
The first class which matches the window class or title determines the
translations to be used for that window.
To find a set of eligible translations, midizap matches class and title
of the window with the keyboard focus against each section, in the order
in which they are listed in the configuration file.
For each section, midizap first tries to match the window class (the
\f[C]WM_CLASS\f[] property; this usually provides the better clues for
identifying an application), then the window title (the \f[C]WM_NAME\f[]
property).
The first section which matches determines the translations to be used
for that window.
An empty \f[I]regex\f[] for the last class will always match, allowing
default translations.
If a translation cannot be found in the matched section, it will be
@ -507,29 +512,35 @@ of zero or more tokens, separated by whitespace, indicating either MIDI
messages or X11 keyboard and mouse events to be output.
The output sequence may be empty, or just the special token \f[C]NOP\f[]
(which doesn't produce any output), to indicate that the translation
outputs nothing at all.
This suppresses any default translation for this input.
outputs nothing at all; this suppresses the default translation for this
input.
Translation classes may be empty as well (i.e., not provide any
translations), in which case \f[I]only\f[] the default translations are
active, even if a later non\-default section matches the same window.
.PP
Example:
.IP
.nf
\f[C]
[Konsole]\ ^konsole$\
\ G5\ \ \ \ XK_Up
\ A5\ \ \ \ XK_Down
[Terminal]\ ^.*\-terminal.*\\|konsole\\|xterm$\
\ F5\ \ \ \ XK_Up
\ F#5\ \ \ "pwd"
\ G5\ \ \ \ XK_Down
\ G#5\ \ \ "ls"
\ A5\ \ \ \ XK_Return
\f[]
.fi
.PP
This binds the G and A keys in the middle octave of your MIDI keyboard
to the X11 cursor up and down keys, in a section named \f[C]Konsole\f[]
which matches KDE terminal windows by their class name \f[C]konsole\f[].
So the bindings in this translation class will let you cycle through the
command history of the shell when the keyboard focus is on a Konsole
window.
This binds a few keys in the middle octave to the Up, Down and Return
keys as well as some frequently used shell commands, in a section named
\f[C]Terminal\f[] which matches some common types of terminal windows by
their class names.
The bindings in this translation class will let you operate the shell
from your MIDI keyboard when the keyboard focus is on a terminal window.
.PP
\f[B]NOTE:\f[] Translations \f[I]must be determined uniquely\f[] in each
translation class, i.e., each input message may be bound to at most one
output sequence in each section.
\f[B]NOTE:\f[] Translations may be listed in any order, but they
\f[I]must be determined uniquely\f[], i.e., each input message may be
bound to at most one output sequence in each translation class.
Otherwise, the parser will print an error message, and the extra
translations will be ignored.
This restriction makes it easier to detect inconsistencies, and it also
@ -1836,8 +1847,8 @@ be worth a look if you need a midizap alternative which runs on these
systems.
.SH Authors, License and Credits
.PP
midizap is free and open source software licensed under the GPLv3, see
the LICENSE file for details.
midizap is free and open source software licensed under the GPLv3,
please see the LICENSE file in the distribution for details.
.PP
Copyright 2013 Eric Messick (FixedImagePhoto.com/Contact)
.PD 0