<commit_before>=head1 NAME

rtoutput - open a new sound file for writing

=head1 SYNOPSIS

B<rtoutput>(I<file_name> [, I<header_type> ] [, I<data_format> ])

=head1 DESCRIPTION

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

After B<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 L<output|output> to open
files for writing, not B<rtoutput>.

=head1 ARGUMENTS

=over 8

=item I<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 L<set_option|set_option> (by saying
set_option("clobber_on")).

=item I<header_type>

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

=over 8

=for html <p>

=item I<aiff>

AIFF format

=item I<aifc>

AIFC format (uncompressed)

=item I<wav>

Microsoft RIFF (Wav) format

=item I<next>

NeXT format (same as I<sun>)

=item I<sun>

Sun "au" format (same as I<next>)

=item I<ircam>

IRCAM format (the older, non-hybrid BICSF format)

=item I<raw>

raw (headerless) format

=back

AIFF is the default if no header type is given.

=item I<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 L<rtsetparams|rtsetparams> at the beginning of the script.

=over 8

=item I<short>

16-bit linear

=item I<float>

32-bit floating point

=item I<normfloat>

32-bit floating point, with samples normally between -1 and +1.

=item S< >I<16>

synonym for "short"

=back

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

=back

=head1 NOTES

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

The case of the I<header_type> and I<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 B<Snd>, choose
"normfloat" format.  If you want to use them in B<Mxv>, choose
the "next" header type.  Many programs don't read AIFC files,
maybe because they assume these are always compressed.<commit_msg>Add info about file name suffix determining header type.<commit_after>=head1 NAME

rtoutput - open a new sound file for writing

=head1 SYNOPSIS

B<rtoutput>(I<file_name> [, I<header_type> ] [, I<data_format> ])

=head1 DESCRIPTION

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

After B<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 L<output|output> to open
files for writing, not B<rtoutput>.

=head1 ARGUMENTS

=over 8

=item I<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 L<set_option|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 I<header_type> string.  Recognized suffixes: ".wav", ".aif",
".aiff", ".aifc", ".snd" (NeXT/Sun), ".au" (NeXT/Sun), ".sf" (IRCAM),
and ".raw".

=item I<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.

=over 8

=for html <p>

=item I<aiff>

AIFF format

=item I<aifc>

AIFC format (uncompressed)

=item I<wav>

Microsoft RIFF (Wav) format

=item I<next>

NeXT format (same as I<sun>)

=item I<sun>

Sun "au" format (same as I<next>)

=item I<ircam>

IRCAM format (the older, non-hybrid BICSF format)

=item I<raw>

raw (headerless) format

=back

AIFF is the default if no header type is given.

=item I<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 L<rtsetparams|rtsetparams> at the beginning of the script.

=over 8

=item I<short>

16-bit linear

=item I<float>

32-bit floating point

=item I<normfloat>

32-bit floating point, with samples normally between -1 and +1.

=item S< >I<16>

synonym for "short"

=back

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

=back

=head1 NOTES

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

The case of the I<header_type> and I<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 B<Snd> editor, choose
"normfloat" format.  If you want to use them in B<Mxv>, choose
the "next" header type.  Many programs don't read AIFC files,
maybe because they assume these are always compressed.
{'fraction_non_alphanumeric': 0.08709735468778118, 'fraction_numerical': 0.006478315637934137, 'mean_word_length': 4.411879259980526, 'pattern_counts': {'":': 0, '<': 70, '<?xml version=': 0, '>': 70, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3267334', 'n_tokens_mistral': 1894, 'n_tokens_neox': 1839, 'n_words': 824}