NAME

     auSegment - Create a new au file segment object.


SYNOPSIS

     auSegment parentName ?option?


OPTIONS

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

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

  -bandwidth
     Indicates maximum number of bytes per second to send. If set
     to  0,  no  maximum  is  enforced.  For  this option to work
     correctly, cycleTime must not  be  non-zero.  See  cycleTime
     option  below.  In  reality, this option isn't really imple-
     mented and does not affect anything.

  -cycleTime
     Indicates how many seconds worth of data to send at a  time.
     If  set  to 0, the object will send data one frame at a time
     and schedule itself to be called again when the  next  frame
     needs to be sent.

  -filename
     Indicates which file to use as a au file.  This  object  can
     understand Sparc .au files as well as .acf audio chunk files
     (an augmented format we  invented  that  includes  preparsed
     information). This option can be set only once.

  -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.

  -clipStart
     Used to specify where in the clip the segment begins. If set
     to "?", this value is computed from the other timing parame-
     ters as:
     clipStart = clipEnd - (logicalEnd - logicalStart)

  -clipEnd
     Used to specify where in the clip the segment ends.  If  set
     to "end", indicates the end of the clip. If set to "?", this
     value is computed from the other timing parameters as:
     clipEnd = clipStart + (logicalEnd - logicalStart)

  -logicalStart
     Used to specify when in logical time the segment  should  be
     sent. This value must be less than the value for logicalEnd.
     If set to "?", this value is computed from the other  timing
     parameters as:
     logicalStart = logicalEnd - (clipEnd - clipStart)

  -logicalEnd
     Used to specify when in logical time the segment should end.
     This  value  must be greater than the value for logicalStart
     If set to "?", this value is computed from the other  timing
     parameters as:
     logicalEnd = logicalStart + (clipEnd - clipStart)


DESCRIPTION

     The auSegment command creates a new au segment object  which
     can be used to read au 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 an auPlay object which would presum-
     ably play the data through speakers.  The au segment  object
     expects the data to be stored on disk in the format of an au
     chunk file. If this format is not true of  the  file  speci-
     fied,  the object attempts to read the file as a SPARC audio
     file.


WIDGET COMMANDS

     The auSegment 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 info ?startTime ?endTime??
          Returns a list of information about the interval speci-
          fied  by  startTime  and  endTime.  If neither value is
          given,  information  is  returned  about  the  interval
          defined  by  the  attribute -clipStart and -clipEnd. If
          only startTime is given, information is returned  about
          the  specific  frame  at  the time given. All times are
          taken as clip times (i.e. where  0.0  equals  the  clip
          beginning). The information returned consists of a list
          of  five  items:  {numFrames  clipLength  format   sam-
          plingRate channelCount}. The numFrames number indicates
          how many frames are in the interval; clipLength is  the
          length  in seconds of the file; format is the format of
          the data; samplingRate is the  number  of  samples  per
          second; and channel count indicates the number of chan-
          nels defined in the file.

          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. Before ready can be
               invoked, the -lts option  must  be  specified  and
               -clipStart  and  -clipEnd  must specify an inteval
               with length greater than 0 (i.e., clipStart cannot
               equal clipEnd). The same is true for -logicalStart
               and -logicalEnd.

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



KEYWORDS

     cm, au, file, segment,  acf,  auSegment,  .au,  .acf,  SPARC
     audio, cm toolkit


AUTHORS

     Ketan Patel (kpatel@cs.berkeley.edu)