Real-time MIDI Support
Prev  Part II. Opcodes Overview  Next

Real-time MIDI Support

Csound supports realtime MIDI input and output, as well as input from MIDI files. Realtime MIDI input is activated using the -M (or --midi-device=DEVICE) command line flag. You must specify the device number or name after the -M. For example to use device number 2, you would use something like:

csound -M2 myrtmidi.csd

You can find out the available devices by using an out of range device:

csound -M99 myrtmidi.csd

[Note] Note

This will only work if the MIDI module can be accessed by device number. For alsa, you must first find the device name using:

cat /proc/asound/cards

You must then use something like:

csound -+rtmidi=alsa -M hw:3 myrtmidi.csd

Realtime MIDI output is activated using -Q, using device number or names as shown above.

You can also load a MIDI file using the -F or --midifile=FILE command line flag. The MIDI file is read in realtime, and behaves as if it was being performed or received in realtime. So the csound program is not aware if MIDI input comes from a MIDI file or directly from a MIDI interface.

Once realtime MIDI input and/or output has been activated, opcodes like MIDI Input and MIDI Output will have effect.

When MIDI input is enabled (with -M or -F), each incoming noteon message will generate a note event for an instrument which has the same number as the channel of the event (This means that MIDI controlled instruments are polyphonic by default, since each note will generate a new instance of the instrument.) If you have 1 instrument only, Csound works in omni mode, ie. it responds to all channels into that single instrument. If you have more than one instrument and instrs 1 - 16 , then by default instr 1 -> chn 1, instr 2 -> chn 2, unless you alter the mapping (see massign and pgmassign to change this behavior). If you have more than one instrument, but instr N in between 1 - 16 is missing, then chn N will be routed by default to the lowest order instrument.

See the MIDI/Score Interoperability opcodes for information on designing instruments which can be used from the score or driven by MIDI.

There are several realtime MIDI modules available, you must use the -+rtmidi flag (See -+rtmidi), to specify the module. The default module is portmidi which provides adequate MIDI I/O on all platforms, however for improved performance and reliability some platform specific modules are also provided.

Currently the midi modules available are:

[Tip] Tip

When csound runs, it will process the score and then quit. If there are no events in the score, Csound will exit immediately. If you want to use only MIDI events instead of score events, you need to tell Csound to run for a certain amount of time. This can be done with a dummy f-statement like "f 0 3600".

Virtual MIDI Keyboard

[Virtual MIDI keyboard]

Virtual MIDI keyboard.

The virtual MIDI keyboard module (activated using -+rtmidi=virtual on the command line flags) provides a way of sending realtime MIDI information to Csound without the need of a MIDI device. It can send note information, control changes, bank and program changes on a specified channel. The MIDI information from the virtual keyboard is processed by Csound in exactly the same way as MIDI information that comes from the other MIDI drivers, so if your Csound orchestra is designed to work with hardware MIDI devices, this will also work.

For the device flag (-M), the virtual keyboard uses this to take in the name of a keyboard mapping files. Like all MIDI drivers, a device must be given to activate the driver. If you would like to just use the default settings of the keyboard, simply passing in 0 (i.e. -M0) and the virtual keyboard will use its default settings. If instead of the 0 a name of a file is given, the keyboard will attempt to load the file as a keyboard mapping. If the file could not be opened or read correctly, the default settings will be used.

Keyboard Mapping files allow the user to customize the name and number of banks as well as the name and number of programs per bank. The following example keyboard mapping (named keyboard.map) has inline comments on the file format. This file is also available with the Csound source distribution in the InOut/virtual_keyboard folder. 

# Custom Keyboard Map for Virtual Keyboard
# Steven Yi
#
# USAGE
#
# When using the Virtual Keyboard, you can supply a filename for a mapping
# of banks and programs via the -M flag, for example:
#
# csound -+rtmidi=virtual -Mkeyboard.map my_project.csd
#
# INFORMATION ON THE FORMAT
#
# -lines that start with '#' are comments
# -lines that have [] start new bank definitions,
#  the contents are bankNum=bankName, with bankNum=[1,16384]
# -lines following bank statements are program definitions
#  in the format programNum=programName, with programNum=[1,128]
# -bankNumbers and programNumbers are defined in this file
#  starting with 1, but are converted to midi values (starting
#  with 0) when read
#
# NOTES
#
# -if an invalid bank definition is found, all program
#  defintions that follow will be ignored until a new
#  valid bank definition is found
# -if a valid bank is defined by no valid programs found
#  for that bank, it will default to General MIDI program
#  definitions
# -if an invalid program definition is found, it will be
#  ignored

[1=My Bank]
1=My Test Patch 1
2=My Test Patch 2
30=My Test Patch 30

[2=My Bank2]
1=My Test Patch 1(bank2)
2=My Test Patch 2(bank2)
30=My Test Patch 30(bank3)

The ten sliders up top are by default set to MIDI Controller number 1-10 though they can be changed to whatever one wishes to use. The controller numbers and values of each slider are set per channel, so one may use different settings and values for each channel.

By default there are 128 banks and for each bank 128 patches defaulting to General Midi names. The MIDI bank standard uses 14-bit resolution to support 16384 possible banks, but the bank numbers by default are 0-127. To use values higher than 127, one should use a custom keyboard map and set the desired bank number value for the bank name. The virtual keyboard will correctly transmit the bank number as MSB and LSB with controller numbers 0 and 32.

Beyond the input available from interacting with the GUI via mouse, one may also trigger off MIDI notes by using the ASCII keyboard when the virtual keyboard window is focused. The layout is done much like a tracker and offers two octaves and a major third to trigger, starting from Middle-C (MIDI note 60). The ASCII keyboard MIDI note values are given in the following table.

Table 5. ASCII Keyboard MIDI Note Values

Keyboard Key MIDI Value
z 60
s 61
x 62
d 63
c 64
v 65
g 66
b 67
h 68
n 69
j 70
m 71
q 72
2 73
w 74
3 75
e 76
r 77
5 78
t 79
6 80
y 81
7 82
u 83
i 84
9 85
o 86
0 87
p 88

Here's an example of usage of the virtual MIDI keyboard. It uses the file virtual.csd. 

<CsoundSynthesizer>
<CsOptions>
; Select audio/midi flags here according to platform
; Audio out   Audio in     Virtual MIDI    -M0 is needed anyway
-odac           -iadc    -+rtmidi=virtual -M0
</CsOptions>
<CsInstruments>
; By Mark Jamerson 2007

sr=44100
ksmps=10
nchnls=2

massign 1,1
prealloc 1,10

instr 1  ;Midi FM synth 

inote cpsmidi
iveloc ampmidi 10000
idur = 2
    xtratim 1

kgate oscil 1,10,2
anoise noise 100*inote,.99
acps  samphold anoise,kgate
aosc oscili 1000,acps,1
aout = aosc

; Use controller 7 to control volume
kvol ctrl7 1, 7, 0.2, 1

outs kvol * aout, kvol * aout

endin

</CsInstruments>
<CsScore>
f0 3600
f1 0 1024 10 1 
f2 0 16 7 1 8 0 8
f3 0 1024 10 1 .5 .6 .3 .2 .5

e 
</CsScore>
</CsoundSynthesizer>

Prev  Up  Next
Tuning Opcodes  Home  MIDI input