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, and 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


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

Arguments are interpreted as ChannelSpecs, so the -C option has been removed. In version 4.0 the command-line syntax has been made neater, and more consistent with midiecho, and version 4.5 uses the MIDI::ALSA module to start its own ALSA client, and therefore no longer needs to hijack a Virtual MIDI client.

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.

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


-o 128:0 or -o TiMidity

This example plays into the ALSA port 128:0, or into the TiMidity client.. It does 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 output 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 etc.

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 pointless 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   ,   .       BassDrums

quiet mode: doesn't display keystroke help


Prints helpful usage information.


Prints 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 in separate xterm's:

  midikbd -o 0 5:91:120 4:14:120 3:91:8 2:14:8 1:29:64 0:14:64 &


  midiecho -i midikbd -d 1,2200,2201,4400,4401 -q 5 -e 1,2,3,4,5

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 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

to duplicate channel 0 onto channels 1,2, and 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).



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


Preselect the MIDI-channel.Just specify the ChannelSpec arguments after the options on the command-line.

-P 32

Preselects Patch number 32 on whatever the current channel is. This option is superseded by the ChannelSpec arguments.


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


Peter J Billam


Uses the CPAN modules Term::ReadKey and MIDI::ASLA.