an open-source digital signal processing and sound synthesis language
about · links · contact
rtoutput - open a new sound file for writing


Synopsis

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

Parameters inside the [brackets] are optional.


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 (unless the print_off scorefile command has been issued).


Arguments

"file_name"
A text string with 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.

Although most soundfile programs now deal with nearly all soundfile types, older advice in this documentation suggested that if you want to use floating-point files in the Snd editor, choose "normfloat'' format. If you want to use them in MiXViews editor, 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")
writes a mono, 32-bit floating-point WAV file with 44100 sampling rate. RTcmix will write over any existing file with the same name, and will not play audio while writing.


See Also

bus_config, rtsetparams, rtoutput, set_option