.TH "SNDIN" 1csound CARL
.SH NAME
sndin 
- read csound 
files onto standard output
.SH SYNOPSIS
.B sndin 
[flags] [filename] > output
.nf
.RS .5i
output format:
	if stdout is a tty, writes arabic numbers,
	else if stdout is a file or pipe, writes floatsams
flags:
-oX	X overrides default output format, X can be
		f pipe: floatsams, tty: floating point
		s pipe: shortsams, tty: integer
-t 	force arabic output (even if output is file or pipe)
	equivalent to "sndin | btoa -s"
-bN	set begin time to N
-eN	set end time to N
-dN	set duration to N
-cS	S is a comma-separated list of selected channel numbers
-H	suppress generating a header.
.RE
defaults: 
.RS .5i
begin time = 0, 
end time = end of file, 
file name = file named test in your current sound file directory.
.RE
.SH DESCRIPTION
.B sndin 
reads samples from an existing sound file onto its standard output.
The format it writes depends on what it is connected to, and any output
format flags.  If it's standard output
is connected to a file or pipe, it writes
.B floatsams
(32-bit floating point samples),
else, when connected to a terminal, it writes 
the sample number and sample
value one line for each sample.
.PP
.SH The Flags
All flags for 
.B sndin 
take options (except -h and -t), 
that is, the flag must be followed by a value, with no intervening space.  
.PP
The -o flag sets the output format, 
that is, the format for the samples
to be written on the standard output.  
This flag takes an "option", which is how to do the formatting.
The two forms of the flag are -of and -os.
The 'f' option to this flag is the default.
With this default in action, and the output connected to a file or pipe,
.B floatsams
are written; if connected to a terminal, 
sample number and
floating point format samples
are printed.
The 's' option causes 
.B shortsams
to be written when the output is a file or pipe; if connected to a terminal,
this option causes sample number and integer format sample values to be
printed.
.PP
The -t flag causes arabic text format to be printed even when the output
is connected to a file or pipe.  It is equivalent to the following
command: "sndin | btoa -s".
.PP
By default, 
.B sndin
writes a header on the front of the data.  The -H flag strips this off.
.SH Specifying Begin and End Times
Specify the begin time and/or the end time by supplying -b or
-e flags, as in:
.RS .5i
% sndin -b3
.RE
which will read file 
.I test 
from 3 seconds to the end of the file, or:
.RS .5i
% sndin -e3.1
.RE
which will read file 
.I test 
from the beginning to 3.1 seconds.
.PP
You may express time in samples instead of time in seconds
when indicating beginning and ending points by use of postoperators.
For instance,
.RS .5i
% sndin -b5S -e13ms
.RE
reads file test from its fifth sample
(truncated to the nearest sample frame boundary),
ending at 13 milliseconds.
Available postoperators include S = samples, s = seconds (default),
ms = milliseconds, m = minutes.  The postoperator K = N*1024, and 
k = N*1000.
The -d flag specifies duration instead of end time.
.PP
.SH Channel Selection
The -c flag takes a comma-separated list of channels to output.
Channels are numbered from 1.  The number of
channels is set by the number of channels in the file.
If the file test were, say 8-channel, we could examine the first
ten sample frames of channels 1,3,4
by saying
.RS .5i
% sndin -e10S -c1,3,4
.RE
Note that not including a -c channel specification selects all channels.
.PP
A variant on the channel specification allows a group of channels to
be selected.  Saying -cNxM, where N and M are channel numbers, selects
all channels starting with N, separated by M channels.  For example,
\-c1x2 selects channels 1, 3, 5, 7, 9... out to the number of channels.
This facilitates extraction of channel sets, for instance, of phase
vocoder data, where the vocoder writes odd numbered channels as amplitude,
even numbered channels as frequency.
.PP
There may be no blanks in the list of channels.
.SH AUTHOR
Gareth Loy
.SH SEE ALSO
sndout(1csound).
.SH DIAGNOSTICS
You will be told if the sound file does not exist, or if you may not read it. 
.SH BUGS
The window of samples selected is different depending on the presence or
absence of the -c flag.  With -c absent, all channels are output, and
if the the window selected with -b, -e and -d time flags includes the
S postoperator, then the S postop. specifies 
.I absolute 
.I samples, 
(rather than sample frames).
With -c present, if time flags include the S postop., then the S postop.
specifies
.I sample
.I frames.
Thus, the command
.RS .5i
% sndin -e10S
.RE
prints the first 10 samples of the file.
The command
.RS .5i
% sndin -c1 -e10S
prints channel 1 of the first 10 sample frames.
