NAME

     mpegFile - Create a new mpeg file object.


SYNOPSIS

     mpegFile parentName ?options?


OPTIONS

  -lts
     Indicates which lts object to use  for  timing  information.
     This  option must be set at some time before the file 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.

  -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 an mpeg file. This  file  can
     be  a  video  only  mpeg, a full interleaved mpeg video with
     mpeg audio, or an mpeg clipfile (see separate man page).  If
     the  file  is  not an mpeg clipfile, frame offset, time, and
     type tables will be generated on  the  fly  resulting  in  a
     delay  that can be up to many seconds after configuring this
     option of the object.

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

  -maxFrameRate
     Used to specify a maximum sending frame rate. If set  to  0,
     no maximum frame rate is enforced. This option only works if
     cycleTime is non-zero (see cycleTime above).


DESCRIPTION

     The mpegFile command creates a new mpeg  file  object  which
     can  be used to read mpeg 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 mpegPlay object which would presum-
     ably display the frames in a window.  The mpeg  file  object
     expects  the  data  to  be stored on disk in the format of a
     mpeg clipfile. If this format is not true of the file speci-
     fied,  the  object attempts to read the file as a video only
     mpeg or as a full interleaved mpeg video with mpeg audio and
     parse  the  information normally found in a mpeg clipfile on
     the fly.
     If lts speed is set to zero, the object will send all frames
     necessary for the decoding of the frame indicated by the lts
     value. In other words, if the lts value indicates that  a  B
     frame  should be sent, but the lts speed is 0.0, the B frame
     will be sent along with all the necessary I and P frames.
     If lts speed is not zero, the object uses heuristics outline
     in a paper presented at SPIE 94 [Patel, 94] to send frames.


WIDGET COMMANDS

     The mpegFile  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 that 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 File should  be  played  and
          when. The values <clip_start> and <clip_end> specify in
          what part of the file is to be played. For example, the
          values  0.0  and  10.0 would indicate that the first 10
          seconds of the file 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 confi-
          guration option) the segment should be played.  If nei-
          ther -start  or  -end  is  indicated,  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 commands. 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 removeSegment <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
          removing  each segment individually with the removeSeg-
          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
          File  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  File  in  gen-
          eral. 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
          File, clip_length is the length of the file in seconds,
          max_size is the largest frame size in the  file,  width
          is the width of each frame, and height is the height of
          each frame.  If width or height is set to 0, this indi-
          cates 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, mpeg, mpeg clipfile, mpgc, mpegFile, cm toolkit


AUTHORS

     Ketan Patel (kpatel@cs.berkeley.edu)