README

   1 What is it?
   2 -----------
   3
   4 jack-keyboard is a virtual MIDI keyboard - a program that allows you to
   5 send JACK MIDI events (play ;-) using your PC keyboard.  It's  somewhat
   6 similar  to  vkeybd,  except it uses JACK MIDI instead of ALSA, and the
   7 keyboard mapping is much better - it uses the same layout  as  trackers
   8 (like Impulse Tracker) did, so you have two and half octaves under your
   9 fingers.
  10
  11 How to compile it?
  12 ------------------
  13
  14 If you're using FreeBSD, install from ports - audio/jack-keyboard.
  15
  16 Otherwise, you need JACK with MIDI support, gtk+ 2.6 or higher,
  17 make(1), gcc and all the standard headers.  Untar the file, type
  18 'make install' and that's it.  If there is any problem, drop me
  19 an email (trasz@FreeBSD.org) and I will help you.  Really.
  20
  21 How to use it?
  22 --------------
  23
  24 You need JACK with MIDI support and some softsynth that accepts
  25 JACK MIDI as input.  Ghostess, http://home.jps.net/~musound/,
  26 is a good choice.  Of course you will also need some DSSI plugin
  27 that will make the actual sound.  WhySynth is nice.
  28
  29 When you have all of these installed: first, run jackd.  Then run
  30 ghostess with a plugin of choice.  Then run jack-keyboard.  Press
  31 'z' key.  You should hear sound.
  32
  33 Keyboard
  34 --------
  35
  36 Keyboard mapping is the same as in Impulse Tracker.  This is your
  37 QWERTY keyboard:
  38
  39    +----+----+    +----+----+----+    +----+----+
  40    | 2  | 3  |    | 5  | 6  | 7  |    | 9  | 0  |
  41 +----+----+----+----+----+----+----+----+----+----+
  42 | q  | w  | e  | r  | t  | y  | u  | i  | o  | p  |
  43 +----+----+----+----+----+----+----+----+----+----+
  44        | s  | d  |    | g  | h  | j  |
  45     +----+----+----+----+----+----+----+
  46     | z  | x  | c  | v  | b  | n  | m  |
  47     +----+----+----+----+----+----+----+
  48
  49 And this is MIDI mapping.
  50
  51    +----+----+    +----+----+----+    +----+----+
  52    |C#5 |D#5 |    |F#5 |G#5 |A#5 |    |C#6 |D#6 |
  53 +----+----+----+----+----+----+----+----+----+----+
  54 | C5 | D5 | E5 | F5 | G5 | A5 | B5 | C6 | D6 | E6 |
  55 +----+----+----+----+----+----+----+----+----+----+
  56        |C#4 |D#4 |    |F#4 |G#4 |A#4 |
  57     +----+----+----+----+----+----+----+
  58     | C4 | D4 | E4 | F4 | G4 | A4 | B4 |
  59     +----+----+----+----+----+----+----+
  60
  61 Spacebar  is  a sustain key.  Holding it when pressing or releasing key
  62 will make that key sustained, i.e. Note Off MIDI event  won't  be  sent
  63 after  releasing  the  key.  To release (stop) all the sustained notes,
  64 press and release spacebar.
  65
  66 Holding Shift when pressing note will  make  it  louder  (it  increases
  67 velocity).   Holding  Ctrl  will  do  the opposite.  You can change the
  68 default velocity by moving the Velocity slider.   You  can  change  the
  69 "high"  and  "low"  velocity  values by moving the slider while holding
  70 Shift or Ctrl keys.
  71
  72 Pressing "-" and "+" keys on numeric keypad  changes  the  octave  your
  73 keyboard  is mapped to.  Pressing "*" and "/" on numeric keypad changes
  74 MIDI program (instrument).  Pressing Insert or Delete keys will connect
  75 jack-keyboard  to  the  next/previous  MIDI  input  port (it will cycle
  76 between running instances of ghostess, for example).  Home and End keys
  77 change  the  MIDI  channel.  Page Up and Page Down keys switch the MIDI
  78 bank.
  79
  80 Esc works as a panic key - when you press it, all sound stops.
  81
  82 Setting channel/bank/program number directly
  83 --------------------------------------------
  84
  85 To switch directly to a channel, bank or program, enter its  number  on
  86 the numeric keypad (it won't be shown in any way) and press Home or End
  87 (to change channel), Page Up or Page Down (to change bank)  or  "/"  or
  88 "*" (to change program).  For example, to change to program number 123,
  89 type, on the numeric keypad, "123/", without quotes.
  90
  91 Titlebar
  92 --------
  93
  94 When -G xor -T is given, some informational messages in the  title  bar
  95 appear.  They  are  supposed  to  be  self  explanatory.   If  you  see
  96 "bank/program change not sent", it means that the bank/program  numbers
  97 as  seen  in  the  title  bar were not sent.  In other words, synth the
  98 jack-keyboard is connected to may use different values.   This  happens
  99 at  startup  and  after  switching  between synths (using Insert/Delete
 100 keys).  To send bank/program change at startup, use -b and  -p  parame-
 101 ters.   To  automatically send bank/program change after reconnect, use
 102 the -u option.
 103
 104 Pianola mode
 105 ------------
 106
 107 In addition to the MIDI output  port,  jack-keyboard  also  opens  MIDI
 108 input  (listening)  port.   MIDI  events  going  into this port will be
 109 passed to the output port unmodified, except for channel number,  which
 110 will be set to the one jack-keyboard is configured to use.  Note On and
 111 Note Off MIDI events will cause visible effect (pressing and releasing)
 112 on  keys, just like if they were being pressed using keyboard or mouse.
 113
 114 jack-keyboard will never connect to it's own MIDI input port.  It  will
 115 also  refuse to connect to any other client whose name begins in "jack-
 116 keyboard", unless the "-k" option is given.  It is,  however,  possible
 117 to  connect  these ports manually, using jack_connect or qjackctl; this
 118 may create feedback loop.
 119
 120 License
 121 -------
 122
 123 JACK Keyboard is distributed under the BSD license, two clause.
 124
 125 Contact
 126 -------
 127
 128 If you have any questions, comments, suggestions, patches or anything,
 129 let me know: Edward Tomasz Napierala <trasz@FreeBSD.org>.
 130