.TH PLAY 1csound CARL 
.SH NAME
play 
\- play sound file(s) through DACs
.SH SYNOPSIS
.B play 
[
.B flags1
] [
.B filename1
] [
.B flags2
] [
.B filename2
] ... [
.B flagsN
] [
.B filenameN
]
.PP
flags:
.TP
.B -p
prompts you before starting to play file
.TP
.B -i
interactive play mode (see below)
.TP
.B -qN
inserts N secs. silence before file
.TP
.B -rN
repeats file N times (no gap between iterations)
.TP
.B -bN
start file at time N
.TP
.B -eN
end file at time N
.TP
.B -RN
force file to be N sampling rate
.TP
.B -FN
force use of filter N (0, 1, 2, 3) (default tracks the sampling rate)
.TP
.B -Dw,x,y,z...
set dacs to use; can be any of {1, 2, 3, 4}
.TP
.B -v
describe in detail what play is doing
.TP
.B -g
make flags not global
.PP
Defaults: tries to play file test in your current sound file directory
if no name is given.
The right anti-aliasing filter is selected automatically if no -F
is given.
.I Nota
.I Bene:
Once a value is set by a flag, it continues in effect across subsequent
files unless -g is given, in which case flags only affect the file they
appear before.
.RE
.SH DESCRIPTION
.B play 
sends the named sound files to the DACs.  It opens them all first
so the inter-file setup time is minimized.  
.PP
Pressing the [DEL] key aborts immediately.
.PP
The flag structure is different for this program than any other sound file
program in that flags only affect the subsequently named sound file (with
rare exceptions such as -i, see below).
If both a silence flag and repeat flag preceed a file, the silence
only applies to the period before the first time the file is played.  
All repetitions are
without intervening silences.  (Repeats with silence can be obtained by
nameing the file more than once with -q in betwen.)
Example:
.RS .5i
play -p -q10 -r3 buzz -q3 toot -r2 foo bar
.RE
.PP
Here, you will be prompted after 10 seconds of silence, and before 
playing buzz.  Buzz will be repeated 3 times without intervening silence.
After 3 seconds of silence, toot will play once, followed immediately
by two times through foo, and once through bar.  Inter-file silences are
constrained by UNIX to be integer multiples of one second.
.PP
Various default actions of 
.B play
can be overridden.  To play through
a channel besides 1, use the -D flag, e.g., -D4 uses channel 4.  
For a stereo file, try -D1,3.  Override the sampling rate with -R, e.g.,
-R32K.
.PP
The -g flag causes all flags to loose their global interpretation 
for the rest of the files to be set up.  Thus,
.RS .5i
% play -D4 foo baz
.RE
plays both foo and baz through dac channel 4, but  
.RS .5i
% play -g -D4 foo baz
.RE
plays baz through the default channel 1.
Flags copied are:
-q, -r, -q, -F, -D, -b, -e.  Note -R is not copied, thus files of
different sampling rate preserve their own rates.
.SH Interactive Mode
Mentioning the -i flag starts up play's interactive mode.  All files named
are then treated interactively.  After opening all the named files,
a status line and a '*' prompt are displayed.  
The status line shows the current file, its current begin time, end time,
sampling rate, repeat count, silence count, and converters selected.
Most actions of 
.B play 
can
be modified from this point, according to the following rules.
(In these rules, objects inside "[]" are optional.  Rules followed by '*'
can be repeated any number of times).
.TP "\w'[e,b,d][>,<][N] 'u"
.B x
exit play
.TP
.B [e,b,d]=N
set [end,begin,duration] time to N
.TP
.B N
change last altered parameter to N
.TP
.B [e,b,d][>,<][N]
move [e,b,d] [ahead,back] by N
or if N is missing, by increment
.TP
.B !
play the file
.TP
.B !!
repeat the last command
.TP
.B n
and go on to next file
.TP
.B p
go back to previous file
.TP
.B r=N
repeat N times
.TP
.B [>,<]*[N]   
move [ahead,back] begin/end play times by * increments,
increment modified by N
.TP
.B i=N
set increment to N
.TP
.B R=N
set sampling rate to N
.TP
.B D=S
set DAC channels to string S
for mono, S is a single number, for multi-channel,
it is a comma-separated list of numbers
.TP
.B q=N
set N seconds of silence preceeding play of the file
.TP
.B I
enter fast interactive mode
.TP
.B v=1
set verbose mode, v=0 resets it
.TP
.B f=[m,s,ms,S]
set print format of begin/end times on status line to
minutes, seconds, milliseconds, samples.
.TP
.B F=[0,1,2,3]
set lowpass filters, 0=12.8kHz, 1=6.4kHz, 
2=bypass, 3=non-ex
.PP
Time values such as begin and end default to
seconds.  Expressions are allowed for all instances of N. 
Expressions may contain postoperators as follows:
.RS .5i
.nf
k	times 1000
K	times 1024
S	time in samples
s	time in seconds (default)
ms	time in milliseconds 
m	time in minutes 
.fi
.RE
Expressions setting the value of a time variable (b,e,d) may
be the character '$' which
stands for the file boundary time.  For the expression "e=$",
e is set to the end of file, for "b=$, b is set to 0, for "d=$",
both b and e are set to the file boundary times.
Caution must be excersized with postoperators in expressions, since
the postoperators commute across the entire expression.  For example,
the following attempt to set b to one sample before one second,
.RS .5i
* b=1-1S
.RE
will be interpreted instead as
.RS .5i
* b=1S-1S
.RE
or 0.  The effective way to say this is:
.RS .5i
* b=1-(1S)
.RE
.PP
Only one command may appear per line , except '!' which may appear
separately or at the end of any other command.  
If any text follows the single '!' command, it is assumed to be a
UNIX command.  In this case, the window is not played.  Instead,
the samples in the window are piped to the named command.  This allows
the following kind of command:
.RS .5i
* !sndout segment
.RE
which captures the current window in a sound file named segment.
Caution must be exercised with this command, it does not behave like
a similar command in the vi(1) or ex(1) text editors.  In particular,
the samples in the window are always written, so you couldn't do
a command like, e.g.,
.RS .5i
* !date
.RE
to find the time of day, since the date command knows nothing about
getting samples on its stdin!  Also, beware of this:
.RS .5i
* !sndout segment &
.RE
.SH Fast Interactive Mode
From interactive mode, you can enter "fast interactive mode", which
has a slightly different syntax that allows immediate play on each
keystroke, for making very fast adjustments to a window.
In the following list, those commands that immediately play the window
are indicated by "(*)".  All the rest do not immediately play.
.sp
Fast Interactive Mode Commands:
.RS .5i
.nf
x		to quit fast interactive mode,
!		plays current window (*),
b or e		subsequent cmds move only begin or end time,
> or <	move forewards/backwards by increment (*),
w		subsequent commands move window,
b=N or e=N	set begin or end time to N,
i=N		set increment to N
.RE
.fi
.SH Segment Editing
In addition to the interactive commands, the following set of commands
allows one to create, read, alter and/or write information about segments
of a file.
.PP
.B play
has several constructs that expedite editing segments of sound files.
They are
.TP
.B the window
which is the difference of the time of the e and b variables.
.TP
.B the named segment list buffers
Named segment list buffers must be UPPER CASE characters A - Z.
A segment list buffer can be used to keep around a list of segments.
Thus, you can identify segments on one list, save it in a named buffer,
and make other lists, modify values on lists, etc.
.TP
.B the unnamed list buffer
which is used for temporary lists.
.PP
In the following,
N and M are either expressions, or the character '$'; S is a segment 
specification of the
form "s1", "s2", etc.; L is a named list buffer as in sA.
The '$' when appearing in the context of a segment number stands for
the last segment, and when appearing as a time stands for the end
of the current file.
.PP
Segment Editing Commands
.PP
.TP "\w'sbX=sbY or sbX=seY 'u"
.B sr [file] 
read segment file,
.TP
.B sw [file][=L]
write segment file,
without [=L], writes out all segments,
with [=L], writes only segments on list L.
.TP
.B sp[L]
print segments,
without [L], prints all segments.
with [L], prints only segments on list L.
.TP
.B sN
set begin/end playing times to segment N.
.TP
.B sb[N]=[M,S]
set begin time of segment N to number M or segment S,
default for N = current segment,
default for M = current begin/end times,
S is another segment spec. like se5.
.TP
.B sb=N or se=N
set current begin/end time to time N.
.TP
.B sbX=N or seX=N
set begin/end time of segment X in unnamed list buffer
to time N.
.TP
.B sbX=sbY or sbX=seY
set begin/end time of segment X to begin/end time
of segment Y.
.TP
.B s=
set begin/end times of current segment in unnamed list
buffer to playing times.
.TP
.B sN=
set begin/end times of segment N to playing times
.TP
.B sm
make new segment using begin/end playing times, add to
unnamed list buffer.
.TP
.B sd[N]
delete segment N, if no N, current segment, from unnamed
list buffer.
.TP
.B s=N,N,...N!
make temporary segment list from segment number list N
and play it.
.TP
.B sL=N,N,...N
store list of segment numbers N,...N in named 
list buffer L.
.TP
.B sL=M
copy list buffer M into list buffer L.
.TP
.B sL=
copy unnamed list buffer into named list buffer L.
.TP
.B sL
fetch segment list from named list buffer L into 
unnamed buffer.
.TP
.B st[L]
time the creation of segments by hitting [CTRL]-\\
optionally store in list buffer L.

.SH Timing Mode
In normal interactive mode (not fast interactive) there is a way to
play a file (or section of it) and hit a key whenever you want to
mark a segment boundary on the file.  This is called timeing mode.
.PP
To do this, issue the command
.sp
* st
.sp
which says to set up the file's default segment
list buffer to automatically save segments
that are created every time you hit a certain key.  You then start
the file playing 
by giving the usual command:
.sp
* !
.sp
(the command can be given at one fell swoop, of course, as "st!").
While the file is playing, you hit the [CTRL]-\\ keys 
whenever you want to mark the end of a segment.  
The current time (measured in seconds 
from the time in the file where you started playing) is printed at
that point.  
You can use any of the labeled segment list buffers (A - Z, uppercase
only) to save the automatically created segments by the command:
.sp
* stA
.sp
for instance, which will use segment list buffer A instead of the
file's default segment list buffer.  
.PP
If the things you want to mark just go by too fast for you to get,
set the sampling rate to a lower number.  The times of the segments
will all be adjusted by the ratio of current_rate/actual_rate, so the
segments will still have the correct times at the actual_rate speed.
.PP
This operation also succeeds on playing just a short segment of the
file.  Set the begin and end times to the desired values, and proceed
as usual.  The begin time reported for the first segment is the
time at which playing began.
.SH AUTHOR
Gareth Loy
.SH SEE ALSO
record(1x), sndio(1x).
For tutorial information about interactive mode, say 
.sp
help csound/play
.sp
.SH DIAGNOSTICS
If any file is not found, or an illegal flag is encountered, the process
aborts.  Any DAC errors are reported with a quasi-English error message,
plus the value of the DAC DMA status register and the converter's
ASC status register.
Command errors in interactive mode induces a help message.
.SH BUGS
The syntax for interactive play is very strange.  While it is
very efficient (requires
very few keystrokes), it is consequently rather arcane.
It is also difficult to extend.
It should have been done with lex and yacc.
.PP
The mecanism for silences is to call sleep(), which 
only gives time quantization to the one second level.
Thus, the period of silence can be off by as much as .5 secs in either
direction.
.PP
There is a limit of 64 files that can be played at one time.
