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
Page 1
mvGetTrackDuration(3dm)mvGetTrackDuration(3dm)
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
*/
Page 2
mvGetTrackDuration(3dm)mvGetTrackDuration(3dm)
#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 ALSOmvIntro(3dm), mvOpen(3dm), mvGetTrackEnable(3dm),
mvGetTrackTimeScale(3dm), mvConvertTime(3dm), mvGetErrno(3dm).
Page 3
