Csound~ Manual

csound~ Manual

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

What is csound~?

Arguments for csound~ (NEW)

Arguments for csound~ (OLD)

Inlets & Outlets

Csound Flags

Csound Score Events

MIDI

Pathnames in Windows

Pathnames in Mac OSX

Recording & Playing Events

Where to Put Your MaxMSP Patch

Latency Issues

Tips

Table of csound~ Messages

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

csound~ can be used to create an effects processor, synthesizer, orchestra player/renderer, etc... . Create a GUI in Max, "link" it up to csound~, and voila!

csound~ accepts audio, MIDI, 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, MIDI, and control data.

Arguments for csound~ (NEW)
As of v1.0.7, you can add attributes and the Csound command line arguments to [csound~].

Example:
[csound~ hello.csd @scale 0 @i 1 @o 2] : No scaling, 1 signal inlet, 2 signal outlets.
[csound~ "fun.csd -m0" @io 2 @overdrive 1] : 2 signal inlets, 2 signal outlets, overdrive enabled.

If you specify a csd/orc/sco file(s) in the argument list, you must still send "start" or "bang" to compile and start the performance.

Attributes:

@i : The # of signal inlets. (default = 2)

@input : Enable/Disable invalue/chnget processing. (default = 1)

@interval : The millisecond interval that determines the rate of message output from [csound~]. "@overdrive 1" overrides this setting. (default = 1ms)
@io : The # of signal inlets and outlets. (default = 2)

@message : Enable/Disable output to the Max window. (default = 1)

@o : The # of signal outlets. (default = 2)

@output : Enable/Disable outvalue/chnset processing. (default = 1)

@overdrive : Enable/Disable overdrive mode. (default = 0)

@scale : Enable/Disable scaling of audio. (default = 1)
"@scale 0" 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. Disabling this feature is useful if you're already treating 1.0 as 0dB in your Csound orchestra. To set 1.0 as 0dB, add "0dbfs = 1" to the orchestra header.

@start : Enable/Disable automatic compilation and starting of Csound performance. (default = 0)
Must provide csd/orc/sco file in argument list for "@start 1" to work. If your orchestra requires certain control values to be initialized before the performance has started, don't use "@start 1".

Arguments for csound~ (OLD)
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.

Example:
[csound~ noscale 1 4] : No scaling, 1 signal inlet, 4 signal outlets.

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 0dB in your Csound orchestra. To set 1.0 as 0dB, add "0dbfs = 1" to the orchestra header.

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 recognized messages.
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 received 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/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/chnset opcode will only output messages 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 to csound~'s outlets, I recommend using the outch opcode. Audio sent out channel 1 will be received in the leftmost outlet.

By default, audio data is scaled between csound~ and Csound. In MaxMSP, 0dB == 1.0. In Csound, 0dB == 32768.0 (unless the user has changed the 0dB level with the 0dbfs opcode). 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 data, flags such as [-i, -o, -M, -L, -B, -b] are not needed.

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

csound hello.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. Using this feature, you can send almost any type of score event in realtime.
When csound~ is running in non-realtime mode (i.e. when rendering to a file), "event" messages are ignored.

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 orchestra) are properly initialized. Otherwise, you may hear nothing, something weird, or something very LOUD!!

Pathnames in Windows In Windows, csound~ works with Max style paths. The default Max path style is very similar to the Windows path style. The only difference is the type of slash. Max uses forward slashes (/) and Windows uses back slashes (\). Since csound~ and Csound5 both work with forward slashes, you can make things easier on yourself by sticking with forward slashes. Here's an example of the path style you should use:

   D:/samples/achtung

Pathnames in Mac OSX In MacOSX, csound~ works with either Max or POSIX style paths (as of v1.0.6). A typical Max style path:

   MyFireWireHD:/samples/achtung

and its POSIX equivalent:

   /Volumes/MyFireWireHD/samples/achtung

When you give csound~ a Max style path, it will convert it to a POSIX path internally.

When specifying an output audio file in your "csound" message, make sure you put a space between "-o" and the filename if the filename is a Max style absolute path.

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 "-o SomeFileName.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, on MacOSX, 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 put your patch in it.

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

3) Make your "csound" message look like this:

"csound hello.csd" or "csound hello.orc hello.sco".

These steps should work for most users.

Latency Issues If the ksmps value set in your orchestra evenly divides the Max signal vector size, then [csound~] will run in zero-latency mode. In other words, it will not delay the audio being processed.
If ksmps does NOT evenly divide the Max signal vector size, ksmps samples of delay will be added to the processed audio.

[csound~] message outlet will only output messages at the current rate, which you can set with the "interval" message or @interval attribute. The default value is 1ms. If that's not enough, use overdrive mode. If latency is not an issue, or the interval of 1ms is taxing your system, increase the interval.

Tips
Immediately after creating a new patch, there's no way to determine which folder contains that patch. After you add a [csound~] external to the new patch, save it, then re-open it. That way, [csound~] will know which folder contains the patch. This is important if you're using relative paths to specify your csd/orc/sco files.

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". Alternatively, you could comment out these types of opcodes in your orchestra.

If you make changes to a csd/ord/sco file, but the name and location haven't changed, then simply sending "start", "bang", 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.
One crash-free solution is to use the "loadsamp" message with a positive table argument.
Another solution is to 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).

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 runs 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 -m0 hello.csd

will disable Csound message output to the Max window.

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

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 -o SomeFileName.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 active 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.

    e f74 1 0 8192 10 1

Loads a sine wave into table # 74.

    e 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.

interval Sets the millisecond interval that determines the rate of message output from [csound~]'s message outlet (default = 1ms). Overdrive mode overrides this setting.

loadsamp Load an audio file into a table. Three arguments: table #, channel, filename, offset time (optional), size time (optional)
arg #1: If the table argument references a non-existent table, it will be created. If the table argument is positive and the table exists, then it won't be replaced. This is useful when you want to replace table data on the fly without causing a crash. If the table is too small for the requested file, then samples will be read until full. If the table argument is negative and the table exists but is too small for the file you want to load, then it will be replaced. Replacing tables during a performance is NOT SAFE! See the "Tips" section above for some crash-free solutions.

arg #2: The channel argument determines which channel of audio data you want to read in. For stereo files, 1 is left, 2 is right. To read in all channels as interleaved data, use 0.

arg #3: The filename argument. On Windows, use Windows style path with forward (/) slashes. On MacOSX, use either Max style paths or POSIX style paths. If it's a relative path, it will be relative to the directory containing the patch.

arg #4 (optional, default = 0): Read offset time in seconds. If negative, time is in sample frames.

arg #5 (optional, default = 0): Amount of time to read in seconds. 0 means read in all data or as much data a possible. If negative, time is in sample frames.

Examples:

    loadsamp 1 2 "/Users/Georg/samples/fun.aif"
If table # 1 exists, then read in channel 2 of fun.aif until the table is full (the table is not replaced). If table # 1 does not exist, then create it and read in all channel 2 data.

    loadsamp -3 0 "/Users/Georg/samples/fun.aif"

If table # 3 does not exist or it's too small, create/replace it. Then read in all channels of fun.aif as interleaved data.

Note: When using loadsamp, some of the table opcodes will not operate as expected. Some of the affected opcodes:

   nsamp, ftchnls, ftlptim, ftsr

To minimize frustration, always load a similar type of sample to the one you're replacing. In other words, if a table contains a single channel of data at 44100 sr, then only load samples with similar characteristics in that table.

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 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 enabled, messages generated by outvalue and chnset will be sent out the fourth from right outlet.

If a message is identical to a previous message, there will be no output. For example, if Csound outputs the message "frequency 224.89" multiple times, only the first time produces output from csound~. Only when the value changes (e.g. "frequency 440.01") will a message starting with "frequency" be output again.

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

open Opens the current .csd/.orc/.sco files in the default editor for those types of files.
In order for this to work, you must first associate .csd/.orc/.sco files with your favorite text editor.

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, messages generated by outvalue and chnset are output at 1ms 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, messages are output as soon as possible.

path Set the current directory for this instance of csound~. "path" accepts an absolute pathname argument. On MacOSX, you can use either Max style paths or POSIX style paths. On Windows, use Max style paths with forward slashes.

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.

readbuf The "readbuf" message will copy audio data from a [buffer~] to a Csound table.
arg #1: Csound table number to write to. A negative number forces the table to be replaced with a table whose size equals the amount of data requested in arg #5. A positive number will not replace an exisiting table, but will create one if it doesn't exist.

arg #2: Channel to read. 0 means read all channels. If > 0, then read from that channel into the Csound table (treating the table as a single channel table).

arg #3: The name of the [buffer~] to read from.

arg #4 (optional, default = 0): Read offset time (from beginning of buffer~). If positive, specifies time in seconds. If negative, specifies time in sample frames.

arg #5 (optional, default = 0): Amount of audio data to read. 0 means read in all data or as much data as possible. If positive, specifies time in seconds. If negative, specifies time in sample frames.

recordstart This message will start the recording of MIDI data, "control" messages, and "event" messages. Previously recorded data will be delete 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.

rsidx Read the table value at a specified index. Two integer arguments: table number, index.
Example:

    rsidx 3 128
If table # 3 exists and the value at index 128 is 0.42481, then this message will be sent out the fourth from right outlet:

    rsidx 0.42481

run Execute a command line command.
If the command you want to run is not in your PATH variable, you must specify the absolute path to the command.

File arguments may be relative or absolute paths. Relative paths are relative to the folder that contains the patch that contains [csound~].

When using paths with spaces in them, enclose the path in double-quotes.

In Mac OSX, many apps are actually folders. In order to use these apps with the run command, you must specify the path to the actual binary executable which is often in Contents/MacOS/.

In Mac OSX, you can use either Max style or POSIX style paths.

In Windows, use forward slashes (/) instead of back slashes (\).

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 active.

New in v1.0.4:
Upon successfull compilation, if DSP is not active, then one k-cycle will be automatically processed. This will force all initializations (including events with a start time of zero) to take place. For example, all tables that were scheduled to be loaded at time zero will be loaded. During this initial k-cycle, audio input will be filled with zeros, and audio output will be ignored.

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.

writebuf The "writebuf" message will copy audio data from a Csound table to a [buffer~].
arg #1: Csound table number to read from.

arg #2: Target [buffer~] channel. If = 0, copy all channels (with the assumption that the Csound table has the same number of channels as [buffer~]). If > 0, treat the Csound table as a single-channel table.

arg #3: arg #3: The name of the target [buffer~].

arg #4 (optional, default = 0): Read offset time in seconds. If negative, time is in sample frames.

arg #5 (optional, default = 0): Amount of time to read in seconds. 0 means read in all data or as much data a possible. If negative, time is in sample frames.

wsidx Set the value at a specific index in a given table. Three arguments: table # (integer), index (integer), value (float)
Example:

    wsidx 5 17 .2515
If table # 5 exists and index 17 is within bounds, then the value at that index will be set to .2515.

What is csound~?	csound~ is a MaxMSP external that runs Csound5. It facilitates communication of audio, control, and MIDI data to/from Csound. Each csound~ object runs one instance of Csound, and you can have multiple csound~'s running at the same time. csound~ can be used to create an effects processor, synthesizer, orchestra player/renderer, etc... . Create a GUI in Max, "link" it up to csound~, and voila! csound~ accepts audio, MIDI, 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, MIDI, and control data.
Arguments for csound~ (NEW)	As of v1.0.7, you can add attributes and the Csound command line arguments to [csound~]. Example: [csound~ hello.csd @scale 0 @i 1 @o 2] : No scaling, 1 signal inlet, 2 signal outlets. [csound~ "fun.csd -m0" @io 2 @overdrive 1] : 2 signal inlets, 2 signal outlets, overdrive enabled. If you specify a csd/orc/sco file(s) in the argument list, you must still send "start" or "bang" to compile and start the performance. Attributes: @i : The # of signal inlets. (default = 2) @input : Enable/Disable invalue/chnget processing. (default = 1) @interval : The millisecond interval that determines the rate of message output from [csound~]. "@overdrive 1" overrides this setting. (default = 1ms) @io : The # of signal inlets and outlets. (default = 2) @message : Enable/Disable output to the Max window. (default = 1) @o : The # of signal outlets. (default = 2) @output : Enable/Disable outvalue/chnset processing. (default = 1) @overdrive : Enable/Disable overdrive mode. (default = 0) @scale : Enable/Disable scaling of audio. (default = 1) "@scale 0" 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. Disabling this feature is useful if you're already treating 1.0 as 0dB in your Csound orchestra. To set 1.0 as 0dB, add "0dbfs = 1" to the orchestra header. @start : Enable/Disable automatic compilation and starting of Csound performance. (default = 0) Must provide csd/orc/sco file in argument list for "@start 1" to work. If your orchestra requires certain control values to be initialized before the performance has started, don't use "@start 1".
Arguments for csound~ (OLD)	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. Example: [csound~ noscale 1 4] : No scaling, 1 signal inlet, 4 signal outlets. 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 0dB in your Csound orchestra. To set 1.0 as 0dB, add "0dbfs = 1" to the orchestra header.
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 recognized messages. 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 received 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/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/chnset opcode will only output messages 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 to csound~'s outlets, I recommend using the outch opcode. Audio sent out channel 1 will be received in the leftmost outlet. By default, audio data is scaled between csound~ and Csound. In MaxMSP, 0dB == 1.0. In Csound, 0dB == 32768.0 (unless the user has changed the 0dB level with the 0dbfs opcode). 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 data, flags such as [-i, -o, -M, -L, -B, -b] are not needed. If you're wondering what flags to add to the "csound" message, my short answer is: none. Just start with something like: csound hello.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. Using this feature, you can send almost any type of score event in realtime. When csound~ is running in non-realtime mode (i.e. when rendering to a file), "event" messages are ignored.
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 orchestra) are properly initialized. Otherwise, you may hear nothing, something weird, or something very LOUD!!
Pathnames in Windows	In Windows, csound~ works with Max style paths. The default Max path style is very similar to the Windows path style. The only difference is the type of slash. Max uses forward slashes (/) and Windows uses back slashes (\). Since csound~ and Csound5 both work with forward slashes, you can make things easier on yourself by sticking with forward slashes. Here's an example of the path style you should use: D:/samples/achtung
Pathnames in Mac OSX	In MacOSX, csound~ works with either Max or POSIX style paths (as of v1.0.6). A typical Max style path: MyFireWireHD:/samples/achtung and its POSIX equivalent: /Volumes/MyFireWireHD/samples/achtung When you give csound~ a Max style path, it will convert it to a POSIX path internally. When specifying an output audio file in your "csound" message, make sure you put a space between "-o" and the filename if the filename is a Max style absolute path.
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 "-o SomeFileName.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, on MacOSX, 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 put your patch in it. 2) Place your csd/orc/sco file(s) in the same directory. 3) Make your "csound" message look like this: "csound hello.csd" or "csound hello.orc hello.sco". These steps should work for most users.
Latency Issues	If the ksmps value set in your orchestra evenly divides the Max signal vector size, then [csound~] will run in zero-latency mode. In other words, it will not delay the audio being processed. If ksmps does NOT evenly divide the Max signal vector size, ksmps samples of delay will be added to the processed audio. [csound~] message outlet will only output messages at the current rate, which you can set with the "interval" message or @interval attribute. The default value is 1ms. If that's not enough, use overdrive mode. If latency is not an issue, or the interval of 1ms is taxing your system, increase the interval.
Tips	Immediately after creating a new patch, there's no way to determine which folder contains that patch. After you add a [csound~] external to the new patch, save it, then re-open it. That way, [csound~] will know which folder contains the patch. This is important if you're using relative paths to specify your csd/orc/sco files. 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". Alternatively, you could comment out these types of opcodes in your orchestra. If you make changes to a csd/ord/sco file, but the name and location haven't changed, then simply sending "start", "bang", 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. One crash-free solution is to use the "loadsamp" message with a positive table argument. Another solution is to 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).

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 runs 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 -m0 hello.csd will disable Csound message output to the Max window. Never use these flags: -+rtmidi, -M, -L, -B, -b 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 -o SomeFileName.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 active 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. e f74 1 0 8192 10 1 Loads a sine wave into table # 74. e 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.
interval	Sets the millisecond interval that determines the rate of message output from [csound~]'s message outlet (default = 1ms). Overdrive mode overrides this setting.
loadsamp	Load an audio file into a table. Three arguments: table #, channel, filename, offset time (optional), size time (optional) arg #1: If the table argument references a non-existent table, it will be created. If the table argument is positive and the table exists, then it won't be replaced. This is useful when you want to replace table data on the fly without causing a crash. If the table is too small for the requested file, then samples will be read until full. If the table argument is negative and the table exists but is too small for the file you want to load, then it will be replaced. Replacing tables during a performance is NOT SAFE! See the "Tips" section above for some crash-free solutions. arg #2: The channel argument determines which channel of audio data you want to read in. For stereo files, 1 is left, 2 is right. To read in all channels as interleaved data, use 0. arg #3: The filename argument. On Windows, use Windows style path with forward (/) slashes. On MacOSX, use either Max style paths or POSIX style paths. If it's a relative path, it will be relative to the directory containing the patch. arg #4 (optional, default = 0): Read offset time in seconds. If negative, time is in sample frames. arg #5 (optional, default = 0): Amount of time to read in seconds. 0 means read in all data or as much data a possible. If negative, time is in sample frames. Examples: loadsamp 1 2 "/Users/Georg/samples/fun.aif" If table # 1 exists, then read in channel 2 of fun.aif until the table is full (the table is not replaced). If table # 1 does not exist, then create it and read in all channel 2 data. loadsamp -3 0 "/Users/Georg/samples/fun.aif" If table # 3 does not exist or it's too small, create/replace it. Then read in all channels of fun.aif as interleaved data. Note: When using loadsamp, some of the table opcodes will not operate as expected. Some of the affected opcodes: nsamp, ftchnls, ftlptim, ftsr To minimize frustration, always load a similar type of sample to the one you're replacing. In other words, if a table contains a single channel of data at 44100 sr, then only load samples with similar characteristics in that table.
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 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 enabled, messages generated by outvalue and chnset will be sent out the fourth from right outlet. If a message is identical to a previous message, there will be no output. For example, if Csound outputs the message "frequency 224.89" multiple times, only the first time produces output from csound~. Only when the value changes (e.g. "frequency 440.01") will a message starting with "frequency" be output again. 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
open	Opens the current .csd/.orc/.sco files in the default editor for those types of files. In order for this to work, you must first associate .csd/.orc/.sco files with your favorite text editor.
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, messages generated by outvalue and chnset are output at 1ms 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, messages are output as soon as possible.
path	Set the current directory for this instance of csound~. "path" accepts an absolute pathname argument. On MacOSX, you can use either Max style paths or POSIX style paths. On Windows, use Max style paths with forward slashes.
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.
readbuf	The "readbuf" message will copy audio data from a [buffer~] to a Csound table. arg #1: Csound table number to write to. A negative number forces the table to be replaced with a table whose size equals the amount of data requested in arg #5. A positive number will not replace an exisiting table, but will create one if it doesn't exist. arg #2: Channel to read. 0 means read all channels. If > 0, then read from that channel into the Csound table (treating the table as a single channel table). arg #3: The name of the [buffer~] to read from. arg #4 (optional, default = 0): Read offset time (from beginning of buffer~). If positive, specifies time in seconds. If negative, specifies time in sample frames. arg #5 (optional, default = 0): Amount of audio data to read. 0 means read in all data or as much data as possible. If positive, specifies time in seconds. If negative, specifies time in sample frames.
recordstart	This message will start the recording of MIDI data, "control" messages, and "event" messages. Previously recorded data will be delete 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.
rsidx	Read the table value at a specified index. Two integer arguments: table number, index. Example: rsidx 3 128 If table # 3 exists and the value at index 128 is 0.42481, then this message will be sent out the fourth from right outlet: rsidx 0.42481
run	Execute a command line command. If the command you want to run is not in your PATH variable, you must specify the absolute path to the command. File arguments may be relative or absolute paths. Relative paths are relative to the folder that contains the patch that contains [csound~]. When using paths with spaces in them, enclose the path in double-quotes. In Mac OSX, many apps are actually folders. In order to use these apps with the run command, you must specify the path to the actual binary executable which is often in Contents/MacOS/. In Mac OSX, you can use either Max style or POSIX style paths. In Windows, use forward slashes (/) instead of back slashes (\).
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 active. New in v1.0.4: Upon successfull compilation, if DSP is not active, then one k-cycle will be automatically processed. This will force all initializations (including events with a start time of zero) to take place. For example, all tables that were scheduled to be loaded at time zero will be loaded. During this initial k-cycle, audio input will be filled with zeros, and audio output will be ignored.
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.
writebuf	The "writebuf" message will copy audio data from a Csound table to a [buffer~]. arg #1: Csound table number to read from. arg #2: Target [buffer~] channel. If = 0, copy all channels (with the assumption that the Csound table has the same number of channels as [buffer~]). If > 0, treat the Csound table as a single-channel table. arg #3: arg #3: The name of the target [buffer~]. arg #4 (optional, default = 0): Read offset time in seconds. If negative, time is in sample frames. arg #5 (optional, default = 0): Amount of time to read in seconds. 0 means read in all data or as much data a possible. If negative, time is in sample frames.
wsidx	Set the value at a specific index in a given table. Three arguments: table # (integer), index (integer), value (float) Example: wsidx 5 17 .2515 If table # 5 exists and index 17 is within bounds, then the value at that index will be set to .2515.