NAME

set_option - turn on and off various RTcmix options

set_option(option_name [, option_name, ... ])

Parameters inside the [brackets] are optional.

Use set_option to control the behavior of RTcmix: whether to play audio, to report clipping and peak amplitude, to overwrite existing sound files, and so on.

The set_option command generally precedes the rtsetparams command because much of what it does effects how rtsetparams sets up the RTcmix process.

option_name

An option_name is a double-quoted string of the form "option = val", where option is a valid RTcmix option for controlling global aspects of RTcmix execution, and val is a boolean parameter determining whether to turn the option on or off, or in certain cases a parameter string used by internally by RTcmix (hardware device names, etc.). The boolean values for val accepted by the RTcmix parser are "yes", "true", "on", and "1" for turning an option on, and "no", "false", "off", and "0" for turing an option off. Case does not matter in the option_name string, and spaces are ignored. For example:

   set_option("audio = on")
   set_option("AUDIO=yes")
   set_option("AUDIO= TRUE")
   set_option("audio=1")

are all equivalent.

A call to set_option can contain more than one option_name, separated by commas. There can be more than one call to set_option in a script. If two calls to set_option in a script conflict, the last one will take precedence.

Some older RTcmix scores will use a set_option system with single option strings. These generally took the form "option_on" or "option_off", depending on whether you wanted to turn the option on or off. Again, the case used for the string is not significant. These older options are still valid; they are noted in the documentation below.

The current options are:

audio = [0|1]

controls whether RTcmix plays audio while executing the scorefile. Turning audio off will cause RTcmix to execute faster than real-time if a soundfile is being written and the scorefile doesn't place a significant load on the processor or disk. For instruments taking real-time input, however, turning the audio off will defeat the input into the instrument. The older-style set_option used the parameters "audio_on" and "audio_off" to control this option.

The default is "AUDIO = ON".

play = [0|1]

turns off the audio output during scorefile execution. This option also interacts with the audio option above. The older-style set_option used the parameters "play_on" and "play_off" to control this option.

The default is "PLAY = ON".

record = [0|1]

turns off audio input during scorefile execution. This option also interacts with the audio option above. It is also affected by the older full_duplex_on, full_duplex_off option. When record is off (or full_duplex_off is in effect), then instruments will not receive any real-time input. In other words, you need to set "record = true" (or the equivalent "on", "1", etc.) if you want to process sound from a mic or line real-time input. Note that this option should be set prior to a call to the rtsetparams scorefile command. The older-style set_option used the parameters "record_on" and "record_off" to change this option.

The default is "RECORD = OFF", except in the [rtcmix~] object; "RECORD = ON" is always enabled for the object.

clobber = [0|1]

controls whether RTcmix overwrites existing sound files without asking. A "true" ("1", "on", etc.) value for clobber means that overwriting is enabled. The older-style set_option used the parameters "clobber_on" and "clobber_off" to control this option.

The default is "CLOBBER = OFF".

print = [0|1]

determines whether or not RTcmix will print information to the standard output and standard error output (i.e. the terminal window) related to scorefile execution -- note parsing and scheduling information, instrument messages, etc. See also the print_on and print_off scorefile commands.

The default is "PRINT = ON".

report_clipping = [0|1]

controls whether RTcmix reports samples that exceed the range provided by signed 16-bit integers. The older-style set_option used the parameters "report_clipping_on" and "report_clipping_off" to set this option.

The default is "REPORT_CLIPPING = ON".

check_peaks = [0|1]

controls whether RTcmix checks, reports, and stores peak amplitude stats in soundfile headers. The older-style set_option used the parameters "check_peaks_on" and "check_peaks_off" to alter this option.

The default is "CHECK_PEAKS = ON".

exit_on_error = [0|1]

determines whether or not RTcmix exits the process when a 'fatal' error is encountered. Generally this is the desired behavior, but if RTcmix is used imbedded within another application, then a full exit may not be appropriate.

The default is "EXIT_ON_ERROR = ON", except in the [rtcmix~] object; "EXIT_ON_ERROR = OFF" is set because shutting down the entire max/msp patch or application for an RTcmix error probably isn't a good idea.

auto_load = [0|1]

sets the ability of RTcmix to automatically load Instruments if an Instrument name is parsed. If this option is set to "true", then an explicit load command is not required for each Instrument used in the score. The default directory for Instrument shared libraries is used (usually RTcmix/shlib), or a different directory can be set using the dsopath option.

The default is "AUTO_LOAD = OFF".

fast_update = [0|1]

allows RTcmix to use a direct-access of static table functions for certain instruments, thus increasing the efficiency of these instruments. Using this option will disable the PField-updating scheme, however. Tables for waveforms and envelopes need to be pre-created using fast_update.

The current list of instruments with this capability includes: WAVETABLE, FMINST, MIX, IIR, STEREO and TRANS.

The default is "FAST_UPDATE = OFF".

full_duplex_on, full_duplex_off

controls whether RTcmix opens the audio device for simultaneous input and output. This option has largely been superceded by the record option. Note that this option should be set prior to a call to the rtsetparams scorefile command, like the record option.

The default is "FULL_DUPLEX = OFF", except in the [rtcmix~] object; "FULL_DUPLEX = ON" is always enabled for the object.

buffer_frames = nsamps

This option sets the default number of samples (nsamps) in each buffer used by RTcmix. Although this seems a rather esoteric paramater, it can have a noticeable effect on RTcmix performance, especially in an interactive application. This option should be set prior to a call to the rtsetparams scorefile command, and in fact the third (optional) paramater for rtsetparams will override this default setting.

The default is "BUFFER_FRAMES = 4096", except in the [rtcmix~] object. The value for nsamps is determined by max/msp.

buffer_count = nbufs

This sets the number of buffers (nbufs) used by the audio conversion device. It is, in fact, a rather esoteric parameter, although it can have an effect on RTcmix perfoprmance.

The default is "BUFFER_COUNT = 2".

device = audio_device_name

indevice = audio_device_name

outdevice = audio_device_name

This option specifies the audio device to use for input and output. The audio_device_name is a string referring to a particular device. For a discussion of device names used, see the ALSA Project device name page. See also the discussion of input sources for the rtinput command.

The device option is useful for specifying multichannel output devices, taking advantage of the multichannel capability of RTcmix. Different devices can be set for input or output using the indevice or outdevice options.

The default is to use the internal computer hardware device.

midi_indevice = midi_device_name

midi_outdevice = midi_device_name

These set the MIDI devices to use for MIDI input (midi_indevice) and output (midi_outdevice). As with the audio device, see the ALSA Project device name page for a discussion of how the MIDI devices used are named.

The default is to use the internal computer hardware MIDI device (if it exists).

dsopath = directory_path

sets up RTcmix to look for Instrument shared libraries in the directory specified by directory_path. This can be an absolute or relative pathname to a directory. This directory is searched by the load operation.

The default is to use the default RTcmix/shlib directory.

rcname = filename

This causes RTcmix to load the file filename containing settings for the various options outlined above. See the note below...

The default setting is to use the .rtcmixrc file in the user's home directory.

homedir = pathname

This will set the internal RTcmix 'homeDir' variable to an arbitrary directory.

The default setting is to use the user's home directory. A whole lotta usin' goin' on.

   set_option("audio = off", "clobber=1")
   rtoutput("myfile.aif")

   set_option("audio=false")
   set_option("clobber = YES")
   rtoutput("myfile.aif")

   set_option("record = on")
   rtsetparams(44100, 2, 128)
   rtinput("AUDIO")

load, print_off, print_on, rtsetparams, rtinput, rtoutput