mvOpen(3dm) mvOpen(3dm) NAME mvOpenFile, mvOpenFD, mvOpenMem - open movie instances SYNOPSIS #include <dmedia/moviefile.h> DMstatus mvOpenFile( const char* fileName, int oflag, MVid* returnMovie ) DMstatus mvOpenFD( int fd, MVid* returnMovie ) DMstatus mvOpenMem( void* pointer, size_t size, MVid* returnMovie ) DESCRIPTION mvOpenFile, mvOpenFD, and mvOpenMem read an existing movie and create a movie instance in memory that holds information about it. A movie instance is a handle that allows you to read, write, edit, and play a movie file. It contains information about the different tracks in a movie. These operations are defined for three different storage media (file name, file descriptor, and memory). mvOpenFile is used to read files on disk. fileName gives the name of the file to open, and oflag must have either O_RDONLY (for read-only access) or O_RDWR (for read/write access) masked in. MPEG files may take additional flags masked into the oflag parameter, to determine whether the MPEG file should be prescanned or not (MV_MPEG1_PRESCAN_OFF), and to determine the decimation factor of the audio (MV_MPEG1_AUDIO_BANDWIDTH_FULL, MV_MPEG1_AUDIO_BANDWIDTH_HALF, MV_MPEG1_AUDIO_BANDWIDTH_QUARTER). Note that MPEG files will have a default audio decimation factor of a quarter. As such the sampling rate will be set to a quarter of its original value. The full bandwidth flag must be used if audio quality is to be played at the same quality of its original recording. Note that in some circumstances, even if a movie is opened O_RDWR, the Movie File Library may still only be able to perform read accesses on it. Reasons for this include incomplete support of certain file formats or lack of necessary compression functionality. mvIsReadOnly(3dm) should be called after a movie has been opened to determine whether or not actions which modify the movie will be allowed. mvOpenFD is used to open a movie from a file descriptor. Using file descriptors allows movies to be embedded within other files. For example, a movie file might be embedded in the file of a word-processing program. When the word processing program is ready to access the movie, it seeks to the position of the movie within its file and passes the file descriptor (fd) to the movie library. mvOpenMem opens a movie of size size at location pointer from memory. mvOpenFile, mvOpenFD, and mvOpenMem all return the identifier for the new movie in returnMovie. If everything goes well they return DM_SUCCESS, otherwise DM_FAILURE is returned. NOTES Movies consist of two parts: the actual frames (called data), and the information used to reference those frames (called metadata). In movie files created by mvCreateFile, both parts are contained in one file, with the metadata portion usually following the data portion. In movie files created on a Macintosh, the two parts are contained in separate files called forks. Data-forks contain the data part of the movie, and resource-forks contain the metadata. Files containing both parts are called single-fork movie files. There are several naming conventions used to associate resource-forks with their data-fork mates. In one convention, the resource-fork for data-fork /tmp/movie.mov (for example) is /tmp/.HSResource/movie.mov: i.e. named identically to the data-fork, residing in a directory called .HSResource directly under the directory containing the data-fork. In another convention, the resource-fork for the same data-fork would be /tmp/%movie.mov--both forks in the same directory, the resource-fork named by prepending a '%' character to the data-fork name. On a Mac, resource-forks are considered to be primarily system files, so their existence is transparent to the user. Therefore, mvOpenFile always expects data-fork names, never resource-fork names. Given a data-fork filename, it automatically searches for a resource-fork complying with either of the above naming conventions, and--if found--uses it during the opening process. If no resource-fork is found, it assumes the data file contains a single-fork movie. Because of this transparent synthesis of the resource-fork name from the input data-fork name, only mvOpenFile works with dual-fork movie files. The Movie library provides the ability to create movies that reference data contained in other movie files (see the byReference parameter of mvCopyFramesAtTime(3dm)). This means that rather than copying data from movie B to movie A and creating references in movie A's metadata to the new data, we can merely create references in movie A's metadata to the data frames residing in movie B. These references are called external references, or aliases. Although this is a very useful capability, the resulting movie file requires that none of the files whose data it uses be moved, modified, or destroyed, since the files contain frames needed by the movie. To create a movie containing no external references from one that does, open an empty movie file, and use mvOptimize(3dm) to copy the external data into the new movie's data section. The result will be a self-contained, or flattened movie. Note that flattened vs. nonflattened and single- vs. double-fork movies are orthogonal concepts. Single- or dual-fork movie files may contain external references, and therefore are not flattened movies, and a movie whose data is entirely self-contained (i.e. flattened) may have its data and metadata in one or two files (i.e. single- or dual-forks, respectively). SEE ALSO mvIntro(3dm), mvCreate(3dm), mvClose(3dm), mvIsReadOnly(3dm), mvGetErrno(3dm), mvCopyFramesAtTime(3dm), mvOptimize(3dm). Page 3