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 following file formats.

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.
Linux	Any format supported by your installed GStreamer plug-ins, as listed on http://gstreamer.freedesktop.org/documentation/plugins.html, including AVI (`.avi`) and Ogg Theora (`.ogg`).

MATLAB throws an error if it cannot construct the object 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).

obj = mmreader(filename, 'P1', V1, 'P2', V2,...) constructs a multimedia reader object, assigning values V1, V2, etc. to the respective specified properties P1, P2, etc. If you specify an invalid property name or property value, MATLAB throws an error and does not create the object. 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
`BitsPerPixel`	Bits per pixel of the video data	Yes
`Duration`	Total length of file in seconds	Yes
`FrameRate`	Frame rate of the video in frames per second	Yes
`Height`	Height of the video frame in pixels	Yes
`Name`	Name of the file from which the reader object was created	Yes
`NumberOfFrames`	Total number of frames in the video stream	Yes
`Path`	String containing the full path to the file associated with the reader	Yes
`Tag`	Generic string for you to set	No	`''`
`Type`	Class name of the object	Yes	`mmreader`
`UserData`	Generic field for any user-defined data	No	`[]`
`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 is 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 to 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.

Counting Frames in a Variable Frame Rate File

To determine the number of frames in a variable frame rate file:

Create the mmreader object:

vidObj = mmreader('varFrameRateFile.wmv')

Read in the last frame:
```
lastFrame = read(vidObj, inf);
```
This counts the number of frames in the file. Note: This step might take a long time to run, as mmreader must decode all video data in the file to reliably count its frames.
Examine the NumberOfFrames property of vidObj to see the frame count:
```
numFrames = vidObj.NumberOfFrames;
```

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 structure 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);

There is no need to close an mmreader object, but when you are finished with it you can clear it from the workspace.

clear(readerobj)