NAME

rtoutput - open a new sound file for writing

SYNOPSIS

rtoutput(file_name [, header_type ] [, data_format ])

DESCRIPTION

Call rtoutput to open a new sound file for subsequent writing by real-time instruments.

After rtoutput creates a sound file, it prints information about the file, such as the header type and sampling rate.

The older disk-based Cmix instruments use output to open files for writing, not rtoutput.

ARGUMENTS

file_name

The name of a sound file, in double-quotes. If the file already exists, the script will terminate with an error, unless you've turned on file clobbering with set_option (by saying set_option("clobber_on'')). If you name the file with a recognized suffix, that suffix will determine the header type, unless overridden by a header_type string. Recognized suffixes: ".wav'', ".aif'', ".aiff'', ".aifc'', ".snd'' (NeXT/Sun), ".au'' (NeXT/Sun), ".sf'' (IRCAM), and ".raw''.

header_type

The type of header to use for the sound file, as a double-quoted string. Note that if you name the file with a recognized suffix (see above), you don't need to specify a header type in this way.

aiff: AIFF format
aifc: AIFC format (uncompressed)
wav: Microsoft RIFF (Wav) format
next: NeXT format (same as sun)
sun: Sun "au'' format (same as next)
ircam: IRCAM format (the older, non-hybrid BICSF format)
raw: raw (headerless) format

AIFF is the default if no header type is given.

data_format

The type of data format to use for the sound file, as a double-quoted string.

NOTE: The sampling rate and number of channels are specified in a call to rtsetparams at the beginning of the script.

short: 16-bit linear
float: 32-bit floating point
normfloat: 32-bit floating point, with samples normally between -1 and +1.
16: synonym for "short''
24: 24-bit linear

"short'' is the default if no data format is given.

NOTES

If you don't want RTcmix to play while you're writing a file, use set_option to turn off playing before you invoke any instruments, by saying set_option("audio_off'').

The case of the header_type and data_format arguments is not significant, nor is their order.

All formats are big-endian, except for "wav,'' which is always little-endian, and "raw,'' which has host byte order.

If you ask for "aiff'' and "float'' (or "normfloat''), you'll get "aifc'' format instead, because AIFF doesn't support floating-point files.

If you want to use floating-point files in the Snd editor, choose "normfloat'' format. If you want to use them in Mxv, choose the "next'' header type. Many programs don't read AIFC files, maybe because they assume these are always compressed.

EXAMPLES

   rtsetparams(22050, 2)
   rtoutput("mysound")

writes a stereo, 16-bit linear AIFF file with 22050 sampling rate.

   rtsetparams(44100, 1)
   set_option("audio_off", "clobber_on")
   rtoutput("myothersound", "wav", "float")