SNDOUT(1csound)

NAME
sndout - write sound files.

SYNOPSIS
sndout [config_flags] [file]
or
sndout [time_flags] [file]
time_flags:
    -bN	set begin time to N (use  $  to mean current EOF)
    -eN	set end time to N
    -dN	set duration to N
config_flags:
    -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.
sndout reads headers for input data format, sampling rate and number of channels. Flags override header properties.

DESCRIPTION
Sndout reads binary samples from the standard input, and writes them in a file on the sound file system.

The Flags
All flags for sndout take options (except -h), that is, the flag must be followed by a value, with no intervening space.

The flags for 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.

Config_Flags
The -c flag sets the number of channels: 1 = mono, 2 = stereo, 4 = quad.

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.

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.

The flags -S -H and -K set scratch, hold and keep status, respectively for the new file. Note: at CARL, keep mode may not be specified when a new file is created. This is to make it difficult to automatically bequeath keep status on files, since this practice can have antisocial consequences if overused. Use keepsf(1carl).

Comments can be included in sound files by the use of the -r flag. For instance,

% sndout -r"look ma, no hands"

will add this text as a comment in the file.

The -IX (for "include") flag copies the name of the file given in X into the descriptor file. The 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.

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.

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.

Files are created non-contiguous by 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.

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.)

The -t flag can override the -T and -C flags for the mode of the file. Its use is deprecated.

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

% sndout -b.3 -e.7 foo < silencefile

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:

% sndout .3 .7 foo < silencefile

is equivalent to the example above. Here's another equivalent:

% sndout -b.3 -d.4 foo < silencefile

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:

% sndout -b1 -e9.5 < silencefile

Samples will be added from time 1 sec out to a maximum of 9.5 or the end of silencefile.

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.

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:

% sndout -bDLOSRS < ...

will fail, whereas

% sndout -bDLOSRS

will succeed, and begin concatenating at the end of the file.

A better way to concatenate to the end of a sound file is as follows:

% sndout -b$ < samples

The '$' operator specifies "the end of the file" and can be used to guarantee concatenating after the last valid sample.

Flags and Headers
sndout reads headers as described in 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.

SEE ALSO
sndin(1csound)

DIAGNOSTICS
The descriptor of the file is rewritten for each buffer of sound data written. This allows e.g.,
    % lsf -f
to show you how the file is growing, etc.