midikbd - a simple monophonic ascii-midi-keyboard


   midikbd [-o output] [-ka|-kd|-kh|-kp|-kw] [-q] <ChannelSpec>...
   midikbd -o 128:0       # plays to ALSA-port 128:0
   midikbd 3              # plays to MIDI-Channel 3 (out of 0..15)
   midikbd 3:0:80 0:73:20     # sets Channel:Patch:Pan, plays to 0
   midikbd 3:92:x10:y1 # mouse X-motion controls pan; Y modulation
   midikbd -ka                # selects the "augmented" keymapping
   midikbd -q         # Quiet mode: doesn't display keystroke help
   xterm -geometry 72x18-1-1 -exec 'midikbd -kd' &
   xterm -geometry 72x24-1-1 -exec 'midikbd -ka' &
   perldoc midikbd

 the "piano" keymap (bottom 2 rows round middleC, top 2 treble clef):
    1    2    3        5    6       8    9    0        =   Back
 F  F# G G# A Bb B   C C# D Eb E  F F# G G# A Bb B   c c# d eb e
 Tab   q    w    e   r    t    y  u    i    o    p   [    ]    \
              s    d        g    h    j       l    ; 
            C C# D Eb  E  F F# G G# A Bb B  C C# D Eb E
            z    x     c  v    b    n    m  ,    .    /

 Q = Quit        C = new Channel        P = new Patch        A = ALSA
 U/D = Up/Down a semitone      PageUp/Down  = Up/Down an octave
 UpArrow    = Volume +10       DownArrow = Volume -10
 RightArrow = Pan +16          LeftArrow = Pan -16
 F1,F2=Una F3,F4=Tre   F5,F6=Sos F7,F8=*Sos   F9,F10=Ped F11,F12=*Ped
 M    = set a MIDI-Controller  X/Y = govern a Controller by mouse X/Y
 Home = reset all controllers  End = all sounds off


Midikbd allows the use of the computer keyboard as a simple monophonic MIDI keyboard.

Midikbd is monophonic because of the impracticality of detecting KeyUp and KeyDown events in an xterm. If the Space-bar is pressed (or any other ascii-key which does not map to a note), then the current note is stopped; otherwise, each note lasts until the next note is played.

This also means that if you hold a key down (as you would on, say, an organ keyboard) the key-repeat mechanism will start up; this may sound, er, unexpected.

Different key-to-note mappings are available. The default mapping is augmented. The piano mapping gives a range of just over three octaves. The lower two rows get the notes round Middle-C, so that z is the C below Middle-C and / is the E above it. Then the upper two rows get the treble-clef notes, so that Tab is the E above Middle-C and ] is the d above the treble-clef.

If the -o option is not given then midikbd writes to the port specified by the ALSA_OUTPUT_PORTS environment variable.

Since version 5.6, the user interface has changed to support the other two Pedals. Function keys F1-F4 now control the Una-corda/Tre-corde pedal, function keys F5-F8 control the Sostenuto-pedal, and the normal sustaining-pedal is now controlled by the function keys F9-F12.
This means that vt100 is no longer fully supported; if you don't have xterm you'll need eg: vt510pcdos or vte+pcfkeys etc.
The test is that   tput kf12|cat -v   should return ^[[24~
and that   tput kf8|cat -v   should return ^[[19~


-o 128:0   or  -o TiMidity

These examples plays into the ALSA port 128:0, or into the TiMidity client. They do this by using the MIDI::ALSA Perl CPAN module. When midikbd exits the connection is automatically deleted.

This option allows midikbd to use the same port-specification as the other alsa-utils, e.g. aplaymidi and aconnect. An ALSA-port is specified by its number; for port 0 of a client, the ":0" part of the port specification can be omitted. The outout port is taken from the ALSA_OUTPUT_PORTS environment variable if none is given on the command line.
Since Version 5.0, you may supply a comma-separated list of ports, e.g. -o 20,128:1
Since Version 5.4, the particular port value zero e.g. -o 0 is taken as an instruction to not connect to anything at all. This is useful if you want the output to go into another program like midiecho or midichord; you no longer have to go through a MIDI-Through client. In separate xterms:
  midikbd -o 0
and then
  midiecho -i midikbd -c 0 -d 250,450 -s 45 -e 1,2

-ka   or   -kd   or   -kh   or   -kp   or   -kw
-k augmented or -k drumkit or -k harmonic or -k piano or -k wholetone

Selects the keymap: possible keymaps are augmented (the default), drumkit, harmonic, piano, and wholetone. All keymappings are aimed at the US-keyboard; this could be seen as a bug. The augmented keymap is particularly good for improvisation. The drumkit keymap preselects Channel 9; in this mode, it is better not to change the Patch or the Transposition. The harmonic keymap is sort of inspired by accordion buttons, and makes it very easy to play major and minor triads; this is unfortunately not very useful as midikbd is only monophonic, which could also be seen as a bug.

 the "piano" keymap (bottom 2 rows round middleC, top 2 treble clef):
    1    2    3        5    6       8    9    0        =   Back
 F  F# G G# A Bb B   C C# D Eb E  F F# G G# A Bb B   c c# d eb e
 Tab   q    w    e   r    t    y  u    i    o    p   [    ]    \
              s    d        g    h    j       l    ; 
            C C# D Eb  E  F F# G G# A Bb B  C C# D Eb E
            z    x     c  v    b    n    m  ,    .    /

 the "wholetone" keymap (bottom 2 rows bass, top 2 treble):
 `    1    2   3    4    5    6    7    8    9    0    -    =   Back
 G G# A Bb B C C# D Eb E F F# G G# A Bb B c c# d  eb e f f# g g# a bb
   Tab  q    w    e    r   t    y    u    i    o     p   [    ]    \
          a    s    d    f    g    h    j   k    l    ;    '
          B_ C C# D Eb E F F# G G# A Bb B C C# D Eb E F F# G
             z    x    c   v    b    n    m    ,    .   /

 the "augmented" keymap (all 4 rows, starting from top left):
 `    1    2   3    4    5    6    7    8    9    0    -    =   Back
 Bb   C    E   G#   C    E    G#   c    e    g#   c    e    g    a
   Tab  q    w    e    r   t    y    u    i    o     p   [    ]    \
    B   C#   F    A    C#  F    A    c#   f    a     c#  f    g#   bb
          a    s    d    f    g    h    j   k    l    ;    '
          D    F#   Bb   D    F#   Bb   d   f#   bb   d    f#
             z    x    c   v    b    n    m    ,    .   /
             Eb   G    B   Eb   G    B    eb   g    b   eb

 the "harmonic" keymap (rightwards, alternate maj and min 3rds):
   1     2   3    4   5   6   7    8    9     0    -     =    Back
   Eb Bb G D Bb F D A F C A E C G  E B  G  D  B F# D  A  F# C# A
      q    w    e   r   t   y   u    i     o    p     [     ]
         a    s   d   f   g   h    j    k     l    ;     '
         F  C A E C G E B G D B F# D A  F# C# A E  C# G# E
            z   x   c   v   b   n    m     ,    .     /

 the "drumkit" keymap (for General-MIDI channel 9):
 Perc  1   2   3   4   5   6   7   8   9   0   -   =    Congas
 HiHat   q   w   e   r   t   y   u   i   o   p   [     Cymbals
 Snare     a   s   d   f   g   h   j   k   l   ;   '   TomToms
 Metronome   z   x   c   v   b   n   m   ,   .   /  Bass-Drums


quiet mode: doesn't display keystroke help


Shows helpful usage information


Displays the version number.


After the options, the remaining command-line arguments are ChannelSpecs, which specify how the MIDI-Channels are to be set up. For example:


This first example preselects Channel number 5 (out of 0..15).

5:91:120 4:14:120 3:91:8 2:14:8 1:91:64 0:14:64

The second example sets up Channel:Patch:Pan on a number of channels, and leaves midikbd playing on the last channel mentioned. A list of General-MIDI Patch-numbers is at ../muscript/gm.html#patch.
E.g. (assuming ALSA-client 14 is a Midi-Through, see aconnect -oil) in separate xterms:
  midiecho -i 14 -d 1,2200,2201,4400,4401 -s 5 -e 1,2,3,4,5
  midikbd -o 14 5:91:120 4:14:120 3:91:8 2:14:8 1:29:64 0:14:64

3:91:y0 2:92:y-0 1:93:x-10 0:94:x10

The third example uses mouse movement X,Y within its window to drive MIDI-controllers, with an x or a y followed by a Controller-number. A list of MIDI-Controller numbers is at /muscript/gm.html#cc and if the number is preceded by a minus sign then midikbd reverses the direction of drive, so that right- or up-motions decrease the parameter rather than increase it as they do normally.

Controller number zero is re-interpreted by midikbd to mean Pitch-Bend, which is not technically a real MIDI-controller, but is very useful. (The real MIDI-controller number zero is a Bank-Select, which is a slow and discontinuous operation not useful under a mouse.)

midikbd -o 14 3:91:y0 2:92:y-0 1:93:x-11 0:94:x11

This fourth example leaves midikbd transmitting to patch 94 on channel 0, after having set patch 91 on channel 3, and 92 on 2, and 93 on channel 1; and the X-motions of the mouse cross-fade from patch 93 to 94, and the Y-motions raise and lower patches 91 and 92 in opposite directions

Previously, in a different xterm, you have to be running:
  midiecho -i 14 -d 1,1,1 -s 1,1,1 -e 1,2,3
(very wild :-).

Midikbd detects mouse-motion events from the xterm, by using the DECSET SET_ANY_EVENT_MOUSE command: \e[?1003h   (An earlier version ran xev and parsed its output).


-p 128:0

Specifies the output ALSA-port. Just use use -o instead.

-C 5

As of version 4.0, the -C option is superseded. Just specify the ChannelSpec arguments after the options on the command-line.

-P 32

Preselects Patch number 32 (out of 0..127) on whatever the current channel is. This option is superseded by the the ChannelSpec arguments.


The current version of midikbd is available by http at www.pjb.com.au/midi/free/midikbd
To install it, save it to disc, move it into your $PATH, make it executable, and if necessary edit the first line to reflect where perl is installed on your system. You will also need to install the MIDI::ALSA and Term::Clui and Term::ReadKey CPAN modules


5.8, 20150603, X and Y mouse-control of pitchwheel displayed helpfully
5.7, 20150531, X and Y mouse-control fixed
5.6, 20150529, UI change: F1-F4=Una/Tre F5-F8=Sos/*Sos F9-F12=Ped
5.5, 20150528, the Synopsis responds to Pedal on/off
5.4, 20130225, -o 0 doesn't connect to anything
5.3, 20120407, the Y-controller works correctly
5.2, 20120401, changing the X- or Y-controller displays correctly
5.1, 20111103, uses the new MIDI-ALSA 1.11 to handle ALSA-ports by their names
5.0, 20111028, OutputPort can be a comma-separated list
4.9, 20110917, if X and Y are set at the command line, the ccNN=X and ccNN=Y are displayed, and "Pan is controlled by mouse" not falsely displayed
4.8, 20110620, drumkit offers z,x = metronome
4.7, 20110509, quit from drumkit mode cleans up screen properly
4.6, 20110414, keystroke A changes ALSA connections
4.5, 20110321, now uses MIDI::ALSA, not aconnect and writing to /dev/snd/midi*
4.4, 20101214, display more compact; Controllers now displayed
4.3, 20101117, keystrokes X and Y map X and Y mouse movements at run-time
4.2, 20101017, AutoPan is cancelled by Pan, but is still unimplemented; keystroke M sets a MIDI-Controller
4.1, 20100819, CursorRow set correctly for drumkit keymap
4.0, 20100419, -C deprecated, -p and -d subsumed into -o
3.6, 20100417, X and Y mouse movements govern controllers
3.5, 20100402, F1,F2 take new pedal; F3,F4 remove pedal
3.4, 20100326, the -C option accepts the Channel:Patch:Pan format
3.3, 20100325, handles multiple -C nn -P nn -C nn -P nn settings
3.2, 20100325, Left and Right pan; Up and Down adjust volume; U and D transpose
3.1, 20100318, -d - outputs to stdout, e.g. to pipe into midiecho -i -
3.0, 20100215, -C and -P, and -p now means ALSA-port
2.9, 20100206, augmented keymapping
2.8, 20100202, uses aconnect to show "connected to" info for virmidi
2.7, 20100202, -d option
2.6, 20100130, in drumkit mode, no Channel, Patch or Transpose
2.5, 20100130, fixed -h option
2.4, 20100130, drumkit keymapping
2.3, 20100129, piano, wholetone and harmonic keymappings; -k option
2.2, 20100128, displays keystroke help (and cleans it up on Quit)
2.1, 20100127, display_note()
2.0, 20100127, different key2note mapping, starting from z=C
1.9, 20100126, bug fixed with note-off for bass c
1.8, 20100126, End = all sounds off, Home = reset all controllers
1.7, 20100126, looks through /dev/snd for midiC* files
1.6, 20100126, remembers Patch per Channel
1.5, 20100125, proper little Clui-style state display
1.4, 20100125, Left and Right arrows change volume
1.3, 20100125, the -p option works
1.2, 20100125, sub note_off; channel change stops last note
1.1, 20100125, PageUp,PageDown,Up,Down change transpose; P changes patch, C changes channel
1.0, 20100124, first working version


Peter J Billam www.pjb.com.au/comp/contact.html