Ubuntu Manpage: qmidiarp - MIDI arpeggiator and LFO

NAME

       qmidiarp - MIDI arpeggiator and LFO

SYNOPSIS

       qmidiarp [OPTION] [file]
       qmidiarp { --help | --version }

DESCRIPTION

QMidiArp is an advanced MIDI arpeggiator, programmable step sequencer and LFO. It runs
with either JACK MIDI or ALSA MIDI. It can hold any number of arpeggiator or LFO modules
running in parallel. The arpeggiator modules produce sequences depending on the notes sent
to their input port, which is typically connected to a keyboard or another sequencer. The
step sequencer modules allow you to create simple linear, monophonic and globally
transposable sequences similar to the first analog sequencers. The MIDI LFOs independently
produce MIDI controller data of adjustable waveform, time resolution, amplitude and
duration. For each module, an input note filter is available, and the output port and
channel can be set independently. Since the modules use a common sequencer queue, they
are automatically in sync with each other. QMidiArp works with an internal tick resolution
of 192 ticks per beat. The queue can be synchronized to an incoming MIDI realtime clock or
as a JACK transport client. Most of the relevant control elements are accessible via MIDI
controller through a MIDI-learn infrastructure. QMidiArp also has a log tool displaying
the history of incoming MIDI events in colors depending on their type. QMidiArp is based
on the Qt4 toolkit.

General Operation
When no commandline options are given, QMidiArp starts as a JACK MIDI client with an input
port and two output ports. For starting QMidiArp as an ALSA client, use the -a option. A
new arpeggiator or LFO module can be created by clicking one of the Add Arp..., Add LFO...
or Add Step Sequencer... buttons, which will show a new tab with the chosen module in the
main area. The modules can be renamed or removed using the corresponding buttons or menu
functions. Modules can be detached from the main window to control and view them in
parallel. They can be brought back to the main window again by clicking on the icon on the
left side of each module title bar. They can also be aligned side-by-side within the same
window if the main window is stretched sufficiently before reinserting a module. The
entire setup containing all arps, sequences and LFOs in the tab bar along with the
parameters set in the Settings window can be saved to or loaded from a QMidiArp XML file
(.qmax). The tempo of the queue can be set in beats per minute and affects all modules.
The queue is started and stopped by the blue arrow button.

MIDI Clock operation (ALSA MIDI only)
In ALSA mode, QMidiArp runs using its own clock and tempo, but it can optionally use
incoming MIDI clock events as clock and start/stop control source. If the MIDI clock
button right of the tempo box is pressed, the running ALSA queue is stopped, and QMidiArp
will wait for an incoming "MIDI Clock Start" event from an external source connected to
QMidiArp's MIDI input. Once this event is received, the queue is started using MIDI
realtime clock events as clock source. QMidiArp will best remain in sync with the incoming
MIDI clock if its internal tempo value (see above) approximately corresponds to that of
the incoming clock. The MIDI clock tempo is, however, measured while the queue is running.
Therefore, if the tempos of the MIDI clock and that of QMidiArp differ, synchronization
should become stable from the second queue start. The queue will stop when a MIDI Clock
Stop event is received. During MIDI Clock operation, QMidiArp's own clock start and stop
functions as well as adding or loading new setups are disabled. They are enabled again by
unchecking the MIDI clock button.

JACK Transport Client Operation
When the Jack Transport Connect button is pressed, QMidiArp will try to connect to a
running Jack server and then function as a Jack Transport client, i.e. set its tempo and
remain synchronized to a running Jack Transport master. Note that QMidiArp will restart
its queue from zero whenever Jack transport is starting regardless of Jack Transport's
position. This also applies in case of a looping Jack Transport queue. The Jack button
will be released automatically if QMidiArp gets disconnected from Jack by a possible Jack
shutdown or if Jack is not available at connection time.

Note: MIDI Clock and Jack Transport button states will be saved with the QMidiArp session
file, and get active or inactive when a new session file is loaded.

Arpeggiator Modules
QMidiArp's arpeggiators can produce complex patterns derived from the notes played on a
MIDI keyboard. QMidiArp's arpeggiator modules were inspired by the MAP1 hardware
arpeggiator by Rudi Linhard.

Input and Output panels

Each arpeggiator has an Input and an Output panel. The Input panel defines the note range
and the MIDI channel to which the arp is assigned. Notes that pass this Input filter are
sorted by pitch and added to the internal note buffer of the arpeggiator. Incoming notes
that do not match any filter can either be discarded or forwarded to a selectable MIDI
port (see Settings ). The Output panel holds settings for the MIDI channel and output port
to which the arpeggiator notes will be sent.

Arpeggiator Patterns

Arpeggio patterns can be selected and edited in the Pattern panel. Pattern presets are
selectable from a combo box. The currently active pattern is displayed as a piano roll
type screen showing the base notes as streaks. The y-scale of the graphics window
corresponds to the index of the notes in the pattern. Octave changes (see Editing patterns
) are shown as additional horizontal lines. The notes that are eventually sent depend on
the input notes received by the arpeggiator. The received notes notes are attributed in
ascending order to the notes defined in the pattern. For example, a single streak on the
bottom of the arp display ("simple" presets) means that at the first pass through the
pattern, the lowermost note played on the keyboard is played. If a chord is played on the
keyboard and only one note is present in the pattern, only the lowermost pressed note is
output at the first pass through the pattern. For the following repetitions of the
pattern, the chosen "repeat mode" is used to determine the following notes. If the
pattern contains stacked note streaks (chord mode), chords played on the keyboard are also
output as chords with polyphony up to the number of notes defined in the stack.

Repeat Mode

This setting defines the behavior of the arpeggio over several repetitions of the pattern
when the number of notes pressed on the keyboard is higher than the number of notes
present in the pattern. When Repeat Mode is "Up", the next higher note played on the
keyboard is played at each repetition. With "Down", the next lower note is played. With a
single note present in the arp pattern, this creates classical linear arpeggios. This way
even simple patterns like "01" (or even "0") will generate a complete arpeggio. When
"Static" is selected, this classical arpeggio mode will be disabled, and the output notes
remain constant.

Trigger mode

QMidiArp's arpeggiators can run in three modes. "No trigger" will cause the arp running
continuously in synchronization with the internal or external clock source. Even when new
notes are played, they will be output quantized to the running queue. "Kbd restart" will
cause a reset of the playhead position upon the next note to be output, but the output
pattern stays quantized to the queue. When "Kbd trigger" is selected, each new note played
in stakato will trigger the pattern with the timing of the played note.

Editing Arp patterns

Arp patterns are defined by a text sequence containing the notes themselves as numbers
along with control changes for chord, tempo, velocity and octave changes. When the Edit
pattern button in the pattern panel is clicked, the current pattern preset appears as a
text input line. The edited pattern can be stored in the preset list by clicking on the
Store pattern button. The currently active pattern can be removed from the preset list by
clicking on the Remove pattern button. All preset patterns are immediately saved in the
.qmidiarprc resource file when a pattern is stored or removed, and the new pattern list is
made available to the other arps in the tab bar. Pattern presets are automatically loaded
on each application start.

The syntax for the pattern text is as follows:

0..9 : Note indices
+ : One octave up
- : One octave down
= : Reset to standard octave
> : Double tempo
< : Half tempo
. : Reset to standard tempo
( ) : Chord, begin..end,
e.g. (012) would be a chord of the
lowermost three notes in the buffer
/ : Volume up by 20%
\ : Volume down by 20%
d : Double length
h : Half length
p : Pause

Any token is valid until the end of a pattern is reached. The token > will e.g. double the
tempo for all following notes of the pattern. When the loop jumps back to the beginning
of the pattern, the tempo is reset to its initial value, i.e. a quarter note.

Random

The timing, velocity and length of the output notes can be randomized using the sliders in
the Random panel. These settings can be used to make the arpeggiator sound less
mechanical, but if they are set to higher values, they add interesting accents to the
patterns.

Envelope

QMidiArp can modulate the velocity of the arpeggios with an envelope function defined by
Attack time and Release time. If an attack time is set, the velocities of the output notes
are ramped up during the attack time defined in seconds. If a release time is set, notes
released from the keyboard are continued to be output while their velocity is ramped down
linearly and until the release time has reached its end. The envelope function only makes
sense if the sound driven by the arp is velocity-sensitive. It works best with highly
polyphonic patterns such as "Chord Oct 16 A".

Groove

The Groove sliders control a linear shift of timing, length and velocity within each beat
of the output pattern. This can be used to create swing timing and accent. The Groove
settings are adjusted for all arps simultaneously.

LFO Modules
In parallel to the arps, QMidiArp can send MIDI controller data in form of a low frequency
oscillator (LFO) to the assigned output. The LFO data consist of controller events that
are in sync with the arpeggiator queue. The queue has to be in running state to enable the
LFO. Each LFO module has a waveform panel to define the shape of the outgoing data and an
output panel to define MIDI Channel, ALSA port and controller number to be produced. The
waveform can currently be set to Sine, Saw Up, Saw Down, Triangle, Square and Custom. The
frequency of the LFO can be set in muliples and divisors of the arp tempo, such that
frequency of 1 produces one full wave per beat. If frequencies lower than 1 are selected,
the length of the wavetable has to be adjusted correspondingly to produce a full wave. The
time resolution of the LFO determines the number of events produced every beat and can be
adjusted to up to 192 events per beat. Amplitude and offset of the waveform can be
adjusted from 0...127. Low resolutions lead to audibly discrete rythmic controller changes
whereas higher resolution values lead to more continuous waves.

Muting individual wave points

Individual wave points can be muted/unmuted by clicking on the corresponding location in
the wave display with the right mouse button. A muted wave point is shown in darker
color.

Custom Waveforms

When Custom is selected, the waveform can be drawn with the left mouse button in the
waveform display. A calculated waveform is copied to the custom waveform whenever it is
being modified by the mouse. This will overwrite the previous custom waveform with the
currently displayed waveform. As all LFO operations, drawing and muting can be done while
the queue is running, and becomes effective immediately.

Play direction and looping

The play mode can be switched between:

->_> : Forward and Loop
<_<- : Backward and Loop
->_< : Forward and Bounce
>_<- : Backward and Bounce
->_| : Forward Single shot
|_<- : Backward Single shot

The direction and loop settings apply immediately when changed on the fly.

Recording

The LFO records incoming controller data as selected in the Input panel, when the Record
button is pressed. Note that the Record button itself can be attributed to a MIDI toggle
controller so that it provides a convenient implementation of a controller motion sampler
and looper.

LFO Input panel

The input panel contains settings on which MIDI CC is to be recorded, how the LFO acts to
note events received on the input. As the arpeggiators, the LFO can be restarted or (re-)
triggered by notes played on the keyboard, and the wave output can be stopped or not when
Note Off events are received on the input Channel

LFO Output panel

The LFO output panel contains the port, channel and controller number settings of the LFO
data produced by each LFO tab. You can also mute each LFO wave.

Step Sequencer Modules
By clicking Add Step Sequencer... in the control tool bar, a new Seq module can be added
to the tab bar. Each of these modules produce a simple linear (monophonic) sequence,
similar to the first analog hardware sequencers. The Seq modules are controllable while
running, also in a similar way to analog step sequencers.

Programming a sequence

As QMidiArp's LFO modules, the step sequencer can be programmed by adjusting notes with
left mouse clicks on the sequence display. The octave range is fixed to 4. The lowest note
is C2 if the global transpose is set to 0. Notes can be muted with the right mouse click.
The sequence length can be adjusted between 1 and 8 beats, and the time resolution can be
set to values between 1 and 16 per beat. A resolution of 4 means that 4 notes are output
every beat, i.e. sixteenth notes. The sequence can also be programmed using the Record
function. When the Record button is pressed, notes received on the input port will be
recorded step-by-step starting from the last modified note. Programming can be done on the
fly also when the sequencer queue is running.

Controlling the sequence globally

There are sliders to adjust the global velocity (volume), note length and transpose of the
sequence in semitones.

Seq Input and Output panels

The Seq Input panel determines how to handle incoming notes on the MIDI Channel set in the
channel box. If Note is checked, the sequence will be globally transposed with the
incoming note as transpose value. If Velocity is checked in addition, the sequence will
output notes with the same velocity as that received on its input. The Input panel also
determines how the sequence behaves when incoming notes are received. It can be restarted,
triggered and stopped with the timing of received notes as the LFO modules.

The Seq Output panel is equivalent to that of arpeggiator and LFO modules.

Note that accents within a pattern can be produced by running LFO modules in parallel to
the Seq module, and by sending to the same channel and port as the Seq module.

Settings
The Settings window allows one to configure if and to which port incoming events that do
not match any module's input filter are forwarded ( unmatched events). It also allows one
to set whether incoming controller events are recognized for muting and controlling the
modules separately. If this option is set, QMidiArp will recognize MIDI control events
that can be attributed to different parameters (see MIDI Control ). By checking the
compact module style all new created modules will show with small GUI elements to be more
economic in space when distributed as separate windows over the desktop.

All settings in this dialog are stored along with the module data in the qmax session
file.

MIDI control
QMidiArp supports MIDI control events if the Modules controllable by MIDI CC option is
checked in the Settings dialog.

MIDI Learn

Controllers can be attributed by right-clicking on the sliders or mute checkbox in each
module and selecting MIDI Learn. QMidiArp will then wait for MIDI control events, and
moving a MIDI controller connected to QMidiArp's input will attribute this controller to
the control item. It is possible to add several MIDI controllers to one item. If MIDI
Forget is selected, all controllers for that item are removed. If Cancel MIDI learning is
selected, the learn process is stopped.

Note that by default, mute controllers are interpreted as toggles, i.e. the mute state is
toggled on reception of a value of 127 from the attributed controller.

Control Editor

The Control Editor is accessible from the View menu. Controls can be edited by MIDI
control number, channel, and the minimum and maximum values that are sent to the control
item. Mute controllers have a special behaviour. If minimum and maximum are equal, the
controller acts as toggler upon reception of the adjusted value. If minimum is different
from maximum, the corresponding module will be muted upon reception of minimum and unmuted
upon reception of maximum as values.

If Remove is pressed, the currently selected line will be removed, pressing Revert reloads
the current controller settings. Pressing Cancel quits the control editor without applying
changes, and only if OK is pressed, the edited control list becomes active.

Global Storage
There is another dock window available for storing and restoring most of the parameters of
all modules at once. In this window, each module and its storages appear as a column, the
first column representing switches for all modules globally. When the small Store button
on the left is clicked, all modules will store their parameters in a location given by the
current row, and the next available storage location appears. Module storages can be
recalled by clicking on the buttons of each individual module or globally (numbered
buttons in the first column). Storage locations can be removed again by clicking on the
"arrow" button on the bottom of the list. When a new module is added at a time when
storage locations already exist for other modules, the storage locations for the new
module will be empty and can be filled by using Store again at this location.

When QMidiArp is running, the switch behavior will depend on the selection made in the
comboboxes in the first row of the window.

End of will cause parameter switches to occur when the module in the second combobox
reaches its pattern end. When individual switches are done the module in the column of the
clicked module determines the switch time.

After will do parameter switches at the end of the number of beats selected in the second
combobox after the restore button is clicked.

The switch can be done by MIDI controller assigned by the MIDI Learn context menu of the
top button of each column. Note that it is the the controller value that corresponds to
the storage location, and that you may want to adjust the range of controllers to your
needs using the MIDI Control Editor With the Global Storage handler, QMidiArp can act as a
simple but handy live sequencer tool. But the Golbal Storage button in the View menu and
in the main toolbar toggles visibility of the Global Storage window.

Event Log
The Event Log displays incoming MIDI events. It is displayed in the bottom area by
default, but can be hidden if not needed or set floating as a top-level window on the
desktop. Logging can also be disabled generally or for MIDI Clock events only.

Example Files
There are currently three demo arpeggios. The demo.qma arpeggio was intended to be used
with the following sound types: Ch 1: Marimba, Ch 2: Celesta, Ch 3: Acoustic Bass, but you
can get interesting results if you use other instrument settings.

The demo_seqlfo.qmax setup shows the use of the new sequencer and LFO modules playing in
parallel. The sequencer outputs should be routed to percussive synthesizer sounds. The LFO
data is intended to act on filter cutoff, which has the standard controller CC#74.
ZynAddSubFX by Paul Nasca reacts on these filter cutoff controllers. The "Bass 1" and
"Plucked 3" presets from this synthesizer work well with this demo file.

OPTIONS

       --portCount <num>
              Set the number of available ALSA output ports to <num>. The default is 2.

       --help Print possible command-line options and exit.

       --version
              Print version information and exit.

       --alsa Use the ALSA MIDI backend

       --jack Use the JACK MIDI backend (default)

       file   Name of a valid QMidiArp (.qmax) XML file to be loaded on start.

FILES

       *.qmax
              QMidiArp XML files containing session data in XML text format.

EXAMPLES

       Example QMidiArp files can be found in /usr/share/qmidiarp or in /usr/local/share/qmidiarp

NOTES

       Errors and warnings are written to stderr(3).

SUPPORT

       qmidiarp-devel@lists.sourceforge.net

AUTHORS

       Frank  Kober,  Nedko  Arnaudov,  Guido  Scholz  and Matthias Nagorni. This manual page was
       written by Frank Kober <emuse@users.sourceforge.net>.

                                            2011-11-07                                QMIDIARP(1)