Read virtually any media file in Windows, Linux, or Mac.
Updated 12 Nov 2009

View License

[video, audio] = mmread(filename, frames, time, disableVideo, disableAudio, matlabCommand, trySeeking, useFFGRAB)
mmread reads virtually any media file. It now uses AVbin and FFmpeg to capture the data, this includes URLs. The code supports all major OSs and architectures that Matlab runs on.

filename input file to read (mpg, avi, wmv, asf, wav, mp3, gif, ...) frames specifies which video frames to capture, default [] for all or to specify time

time [startTime stopTime], default [] for all disableVideo disables ALL video capturing, to save memory or time disableAudio disables ALL audio capturing, to save memory or time

matlabCommand Do not return the video structure, but call the function specified by matlabCommand. The function definition must match that of processFrame.m. See processFrame.m for more information.
trySeeking [true] setting this to false makes the code slower but more precise. If the first several frames are distorted or timing information isn't accurate, set this to false.

useFFGRAB [true] Use the new version of mmread, which uses ffmpeg. However, if an audio or video stream can't be read AND you are running Windows try setting this to false (old version).

video is a struct with the following fields:
width width of the video frames
height height of the video frames
rate the frame rate of the video, if it can't be determined it will be 1.

nrFramesTotal the total number of frames in the movie regardless of how many were captured. Unfortunately, this can not always be determined. If it is negative then it is an estimate based upon the duration and rate (normally accurate to within .1%). It can be 0, in which case it could not be determined at all. If it is a possitive number then it should always be accurate.

totalDuration the total length of the video in seconds.
frames a struct array with the following fields:
cdata [height X width X 3] uint8 matricies
colormap always empty
times the corresponding time stamps for the frames (in msec)
skippedFrames some codecs (not mmread) will skip duplicate frames (i.e. identical to the previous) in fixed frame rate movies to save space and time. These skipped frames can be detected by looking for jumps in the "times" field. This field will be true when frames are skipped.

audio is a struct with the following fields:
nrChannels the number of channels in the audio stream (1 or 2)
rate sampling rate of the audio, ex. 44100. If it can't be determined then it will be 1.

bits bit depth of the samples (8 or 16)
data the real data of the whole audio stream. This can be played using wavplay. If time ranges are specified, the length of the data may not correspond to the total time. This normally happens with movies. The issue is that the start of the audio stream is generally counted at the END of the first frame. So, time is shifted by 1/framerate.

nrFramesTotal Audio comes in packets or frames when captured, the division of the audio into frames may or may not make sense.

totalDuration the total length of the audio in seconds.
frames cell array of uint8s. Probably not of great use.
times the corresponding time stamps for the frames (in milliseconds)

If there is no video or audio stream the corresponding structure will be empty.

Specifying frames does not effect audio capturing. If you want only a subsection of the audio use the 3rd parameter "time". Specifying time effects both audio and video. Time is specified in seconds (subsecond resolution is supported with fractional numbers ex. 1.125), starting at 0. Time is defined as startTime (inclusive) to stopTime (exclusive), or using set notation [startTime stopTime).

If there are multiple video or audio streams, then the structure will be of length > 1. For example: audio(1).data and audio(2).data.

[video, audio] = mmread('chimes.wav'); % read whole wav file

video = mmread('mymovie.mpg'); % read whole movie

video = mmread('mymovie.mpg',1:10); %get only the first 10 frames

video = mmread('mymovie.mpg',[],[0 3.5]); %read the first 3.5 seconds of the video

[video, audio] = mmread('chimes.wav',[],[0 0.25]); %read the first 0.25 seconds of the wav
[video, audio] = mmread('chimes.wav',[],[0.25 0.5]); %read 0.25 to 0.5 seconds of the wav, there is no overlap with the previous example.

read a movie directly from a URL
video = mmread('');

video = mmread('mymovie.mpg',[],[],false,true); %read all frames, disable audio

mmread('mymovie.mpg',[],[],false,false,'processFrame'); %Use inline processing for all frames in a movie using the function processFrame.m

Cite As

Micah Richert (2024). mmread (, MATLAB Central File Exchange. Retrieved .

MATLAB Release Compatibility
Created with R14
Compatible with any release
Platform Compatibility
Windows macOS Linux

Community Treasure Hunt

Find the treasures in MATLAB Central and discover how the community can help you!

Start Hunting!
Version Published Release Notes

Fixed the "specified procedure could not be found" error on Win64 systems.

Added support for anonymous functions

Removed __isoc99* functions

Removed dependency on libbz2

Fixed the FFGrab.mexa64: undefined symbol:
avbin_open_filename_with_format error.

Changed to BSD license. Minor bug fixes.

Minor updates are accepted the BSD license.

Several bug fixes and now the code is MUCH faster for sequential reads from the same file.

This is a completely new version that now supports Linux and Mac by using FFmpeg and AVbin.

Fixed a nasty multi-threaded bug that was randomly crashing Matlab.