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 turning 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.
require_sample_rate = [0|1]
determines whether RTcmix will fail if it cannot set the device sampling rate to what the score requests, or if it should allow whatever it is able to set it to. Note that any input sounds will be played at the wrong pitch if the sample rate does not match that of the sounds.
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”.
print_list_limit = n_items
determines how many items will be displayed when RTcmix prints the contents of a Minc list during print, printf, and Minc command parsing. Sometimes complex scores can use very long lists, and limiting what is displayed can keep the text information readable.
The default is “print_list_limit = 16”.
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 embedded 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.
bail_on_parser_warning = [0|1]
determines whether or not RTcmix exits the process when the parser generates a ‘warning’ message. Generally this is not necessary, but if your score does not behave as you expect, sometimes exiting for minor mistakes is the best way to find the problem.
The default is “bail_on_parser_warning = 0”.
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.
NOTE: All of these options may also be specified in a file .rtcmixrc created in your home directory. Check the documentation for the setup_rtcmixrc utility command.
set_option("audio = off", "clobber=1")
rtoutput("myfile.aif")
turns off audio playback and enables overwriting of existing files. This is the standard way to make a script that writes a sound file.
set_option("audio=false")
set_option("clobber = YES")
rtoutput("myfile.aif")
this does exactly the same thing.
set_option("record = on")
rtsetparams(44100, 2, 128)
rtinput("AUDIO")
sets up RTcmix to process audio received from the audio device in real time.