NAME
auPlay - Create a new audio play object.
SYNOPSIS
auPlay parentName ?options?
DESCRIPTION
The auPlay command create a new object which can be used to
play audio data the consists of a sequence of discrete sam-
ples (au format, which is not the same as Sparc .au format).
An auPlay object cannot play sound until at least the lts
and device slots are set. Once they are both set and the
object is ready, incoming data is played at the appropriate
time using the appropriate device. A device is part of the
auPlay object responsible for actually sending audio data to
a physical device and playing it. Devices currently avail-
able are a Sparc audio device ("sparc"), an AudioFile device
("af"), a Windows-compatible device ("winaudio"), and a
Linux audio device ("linux_audio"). At compile time, one of
those devices is designated as the default and can be
referred to with the name "default".
auPlay objects can be in one of two states: ready or
unready. When first created the object is in the unready
state. The object does nothing in the unready state and all
buffers passed to it will be dropped. The object can be put
into the ready state by calling the object's ready command.
The required slots (lts and device) must be set before cal-
ling the ready command. Any call to the object's configure
command that sets a slot value automatically puts the object
in the unready state and the ready command must be given
again to put the object in action. If the configure command
was used to query a slot's value, the ready/unready state is
unchanged.
OPTIONS
-gain
The output gain at which sound should be played, specified
as a floating point number between 0 and 1. The object does
not actually use this value, but passes it to the device.
-sampleRate
An integer specifying the number of samples per second.
This option is also used only by the device.
-channels
An integer specifying the number of channels of ouput. Used
only by the device.
-output
Destination for the sound. Valid values are the strings
"speaker" and "headphone". Used only by the device.
-sendAhead
How many seconds in advance of scheduled playback time to
send audio data to the device. This affects the amount of
data buffered by the object.
-device
Should be set to the decoding device type. If "default", the
compiled default device will be used. Current device types
are: "sparc" and "af". This slot must be set for the object
to work. Attempting to issue the "ready" command to the
object when this slot has not yet been set will generate an
error.
-lts
Should be set to the logical time system object (lts) to be
used for synchronization. This slot must be set for the
resource object to work. Attempting to issue the "ready"
command to the object when this slot has not yet been set
will generate an error.
WIDGET COMMANDS
The auPlay command creates a new command objectName.
ObjectName is generating by concatenating the value of
parent and a unique string generated internally. The empty
string is a valid value for parent. This new command,
objectName, is used to invoke various operations on the new
object.
For more information on object names and why they are gen-
erated by the cm process and not set by the user, please
read the object management overview for the cm toolkit.
The command objectName has the following general form:
objectName option ?arg arg arg...?
Option and the args determine the exact behavior of the com-
mand. The following commands are available:
objectName configure ?options?
Query or modify the configuration options described
above. If the object was in the ready state (see the
ready command below), the configure command puts the
object into the unready state, requiring the the ready
command be given again for data to start flowing.
objectName destroy
Destroys the object.
objectName ready
This command readies the object. The required slots
(lts and device) must be set.
objectName unready
This command unreadies the object stopping data from
being played.
objectName accept scatter-buffer-list
This command accepts scatter-buffer-list as au data to
be played. A standard scatter buffer list accepting C
interface to this command is registered as
objectName.accept.
objectName deviceList
This command returns a list of devices that are legal
for the configuration slot -device.
objectName stats
This command is not yet implemented but will eventually
return a list of statistics about the objects perfor-
mance.
KEYWORDS
cm, audio, audiofile, play, cm toolkit
SEE ALSO
AF(1), audio(5), lts(l)
AUTHORS
Andrew Swan (aswan@CS.Berkeley.EDU) Jonathan Logan
(logan@acm.org)