NAME

     auFile - Create a new audio clipfile object.


SYNOPSIS

     auFile parentName ?options?


OPTIONS

  -lts
     Indicates which lts object to use  for  timing  information.
     This  option  must  be  set at some time before the clipfile
     object will do anything.

  -sendAhead
     Indicates how many seconds  in  advance  to  send  data.  By
     default, this value is set at 0.2 seconds.

  -cycleTime
     Indicates how many seconds' worth of data to send at a time.
     Defaults to 1.0 seconds.

  -filename
     Indicates which file to use as a sparc  audio  clipfile.  If
     this  file is not in the correct clipfile format, an attempt
     to read the file as a raw sparc .au is made. If this attempt
     fails, an error is returned and no file is opened.

  -outCmd
     Indicates the command to call when sending data.  This  com-
     mand  will  be  appended  with  a  scatter  buffer  list and
     evaluated. A C interface to a scatter buffer list  accepting
     command can be specified using the @ syntax discussed in the
     application programmer's guide.



DESCRIPTION

     The auFile command creates a new audio clipfile object which
     can be used to read audio data from a file and send the data
     to another object. Data is sent using the  standard  scatter
     buffer  list  method  and can be sent to any object that can
     accept scatter buffer lists. The  data  is  intended  to  be
     eventually  received  by a auPlay object which would presum-
     ably play the audio. The audio clipfile object  expects  the
     data to be stored on disk in the format of a audio clipfile.
     If this format is not true of the file specified, the object
     attempts to read the file as a Sparc audio file.


WIDGET COMMANDS

     The  auFile  command  creates  a  new  command   objectName.
     ObjectName is generated by concatenating the value of parent
     and a unique string which is  generated  on  the  fly.   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 possible:

     objectName configure option ?value option value ...?
          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  addSegment   <clip_start>   <clip_end>   ?-start
     <logical_start>? ?-end <logical_end>?
          Specifies what part of the clipfile  should  be  played
          and   when.  The  values  <clip_start>  and  <clip_end>
          specify in what part of the clipfile is to  be  played.
          For  example,  the  values  0.0 and 10.0 would indicate
          that the first 10 seconds of the  clipfile  are  to  be
          played.  The option -start and -end parameters indicate
          when in terms of logical time (i.e. in terms of the lts
          set  with  the  -lts  configuration option) the segment
          should be played.  If neither -start or -end  is  indi-
          cated,  the  segment is assumed to be played at logical
          time 0.0. If -start is indicated alone, the segment  is
          set  to start at that time. If -end is indicated alone,
          the segment is set to play in such a way as to  end  at
          that time. If both values are indicated, the segment is
          set to start and end at the times  specified  with  the
          appropriate  stretching  or  squeezing necesary to make
          the segment fit. This command returns a segment  id  in
          the form of an integer that can be used to refer to the
          segment in other command. If a segment is specified  to
          play at a logical time during which a different segment
          has already been set to play, an error is returned.

     objectName deleteSegment <segment_id>
          Removes the segment identified by <segment_id> from the
          list of segments to be played.

     objectName clearSegments
          Clears the list of segments to be played. Equivalent to
          deleting  each segment individually with the deleteSeg-
          ment command.

     objectName segmentInfo <segment_id>
          Returns  a  list  of  information  about  the   segment
          <segment_id>. This list is in the form:
               {clip_start clip_end log_start log_end  num_frames
               max_size}
          where clip_start and clip_end specify which part of the
          clipfile is being played, log_start and log_end specify
          when the segment is being played according  to  logical
          time,  num_frames  is  the number of frames in the seg-
          ment, and max_size is the largest frame  size  in  this
          segment in bytes.

     objectName info
          Returns a list of information  about  the  clipfile  in
          general. This list is in the form:
               {num_frames clip_length max_size width height}
          where num_frames is the total number of frames  in  the
          clipfile,  clip_length is the length of the clipfile in
          seconds, max_size is the  largest  frame  size  in  the
          clipfile,  width is the width of each frame, and height
          is the height of each frame.  If width or height is set
          to  0,  this  indicates  that the value is undetermined
          (i.e.  variable or not known).

     objectName ready
          This command readies the object. The lts is checked  to
          see  if  data needs to be sent. If so, data is sent and
          the object queues itself  to  send  data  according  to
          cycleTime  and the segments specified. Before ready can
          be invoked, the -lts option must be  specified  and  at
          least one segment specified. If either of these are not
          true, the ready command will effectively do nothing.

     objectName unready
          This command unreadies the object  stopping  data  from
          being sent.



KEYWORDS

     cm, audio, clipfile, acf, sparc2acf, auFile, cm toolkit


AUTHORS

     David Simpson  (davesimp@cory.berkeley.edu)  Jonathan  Logan
     (logan@cs.cornell.edu)