
Q-Midi
======

This is the Q MIDI module, which allows you to create simple MIDI applications
with the Q programming language. The module runs on top of Grame's excellent
portable MidiShare package, see http://www.grame.fr/MidiShare/. The currently
supported platforms are Linux, Mac OS X and Windows.

As of release 1.6, this module has been dubbed "stable". There's no real
manual yet, but see below for essential information to get you started. Please
also refer to the the midi.q script and the MidiShare developer documentation
for more information. Some basic examples can be found in the midi_examp.q
script provided with the package. Moreover, some useful applications come
bundled with this Q-Midi release; see the end of this file for details.

This package is distributed under the GPL V2 (see COPYING), and requires the Q
programming system, which can be found at the Q homepage:

	http://q-lang.sourceforge.net.

Make sure you get Q version 7.1 or later. Use one of the binary packages of
the Q programming system, if you can. These already include the Q-Midi module;
the Windows package (Qpad-*.msi) also contains the necessary dlls and config
files for running MidiShare under Windows. On Linux and other systems you will
have to install MidiShare separately (MidiShare rpms are available from the Q
website as well). For installation from source see the comments below.


INSTALLATION - LINUX
============ = =====

If you want to or need to compile this module from the sources, you'll need
both the MidiShare and POSIX thread libraries, and an installed version of the
Q core system. See INSTALL for generic UNIX installation instructions. If you
have the required libraries installed in the standard locations, running

	./configure; make; make install

should do the job. Make sure that you get the installation prefix right (it
should match Q's installation prefix). If necessary, you can specify the
prefix with configure's --prefix option. You might also wish to add some
compilation options. E.g.:

	CFLAGS=-O3 ./configure --prefix=/usr; make; make install

Note that the Linux version of MidiShare consists of both a shared library and
a kernel module. Q-Midi won't work unless the kernel module is running on your
system. You can either start up the module manually (with modprobe) or install
a startup script in your /etc/init.d directory which starts the module at boot
time; see the MidiShare docs for details. (This is all taken care of
automatically when you install the midishare rpm available on the Q homepage.)

To verify that everything has been installed properly, fire up the midi.q
script and evaluate `midi_ready'; it should return `true'. If the midi module
does not load (you'll see an error message and complaints about a lot of
unresolved externals in this case) then probably libMidiShare.so is missing.
If the module loads, but `midi_ready' returns `false' then maybe the MidiShare
kernel module is not running. You can verify this with `lsmod | grep
MidiShare'. If the module runs but `midi_ready' still returns `false' then
maybe the MidiShare device node is missing; you can create it manually with
`mknod /dev/MidiShare c 151 0' (`mknod /dev/MidiShare c 120 0' for MidiShare
versions >=1.90).

Finally, to actually get some sound you need to run a driver which you can
connect your Q-Midi and other MidiShare applications to. (This can also be
taken care of by running the midicc application described at the end of this
file.) Various drivers are distributed with MidiShare. Unless you really need
to use OSS, we recommend going with the new MidiShare/ALSA driver, msAlsaSeq,
which is included in all recent MidiShare versions; this driver is also
included in the latest versions of the MidiShare rpms provided on the Q
homepage. It allows you to connect your MidiShare applications to arbitrary
ALSA devices and other ALSA sequencer clients, and to map the ALSA client
ports to corresponding MidiShare ports; see the msAlsaSeq(1) man page for
details.

You might also wish to take a look at some of the other tools distributed with
MidiShare, like the msconnect and msdisplay programs, which are *very* useful
for debugging purposes.

Another fine program is fluidsynth (formerly called iiwusynth), available from
http://www.fluidsynth.org/. This is a SoundFont-compatible software
synthesizer which can be run as an ALSA or MidiShare client, in order to
render MIDI on your soundcard instead of an external MIDI device. (Note that
fluidsynth does not require a SoundFont-compatible soundcard, so any type of
soundcard will do. You just need a suitable SoundFont file. If you do have a
SoundFont-compatible soundcard like the SBLive, you should be able to find
suitable SoundFont files on your driver CD. On http://alsa.opensrc.org/ you
can find some links to SoundFonts on the web.)


INSTALLATION - OS X
============ = == =

Get MidiShare at http://www.grame.fr/MidiShare/ and install it on your
system. There is a binary release available for OS X, thus you might wish to
use that (you need both the user and the developer kit). Follow the
instructions in the application directory to define the MIDI ports with the
msDrivers application.

To compile the Q-Midi module from the sources, you need Apple's developer
toolkit (gcc and friends). Unpack the Q-Midi sources, configure and compile as
usual:

	./configure; make; make install

Make sure that you get the installation prefix right (it should match Q's
installation prefix). If necessary, you can specify the prefix with
configure's --prefix option. You might also wish to add some compilation
options. E.g.:

	CFLAGS=-O3 ./configure --prefix=/usr; make; make install

NOTE: Apparently recent versions of the MidiShare binaries for OSX provide the
MidiShare library as a framework instead of an ordinary system library. To
compile Q-Midi with those versions you'll have to fiddle around with the
linker options (replace -lMidiShare with something like -framework MidiShare).


INSTALLATION - WINDOWS
============ = =======

(Tested on Windows 98/2K/ME/XP.)

To get the software, just install the Qpad-<version>.msi package from the Q
homepage; this includes the Q-Midi module (among lots of other goodies).

If you have not installed MidiShare before, you'll have to configure the MIDI
driver ports. To do this, run the msDrivers program from the Qpad folder in
the start menu, following the instructions in the MidiShare Docs\Setup.html
file; a link to this file can also be found in the start menu.

After running msDrivers, you should have a file named msMMSystem.ini in your
Windows folder which contains the port definitions you made. (If, for some
reason that file is created somewhere else, make sure you move it to the
Windows folder.) You can rerun msDrivers at any time to change the port
definitions (but make sure that you have no other Q-Midi/MidiShare
applications running while doing so).


USAGE
=====

Once Q-Midi has been installed, you can give it a try. Go to the examples/midi
directory and run the midi_examp.q script with the Q interpreter. Evaluate
`record' and play some notes on your keyboard. Press <CR> to finish the
recording. If everything has been configured properly, the recorded sequence
should be printed as a list of (TIME,MSG) pairs, and you can play back the
sequence with `play _'; press <CR> again to terminate the playback. To play
the prelude3.mid file included in the distribution, evaluate `play (load
"prelude3.mid")'.

To use the MIDI interface in your own scripts, just include/import the midi.q
script. Take midi_examp.q as a start and modify it for your purposes. Have
fun. :)


PROGRAMMING
===========

Most of the basic MidiShare functionality is implemented in this release, and
appropriate data types and external functions are provided to handle MidiShare
clients and connections, MIDI I/O, and MIDI file access. The interface is
divided into several different sections described in the following.


GENERAL FUNCTIONS
======= =========

The `midi_ready' and `midi_version' functions are used to check that MidiShare
is up and running, and which MidiShare version is installed on your system.
Note that if `midi_ready' returns false, then *all* other operations of this
module will fail.

Some functions for managing MidiShare's internal event memory are also
provided. The `midi_total_space' function returns the total number of event
cells in the memory pool, `midi_free_space' the number of currently unused
cells available to clients. At startup, Q-Midi makes sure that a reasonably
large number (usually 60000) of cells is available. This should suffice for
most applications. However, some functions of this module may fail if not
enough internal memory is available to complete the operation. This can
happen, e.g., when reading huge tracks from a MIDI file. In this case you can
increase the size of the internal memory pool with the `midi_grow_space'
function.


MIDI MESSAGE TYPE
==== ======= ====

For convenience, MIDI messages are not represented as raw byte sequences, but
are mapped into constructor terms of the `MidiMsg' type. Take a look at the
definition of this type in midi.q to see which types of messages are supported
and how they are encoded. The messages listed there should cover just about
anything that you'll ever encounter in a MIDI file or on an instrument, plus
some MidiShare-specific extensions. For instance, a "note on" message will be
represented as `note_on CHAN PITCH VEL', and a "system exclusive" message will
look like `sysex [BYTE1,BYTE2,...]'. Pretty obvious, isn't it? The other types
of messages are encoded in a fairly straightforward manner as well.

We do not describe the semantics of the different messages here; you can find
a closer description of all standard MIDI messages (albeit in raw format) on
http://www.borg.com/~jglatt/. The MidiShare-specific messages supported in
this release are:

- `note CHAN PITCH VEL DUR': a note sounding for a duration DUR. On output to
  a MIDI device, MidiShare will expand this to a sequence of "note on" and
  "off" messages with the appropriate timing.

- `ctrl14b_change CHAN CTRL VAL': set the value of a 14 bit controller CTRL in
  the range 0..31. This can be used to replace two separate `ctrl_change'
  messages affecting corresponding coarse and fine controllers.

- `non_reg_param CHAN PARAM VAL', `reg_param CHAN PARAM VAL': set (non-)
  registered parameters with a single message. This expands to a corresponding
  sequence of controller messages.

- `midi_stream [BYTE1,BYTE2,...]': this message allows you to send raw
  (unencoded) MIDI messages as a literal byte stream.

Other (mostly internal) MidiShare-specific messages are encoded as the
constant `unknown' if they are encountered in a MIDI stream.

Besides the MidiMsg type itself, the module also provides various functions
for determining the category of a message (is_voice, is_system_common, etc.),
and to check for specific messages (is_note_on, is_note_off, ...). These are
useful, e.g., for filtering purposes.


DRIVER MANAGEMENT
====== ==========

These functions allow you to determine which MidiShare drivers are loaded,
which hardware ports ("slots") they have, and how the 256 logical MidiShare
ports are connected to the driver ports. Note that only the application-side
subset of MidiShare's driver management functions are provided. Also note that
these operations are currently *not* supported in the Linux version, where
drivers are implemented as ordinary (userland) MidiShare clients.

The `midi_drivers' function returns the reference numbers of all loaded
drivers. Information about a specific driver can be retrieved with
`midi_driver_info'. Driver information is represented as a triple
(NAME,VERSION,SLOTS) denoting the name of the driver, its version number (an
integer) and a list of the slots it provides. Each slot is given as a pair
consisting of the driver number and a slot number.

Information about a driver slot is encoded as a triple (NAME,DIR,PORTS)
denoting the name of the slot, its direction (1 = input only, 2 = output only,
3 = input and output), and a list of the MidiShare ports it is connected
to. This information can be retrieved with `midi_slot_info'.

The `midi_slot_connect' and `midi_slot_disconnect' operations allow you to
specify how the 256 logical MidiShare ports are connected to the physical
driver slots. The current status of a connection can be verified with
`midi_slot_connected'.

Moreover, some convenience functions (`midi_ports', `midi_slots' and
`midi_port_info') are provided to see which ports and slots are available on
your system, and which slots a given port is connected to.


SESSION MANAGEMENT
======= ==========

In order to perform MIDI I/O, you first have to register a client (also called
an "application" in the MidiShare documentation) with MidiShare. Each client
has a name (a string) and a reference number (an integer) by which it is known
to the MidiShare system. The name is set with the `midi_open' function. The
reference number returned by `midi_open' can then be used in MIDI I/O
operations. A client is removed with the `midi_close' function, or
automatically when exiting the Q interpreter. Multiple clients can be
registered in a single Q script, which is useful if several tasks each
performing their own MIDI I/O have to be executed.

Note that most of the MIDI file and I/O related operations of this module will
only work properly if at least one client has been registered. This is
achieved most easily by including a definition like

	def REF = midi_open "myapp";

in your script.

The list of (the reference numbers of) all clients currently known to the
MidiShare system -- including clients registered by other application programs
-- can be retrieved with the `midi_clients' function. (Note that you'll only
see MidiShare clients registered by other processes in the Linux version.  The
MidiShare "monoapp" versions under Windows and OSX can only access clients
within the same address space, i.e., the clients must reside in the same
process.) You can also get and set the name of a client with the
`midi_client_name' and `midi_set_client_name' routines. Finally, the reference
number of a client given by its name can be obtained with `midi_client_ref'.

Moreover, the module also provides a convenience function for accessing an
"external" client, starting up the client with a shell command if necessary.
This is most useful for managing drivers and other clients under Linux. The
`midi_client' function looks for the reference number of a client given by its
name, and, if the client is not present already, it will start the client with
the given shell command and wait until it shows up in the client list. In
either case, the function returns the client's reference number. Note that the
client's startup command should be run in the background (if necessary, use
`&' at the end of the command to achieve this).


CONNECTION MANAGEMENT
========== ==========

The `midi_connect' and `midi_disconnect' functions are used to specify how
MIDI messages are to be routed between different clients (including clients
hosted by other application programs). When a MIDI message is sent from a
given client, it will be routed to all target clients to which the source
client is connected. The status of existing connections can be checked with
the `midi_connected' function. Moreover, the `midi_in_connections' and
`midi_out_connections' convenience functions return the lists of clients for
incoming and outgoing connections of the given client, respectively.

Note again that currently only the Linux version of MidiShare allows you to
directly connect to MidiShare clients in other processes. Under Windows and
OS X, you can employ virtual MIDI "loopback" devices and a MIDI routing
software (such as MidiYoke/MidiOX under Windows, see http://www.midiox.com) to
work around this limitation.

These routines are also used to connect a client to physical MIDI devices.
Under OS X and Windows, it is sufficient to connect with client #0 (the
predefined "MidiShare" client) which manages the MIDI I/O drivers according to
the port definitions specified with the msDrivers application. Under Linux,
drivers are currently implemented as ordinary clients, such as the msAlsaSeq
and msRawMidi drivers distributed with the Linux version of MidiShare. Here
you have to connect directly with the MIDI driver client which you want to
use.

As of Q-Midi 1.16, the midi.q script provides the function `midishare_client'
to connect an application to MIDI input/output in a portable manner. Here's
some boilerplate code showing how this function is to be used:

def DRV = midishare_client, REF = midi_open "myapp",
  _ = midi_connect DRV REF || midi_connect REF DRV;

Under Linux, you can also automate the process of connecting MidiShare
applications to various (driver) clients, and even arrange for drivers to be
started automatically, using the midicc application which is discussed at the
end of this file.


FILTERING
=========

These functions allow you to determine the messages a client wants to receive
with `midi_get' (see MIDI MESSAGING, below). By default, all ports, channels
and message types are received. The `midi_accept_port', `midi_accept_chan' and
`midi_accept_type' functions can be used to restrict the messages which are
received by a client, on the basis of the source/destination port, channel,
and type of a message. Message types are specified using the corresponding
constructor symbol, as in `midi_accept_type REF ctrl_change false' which will
cause all ctrl_change messages to be suppressed. For convenience, some
predefined lists of message constructors let you specify the various message
types. E.g., filtering out all voice messages for a given client REF can be
done as follows:

	do (flip (midi_accept_type REF) false) voice

The current filter states can be checked with `midi_is_accepted_port',
`midi_is_accepted_chan' and `midi_is_accepted_type'. To turn off all filtering
you can use the `midi_accept_all' function.


TIMING
======

MidiShare maintains an internal 32 bit time value which counts the time in
milliseconds which elapsed since MidiShare was last activated. The current
value of this counter can be accessed with the `midi_time' function. A client
can also wait for a specific time to arrive with the `midi_wait' function,
which sleeps until the given time and then returns that time value. (The TIME
argument of `midi_wait' is taken modulo 0x100000000 automatically, so you do
not have to worry about wrapover at the end of the time range.) Applications
typically use this function to perform scheduling of MIDI events.


MIDI MESSAGING
==== =========

The `midi_send' and `midi_get' routines provide the basic functionality of
sending and receiving MIDI events.

Use `midi_send REF PORT MSG' to send a MIDI message MSG (of type `MidiMsg')
immediately, where REF denotes the sending client and PORT the destination
port. (Under OS X and Windows, the ports are associated with hardware devices
using the msDrivers application. Under Linux, the msAlsaSeq driver allows you
to achieve the same effect with its -i and -o options, see msAlsaSeq(1) for
details.) Instead of MSG, you can also specify a (TIME,MSG) pair to send MSG
at the specified TIME value, which is taken modulo 0x100000000
automagically. The message will then be sent by MidiShare when the current
`midi_time' (see above) becomes equal to TIME.

Incoming MIDI messages are received with the `midi_get' function which returns
a (REF,PORT,TIME,MSG) tuple denoting the reference number of the client the
message was received from, the port of the message (which will be the source
port if the message was received from a MIDI I/O driver, and the destination
port specified with `midi_send' if the message was received from a regular
client), the time when the message was received, and the message (of type
`MidiMsg') itself. Note that unlike the corresponding MidiShare function
MidiGetEv, this function is blocking, i.e., it waits for a message to become
available. You can also check beforehand whether a message is currently
available with the `midi_avail' function, and empty a client's input queue
with the `midi_flush' function.


REALTIME ISSUES
======== ======

When implementing a realtime loop (such as a sequencer or an arpeggiator) it
is often essential that timing is performed very accurately and MIDI events
are always processed immediately. This can only be guaranteed when the thread
executing the realtime loop runs at a high priority, which can be achieved
with clib's setsched function (see the Clib section in the Q manual for
details). An example for the use of setsched in realtime Q-Midi programs can
be found in midi_examp.q.


MIDI FILE I/O
==== ==== ===

These functions let you read and write MIDI files. MIDI files are represented
using the extern `MidiFile' type. Objects of this type are returned by the
`midi_file_open', `midi_file_append' and `midi_file_create' functions, which
open a file for reading, append to an existing file and create a new file,
respectively. Each of these functions takes the name of the file to be opened
as its (first) argument. A `MidiFile' object can be closed with the
`midi_file_close' function (this operation is also performed automatically
when a `MidiFile' object is garbage-collected).

MIDI files can have one of three formats, 0 = single track, 1 = multiple
tracks/single song, 2 = multiple tracks/multiple songs. By definition, a
format 0 file consists of a single track, into which all MIDI events go. A
format 1 file (the most common format used by sequencers) contains several
tracks forming a single piece; the tempo map of the piece is to be found in
the first track. A format 2 file has several independent tracks which are
to be played separately; in this case each track contains its own tempo
map.

The MIDI file header information also describes how many tracks the file
contains and which "division" the timestamps of events in the file are based
upon. The division can be either a number denoting pulses per quarter note
(PPQN), or an SMPTE type division consisting of a number of frames per seconds
(24, 25, 29 or 30) together with the number of subdivisions of each frame. In
Q land, division is represented either as an integer (PPQN) or as a
(FRAMES_PER_SEC,TICKS_PER_FRAME) pair.

The MIDI file header information can be determined with the
`midi_file_format', `midi_file_division' and `midi_file_num_tracks'
functions. Moreover, the "current" time of the file (time of the last event
read or written) can be retrieved with the `midi_file_time' function, and you
can check whether the file has been opened for reading or writing with the
`midi_file_mode' function.

For both reading and writing, the events in each track are represented as
(TIME,MSG) pairs, where TIME is the time of the event and MSG is the MIDI
message of type `MidiMsg'. Tracks are represented as event lists. Note that
the time values are always absolute (zero-based) timestamps, whereas they are
actually stored as "deltas" (time difference w.r.t. the previous event) in a
MIDI file. Moreover, the timestamps are measured in "ticks", i.e., in the unit
specified by "division", thus you'll have to use the value of "division" and
the tempo map of the piece to tranform these values to milliseconds, if you
want to play back the sequence.

The tracks in a MIDI file opened for reading can be accessed in sequence,
either by reading whole tracks at once with `midi_file_read_track', or by
opening a track with `midi_open_track' and reading individual events from it
with `midi_file_read'. The `midi_file_read' function will fail (and the track
will be closed, advancing the file pointer to the next track) when no more
events are available. (In case of another error condition, like a format
error, `midi_file_read' will fail as well, but the track will remain open. You
can check for this condition with the `midi_file_track_open' function.) You
can also close a track explicitly with the `midi_file_close_track' function.

Moreover, when a  MIDI file has been opened for reading, you can position the
file pointer at an arbitrary track with `midi_file_choose_track', which takes
a zero-based track index as argument.

Creating a new or appending to an existing MIDI file works analogously. A new
track is written at the end of the file with the `midi_file_write_track'
function. You can also use `midi_file_new_track', `midi_file_write' and
`midi_file_close_track' to write a track event by event.

Note that random track access is not supported while writing, i.e., the
`midi_file_choose_track' function can only be used while reading a file. New
tracks can only be added at the end of the file.


APPLICATIONS
============

This Q-Midi release comes bundled with some useful applications. Currently
there's a graphical MIDI player which lets you record and play back MIDI
sequences, and midicc, a variation of the MidiShare msconnect program which
also lets you manage driver clients and connections between different Q-Midi
and MidiShare applications under Linux. Both programs require Tcl/Tk.

If you are using Linux, you should also take a look at the Qt/KDE based
applications on the Q website (see http://q-lang.sf.net/examples.html), which
include much nicer replacements for the MIDI player and midicc program in this
package.


MIDI PLAYER
==== ======

The midi_player.q script provides some additional utility functions for MIDI
programming. The main function, `midi_player', lets you play back and record
multi-track MIDI sequences using a graphical application implemented using the
Q-Tk interface.

This version of the midi_player script comes bundled with Q-Midi. The script
requires Tcl/Tk 8.3 or later, available from http://www.tcl.tk/.

The script can be run directly from the source directory. It will also be
installed in the Q library directory.

USAGE
-----

NOTE: As of version Q-Midi 2.1, if you wish to use the midi_player.q script
directly in the interpreter, you'll have to set up your QPATH so that it
points to <prefix>/share/q/apps/midi_player, where <prefix> is the Q
installation prefix.

Run the script interactively with the interpreter as follows:

	$ q -i midi_player

To invoke the player from the Q interpreter you can then use a command like
the following:

	==> midi_player SEQ

where SEQ either denotes the name of a MIDI file, or a time-ordered list of
(TRACK,TIME,MSG) triples forming a MIDI sequence. There also is a function
`midi_play' which works like `midi_player' but starts playback immediately.
Likewise, the `midi_record' function starts up the player in recording mode.

To use the player in your own scripts, simply put an import or include
declaration like

	import midi_player;

near the beginning of your script. See the beginning of midi_player.q for an
overview of the operations provided by the script.

On Linux and OS X you can also invoke the script directly from the shell as
follows:

	$ midi_player midi-file

The midi-file name is optional. You can also run `midi_player -help' or
`midi_player -h' to get a brief help message.

Usage of the player application is fairly straightforward. In the current
version, output always goes to MidiShare port 0 (you can change this at the
beginning of the script). The main window is divided into a menu bar, a
toolbar with the usual pushbutton controls (play, record, stop, etc.), a text
area in which MIDI messages are printed while a sequence is played or
recorded, and a status line.

MIDI messages are printed in the text area in a 5-column format:

5872580    0:00:000   1   seq_name "Track 1"
5872643    0:00:063   1   note_on 0 48 127     C 4

The value in the leftmost column is the MidiShare time, the second column
shows the current sequence time in minutes:seconds:milliseconds. The third
column shows the track number of the message, and the fourth column is the
message itself (as it would be printed in the Q interpreter). In the case of
note on/off messages, the note name is printed in the fifth column (using
standard MIDI note names, i.e., note 60 a.k.a. middle C is denoted C5).

The status line gives feedback on some operations and displays the current
mode ("PLAY" while playing back, "REC" while recording, and "IDLE" otherwise).

Note that multiple tracks can be recorded during a single player session. When
finished with a track, use the `New track' command (Ctrl+K) to create a new
track. Subsequent recordings will use the new track. The number of the current
record track is shown in the status line.

MENU
----

The menu offers the following operations (with keyboard shortcuts given in
parentheses):

File menu:

New (Ctrl+N)		- create a new sequence (also deletes all recorded
			  events without asking, so be careful!)
Open (Ctrl+O)		- load a new sequence from a MIDI file
Save (Ctrl+S)		- save the sequence under its name
Save as			- save the sequence under a new name
New track (Ctrl+K)	- switch to a new track for recording
Clear log (Ctrl+C)	- clear the text area
Quit (Ctrl+Q)		- exit the application

Help menu:

About			- show a message box with some information about
			  the program

TOOLBAR
-------

The toolbar consists of three buttons to create a new sequence, load and save
a MIDI file (equivalent to the New, Open and Save commands in the File menu),
a progress bar, and a collection of transport controls.

The transport controls, from left to right, are the following (with keyboard
shortcuts given in parentheses):

Start (Ctrl+A)		- go to the beginning of the sequence
Play (Ctrl+P)		- start playing at the current position
Record (Ctrl+R)		- start recording (while playing back the current
			  sequence) at the current position
Stop (Ctrl+T)		- stop playback/recording, save recorded events
Cancel (Ctrl+X)		- stop recording, scratch the recorded events
End (Ctrl+E)		- go to the end of the sequence

At the right end of the toolbar there is another "New track" button which is
equivalent to the corresponding menu command.

You can also start and stop playback/recording by sending start/stop messages
from your MIDI keyboard.

To the left of the transport controls there is a progress scale which shows
the current position in the sequence. When playback is stopped you can drag
the scale slider to move the song pointer to a new position.

DEVELOPER NOTES
--------- -----

The source code is in midi_player.q, the Tcl/Tk interface in midi_player.tcl.
The latter has been created with vtcl 1.6, a visual GUI builder for Tcl/Tk
available from SourceForge.


MIDICC
======

Midicc is Q-Midi's "MIDI control center", which has been written for the Linux
version of MidiShare, to facilitate the task of starting the driver clients
and managing connections between drivers and other Q-Midi and MidiShare
applications.

The program works mostly like msconnect from the MidiShare distribution in
that you can inspect currently running MidiShare clients and modify their
connections. In addition, it automagically starts clients and establishes
connections as specified in the midiccrc config file.

USAGE
-----

Take a look at the midiccrc file and modify for your purposes. Midicc will
look for its config file first in ./.midiccrc, then in ~/.midiccrc and finally
for the midiccrc file in its installation directory (usually <prefix>/share/q/
apps/midicc). That way you can have a global default setup, your personal
setup in your home directory, and other special setups for different projects
in various subdirectories.

Now fire up midicc before starting any other Q-Midi and MidiShare programs.
Your autostart clients (usually drivers) will be started, and whenever you run
a new client its connections will be established automatically as specified in
the midiccrc file. To inspect the connections of a client, select that client
in the middle "Client" listbox. The client's inputs and outputs will be
highlighted in the left ("Input") and right ("Output") listboxes and you can
toggle the state of connections on the fly by clicking on the source and
destination clients, just as with the msconnect program.

In the text window in the lower half of the main window midicc logs the output
from the autostarted clients, and also prints MIDI output received from other
clients connected to the midicc client. When clicking on the transport buttons
in the lower left of the window, midicc sends start and stop messages to the
clients it is connected to. The three buttons on the lower right let you edit
the current config file, restart the autostart clients (this also causes the
config file to be reloaded) and exit the program.


Enjoy! :)

October 2007
Albert Graef
ag@muwiinfa.geschichte.uni-mainz.de, Dr.Graef@t-online.de
http://www.musikinformatik.uni-mainz.de/ag
