Read video frames and audio samples from video file


The VideoFileReader object reads video frames, images, and audio samples from a video file. The object can also read image files.


File Formats

All Platforms

AVI, including uncompressed, indexed, grayscale, and Motion JPEG-encoded video (.avi)
Motion JPEG 2000 (.mj2)

All Windows®

MPEG-1 (.mpg)
Windows Media® Video (.wmv, .asf, .asx)
Any format supported by Microsoft® DirectShow®

Windows 7 or later

MPEG-4, including H.264 encoded video (.mp4, .m4v)
Apple QuickTime Movie (.mov)
Any format supported by Microsoft Media Foundation


Most formats supported by QuickTime Player, including:
MPEG-1 (.mpg)
MPEG-4, including H.264 encoded video (.mp4, .m4v)
Apple QuickTime Movie (.mov)

Note: For OS X Yosemite (Version 10.10) and later, MPEG-4/H.264 files written using VideoWriter, play correctly, but display an inexact frame rate.


Any format supported by your installed plug-ins for GStreamer 1.0 or higher, as listed on, including Ogg Theora (.ogg).

To read a file:

  1. Create the vision.VideoFileReader object and set its properties.

  2. Call the object with arguments, as if it were a function.

To learn more about how System objects work, see What Are System Objects? (MATLAB).




videoFReader = vision.VideoFileReader(Filename) returns a video file reader System object™, videoFReader, that sequentially reads video frames or audio samples from an input file, Filename.

videoFReader = vision.VideoFileReader(___,Name,Value)additionally sets properties using one or more name-value pairs. Enclose each property name in quotes. For example, videoFReader = vision.VideoFileReader('PlayCount',1)


expand all

Unless otherwise indicated, properties are nontunable, which means you cannot change their values after calling the object. Objects lock when you call them, and the release function unlocks them.

If a property is tunable, you can change its value at any time.

For more information on changing property values, see System Design in MATLAB Using System Objects (MATLAB).

File name, specified as a character vector. The full path for the file needs to be specified only if the file is not on the MATLAB® path.

Number of times to play file, specified as a positive integer.

Output audio data, specified as true or false. Use this property to control the audio output only when the input file contains audio and video streams.

Image format, specified as RGB, YCbCr 4:2:2, or intensity video frames when the input file contains video.

Output video data type, specified as one of the data types listed and inherit. This property applies when the input file contains video.

Data Types: double | int8 | int16 | int32 | uint8 | uint16

Output audio samples data type, specified as one of the data types listed and inherit. This property applies when the input file contains audio.

Data Types: double | single | int16 | uint8



I = videoFReader() returns the next video frame.

[Y,Cb,Cr] = videoFReader() returns the next frame of YCbCr 4:2:2 format video in the color components Y, Cb, and Cr. This syntax requires that you set the 'ImageColorSpace' property to 'YCbCr 4:2:2'

[___,audio] = videoFReader() also returns one frame of audio samples, audio. This syntax requires that you set the AudioOutputPort property to true.

[___,EOF] = videoFReader() also returns the end-of-file indicator, EOF. The object sets EOF to true each time the output contains the last audio sample and/or video frame.

Output Arguments

expand all

Video frame, returned as a truecolor or 2-D grayscale image.

YCbCr color channels of a YCbCr 4:2:2 format image, returned as numeric matrices.

One frame of audio samples, returned in one of the following formats.

PlatformSupported File Name Extensions
All PlatformsAVI (.avi)
Windows Image:
MPEG (.mpeg)
MPEG-2 (.mp2)

MPEG-4, including H.264 encoded video (.mp4, .m4v)
Motion JPEG 2000 (.mj2)
Windows Media Video (.wmv,.asf, .asx, .asx)
and any format supported by Microsoft DirectShow® 9.0 or higher.
WAVE (.wav)
Windows Media Audio File (.wma)
Audio Interchange File Format (.aif, .aiff)
Compressed Audio Interchange File Format(.aifc),
MP3 (.mp3)
Sun Audio (.au)
Apple (.snd)
Macintosh Video:
Motion JPEG 2000 (.mj2)
MPEG-4, including H.264 encoded video (.mp4, .m4v)
Apple QuickTime Movie (.mov)
and any format supported by QuickTime as listed on
Uncompressed .avi
Linux Motion JPEG 2000 (.mj2)
Any format supported by your installed plug-ins for GStreamer 0.1 or higher, as listed on, including Ogg Theora (.ogg).

Windows XP and Windows 7 x64 platform ships with a limited set of 64-bit video and audio codecs. If a compressed multimedia file fails to play, try saving the multimedia file to a supported file format listed in the table above.

If you use Windows, use Windows Media player Version 11 or later.


MJ2 files with bit depth higher than 8-bits are not supported by vision.VideoFileReader. Use VideoReader and VideoWriter for higher bit depths.

Reading audio from compressed MP4 files with video and audio is not supported by vision.VideoFileReader.

End-of-file indicator, returned as true or false.

Object Functions

To use an object function, specify the System object as the first input argument. For example, to release system resources of a System object named obj, use this syntax:


expand all

infoInformation about specified video file
isDoneEnd-of-file status (logical)
stepRun System object algorithm
releaseRelease resources and allow changes to System object property values and input characteristics
resetReset internal states of System object


collapse all

Load the video using a video reader object.

videoFReader = vision.VideoFileReader('ecolicells.avi');

Create a video player object to play the video file.

videoPlayer = vision.VideoPlayer;

Use a while loop to read and play the video frames. Pause for 0.1 seconds after displaying each frame.

while ~isDone(videoFReader)
  videoFrame = videoFReader();

Release the objects.



  • Video Reading Performance on Windows Systems:To achieve better video reader performance on Windows for MP4 and MOV files, MATLAB uses the system's graphics hardware for decoding. However, in some cases using the graphics card for decoding can result in poorer performance depending on the specific graphics hardware on the system. If you notice slower video reader performance on your system, turn off the hardware acceleration by typing:'off') 
    Hardware acceleration can be reenabled by typing:'on')  

Extended Capabilities

Introduced in R2012a