jack-keyboard/man/jack-keyboard.1

.\" This manpage has been automatically generated by docbook2man 
.\" from a DocBook document.  This tool can be found at:
.\" <http://shell.ipoline.com/~elmert/comp/docbook2X/> 
.\" Please send any bug reports, improvements, comments, patches, 
.\" etc. to Steve Cheng <steve@ggi-project.org>.
.TH "JACK-KEYBOARD" "1" "20 April 2008" "jack-keyboard 2.4" ""

.SH NAME
jack-keyboard \- A virtual keyboard for JACK MIDI
.SH SYNOPSIS

\fBjack-keyboard\fR [ \fB-C\fR ] [ \fB-G\fR ] [ \fB-K\fR ] [ \fB-T\fR ] [ \fB-V\fR ] [ \fB-a \fIinput port\fB\fR ] [ \fB-k\fR ] [ \fB-r \fIrate\fB\fR ] [ \fB-t\fR ] [ \fB-u\fR ] [ \fB-c \fIchannel\fB\fR ] [ \fB-b \fIbank\fB\fR ] [ \fB-p \fIprogram\fB\fR ] [ \fB-l \fIlayout\fB\fR ]

.SH "OPTIONS"
.TP
\fB-C\fR
Enable "keyboard cue" - two
horizontal lines over a part of keyboard; keys under the lower line are mapped
to the lower row of your PC keyboard; keys under the upper line are mapped
to the upper row.
.TP
\fB-G\fR
Disable GUI.  It makes \fBjack-keyboard\fR look like it did before version 2.0.
.TP
\fB-K\fR
Grab the keyboard.  This makes \fBjack-keyboard\fR receive keyboard events
even when it does not have focus.  In other words, you can play while mousing in a different
window.

Note: It's not reliable yet.  It does not work when some other application keeps
the keyboard grabbed.  It does not work with GNOME.  Even when it seems to work,
some keyboard events may get lost.
.TP
\fB-T\fR
Toggle titlebar, on which channel/bank/program information is shown.
With -G option, it disables titlebar; otherwise it enables it.
.TP
\fB-V\fR
Print version number to standard output and exit.
.TP
\fB-a \fIinput port\fB\fR
Automatically connect to the named input port.  Note that this may cause problems with LASH.
.TP
\fB-k\fR
Allow connecting to other instances of jack-keyboard (see PIANOLA MODE below).
Without this option, \fBjack-keyboard\fR will refuse to connect to any
JACK client whose name starts in "jack-keyboard"; this is to prevent loops.
Note that it's impossible to connect instance of \fBjack-keyboard\fR
to itself, even with this option set.
.TP
\fB-r \fIrate\fB\fR
Set rate limit to \fIrate\fR, in Kbaud.  Limit
defined by the MIDI specification is 31.25.  By default this parameter is zero, that
is, rate limiting is disabled.
.TP
\fB-t\fR
Send all MIDI messages with zero time offset, making them play as soon
as they reach the synth.  This was the default behavior before version 1.6.
.TP
\fB-u\fR
By default, \fBjack-keyboard\fR does not send program/bank
change messages after reconnecting, so the newly connected instrument
remains at previous settings.  This option changes that behaviour.
.TP
\fB-c \fIchannel\fB\fR
Set initial MIDI channel to \fIchannel\fR;
by default it's 1.
.TP
\fB-b \fIbank\fB\fR
Set initial MIDI bank to \fIbank\fR\&.
With this option, \fBjack-keyboard\fR will send the bank/program
change once, when it connects. 
.TP
\fB-p \fIprogram\fB\fR
Set initial MIDI program to \fIprogram\fR\&.
With this option, \fBjack-keyboard\fR will send the bank/program
change once, when it connects. 
.TP
\fB-l \fIlayout\fB\fR
Specify the layout of computer keyboard being used.  Valid arguments are QWERTY,
QWERTZ and AZERTY.  Default is QWERTY.
.SH "DESCRIPTION"
.PP
\fBjack-keyboard\fR is a virtual MIDI keyboard - a program that allows
you to send JACK MIDI events (play ;-) using your PC keyboard.  It's
somewhat similar to \fBvkeybd\fR, except it uses JACK MIDI instead of
ALSA, and the keyboard mapping is much better - it uses the same
layout as trackers (like Impulse Tracker) did, so you have two and
half octaves under your fingers.
.SH "KEY BINDINGS"
.PP
Keyboard mapping is the same as in Impulse Tracker.  This is your
QWERTY keyboard:

.nf
		   +----+----+    +----+----+----+    +----+----+
		   | 2  | 3  |    | 5  | 6  | 7  |    | 9  | 0  |
		+----+----+----+----+----+----+----+----+----+----+
		| Q  | W  | E  | R  | T  | Y  | U  | I  | O  | P  |
		+----+----+----+----+----+----+----+----+----+----+
		       | S  | D  |    | G  | H  | J  |
		    +----+----+----+----+----+----+----+
		    | Z  | X  | C  | V  | B  | N  | M  |
		    +----+----+----+----+----+----+----+
		
.fi
And this is MIDI mapping:

.nf
		   +----+----+    +----+----+----+    +----+----+
		   |C#5 |D#5 |    |F#5 |G#5 |A#5 |    |C#6 |D#6 |
		+----+----+----+----+----+----+----+----+----+----+
		| C5 | D5 | E5 | F5 | G5 | A5 | B5 | C6 | D6 | E6 |
		+----+----+----+----+----+----+----+----+----+----+
		       |C#4 |D#4 |    |F#4 |G#4 |A#4 |
		    +----+----+----+----+----+----+----+
		    | C4 | D4 | E4 | F4 | G4 | A4 | B4 |
		    +----+----+----+----+----+----+----+
		
.fi
.PP
Spacebar is a sustain key.  Holding it when pressing or releasing key
will make that key sustained, i.e. Note Off MIDI event won't be sent
after releasing the key.  To release (stop) all the sustained notes,
press and release spacebar.
.PP
Holding Shift when pressing note will make it louder (it increases
velocity).  Holding Ctrl will do the opposite.  You can change the
default velocity by moving the Velocity slider.  You can change the "high"
and "low" velocity values by moving the slider while holding Shift
or Ctrl keys.
.PP
Pressing "-" and "+"
keys on numeric keypad changes the octave your keyboard is mapped to.
Pressing "*" and "/" on numeric keypad changes
MIDI program (instrument).  Pressing Insert or Delete keys will
connect \fBjack-keyboard\fR to the next/previous MIDI input port (it will cycle between running
instances of ghostess, for example).  Home and End keys change the MIDI channel.
Page Up and Page Down keys switch the MIDI bank.
.PP
Esc works as a panic key - when you press it, all sound stops.
.SH "SETTING CHANNEL/BANK/PROGRAM NUMBER DIRECTLY"
.PP
To switch directly to a channel, bank or program, enter its number on the numeric
keypad (it won't be shown in any way) and press Home or End (to change channel),
Page Up or Page Down (to change bank) or "/" or "*"
(to change program).  For example, to change to program number 123,
type, on the numeric keypad, "123/", without quotes.
.SH "TITLEBAR"
.PP
When \fB-G\fR xor \fB-T\fR is given, some informational
messages in the title bar appear. They are supposed to be self explanatory.
If you see "bank/program change not sent",
it means that the bank/program numbers as seen in the title bar were not sent.  In other words,
synth the \fBjack-keyboard\fR is connected to may use different values.  This happens
at startup and after switching between synths (using Insert/Delete keys).  To send bank/program
change at startup, use \fB-b\fR and \fB-p\fR parameters.  To automatically
send bank/program change after reconnect, use the \fB-u\fR option.
.SH "PIANOLA MODE"
.PP
In addition to the MIDI output port, \fBjack-keyboard\fR also opens MIDI input (listening) port.
MIDI events going into this port will be passed to the output port unmodified, except for channel number,
which will be set to the one \fBjack-keyboard\fR is configured to use.  Note On and Note Off
MIDI events will cause visible effect (pressing and releasing) on keys, just like if they were being pressed
using keyboard or mouse.
.PP
\fBjack-keyboard\fR will never connect to it's own MIDI input port.  It will also refuse
to connect to any other client whose name begins in "jack-keyboard", unless the "-k" option is given.
It is, however, possible to connect these ports manually, using \fBjack_connect\fR
or \fBqjackctl\fR; this may create feedback loop.
.SH "SEE ALSO"
.PP
\fBjackd\fR(1),
\fBghostess\fR(1),
\fBqjackctl\fR(1)
.SH "BUGS"
.PP
Key grabbing is unreliable.
.PP
Many PC keyboards have problems with polyphony.  For example, with the one I'm using right now,
it's impossible to press "c", "v" and "b" at the same time.  It's a hardware problem, not the
software one.
.PP
The spin widgets used to set channel/bank/program number don't take focus, so the value cannot be entered
into them in the usual way.  It's because \fBjack-keyboard\fR already uses numeric keys
for different purposes.  You can still directly enter channel/bank/program in a way described above.