- Table of Contents
- 1. Introduction
- 2. Configuring QMidiCC
- 3. Using QMidiCC
- 4. Credits and License
- A. Installation
- A.1. How to obtain QMidiCC
- A.2. Requirements
- A.3. Installation Process
- B. Configuration File Format
- B.1. Autostart Clients
- B.2. Patches
- List of Examples
- B-1. Autostart Client Examples
- B-2. Patch Examples
Chapter 1. Introduction
QMidiCC is Q's MidiShare patchbay. MidiShare is Grame's cross-platform MIDI library which provides MIDI scheduling, I/O and standard MIDI file access. On Linux, MidiShare can route MIDI data between different application programs as well as between different clients within the same program. Making the management of these connections between MidiShare clients easy and convenient is what QMidiCC was made for. QMidiCC works mostly like the msconnect program from the MidiShare Linux version 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. This is quite useful under Linux, where MidiShare applications can communicate across different processes, and where you also need separate driver clients to access the MIDI I/O ports.
Using QMidiCC is rather straightforward. After installation the program can be run by just typing qmidicc on the command line. However, to get QMidiCC to work smoothly with your MidiShare drivers and MIDI hardware setup, you probably have to configure some things for your system, so we discuss this first.
Chapter 2. Configuring QMidiCC
Before you run QMidiCC for the first time, you may want to tell it about the MidiShare device drivers and client connections for your system. To these ends, you'll have to take a look at the midiccrc file and modify it for your purposes. QMidiCC will look for this file first in ./.midiccrc, then in ˜/.midiccrc, and finally for the midiccrc file in its installation directory. (The same configuration file is used by both QMidiCC and the basic midicc script included in the Q-Midi distribution, so you can use both applications interchangeably.)
We recommend that you copy the global midiccrc file, either from the installation directory or from the source tarball, to .midiccrc in your home directory, where it can be edited. Follow the comments in the file and change the relevant configuration lines as needed. A brief overview of the configuration file format can be found in Appendix B. The default configuration should work pretty well if you have MidiShare's msAlsaSeq driver installed, but you may have to customize the corresponding entries to reflect your hardware setup, and you may want to edit the lines with the automatic connections configuration.
If you now run QMidiCC, it should display messages from the MidiShare driver programs, indicating whether they are running properly or not. In particular, if you're running the msAlsaSeq driver, it shows the ALSA MIDI devices it connects to, if it can. If it displays some error messages instead (shown in red), you can use a program like QJackCtl or the ALSA command line utilities to check the ALSA MIDI ports on your system and edit your midiccrc file accordingly.
Once you have an initial configuration, you can press the button in QMidiCC at any time to further edit the configuration as needed, and then to reload the configuration and restart the driver programs.
Chapter 3. Using QMidiCC
After configuring it to your liking, you can now fire up QMidiCC before starting your other Q-Midi and MidiShare applications, et voilà, QMidiCC will automagically invoke the configured MidiShare drivers at startup time, and then show the currently registered MidiShare clients and their connections and manage automatic connections of new MidiShare applications according to its configuration. You can also use QMidiCC to connect clients manually as detailed below.
The following screenshot shows QMidiCC in action:
QMidiCC's main window is divided vertically into two panes (as usual, you can drag the sash between the two panes to divide the space between the two panes as you like it). The Clients view in the upper pane of the window shows all MidiShare clients with their reference numbers; you can click on the clients shown there to have their input and output connections displayed in the Inputs and Outputs views. The lower pane of the QMidiCC window is a scrollable text view, the Log, which displays messages from both the driver programs and QMidiCC itself. This lets you check which drivers are loaded and which actions are performed on MidiShare client connections.
For typical usage, you will probably want to keep QMidiCC running all the time and even have it restarted automatically by your session manager at login time. To support such usage, QMidiCC remembers its window size and minimization state and will restore that state when it is run the next time.
3.1. Basic Operations
Selecting and deselecting items in the Inputs and Outputs views changes the connections of the client selected in the Clients view accordingly. The trifold layout of the upper pane (which was shamelessly pilfered from Grame's original msconnect program) lets you change both the inputs and the outputs of a client in one go. Here are the exact steps you need to perform in order to change the connections of a given client:
Select the client to be changed in the center, i.e., Clients, view. Note that the selections in the Inputs and Outputs views are updated to show the current input and output connections of the selected client.
Click on an item in the left-hand, i.e., Inputs, view to change the corresponding connection. Selecting an item in the Inputs view adds a connection from the input client to the target client, deselecting it removes the input connection. Watch the corresponding messages being displayed in the Log view as the actions are performed. Repeat this step as often as you want until the input connections are what you would like them to be.
Output connections, i.e., connections from the target client to an output client, are dealt with in exactly the same manner, by selecting and deselecting items in the right-hand Outputs view.
At the bottom of the main window there is a strip of buttons which let you perform some additional operations. Use the button to edit the midiccrc file and to reload the configuration, restart all drivers and reestablish automatic connections after the configuration has been edited. The button exits the application, as does closing its window. The and buttons are described in the following section.
3.2. Monitoring and Controlling MIDI Applications
QMidiCC is a MidiShare client itself, and can be configured to receive the MIDI output of any other MidiShare client. To these ends, just connect the clients you want to monitor to QMidiCC's input (following the steps explained in the previous section). The received MIDI messages will then be displayed in the Log view as they become available.
Conversely, you can also use QMidiCC to send MIDI messages to other MidiShare clients. Currently, QMidiCC can send the MIDI sequencer start and stop messages, which are useful for transport control (provided that the clients are prepared to deal with these messages). Connect QMidiCC's output to the relevant clients. Now you can push the and button to send the corresponding MIDI messages. Most of the Q MIDI applications, like QMidiPlayer and QFSynth, respond to these messages. You can wire QMidiCC up to multiple clients in this manner to have all clients be started and stopped at the same time, which is useful for synchronization purposes. (E.g., you might want to start a step sequencer program and an instance of QMidiPlayer at the same time to record the performance.)
3.3. Online Help
The help file you're looking at is also available online (you probably discovered this already; otherwise you won't be reading this). You can press the right mouse button anywhere in the QMidiCC window to get a popup menu with the command, which works in a context-sensitive fashion; e.g., if you right-click on the button and select , QMidiCC will show Chapter 2. (This works everywhere except in the Log, where a specialized popup menu with text selection operations is available.) You can also press the F1 key to invoke the online help.
Chapter 4. Credits and License
This document is Copyright © 2007 Albert Gräf. The documentation is licensed under the terms of the GNU Free Documentation License.
QMidiPlayer is Copyright © 2007 Albert Gräf. The program is distributed under the GNU General Public License. This version of QMidiCC is based on an earlier version (0.3) by the same author which was partly written in C++. The new version is now just plain Q, using the new Qt/Q module.
Appendix A. Installation
A.1. How to obtain QMidiCC
QMidiCC is available together with the other Q-Midi applications as a source tarball, as well as source and binary RPM packages, from the Q website at http://q-lang.sourceforge.net.
A.2. Requirements
You'll need the Q programming system, including the Q-Midi and Qt/Q modules, available from the Q website at http://q-lang.sourceforge.net. The Q-Midi and Qt/Q modules in turn require the following libraries:
Grame's MidiShare, available from http://midishare.sourceforge.net. RPMs for MidiShare can be found at http://q-lang.sourceforge.net.
Trolltech's Qt (http://trolltech.com, should be readily available on most if not all Linux distros).
A.3. Installation Process
As with other plain Q scripts, there's no compilation, so just run make install when installing from the sources. You may have to specify the proper installation prefix with prefix=; this should match Q's installation prefix, usually /usr/local or /usr. There are also some icons and desktop files included in the package, which are useful for the KDE and Gnome desktop environments, but these will have to be installed manually. (If you're installing from an RPM, these files should be copied the appropriate locations automatically, so that your application menu will show an entry for QMidiCC after installation.)
path
Appendix B. Configuration File Format
This appendix provides a brief description of the format of the midiccrc configuration file used by the QMidiCC program. Please refer to the file itself for more details and further examples.
The configuration file format is line-oriented. Lines with # in the first column are comments. The remaining lines are partitioned into fields delimited with (one or more) tab characters. (Thus you can use blanks inside fields, but no tabs.). There are two types of entries: autostart entries (typically used for driver programs) and patch entries (describing automatic connections between clients). Autostart entries have three, patch entries two tab-delimited columns. We describe each of these in turn.
B.1. Autostart Clients
Autostart clients are MidiShare clients which are started automatically when running QMidiCC and when clicking the button. These entries are typically used for MidiShare driver programs like msAlsaSeq. Each line has three fields: a brief description (currently unused); the name under which the client is known to MidiShare (this can also be pattern involving the shell wildcards *, ? etc.); and the shell command with which the client is to be invoked. Clients will only be started by QMidiCC if they have not been started already (i.e., only if no client with a name matching the second field has already been registered).
Example B-1. Autostart Client Examples
Here is a basic entry for the msAlsaSeq driver which connects it to ALSA sequencer port 64:0 on both input and output (see the msAlsaSeq manpage for information about the command line options this driver is invoked with):
ALSA Sequencer MidiShare/ALSA Bridge msAlsaSeq -i 64:0 -o 64:0
msAlsaSeq allows you to do much more elaborate setups. Instead of device numbers, you can also specify ALSA devices by their names, and you can even use shell wildcards to denote matching devices. Moreover, it is possible to assign ALSA ports to MidiShare port numbers so that you can address specific hardware ports directly in your MidiShare application. For instance, here is a line I use at home to start up an instance of msAlsaSeq which connects to various different MPU and WaveTable ports of my Soundblaster Live card:
ALSA Sequencer MidiShare/ALSA Bridge msAlsaSeq -i '*MPU*':0/0 -o '*MPU*':0/0 -o '*WaveTable':0/1 -o '*WaveTable':1/2 -o '*WaveTable':2/3 -o '*WaveTable':3/4
Here is another useful line, which I use to connect to an Edirol UM1 USB MIDI device on my laptop:
ALSA Sequencer MidiShare/ALSA Bridge msAlsaSeq -i '*UM1*':0/0 -o '*UM1*':0/0
It is possible to invoke multiple instances of msAlsaSeq under different client names. E.g., I often have a secondary msAlsaSeq instance running which serves as a "proxy" to connect with non-MidiShare MIDI applications such as Rosegarden:
MidiShare/ALSA Proxy MidiShare/ALSA Proxy msAlsaSeq "MidiShare/ALSA Proxy"
Of course you can also run various other MidiShare drivers (which is rarely necessary if you have ALSA, unless for some reason you have to use "raw" MIDI devices):
# Comment Client name Shell command Raw MIDI /dev/midi msRawMidi /dev/midi Network msWANDriver msInetDriver -lat 10 -g 10 -s localhost Fluidsynth fluidsynth fluidsynth -g 1 -m midishare /usr/share/sfbank/creative/default.sf2
B.2. Patches
These entries are used to configure automatic connections between MidiShare clients. The given connections will automatically be established when a new client is registered (no matter whether it is an autostart client or started manually by the user). Each line has two fields: the name of the source and the name of the destination client. Shell wildcards may be used to match multiple clients. Note that if different clients have the same name, connections will be established for each of them.
Example B-2. Patch Examples
The following lines will make QMidiCC autoconnect QMidiPlayer's output to an instance of the msAlsaSeq driver, and its own output to QMidiPlayer's input (so that QMidiPlayer can be controlled with QMidiCC's and buttons).
# Source Target QMidiPlayer MidiShare/ALSA Bridge QMidiCC QMidiPlayer