Csound~ Manual

csound~ Manual

csound~ csound~ is a MaxMSP external for the Csound5 API. You can download it here.
csound~ accepts 0-2 integer arguments and 0-1 string arguments. If no arguments are present, the # of signal inlets/outlets is 2 and audio is scaled when passed to and received from Csound.
One integer argument specifies the # of signal inlets/outlets. If there are two integer arguments, the first one specifies the # signal inlets and the second specifies the # signal outlets. If the flag "noscale" is present (it does not matter where in the list of arguments you put it) then 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 OdB level. The "noscale" flag allows this feature to be bypassed.
Multiple instances of csound~ are possible, so if your orc/sco/csd files are getting too big, break them up and run them in seperate csound~ instances.

Inlets & Outlets csound~ always has a number of inlets equal to 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. Currently, this feature hasn't been tested.
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 opcode in a csd/orc file will output values via this outlet. Outvalue processing (see "output" message description) must be enabled for this feature to work. An outvalue opcode will only output values when there is at least one active instance of the containing instrument.
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 [0,1] will be scaled to [0, 32768]. The reverse situation applies to audio output from csound~. To bypass scaling, add the "noscale" flag to csound~'s argument list.

MIDI csound~ accepts integers in its leftmost inlet as part of a MIDI byte stream. An alternative is to use the "midi" message (see the table below).
Remember to send initializing MIDI control values AFTER the csound orchestra has been compiled.

Realtime Score Events csound~ accepts realtime score events using the "event" message. See the table below for a more detailed description of this feature.

Notes If you're concerned about performance (perhaps in a live situation), then disable csound message output by passing "message 0" to csound~. The same goes for outvalues, which can be disabled with "output 0", and invalues, which can be disabled with "input 0". If your live situation depends on any of these features, then don't disable them. If you're using outvalue processing for debugging purposes in you orc/csd, then comment out the outvalue 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.
Try to avoid placing your patches within the Max search path. csound~ uses a Max function in order to figure out the absolute pathname of the directory that contains the patch. This is done when a patch containing csound~ is opened. If the patch is somewhere in Max's search path, then csound~ will think that the directory containing the patch is one of the topmost directories in Max's search path. So, if you're using relative pathnames in the "csound" message, you will get an error when "start" is sent saying that your csd/orc/sco file(s) could not be found.

Here is a table of csound~ messages and their descriptions:

Message Description

csound Load the command line that will be passed to Csound when the "start" message is received. For example:
csound hello.csd
hello.csd should be in the same directory as the patch that contains csound~ for the above command to work. 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, but avoid using these flags:
-+rtmidi
-M
... (other flags may also be bad)
If you want to render to an audio file, use the "-o" flag and append the name of the audio file you want to create, but keep in mind that csound~ will not output audio from its signal outlets. When rendering to a file, the csound performance is run in a seperate thread.
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.
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.
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.
input Enable/disable invalue and chnget processing (enabled by default). A non-zero argument enables and zero disables.
output Enable/disable outvalue 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.
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.
control/c Send k-rate values to Csound using invalue and chnget processing. Here's an example:
control gain .1
To access this value in your orc/csd, use the invalue or chnget opcode like this:
kgain invalue "gain"
kgain chnget "gain"
igain chnget "gain"
Invalue processing (see "input" message description) must be enabled in order for "control" messages to send values to their respective invalue or chnget opcodes.
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.
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.
path Set the current directory for this instance of csound~. "path" accepts one argument: an absolute pathname.

Message	Description
csound	Load the command line that will be passed to Csound when the "start" message is received. For example: csound hello.csd hello.csd should be in the same directory as the patch that contains csound~ for the above command to work. 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, but avoid using these flags: -+rtmidi -M ... (other flags may also be bad) If you want to render to an audio file, use the "-o" flag and append the name of the audio file you want to create, but keep in mind that csound~ will not output audio from its signal outlets. When rendering to a file, the csound performance is run in a seperate thread. 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.
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.
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.
input	Enable/disable invalue and chnget processing (enabled by default). A non-zero argument enables and zero disables.
output	Enable/disable outvalue 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.
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.
control/c	Send k-rate values to Csound using invalue and chnget processing. Here's an example: control gain .1 To access this value in your orc/csd, use the invalue or chnget opcode like this: kgain invalue "gain" kgain chnget "gain" igain chnget "gain" Invalue processing (see "input" message description) must be enabled in order for "control" messages to send values to their respective invalue or chnget opcodes.
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.
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.
path	Set the current directory for this instance of csound~. "path" accepts one argument: an absolute pathname.

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

HOME | csound~

csound~	csound~ is a MaxMSP external for the Csound5 API. You can download it here. csound~ accepts 0-2 integer arguments and 0-1 string arguments. If no arguments are present, the # of signal inlets/outlets is 2 and audio is scaled when passed to and received from Csound. One integer argument specifies the # of signal inlets/outlets. If there are two integer arguments, the first one specifies the # signal inlets and the second specifies the # signal outlets. If the flag "noscale" is present (it does not matter where in the list of arguments you put it) then 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 OdB level. The "noscale" flag allows this feature to be bypassed. Multiple instances of csound~ are possible, so if your orc/sco/csd files are getting too big, break them up and run them in seperate csound~ instances.
Inlets & Outlets	csound~ always has a number of inlets equal to 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. Currently, this feature hasn't been tested. 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 opcode in a csd/orc file will output values via this outlet. Outvalue processing (see "output" message description) must be enabled for this feature to work. An outvalue opcode will only output values when there is at least one active instance of the containing instrument. 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 [0,1] will be scaled to [0, 32768]. The reverse situation applies to audio output from csound~. To bypass scaling, add the "noscale" flag to csound~'s argument list.
MIDI	csound~ accepts integers in its leftmost inlet as part of a MIDI byte stream. An alternative is to use the "midi" message (see the table below). Remember to send initializing MIDI control values AFTER the csound orchestra has been compiled.
Realtime Score Events	csound~ accepts realtime score events using the "event" message. See the table below for a more detailed description of this feature.
Notes	If you're concerned about performance (perhaps in a live situation), then disable csound message output by passing "message 0" to csound~. The same goes for outvalues, which can be disabled with "output 0", and invalues, which can be disabled with "input 0". If your live situation depends on any of these features, then don't disable them. If you're using outvalue processing for debugging purposes in you orc/csd, then comment out the outvalue 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. Try to avoid placing your patches within the Max search path. csound~ uses a Max function in order to figure out the absolute pathname of the directory that contains the patch. This is done when a patch containing csound~ is opened. If the patch is somewhere in Max's search path, then csound~ will think that the directory containing the patch is one of the topmost directories in Max's search path. So, if you're using relative pathnames in the "csound" message, you will get an error when "start" is sent saying that your csd/orc/sco file(s) could not be found.