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