.TH "SNDOUT" 1csound CARL
.SH NAME
sndout 
- write sound files.
.SH SYNOPSIS
.B sndout 
[config_flags] [file]
.br
or
.br
.B sndout 
[time_flags] [file]
.nf
time_flags:
.RS .5i
-bN	set begin time to N (use  $  to mean current EOF)
-eN	set end time to N
-dN	set duration to N
.RE
config_flags:
.RS .5i
-cN	number of channels: 1, 2, 4, default: 1; 
-RN	sampling rate: 0 to DHISR, default: DLOSR;
-i	input packing: s (short), f (float), default: f;
-o	output packing s (short), f (float), default: s;
-TN	file size (expressed as time in seconds)
-CN	file size (expressed in cylinders, default: 1;
-tc	realtime flag: r (realtime), n (not realtime), default: n;
-rtext  remark: quoted text string, default: none;
-Ifile  include file: unix filename, default: none;
-pN	file protection: 0000 - 0666, default: (0644)
-S	set scratch status for file
-H	set hold mode 
-K	set keep mode (Note: this is disabled at CARL, see below)
-h	help message, prints a summary of this list.
.RE
.fi
.B sndout 
reads headers for input data format, sampling rate and number of channels.
Flags override header properties.
.SH DESCRIPTION
Sndout reads binary samples from the standard input, and writes them
in a file on the sound file system.
.SH The Flags
All flags for 
.B sndout 
take options (except -h), 
that is, the flag must be followed
by a value, with no intervening space.  
.PP
The flags for 
.B sndout 
are divided on whether they specify how the file
is to be configured (config_flags) or where to start/stop writing samples
into the file (time_flags).  When time_flags are used, it is assumed that
you are modifying an existing file, and the config_flags, if any, are
ignored.
.SH Config_Flags
The -c flag sets the number of channels: 1 = mono, 2 = stereo, 4 = quad.
.PP
The -R flag sets the sampling rate.  At CARL, the default sampling rate
is DHISR sample-frames per second, to match the native speed of our DSC
converters.  A sample frame contains one sample for each channel.
.PP
The -i and -o flags set the packing mode.
Samples appearing on the standard input are expected to be binary floating
point numbers (as indicated in the synopsis
by the 'f' default for the input packing flag).
Similarly, the -o packing flag determines the format of the samples
in the sound file being written.  
By default, samples are stored as shortsams (short integers)
for compactness of storage, and so that
they may be played through converters in realtime. 
.PP
The flags -S -H and -K set 
.I scratch, 
.I hold 
and 
.I keep
status, respectively for the new file.
Note: at CARL, 
.I keep
mode may not be specified when a new file is created.
This is to make it difficult to automatically bequeath
.I keep
status on files, since this practice can have antisocial
consequences if overused.  Use
.I keepsf(1carl).
.PP
Comments can be included in sound files by the use of the -r flag.  For
instance,
.sp
% sndout -r"look ma, no hands"
.sp
will add this text as a comment in the file.
.PP
The -IX (for "include") flag 
copies the name of the file given in X into the descriptor file.
The 
.I csound
file system itself does nothing with this flag except to carry the
filename along in the descriptor file.  However, this mechanism allows
other programs to associate auxiliary data to a sound file.
This could be used, for instance, to keep track of
the names of the score files used to create the sound file, or more
extensive comments, or the like.
.PP
A subset of the unix file protection scheme is implemented. 
Default protection of 0644 is decoded to mean: 6: owner can read and
write the file; 4: owner's group can read the file; 4: others can
read the file.  4 gives read permission, and 2 gives write permission to
owner, owner's group, and others, respectively.  The other protection bits
are reserved; there is (currently) no adjustable 
directory protection.  Directory permission is currently hardwired
as 0644, meaning only the owner may write in it, but all others
may read it.
.PP
.SH Contiguous / Non-contiguous Files
By default, a sound file occupies non-contiguous blocks of storage.
This allows files to grow on demand.  However, there are potential
liabilities
associated with non-contiguous files, in that the time it takes the
disk head to reposition itself from one block to the next may be
greater than the time lag the converters can withstand, resulting in
clicks or missed data.  Generally, for recording, contiguous files
are used to help guard against missed data, 
and for all other purposes, the default non-contiguous
files work fine.
.PP
Files are created non-contiguous by
.B sndout
unless the -T or -C or -tr flags are given.  If any of these flags
appear, the file is made contiguous, and it may not grow in size
beyond the space claimed with these flags.
.PP
The -T and -C flags set the size of contiguous sound files.
The -T flag allows the size of the file to be set in
seconds, the -C flag sets it in units of cylinders.  In either
case, files are measured in units of cylinders, the T flag is just
a convenience.  A file of one
cylinder's length, with short output packing set, mono, at DHISR KHz
sampling rate lasts about 3 seconds.
(Note that this means that a file that may store just a few
samples will still occupy an entire cylinder.)
.PP
The -t flag can override the -T and -C flags for the mode of the file.
Its use is deprecated.
.SH Time_Flags
Once a file is created, its contents can be overwritten, and possibly
extended by use of the time_flags.  For instance, if file named "foo" 
exists and is 1 second long, then
.sp
% sndout -b.3 -e.7 foo < silencefile
.sp
will cause the first .4 secs of the UNIX file silencefile to replace
the contents of foo.
If silencefile is longer
than .4 secs, the remainder is not used.  If it is less than .4 secs,
the remaining samples are unchanged.  Saying:
.sp
% sndout .3 .7 foo < silencefile
.sp
is equivalent to the example above.  Here's another equivalent:
.sp
% sndout -b.3 -d.4 foo < silencefile
.sp
A realtime file can be extended out to the limit of its cylinder allocation this
way.  A non-realtime file can be extended out to the limit of available
cylinders.  For instance, if sound file test is a realtime file,
has 1 cylinder, is mono, using 16 bit samples, at 16KHz sampling
rate, it is able to store 9.5 secs of sound.  Thus, if it currently
stored 1 sec. of sound, the call:
.sp
% sndout -b1 -e9.5 < silencefile
.sp
Samples will be added from time 1 sec out to a maximum of 9.5 or the end of
silencefile.
.PP
Simple arithmetic expressions and the postoperators 's', 'S' and 'K', 'm'
and 'ms' are available and work as they do for sndin.  For instance, -b1KS 
specifies beginning at the 1024'th sample frame.
.PP
The starting sample you specify may not be greater than the length of
the file.  For instance, if file test has DLOSR samples, the call:
.sp
% sndout -bDLOSRS < ...
.sp
will fail, whereas
.sp
% sndout -bDLOSRS
.sp
will succeed, and begin concatenating at the end of the file.
.PP
A better way to concatenate to the end of a sound file is as follows:
.sp
% sndout -b$ < samples
.sp
The '$' operator specifies "the end of the file" and can be used
to guarantee concatenating after the last valid sample.
.SH Flags and Headers
.B sndout
reads headers as described in
.I procom(3carl).
It is gleans the input data format, the sampling rate and number of
channels from the header.  If flags are given for these properties,
they override the values obtained from the header.
.SH SEE ALSO
sndin(1csound)
.SH DIAGNOSTICS
The descriptor of the file is rewritten for each
buffer of sound data written.  This allows e.g., 
.RS .5i
% lsf -f
.RE
to show you how the file is growing, etc.
