Csound~ Manual

csound~ Manual

This is the manual for csound~ v1.0.3.
Manuals for earlier versions are contained within their respective archive files.

What is csound~?

Arguments for csound~

Inlets & Outlets

Csound Flags

Csound Score Events

MIDI

Recording & Playing Events

Where to Put Your MaxMSP Patch

Tips

Table of csound~ Messages

What is csound~? csound~ is a MaxMSP external that runs Csound5. In essence, it facilitates communication of audio/control/MIDI data to and from Csound. Each csound~ object runs one instance of Csound, and you can have multiple csound~'s running at the same time.

The most common way csound~ is used is by creating a GUI in Max that "links" up to a Csound orchestra. Likely applications include an effects processor, synthesizer, orchestra player/renderer, etc... .

csound~ accepts audio data, MIDI data, control data, and Csound events. This data can be accessed from inside your Csound orchestra. csound~ also outputs various forms of data from Csound. This includes audio data, control data, and MIDI data.

Arguments for csound~
0 int argument(s): 2 signal inlets/outlets.
1 int argument(s): # of signal inlets/outlets.
2 int argument(s): # signal inlets and # of signal outlets respectively.
"noscale": If present, don't scale audio from [-1, 1] to Csound's 0dB level.

Adding the "noscale" flag means that audio data is not scaled between csound~ and Csound. By default, audio data passed to Csound is multiplied by Csound's 0dB level, and audio data received from Csound is divided by Csound's 0dB level. The "noscale" flag allows this feature to be bypassed. This is useful if you're already treating 1.0 as your 0dB level in your Csound orchestra, or you're using audio data for parameter manipulation in Csound.

Inlets & Outlets The # of inlets always equals the # of signal inlets. The first inlet is special in that it accepts messages, integers (MIDI bytes) as well as an audio signal. See the table below for a complete list of messages recognized by csound~.
The rightmost outlet sends a bang when the score is finished, or when the csound performance is stopped prematurely by the user with the "stop" message.

The second from right outlet sends a bang when a csd/orc is successfully compiled. This bang is useful if you need to initialize Csound MIDI control opcodes with data stored in your Max patch.

The third from right outlet sends MIDI bytes output from Csound. To enable MIDI output from this outlet, you must add the flag "-Q0" to the "csound" message.

The fourth from right outlet sends two element messages. The first element is a symbol and the second is a floating point value. The outvalue and chnset opcodes in a csd/orc file will output values via this outlet. Outvalue processing must be enabled for this feature to work (see "output"). An outvalue opcode will only output values when there is at least one active instance of the containing instrument. Outvalue pairs are output every 50ms, by default. To output pairs as soon as possible, send the message "overdrive 1" to csound~.

All other outlets are signal outlets.

In order to access audio signals from MSP inside Csound, use the inch opcode. Audio sent to the leftmost inlet corresponds to channel 1. To send audio from Csound to the csound~'s outlets, I recommend using the outch opcode. Audio sent out channel 1 will be received in the leftmost outlet of csound~.

When passing audio data to csound~, keep in mind that, by default, values are scaled to csound's 0db level. For example, if 0db is 32768, then an audio signal with a range of [-1,1] will be scaled to [-32768, 32768]. The reverse situation applies to audio output from csound~. To bypass scaling, add the "noscale" flag to csound~'s argument list.

When using chnset, you must declare all output channels in the orchestra header using the chn_k opcode.

Csound Flags In most situations, you won't need to add any flags to your "csound" message. Since csound~ handles the communication of audio and MIDI data between MaxMSP and Csound, flags such as [-i, -o, -M, -L] are not needed.

If you're just starting out with csound~ and you're wondering what flags to add to the "csound" message, my short answer is: none. Just start with something like:

csound myfirsttime.csd

and you should be fine (as long as your csd/orc/sco files are in the same directory as your MaxMSP patch). For more detailed information, see the "csound" message description.

Csound Score Events csound~ accepts score events using the "event" message. When csound~ is running in non-realtime mode (i.e. when rendering to a file), "event" messages are ignored. Using this feature, you can send almost any type of score event to Csound in realtime.

MIDI csound~ accepts integers in its leftmost inlet as part of a MIDI byte stream. An alternative is to use the "midi" message. When using this message, make sure each message contains a complete MIDI event. For example, a NoteOn event needs exactly 3 integers (e.g. "midi 144 64 127"). csound~ is able to process these types of MIDI data: NoteOn, NoteOff, PitchBend, Aftertouch, ControlChange, ProgramChange, and ChannelAftertouch. csound~ will ignore Sysex data.
Remember to send initializing MIDI control values AFTER the csound orchestra has been compiled. When an orchestra has been compiled, a "bang" is sent out the second from right outlet. Use this "bang" to trigger your UI elements (faders, knobs, etc...) so that your MIDI opcodes (in your Csound orchestra) are properly initialized. Otherwise, you may hear nothing, something weird, or something very LOUD!!

Recording & Playing Events You can record MIDI data, "control" messages, and "event" messages, play them back, and save a recorded sequence to a file.
Start recording with the "recordstart" message and stop with "recordstop". To play/stop a recording, use the "playstart" and "playstop" messages. To save/load a recorded sequence, use the "read" and "write" messages. For detailed information on related messages, consult the table of csound messages below.

This feature was originally added to make the creation of high-quality non-realtime rendering of realtime performances easier.
The idea was to capture a performance using low-quality instruments that don't tax the cpu, then render that performance in non-realtime using high-quality/cpu-intensive instruments. As such, there aren't many extra features... but it works.

Here are some miscellaneous facts:

The maximum recording time is 60 minutes.

The timing resolution of recorded events is approximately 1ms.

The recorded data is saved in binary format, not text (this may change in the future).

If you start a non-realtime rendering e.g. by adding "-oSomeFileName.aif" to your "csound" message) and
csound~ has a recorded sequence in memory, that sequence will be played back along with the rendering.



Where to Put Your MaxMSP Patch Where you put your patch may affect csound~'s ability to find your csd/orc/sco files. If your patch is within the Max search path, csound~ may not be able to find your csd/orc/sco file(s). Here are some example "csound" messages:

csound hello.csd

In this example, "hello.csd" must be in the same directory as your patch. If your patch is inside Max's search path, Max will search within the search path and open the first file called "hello.csd" that it finds (take care not to have multiple csd's with the same name in the search path).

csound /Users/george/CsoundStuff/hello.csd

In this example, an absolute pathname is used to specify the location of your CSD file. This will always work no matter where your patch is located. By the way, external drives are rooted in the /Volumes folder.

csound version3/hello.csd

In this example, a relative pathname is being used. This will only work when your patch is outside Max's search path.

If you're still confused, or you don't know what the Max search path is, then here's my suggestion:

1) Create a directory in your home directory and place your csound~ patch in it.

2) Place your csd/orc/sco file(s) in the same directory.

3) Modify your "csound" message to look like this: "csound hello.csd" or "csound hello.orc hello.sco".

These steps are most likely to work for all users.

Tips If you're concerned about performance (perhaps in a live situation), then disable csound message output by passing "message 0" to csound~, or by adding the flag "-m0" to your "csound" message. This will prevent Csound from printing to the Max window. The same goes for outvalue and chnset processing, which can be disabled with "output 0". Invalue and chnget processing can be disabled with "input 0". If you're using outvalue processing for debugging purposes in you orc/csd, then comment out outvalue and chnset opcodes when you're not debugging.

If you make changes to a csd/ord/sco file, but the name and location haven't changed, then simply sending "start" or "reset" will recompile the file and re-start the performance; you don't have to re-send the "csound" message.

Never put csound~.mxo or csound~.mxe in the same directory as your MaxMSP patch.

For greater timing accuracy of MIDI, "event" messages, and "control" messages to/from csound~:

    Lower your orchestra ksmps (i.e. increase kr).

    Decrease the MSP signal vector size (Options -> DSP Status...).

    Enable "Max Scheduler In Overdrive" in the Options menu.

    Enable "Scheduler In Audio Interrupt" in the DSP Status window (Options -> DSP Status...).

    Send the message "overdrive 1" to csound~.

To minimize timing latency, decrease the I/O vector size in MaxMSP (Options -> DSP Status...). As is often the case, there is no best combination of settings for all contingencies. To find the best settings for a particular situation, set things up for maximum timing accuracy and minimum latency, then scale back if the audio is breaking up.

If you have a polyphonic Csound instrument that uses k-rate data from invalue or chnget, you can reduce redundancy by using global variables and creating an always-on instrument to contain the invalue/chnget opcodes. This new instrument should have a smaller instrument # than your polyphonic instrument. Set things up so that the invalue/chnget opcodes write to global variables and change your polyphonic instrument to access those variables. For example:
    ; always-on instrument
    instr 1
        gkfrq chnget "frq"
        gkfilterQ chnget "Q"
    endin
    ; polyphonic instrument
    instr 2
        ifrq cpsmidi
        a1 vco 1, ifrq, 1
        aout svfilt a1, gkfrq, gkfilterQ
        outs aout, aout
    endin

The "event" message allows you to load/replace Csound f-tables in realtime. However, Csound may crash when you are replacing a table that is being accessed by an instrument. To prevent such crashes, make sure there aren't any active instruments using that table. If you have an instrument that's activated by MIDI, then flush all MIDI notes and wait until all active instances are inactive. If your instrument is score activated, then use the turnoff or turnoff2 opcodes to deactivate active instances (or just wait until their durations expire).

Another way to prevent crashes due to replacement of f-tables is to use conditionals to bypass the offending opcode(s). Here is an example where the offending opcode is bypassed when "bypass 1" is sent to csound~:

   ; always-on instrument
    instr 1
        gkbypass chnget "bypass"
    endin

    ; polyphonic instrument
    instr 2
        ifrq cpsmidi
        if gkbypass == 1 kgoto silent_out
            aout oscil 1, ifrq, 1 ; uses f-table # 1
            kgoto continue:
        silent_out:
            aout = 0
        continue:

        outs aout, aout
    endin

In my experience, I've found that crashes due this problem are infrequent. You could do 100 replacements and not have a crash, or you may crash on the first try. If you hate crashes (who doesn't?) or you're going to do replacements live, then do some extra work to prevent them.

Table of csound~ Messages:

Message Description

bypass Enable/disable audio bypass. A non-zero argument enables and zero disables.
When bypass mode is enabled, audio arriving at [csound~]'s inlets will be copied to their respective outlets. If there is an active Csound performance, it will not be performed while in bypass mode, thus saving CPU cycles.

control/c Sends k-rate values to Csound using invalue and chnget processing. Here are some examples:
    control gain .1
    c filterQ .8
    c atk 1.4

To access this value in your orc/csd, use the invalue or chnget opcode like this:

    kgain invalue "gain"
    kQ chnget "filterQ"
    iatk chnget "atk"

Invalue processing (see "input" message description) must be enabled in order for "control" messages to send values to their respective invalue or chnget opcodes.

Use of chnget is preferred over invalue. chnget is a little faster than invalue and it can run at i-rate as well as k-rate (invalue only runs at k-rate).

csound Loads the command line that will be passed to Csound when the "start" or "bang" message is received.
   csound hello.csd

In this example, hello.csd should be in the same directory as the patch. By default, whenever a patch is opened, csound~ will save the path to the directory that contains it. This directory will be the current directory. When "start" is received, Csound will look for hello.csd relative to the current directory.

You can change the current directory for a given instance of csound~ using the "path" message. Each instance of csound~ keeps track of its own current directory.

Here's a MacOSX example. Let's say your patch is located at /Users/george/patches/ and your csd file is located at /Users/george/patches/csd_files/. In this case, your "csound" message should look like:

   csound csd_files/hello.csd

You can add Csound flags to the message. For example:

    csound hello.csd -m0

will disable Csound message output to the Max window.

Never use these flags: -+rtmidi, -M, -L

When using csound~ in realtime (i.e. not rendering to an audio file), don't use these flags: -o, -i

To enable non-realtime rendering, add -oSomeFileName.aif to the "csound" message. In non-realtime mode, rendering is done in a seperate thread. This means that audio will not be output from csound~'s outlets. Rendering will be done regardless of whether DSP is activated or not. MIDI data, "control" messages, and "event" messages will be ignored by csound~. To render with a MIDI file, use the -F flag (and -T if appropriate).

If csound~ has a recorded sequence loaded when non-realtime rendering begins, that sequence will playback from the beginning and will "keep time" with the rendering process. This will allow users to render recorded sequences in non-realtime mode. This is useful if the user wants to produce a higher quality rendering with, for example: higher samplerate and/or krate, increased polyphony, better (but more cpu hungry) filters, etc... .

If neither -d or -g is present in the "csound" message, then csound~ will add -g so that ASCII representations of f-tables will appear in the Max window.

event/e Pass score line events to Csound during a realtime performance. Here are some examples:
    event i3 0 3.33 440

Creates a new instance of instr 3 to be played immediately for 3.33 seconds with a 4'th argument set to 440.

    event f74 1 0 8192 10 1

Loads a sine wave into table # 74.

    event a 0 0 60

Advances the score time by 60 seconds.

    e i3 0 3.33 220, e i3 0 3.33 440, e i3 0 3.33 880

A comma delimited list of events packed into one message.

input Enable/disable invalue and chnget processing (enabled by default). A non-zero argument enables and zero disables.

message/
printout Enable/disable Csound message posting to the Max window (enabled by default). A non-zero argument enables and zero disables.
An alternative to disabling message posting is to add the "-m0" flag to the "csound" message. You will still see the results of Csound initialization and compilation, but Csound events won't be posted.

midi/m Send a complete MIDI message to Csound. For example, to send a note-on to Csound do something like:
    midi 144 64 127

An alternative to the "midi" message is to send a MIDI byte stream to the first inlet of csound~ . Do not to connect more than one MIDI byte stream to csound~. If you're working with multiple byte streams, use the Max objects midiparse and midiformat to merge them.

output Enable/disable outvalue and chnset processing (enabled by default). A non-zero argument enables and zero disables.
When using chnset, remember to declare the output channels in your orchestra header with the chn_k opcode. For example:

   chn_k "frq", 2
   instr 1
   ...
      chnset kFrq, "frq"
   endin

overdrive Enable/disable outvalue and chnset processing in overdrive mode. A non-zero argument enables overdrive mode and zero disables it.

When overdrive is disabled, value pairs are output from csound~ at 50ms intervals. Use this mode when you're debugging. If you need better timing accuracy, enable overdrive with the message "overdrive 1". When overdrive is enabled, value pairs are output as soon as possible.

Note: If a value pair is identical to a previous value pair, csound~ will not output it. For example, if the pair "frequency 224.89" is received by csound~ multiple times, only the first time produces output from csound~. Only when the value changes (e.g. "frequency 440.01") will a pair starting with "frequency" be output again.

path Set the current directory for this instance of csound~. "path" accepts an absolute pathname argument.

playstart This message will start playback of recorded MIDI data, "control" messages, and "event" messages.

playstop This message will stop playback of recorded MIDI data, "control" messages, and "event" messages.

read This message is used to load a csound~ recorded sequence. It has one argument: the pathname of a file. There is no requirement for the file extension.

recordstart This message will start the recording of MIDI data, "control" messages, and "event" messages. Previously recorded data will be deleted before recording starts.

When "recordstart" is received by csound~, it will automatically generate MIDI control events and "control" messages to reflect the last known state of all such data. This will allow the user to start recording without having to send initializing MIDI and "control" data afterwards.

recordstop This message will stop the recording of MIDI data, "control" messages, and "event" messages. To playback the recorded data, send the message "playstart".

If there are any hanging MIDI notes when recording stops, MIDI NoteOff's will be added to cancel them.

Events are moved in time within the recorded sequence so that the "empty space" at the beginning of the recording is removed. This will allow playback of recorded events to start immediately upon receiving the "playstart" message.

reset Stop the current performance (if it's still running), recompile the orc/csd, then restart the performance.

rewind Set the score offset to 0 seconds. Score playback will resume from that time.

sfdir Set the Csound variables SFDIR, SSDIR, and SADIR. Accepts one argument: an absolute pathname to a directory. It has been provided for compatiblity with Ingalls' csound~ patches.

start/bang Compile the csd/orc file specified in the "csound" message (which should have been received before "start"). If the compilation is successful, then performance will start once DSP processing is started. If DSP processing is already active, then the csound performance will start immediately.
When rendering to a file, DSP processing need not be activated.

stop Stop the csound performance and send a bang out the rightmost outlet.

tempo Set the relative playback speed of recorded events. Accepts one float argument.
"tempo 1.0" means playback at original speed. "tempo" messages are not recorded.

write This message will save a recorded sequence to a binary file. It has one argument: the pathname of a file to save to. There is no requirement for the file extension.

Message	Description
bypass	Enable/disable audio bypass. A non-zero argument enables and zero disables. When bypass mode is enabled, audio arriving at [csound~]'s inlets will be copied to their respective outlets. If there is an active Csound performance, it will not be performed while in bypass mode, thus saving CPU cycles.
control/c	Sends k-rate values to Csound using invalue and chnget processing. Here are some examples: control gain .1 c filterQ .8 c atk 1.4 To access this value in your orc/csd, use the invalue or chnget opcode like this: kgain invalue "gain" kQ chnget "filterQ" iatk chnget "atk" Invalue processing (see "input" message description) must be enabled in order for "control" messages to send values to their respective invalue or chnget opcodes. Use of chnget is preferred over invalue. chnget is a little faster than invalue and it can run at i-rate as well as k-rate (invalue only runs at k-rate).
csound	Loads the command line that will be passed to Csound when the "start" or "bang" message is received. csound hello.csd In this example, hello.csd should be in the same directory as the patch. By default, whenever a patch is opened, csound~ will save the path to the directory that contains it. This directory will be the current directory. When "start" is received, Csound will look for hello.csd relative to the current directory. You can change the current directory for a given instance of csound~ using the "path" message. Each instance of csound~ keeps track of its own current directory. Here's a MacOSX example. Let's say your patch is located at /Users/george/patches/ and your csd file is located at /Users/george/patches/csd_files/. In this case, your "csound" message should look like: csound csd_files/hello.csd You can add Csound flags to the message. For example: csound hello.csd -m0 will disable Csound message output to the Max window. Never use these flags: -+rtmidi, -M, -L When using csound~ in realtime (i.e. not rendering to an audio file), don't use these flags: -o, -i To enable non-realtime rendering, add -oSomeFileName.aif to the "csound" message. In non-realtime mode, rendering is done in a seperate thread. This means that audio will not be output from csound~'s outlets. Rendering will be done regardless of whether DSP is activated or not. MIDI data, "control" messages, and "event" messages will be ignored by csound~. To render with a MIDI file, use the -F flag (and -T if appropriate). If csound~ has a recorded sequence loaded when non-realtime rendering begins, that sequence will playback from the beginning and will "keep time" with the rendering process. This will allow users to render recorded sequences in non-realtime mode. This is useful if the user wants to produce a higher quality rendering with, for example: higher samplerate and/or krate, increased polyphony, better (but more cpu hungry) filters, etc... . If neither -d or -g is present in the "csound" message, then csound~ will add -g so that ASCII representations of f-tables will appear in the Max window.
event/e	Pass score line events to Csound during a realtime performance. Here are some examples: event i3 0 3.33 440 Creates a new instance of instr 3 to be played immediately for 3.33 seconds with a 4'th argument set to 440. event f74 1 0 8192 10 1 Loads a sine wave into table # 74. event a 0 0 60 Advances the score time by 60 seconds. e i3 0 3.33 220, e i3 0 3.33 440, e i3 0 3.33 880 A comma delimited list of events packed into one message.
input	Enable/disable invalue and chnget processing (enabled by default). A non-zero argument enables and zero disables.
message/ printout	Enable/disable Csound message posting to the Max window (enabled by default). A non-zero argument enables and zero disables. An alternative to disabling message posting is to add the "-m0" flag to the "csound" message. You will still see the results of Csound initialization and compilation, but Csound events won't be posted.
midi/m	Send a complete MIDI message to Csound. For example, to send a note-on to Csound do something like: midi 144 64 127 An alternative to the "midi" message is to send a MIDI byte stream to the first inlet of csound~ . Do not to connect more than one MIDI byte stream to csound~. If you're working with multiple byte streams, use the Max objects midiparse and midiformat to merge them.
output	Enable/disable outvalue and chnset processing (enabled by default). A non-zero argument enables and zero disables. When using chnset, remember to declare the output channels in your orchestra header with the chn_k opcode. For example: chn_k "frq", 2 instr 1 ... chnset kFrq, "frq" endin
overdrive	Enable/disable outvalue and chnset processing in overdrive mode. A non-zero argument enables overdrive mode and zero disables it. When overdrive is disabled, value pairs are output from csound~ at 50ms intervals. Use this mode when you're debugging. If you need better timing accuracy, enable overdrive with the message "overdrive 1". When overdrive is enabled, value pairs are output as soon as possible. Note: If a value pair is identical to a previous value pair, csound~ will not output it. For example, if the pair "frequency 224.89" is received by csound~ multiple times, only the first time produces output from csound~. Only when the value changes (e.g. "frequency 440.01") will a pair starting with "frequency" be output again.
path	Set the current directory for this instance of csound~. "path" accepts an absolute pathname argument.
playstart	This message will start playback of recorded MIDI data, "control" messages, and "event" messages.
playstop	This message will stop playback of recorded MIDI data, "control" messages, and "event" messages.
read	This message is used to load a csound~ recorded sequence. It has one argument: the pathname of a file. There is no requirement for the file extension.
recordstart	This message will start the recording of MIDI data, "control" messages, and "event" messages. Previously recorded data will be deleted before recording starts. When "recordstart" is received by csound~, it will automatically generate MIDI control events and "control" messages to reflect the last known state of all such data. This will allow the user to start recording without having to send initializing MIDI and "control" data afterwards.
recordstop	This message will stop the recording of MIDI data, "control" messages, and "event" messages. To playback the recorded data, send the message "playstart". If there are any hanging MIDI notes when recording stops, MIDI NoteOff's will be added to cancel them. Events are moved in time within the recorded sequence so that the "empty space" at the beginning of the recording is removed. This will allow playback of recorded events to start immediately upon receiving the "playstart" message.
reset	Stop the current performance (if it's still running), recompile the orc/csd, then restart the performance.
rewind	Set the score offset to 0 seconds. Score playback will resume from that time.
sfdir	Set the Csound variables SFDIR, SSDIR, and SADIR. Accepts one argument: an absolute pathname to a directory. It has been provided for compatiblity with Ingalls' csound~ patches.
start/bang	Compile the csd/orc file specified in the "csound" message (which should have been received before "start"). If the compilation is successful, then performance will start once DSP processing is started. If DSP processing is already active, then the csound performance will start immediately. When rendering to a file, DSP processing need not be activated.
stop	Stop the csound performance and send a bang out the rightmost outlet.
tempo	Set the relative playback speed of recorded events. Accepts one float argument. "tempo 1.0" means playback at original speed. "tempo" messages are not recorded.
write	This message will save a recorded sequence to a binary file. It has one argument: the pathname of a file to save to. There is no requirement for the file extension.

All software and music by Davis Pyon (dmpyon AT yahoo DOT com).

HOME | csound~

What is csound~?	csound~ is a MaxMSP external that runs Csound5. In essence, it facilitates communication of audio/control/MIDI data to and from Csound. Each csound~ object runs one instance of Csound, and you can have multiple csound~'s running at the same time. The most common way csound~ is used is by creating a GUI in Max that "links" up to a Csound orchestra. Likely applications include an effects processor, synthesizer, orchestra player/renderer, etc... . csound~ accepts audio data, MIDI data, control data, and Csound events. This data can be accessed from inside your Csound orchestra. csound~ also outputs various forms of data from Csound. This includes audio data, control data, and MIDI data.
Arguments for csound~	0 int argument(s): 2 signal inlets/outlets. 1 int argument(s): # of signal inlets/outlets. 2 int argument(s): # signal inlets and # of signal outlets respectively. "noscale": If present, don't scale audio from [-1, 1] to Csound's 0dB level. Adding the "noscale" flag means that audio data is not scaled between csound~ and Csound. By default, audio data passed to Csound is multiplied by Csound's 0dB level, and audio data received from Csound is divided by Csound's 0dB level. The "noscale" flag allows this feature to be bypassed. This is useful if you're already treating 1.0 as your 0dB level in your Csound orchestra, or you're using audio data for parameter manipulation in Csound.
Inlets & Outlets	The # of inlets always equals the # of signal inlets. The first inlet is special in that it accepts messages, integers (MIDI bytes) as well as an audio signal. See the table below for a complete list of messages recognized by csound~. The rightmost outlet sends a bang when the score is finished, or when the csound performance is stopped prematurely by the user with the "stop" message. The second from right outlet sends a bang when a csd/orc is successfully compiled. This bang is useful if you need to initialize Csound MIDI control opcodes with data stored in your Max patch. The third from right outlet sends MIDI bytes output from Csound. To enable MIDI output from this outlet, you must add the flag "-Q0" to the "csound" message. The fourth from right outlet sends two element messages. The first element is a symbol and the second is a floating point value. The outvalue and chnset opcodes in a csd/orc file will output values via this outlet. Outvalue processing must be enabled for this feature to work (see "output"). An outvalue opcode will only output values when there is at least one active instance of the containing instrument. Outvalue pairs are output every 50ms, by default. To output pairs as soon as possible, send the message "overdrive 1" to csound~. All other outlets are signal outlets. In order to access audio signals from MSP inside Csound, use the inch opcode. Audio sent to the leftmost inlet corresponds to channel 1. To send audio from Csound to the csound~'s outlets, I recommend using the outch opcode. Audio sent out channel 1 will be received in the leftmost outlet of csound~. When passing audio data to csound~, keep in mind that, by default, values are scaled to csound's 0db level. For example, if 0db is 32768, then an audio signal with a range of [-1,1] will be scaled to [-32768, 32768]. The reverse situation applies to audio output from csound~. To bypass scaling, add the "noscale" flag to csound~'s argument list. When using chnset, you must declare all output channels in the orchestra header using the chn_k opcode.
Csound Flags	In most situations, you won't need to add any flags to your "csound" message. Since csound~ handles the communication of audio and MIDI data between MaxMSP and Csound, flags such as [-i, -o, -M, -L] are not needed. If you're just starting out with csound~ and you're wondering what flags to add to the "csound" message, my short answer is: none. Just start with something like: csound myfirsttime.csd and you should be fine (as long as your csd/orc/sco files are in the same directory as your MaxMSP patch). For more detailed information, see the "csound" message description.
Csound Score Events	csound~ accepts score events using the "event" message. When csound~ is running in non-realtime mode (i.e. when rendering to a file), "event" messages are ignored. Using this feature, you can send almost any type of score event to Csound in realtime.
MIDI	csound~ accepts integers in its leftmost inlet as part of a MIDI byte stream. An alternative is to use the "midi" message. When using this message, make sure each message contains a complete MIDI event. For example, a NoteOn event needs exactly 3 integers (e.g. "midi 144 64 127"). csound~ is able to process these types of MIDI data: NoteOn, NoteOff, PitchBend, Aftertouch, ControlChange, ProgramChange, and ChannelAftertouch. csound~ will ignore Sysex data. Remember to send initializing MIDI control values AFTER the csound orchestra has been compiled. When an orchestra has been compiled, a "bang" is sent out the second from right outlet. Use this "bang" to trigger your UI elements (faders, knobs, etc...) so that your MIDI opcodes (in your Csound orchestra) are properly initialized. Otherwise, you may hear nothing, something weird, or something very LOUD!!
Recording & Playing Events	You can record MIDI data, "control" messages, and "event" messages, play them back, and save a recorded sequence to a file. Start recording with the "recordstart" message and stop with "recordstop". To play/stop a recording, use the "playstart" and "playstop" messages. To save/load a recorded sequence, use the "read" and "write" messages. For detailed information on related messages, consult the table of csound messages below. This feature was originally added to make the creation of high-quality non-realtime rendering of realtime performances easier. The idea was to capture a performance using low-quality instruments that don't tax the cpu, then render that performance in non-realtime using high-quality/cpu-intensive instruments. As such, there aren't many extra features... but it works. Here are some miscellaneous facts: The maximum recording time is 60 minutes. The timing resolution of recorded events is approximately 1ms. The recorded data is saved in binary format, not text (this may change in the future). If you start a non-realtime rendering e.g. by adding "-oSomeFileName.aif" to your "csound" message) and csound~ has a recorded sequence in memory, that sequence will be played back along with the rendering.
Where to Put Your MaxMSP Patch	Where you put your patch may affect csound~'s ability to find your csd/orc/sco files. If your patch is within the Max search path, csound~ may not be able to find your csd/orc/sco file(s). Here are some example "csound" messages: csound hello.csd In this example, "hello.csd" must be in the same directory as your patch. If your patch is inside Max's search path, Max will search within the search path and open the first file called "hello.csd" that it finds (take care not to have multiple csd's with the same name in the search path). csound /Users/george/CsoundStuff/hello.csd In this example, an absolute pathname is used to specify the location of your CSD file. This will always work no matter where your patch is located. By the way, external drives are rooted in the /Volumes folder. csound version3/hello.csd In this example, a relative pathname is being used. This will only work when your patch is outside Max's search path. If you're still confused, or you don't know what the Max search path is, then here's my suggestion: 1) Create a directory in your home directory and place your csound~ patch in it. 2) Place your csd/orc/sco file(s) in the same directory. 3) Modify your "csound" message to look like this: "csound hello.csd" or "csound hello.orc hello.sco". These steps are most likely to work for all users.
Tips	If you're concerned about performance (perhaps in a live situation), then disable csound message output by passing "message 0" to csound~, or by adding the flag "-m0" to your "csound" message. This will prevent Csound from printing to the Max window. The same goes for outvalue and chnset processing, which can be disabled with "output 0". Invalue and chnget processing can be disabled with "input 0". If you're using outvalue processing for debugging purposes in you orc/csd, then comment out outvalue and chnset opcodes when you're not debugging. If you make changes to a csd/ord/sco file, but the name and location haven't changed, then simply sending "start" or "reset" will recompile the file and re-start the performance; you don't have to re-send the "csound" message. Never put csound~.mxo or csound~.mxe in the same directory as your MaxMSP patch. For greater timing accuracy of MIDI, "event" messages, and "control" messages to/from csound~: Lower your orchestra ksmps (i.e. increase kr). Decrease the MSP signal vector size (Options -> DSP Status...). Enable "Max Scheduler In Overdrive" in the Options menu. Enable "Scheduler In Audio Interrupt" in the DSP Status window (Options -> DSP Status...). Send the message "overdrive 1" to csound~. To minimize timing latency, decrease the I/O vector size in MaxMSP (Options -> DSP Status...). As is often the case, there is no best combination of settings for all contingencies. To find the best settings for a particular situation, set things up for maximum timing accuracy and minimum latency, then scale back if the audio is breaking up. If you have a polyphonic Csound instrument that uses k-rate data from invalue or chnget, you can reduce redundancy by using global variables and creating an always-on instrument to contain the invalue/chnget opcodes. This new instrument should have a smaller instrument # than your polyphonic instrument. Set things up so that the invalue/chnget opcodes write to global variables and change your polyphonic instrument to access those variables. For example: ; always-on instrument instr 1 gkfrq chnget "frq" gkfilterQ chnget "Q" endin ; polyphonic instrument instr 2 ifrq cpsmidi a1 vco 1, ifrq, 1 aout svfilt a1, gkfrq, gkfilterQ outs aout, aout endin The "event" message allows you to load/replace Csound f-tables in realtime. However, Csound may crash when you are replacing a table that is being accessed by an instrument. To prevent such crashes, make sure there aren't any active instruments using that table. If you have an instrument that's activated by MIDI, then flush all MIDI notes and wait until all active instances are inactive. If your instrument is score activated, then use the turnoff or turnoff2 opcodes to deactivate active instances (or just wait until their durations expire). Another way to prevent crashes due to replacement of f-tables is to use conditionals to bypass the offending opcode(s). Here is an example where the offending opcode is bypassed when "bypass 1" is sent to csound~: ; always-on instrument instr 1 gkbypass chnget "bypass" endin ; polyphonic instrument instr 2 ifrq cpsmidi if gkbypass == 1 kgoto silent_out aout oscil 1, ifrq, 1 ; uses f-table # 1 kgoto continue: silent_out: aout = 0 continue: outs aout, aout endin In my experience, I've found that crashes due this problem are infrequent. You could do 100 replacements and not have a crash, or you may crash on the first try. If you hate crashes (who doesn't?) or you're going to do replacements live, then do some extra work to prevent them.