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)