NAME

     auPriority - Create a new audio prioritizing and packetizing
     object



SYNOPSIS

     auPriority parentName ?options?



DESCRIPTION

     auPriority can be used to packetize a CMT audio  stream  for
     network transmission. An auPriority object will subsample an
     audio buffer into a group of packets. The object's  -pktFac-
     tor  configuration option specifies how many packets to sub-
     sample the buffer into, and also represents the  subsampling
     factor.   For  example, a buffer of 500 ms of 44,100 Hz, 16-
     bit monaural audio (44,000 bytes) might be  divided  into  6
     packets of 7350 bytes each. Moreover, packet 1 would contain
     samples (0,6,12,...), while packet 2 would  contain  samples
     (1,7,13,...) and so on. Each packet is effectively a 7350 Hz
     resampling of the original.

     The packets generated are then  re-ordered  according  to  a
     priority algorithm that tries to guarantee that a reasonable
     approximation of the original audio can be constructed, a la
     Cyclic-UDP. For the 6 packet case described above the order-
     ing would be: 1 4 2 5 3 6. These packets  are  passed  to  a
     pktSrc  object  which  attempts  delivery in the prioritized
     order.

     An auReassem object must be used to reassemble the  original
     audio  stream  (possibly interpolating) on the other side of
     the network connection.



OPTIONS

  -pktFactor
     An integer specifying the number of packets to  divide  each
     incoming buffer into.



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


  -outCmd
     Indicates the command to call to send packetized data.


WIDGET COMMANDS

     The auPriority 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 ready
          Readies the object. When in the ready state, the object
          operates  as  configured.  If unready, the object drops
          all incoming packets and does nothing. The  ready  com-
          mand must be given after any of the configuration slots
          have been set.

     objectName unready
          Unreadies the object. When in the  unready  state,  the
          object does nothing and drops all data sent to it.

     objectName destroy
          Destroys the object.

     objectName accept scatter-buffer-list
          This command accepts scatter-buffer-list as au data  to
          be  packetized.  A standard scatter buffer list accept-
          ing C  interface  to  this  command  is  registered  as
          objectName.accept.



KEYWORDS

     cm, audio, audiofile, packet, cm toolkit




SEE ALSO

     audio(5), lts(l), auFile(l), auPlay(l), auReassem(l)



AUTHORS

     Jonathan Logan (logan@acm.org)