MATLAB^®

mmreader - Create multimedia reader object for reading video files

Syntax

obj = mmreader(filename) obj = mmreader(filename, 'P1', V1, 'P2', V2,...)

Description

obj = mmreader(filename) constructs a multimedia reader object, obj, that can read video data from a multimedia file. filename is a string specifying the name of a multimedia file. There are no restrictions on file extensions. By default, the MATLAB software looks for the file filename on the MATLAB path. mmreader supports the file formats listed in the following table:

Platform	Supported File Formats
Windows	AVI (`.avi`), MPEG-1 (`.mpg`), Windows Media^® Video (`.wmv`, `.asf`, `.asx`), and any format supported by Microsoft DirectShow.
Macintosh	AVI (`.avi`), MPEG-1 (`.mpg`), MPEG-4 (`.mp4`, `.m4v`), Apple QuickTime^® Movie (`.mov`), and any format supported by QuickTime as listed on http://www.apple.com/quicktime/player/specs.html.

If the object cannot be constructed for any reason (for example, if the file cannot be opened or does not exist, or if the file format is not recognized or supported), MATLAB throws an error.

obj = mmreader(filename, 'P1', V1, 'P2', V2,...) constructs a multimedia reader object, assigning values V1, V2, etc. to the specified properties P1, P2, etc., respectively. If an invalid property name or property value is specified, MATLAB throws an error and the object is not created. Note that the property value pairs can be in any format supported by the set function, i.e., parameter-value string pairs, structures, or parameter-value cell array pairs. The mmreader object supports the following properties.

Property	Description	Read-Only	Default Value
`Duration`	Total length of file in seconds	Yes
`Name`	Name of the file from which the reader object was created	Yes
`Path`	String containing the full path to the file associated with the reader	Yes
`Tag`	Generic string for the user to set	No	`''`
`Type`	Classname of the object	Yes	`mmreader`
`UserData`	Generic field for any user-defined data	No	`[]`
`BitsPerPixel`	Bits per pixel of the video data	Yes
`FrameRate`	Frame rate of the video in frames per second	Yes
`Height`	Height of the video frame in pixels	Yes
`NumberOfFrames`	Total number of frames in the video stream	Yes
`VideoFormat`	String indicating the video format as it is represented in MATLAB, e.g., `RGB24`	Yes
`Width`	Width of the video frame in pixels	Yes

Remarks

Working with Variable Frame Rate Video

If the video file provided to mmreader is a variable frame rate file (as with many Windows Media Video files), the MATLAB software shows a warning, as in this hypothetical case:

>> obj = mmreader('VarFrameRate.wmv')
Warning: Unable to determine the number of frames in this file.

Summary of Multimedia Reader Object for 'VarFrameRate.wmv'.

  Video Parameters:  23.98 frames per second, RGB24 1280x720.
                     Unable to determine video frames available.

Because the file VarFrameRate.wmv was encoded as a variable frame rate video, the number of frames is not known when you construct the mmreader object.

Attempting to Read Beyond the End of the File

You can still read from a variable frame rate file by specifying the number of frames, but mmreader and read will behave slightly differently depending on the context of the read request.

If you ask for a frame range beyond the end of the file, the system generates an error. For example, suppose you attempt to read frame 3000 in a file that has only 2825 frames:

>> images = read(obj, 3000);
??? The frame range requested is beyond the end of the file.

If the requested frame range straddles the end of the file, the system returns a warning as shown in the next example, where frames 2800–3000 are requested in a file that has only 2825 frames:

>> images = read(obj, [2800 3000]);
Warning: The end of file was reached before the 
requested frames were read completely.  
Frames 2800 through 2825 were returned.

Examples

Construct a multimedia reader object associated with file xylophone.mpg with the user tag property set to 'myreader1'.

readerobj = mmreader('xylophone.mpg', 'tag', 'myreader1');

Read in all the video frames.

vidFrames = read(readerobj);

Find out how many frames there are.

numFrames = get(readerobj, 'numberOfFrames');

Create a MATLAB movie struct from the video frames.

for k = 1 : numFrames
    mov(k).cdata = vidFrames(:,:,:,k);
    mov(k).colormap = [];
end

Play back the movie once at the video's frame rate.

movie(mov, 1, readerobj.FrameRate);