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

Text changes.

master
Albert Graef 2018-09-03 23:33:37 +02:00
parent 94436fc266
commit a11da5c9ec
2 changed files with 54 additions and 34 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

20
README.md
View File

@ -174,21 +174,27 @@ 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. 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.
Each `[name] regex` line introduces the list of MIDI message translations for the named translation class. E.g., the following line might be used to begin a section for the Kdenlive video editor: 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).
~~~ 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.
[Kdenlive] ^kdenlive$
~~~
Please refer to regex(7) for an explanation of the regular expression syntax. When focus is on a window whose class or title matches the (basic) regular expression `regex`, the corresponding translations are in effect. The sections are matched in the order in which they are listed in the configuration, so classes with the most specific regexes should come first. An empty regex for the last class will always match, allowing default translations. Any output sequences not bound in a matched section will be loaded from the default section if they are bound there. 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 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 any default translation for this input.
Example:
~~~
[Konsole] ^konsole$
G5 XK_Up
A5 XK_Down
~~~
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.
**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 *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.
## MIDI Message Notation ## MIDI Message Notation
There's no real standard for symbolic designations of MIDI messages, but we hope that most users will find midizap's notation easy to understand and remember. Notes are specified using a customary format which musicians will find familiar: a note name `A..G` is followed by an (optional) accidental (`#` or `b`), and a (mandatory) MIDI octave number. Note that all MIDI octaves start at the note C, so `B0` comes before `C1`. By default, `C5` denotes middle C (you can change this if you want, see *Octave Numbering* below). Enharmonic spellings are equivalent, so, e.g., `D#5` and `Eb5` denote exactly the same MIDI note. There's no real standard for symbolic designations of MIDI messages, but we hope that most users will find midizap's notation easy to understand and remember. Notes are specified using a customary format which musicians will find familiar: a note name `A`, `B`, ..., `G` is followed by an (optional) accidental (`#` or `b`), and a (mandatory) MIDI octave number. Note that all MIDI octaves start at the note C, so `B0` comes before `C1`. By default, `C5` denotes middle C (you can change this if you want, see *Octave Numbering* below). Enharmonic spellings are equivalent, so, e.g., `D#5` and `Eb5` denote exactly the same MIDI note.
The other messages are denoted using short mnemonics: `KP:`*note* (aftertouch a.k.a. key pressure for the given note); `CC`*n* (control change for the given controller number); `PC`*n* (program change for the given program number); `CP` (channel pressure); and `PB` (pitch bend). We will go into the other syntactic bits and pieces of MIDI message designations later, but it's good to have the following grammar in EBNF notation handy for reference. (To keep things simple, the grammar is somewhat abridged, but it covers all the frequently used notation. There is some additional syntax for special forms of translations which will be introduced later.) The other messages are denoted using short mnemonics: `KP:`*note* (aftertouch a.k.a. key pressure for the given note); `CC`*n* (control change for the given controller number); `PC`*n* (program change for the given program number); `CP` (channel pressure); and `PB` (pitch bend). We will go into the other syntactic bits and pieces of MIDI message designations later, but it's good to have the following grammar in EBNF notation handy for reference. (To keep things simple, the grammar is somewhat abridged, but it covers all the frequently used notation. There is some additional syntax for special forms of translations which will be introduced later.)

68
midizap.1
View File

@ -467,29 +467,26 @@ is skipped by the parser.
Empty lines and lines containing nothing but whitespace are also Empty lines and lines containing nothing but whitespace are also
ignored. ignored.
.PP .PP
Each \f[C][name]\ regex\f[] line introduces the list of MIDI message Lines beginning with a \f[C][\f[]\f[I]name\f[]\f[C]]\f[] header are also
translations for the named translation class. special.
E.g., the following line might be used to begin a section for the Each such line introduces a translation class \f[I]name\f[], which may
Kdenlive video editor: be followed by a basic regular expression \f[I]regex\f[] (see the
.IP regex(7) manual page) to be matched against the X11 window class and
.nf title (in that order).
\f[C] Note that \f[I]everything\f[] following the
[Kdenlive]\ ^kdenlive$ \f[C][\f[]\f[I]name\f[]\f[C]]\f[] header is taken verbatim here; the
\f[] \f[I]regex\f[] part is the entire rest of the line, ignoring leading and
.fi trailing whitespace, but including embedded whitespace or \f[C]#\f[]
characters (so you can't place a comment on such lines).
.PP .PP
Please refer to regex(7) for an explanation of the regular expression The sections are matched against the window with the keyboard focus in
syntax. the order in which they are listed in the configuration file.
When focus is on a window whose class or title matches the (basic) The first class which matches the window class or title determines the
regular expression \f[C]regex\f[], the corresponding translations are in translations to be used for that window.
effect. An empty \f[I]regex\f[] for the last class will always match, allowing
The sections are matched in the order in which they are listed in the default translations.
configuration, so classes with the most specific regexes should come If a translation cannot be found in the matched section, it will be
first. loaded from the default section if possible.
An empty regex for the last class will always match, allowing default
translations.
Any output sequences not bound in a matched section will be loaded from
the default section if they are bound there.
In addition, there are two special default sections labeled In addition, there are two special default sections labeled
\f[C][MIDI]\f[] and \f[C][MIDI2]\f[] which are used specifically for \f[C][MIDI]\f[] and \f[C][MIDI2]\f[] which are used specifically for
MIDI translations, please see the \f[I]MIDI Output\f[] and \f[I]MIDI MIDI translations, please see the \f[I]MIDI Output\f[] and \f[I]MIDI
@ -497,8 +494,8 @@ Feedback\f[] sections for details.
If these sections are present, they should precede the main default If these sections are present, they should precede the main default
section. section.
All other sections, including the main default section, can be named any All other sections, including the main default section, can be named any
way you like; the name is only used for debugging output and way you like; the given \f[I]name\f[] is only used for debugging output
diagnostics, and needn't be unique. and diagnostics, and needn't be unique.
.PP .PP
The translations define what output should be produced for the given The translations define what output should be produced for the given
MIDI input. MIDI input.
@ -513,6 +510,23 @@ The output sequence may be empty, or just the special token \f[C]NOP\f[]
outputs nothing at all. outputs nothing at all.
This suppresses any default translation for this input. This suppresses any default translation for this input.
.PP .PP
Example:
.IP
.nf
\f[C]
[Konsole]\ ^konsole$\
\ G5\ \ \ \ XK_Up
\ A5\ \ \ \ XK_Down
\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.
.PP
\f[B]NOTE:\f[] Translations \f[I]must be determined uniquely\f[] in each \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 translation class, i.e., each input message may be bound to at most one
output sequence in each section. output sequence in each section.
@ -528,9 +542,9 @@ There's no real standard for symbolic designations of MIDI messages, but
we hope that most users will find midizap's notation easy to understand we hope that most users will find midizap's notation easy to understand
and remember. and remember.
Notes are specified using a customary format which musicians will find Notes are specified using a customary format which musicians will find
familiar: a note name \f[C]A..G\f[] is followed by an (optional) familiar: a note name \f[C]A\f[], \f[C]B\f[], \&..., \f[C]G\f[] is
accidental (\f[C]#\f[] or \f[C]b\f[]), and a (mandatory) MIDI octave followed by an (optional) accidental (\f[C]#\f[] or \f[C]b\f[]), and a
number. (mandatory) MIDI octave number.
Note that all MIDI octaves start at the note C, so \f[C]B0\f[] comes Note that all MIDI octaves start at the note C, so \f[C]B0\f[] comes
before \f[C]C1\f[]. before \f[C]C1\f[].
By default, \f[C]C5\f[] denotes middle C (you can change this if you By default, \f[C]C5\f[] denotes middle C (you can change this if you