mvGetTrackDuration(3dm)                                mvGetTrackDuration(3dm)


NAME
     mvGetTrackDuration, mvGetTrackOffset, mvGetMovieDuration,
     mvGetEstMovieDuration, mvSetTrackOffset - get and set movie/track offset
     and duration.


SYNOPSIS
     #include <dmedia/moviefile.h>


     MVtime mvGetTrackDuration( MVid track, MVtimescale timeScale );
     DMstatus mvSetTrackOffset( MVid track, MVtime time,
                                MVtimescale timeScale );
     MVtime mvGetMovieDuration( MVid movie, MVtimescale timeScale );
     MVtime mvGetEstMovieDuration( MVid movie, MVtimescale timeScale );
     MVtime mvGetTrackOffset( MVid track, MVtimescale timeScale );


DESCRIPTION
     For information one how to interpret a time, timeScale pair, please see
     the ``Time and Timescale'' section of  mvIntro(3dm).

     These function in the movie library are provided to allow the user to get
     or set information about a movie's time properties, such as a track's
     duration, and a track's starting time.


OFFSET AND DURATION
     Offset and duration are times describing when a track starts and how long
     (in time) a track or movie lasts.

     The definition of "Track Duration" is the ending time of the track.
     mvGetTrackDuration allows the user to find out when a track ends.
     mvGetTrackDuration returns an MVtime (in the timeScale supplied by the
     user).

     The definition of "Movie Duration" is the ending time of the movie--that
     is, "track duration" of the longest track in the movie.
     mvGetMovieDuration allows the user to find out the movie duration.
     mvGetMovieDuration returns an MVtime (in the timeScale supplied by the
     user).  It is possible to open an mpeg movie without first scanning the
     entire movie (see mvOpen).  For such movies mvGetMovieDuration will
     return MV_DURATION_UNKNOWN  until the end of the movie is reached, at
     which point the actual duration of the movie will be returned.  It is
     possible to get an estimate for the duration of such movies by calling
     mvGetEstMovieDuration.

     The valid time interval of a movie or a track is a half-open interval.
     If the duration of a movie is N in a particular time scale, valid movie
     time ranges from 0 to N-1 in that time scale.

     A "Track Offset" is an empty segment at the beginning of a track in a


     movie, for which there is no data. mvSetTrackOffset allows the user to
     set the size of this offset by passing in a time and timeScale, while
     mvGetTrackOffset allows the user to find out what the offset of a track
     currently is. mvGetTrackOffset returns an MVtime representing the offset
     (in the timeScale supplied by the user). Immediately after a track is
     created (e.g., via mvAddTrack), its offset is zero.

     The following diagram will help clarify this.

     Time is increasing from the left. The movie being represented has two
     tracks, the first of which has no offset, and the second of which has an
     offset. (X's represent actual data).

     Note that ``Track 1 Duration'' is the ending time of track 1, and track
     1's offset is 0.

     Track 2 has an offset shown by ``T2 off,'' and note track 2's duration
     includes its offset.

     The movie duration is the same as track 2's duration, because track 2 is
     the longest track in the movie.


          time      0                                               t
          track 1:  XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
          track 2:           XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
                    |<---------Track 1 Duration--------->|
                    |<T2 off>|
                    |<--------------Track 2 Duration--------------->|
                    |<---------------Movie Duration---------------->|


     Also note that while Offsets may be directly set via the mvSetTrackOffset
     call, the duration may not be directly set; it is maintained by the
     library, as data is added or deleted from a track, and as track offsets
     are changed.


RETURN VALUES
     mvGetTrackDuration, mvGetTrackOffset, and mvGetMovieDuration return a
     time value, or -1 on error (eg, a bad movie id, or a bad timescale).

     mvSetTrackOffset returns DM_SUCCESS or DM_FAILURE.


EXAMPLES
          /*
           * this piece of code describes how to find the duration
           * of all tracks in seconds
           */


          #include <moviefile.h>

          #define MY_TIME_SCALE 60

          void ListTrackDuration( MVid movie )
          {
               int i;
               for (i = 0; i < mvGetNumTracks( movie ); ++i) {
                    MVid track;
                    if (mvFindTrackByIndex( movie, i, &track ) != DM_SUCCESS)
                         fprintf( stderr, "could not find track %d\n", i );
                    else {
                         MVtime dur = mvGetDuration( track, MY_TIME_SCALE );
                         fprintf( stdout, "Track %d lasts %f seconds\n",
                                    i,
                                    (float)dur/MY_TIME_SCALE );
                    }
               }
          }


NOTES
     mvGetMovieDuration does NOT take into account track enabled states (see
     mvGetTrackEnable(3dm)).


SEE ALSO
     mvIntro(3dm), mvOpen(3dm), mvGetTrackEnable(3dm),
     mvGetTrackTimeScale(3dm), mvConvertTime(3dm), mvGetErrno(3dm).


                                                                        Page 3