VideoReader
Create object to read video files
Description
Use a VideoReader
object to read files containing video
data. The object contains information about the video file and enables you to read data
from the video. You can create a VideoReader
object using the
VideoReader
function, query information about the video using the
object properties, and then read the video using object functions.
For more information, see Supported Video and Audio File Formats.
Creation
Description
sets the properties v
= VideoReader(filename
,Name,Value
)CurrentTime
, Tag
, and
UserData
using name-value arguments. For example,
VideoReader('myfile.mp4','CurrentTime',1.2)
starts
reading 1.2
seconds into the video. You can specify multiple
name-value arguments. Enclose each property name in single quotes followed by
the corresponding value.
Input Arguments
filename
— File name
character vector | string scalar
File name, specified as a character vector or string scalar.
Depending on the location of your file, filename
can take one of these forms.
Location | Form | ||||||||
---|---|---|---|---|---|---|---|---|---|
Current folder | Specify the name of the file in
Example:
| ||||||||
Other folders | If the file is not in the current folder or
in a folder on the MATLAB® path, then specify the full or
relative path in
Example:
Example:
| ||||||||
URL | If the file is located by an internet URL,
then Example:
| ||||||||
Remote location | If the file is stored at a remote location,
then
Based on your
remote location,
For more information, see Work with Remote Data. Example:
Note
|
For more information, see Supported Video and Audio File Formats.
Data Types: char
| string
Properties
The VideoReader
object has properties that
contain information about the video file. Properties are read-only, except
CurrentTime
, Tag
, and
UserData
. You can view or modify the value of a property
after creating the object. For example, this command finds the value of the
Duration
property of the VideoReader
object,
v
.
D = v.Duration;
BitsPerPixel
— Bits per pixel of video data
numeric scalar
This property is read-only.
Bits per pixel of the video data, specified as a numeric scalar.
Data Types: double
CurrentTime
— Timestamp of video frame to read
numeric scalar
Timestamp of the video frame to read, specified as a numeric scalar. The
timestamp is specified in seconds from the start of the video file. The
value of CurrentTime
can be between zero and the duration
of the video.
On some platforms, when you create a VideoReader
object, the 'CurrentTime'
property might contain a value
close to, but not exactly, zero. This variation in the value of the
'CurrentTime'
property is due to differences in how
each platform processes and reads videos.
Example: 5.6
Data Types: double
Duration
— Length of file
numeric scalar
This property is read-only.
Length of the file in seconds, specified as a numeric scalar.
Data Types: double
FrameRate
— Number of video frames per second
numeric scalar
This property is read-only.
Number of video frames per second, specified as a numeric scalar. For
variable-frame rate video, FrameRate
is the average frame
rate.
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.
Data Types: double
Height
— Height of video frame
numeric scalar
This property is read-only.
Height of the video frame in pixels, specified as a numeric scalar.
Data Types: double
Name
— File name
character vector | string scalar
This property is read-only.
File name, specified as a character vector or string scalar.
Data Types: char
| string
NumFrames
— Number of frames in video stream
numeric scalar
This property is read-only.
Number of frames in the video stream, specified as a numeric scalar.
Note
For certain length videos, the value of the
NumFrames
property is not immediately
available. To get the NumFrames
property, type
v.NumFrames
in the command line.
Data Types: double
Path
— Full path to video file
character vector | string scalar
This property is read-only.
Full path to the video file associated with the reader object, specified as a character vector or string scalar.
Data Types: char
| string
Tag
— Generic text
''
(default) | character vector | string scalar
Generic text, specified as a character vector or string scalar.
Example: 'Experiment 109'
Data Types: char
| string
UserData
— User-defined data
[]
(default) | any data type
User-defined data, specified as a value of any data type.
VideoFormat
— MATLAB representation of video format
character vector | string scalar
This property is read-only.
MATLAB representation of the video format, specified as a character vector or string scalar.
File types, except for Motion JPEG 2000 files, have one of these
VideoFormat
values.
Video Format | Value of
|
---|---|
AVI or MPEG-4 files with RGB24 video | 'RGB24' |
AVI files with indexed video | 'Indexed' |
AVI files with grayscale video | 'Grayscale' |
Motion JPEG 2000 files, have one of the following
VideoFormat
values.
Format of Image Data | Value of
|
---|---|
Single-band uint8 | 'Mono8' |
Single-band int8 | 'Mono8 Signed' |
Single-band uint16 | 'Mono16' |
Single-band int16 | 'Mono16 Signed' |
Three-banded uint8 | 'RGB24' |
Three-banded int8 | 'RGB24 Signed' |
Three-banded uint16 | 'RGB48' |
Three-banded int16 | 'RGB48 Signed' |
Data Types: char
| string
Width
— Width of video frame
numeric scalar
This property is read-only.
Width of the video frame in pixels, specified as a numeric scalar.
Data Types: double
Object Functions
hasFrame | Determine if video frame is available to read |
read | Read one or more video frames |
readFrame | Read next video frame |
VideoReader.getFileFormats | File formats that VideoReader supports |
Examples
Create VideoReader
Object and Read Video
Create a VideoReader
object for the sample video file xylophone_video.mp4
.
v = VideoReader("xylophone_video.mp4");
Read all the frames from the video, one frame at a time.
while hasFrame(v) frame = readFrame(v); end
Display information about the last frame returned by readFrame
.
whos frame
Name Size Bytes Class Attributes frame 240x320x3 230400 uint8
Clear the VideoReader
object.
clear v
Read Video Frames Starting at Specific Time
Create a VideoReader
object for the sample video file xylophone_video.mp4
.
v = VideoReader("xylophone_video.mp4");
Specify to start reading frames at 2.5 seconds from the beginning of the video.
v.CurrentTime = 2.5;
Create an axes
object to display the frame. Then continue to read and display video frames until no more frames are available to read.
currAxes = axes; while hasFrame(v) vidFrame = readFrame(v); image(vidFrame,"Parent",currAxes) currAxes.Visible = "off"; pause(1/v.FrameRate) end
Clear the VideoReader
object.
clear v
Read Video Frames Using Frame Index
Create a VideoReader
object for the sample video file xylophone_video.mp4
.
v = VideoReader("xylophone_video.mp4");
Read only the first video frame.
firstFrame = read(v,1);
Read only the last video frame.
lastFrame = read(v,Inf);
Read frames 5 through 10.
earlyFrames = read(v,[5 10]);
Read from the 50th frame to the end of the video file.
lateFrames = read(v,[50 Inf]);
Display the size and type information of the video frame variables.
whos *Frame*
Name Size Bytes Class Attributes earlyFrames 240x320x3x6 1382400 uint8 firstFrame 240x320x3 230400 uint8 lastFrame 240x320x3 230400 uint8 lateFrames 240x320x3x92 21196800 uint8
Clear the VideoReader
object.
clear v
Read Video Using Frame Index and Time Interchangeably
Read a frame from a video by specifying a frame index, and then read the remaining frames of the video one frame at a time.
Create a VideoReader
object and display the value of the CurrentTime
property. A zero value for the CurrentTime
property indicates that no frames have been read from the video.
vidObj = VideoReader("xylophone_video.mp4");
vidObj.CurrentTime
ans = 0
Read the 20th frame from the video by specifying the frame index. Then, display the value of the CurrentTime
property. The read
method automatically updates the CurrentTime
property to reflect that the 20th frame has been read.
frame20 = read(vidObj,20); vidObj.CurrentTime
ans = 0.6667
At this point, a call to the readFrame
function would return the 21st frame.
Read the remaining frames of the video using the readFrame
method. The readFrame
method returns the frame corresponding to the time in the CurrentTime
property. For instance, this code reads and displays the frames starting at the 21st frame and continues until there are no more frames to read.
while(hasFrame(vidObj)) frame = readFrame(vidObj); imshow(frame) title(sprintf("Current Time = %.3f sec",vidObj.CurrentTime)) pause(2/vidObj.FrameRate) end
Clear the VideoReader
object.
clear vidObj
Limitations
For some MP4 files, the
NumFrames
property can return different values in Windows®, Mac, and Linux® platforms. This variation results from differences in the underlying platform-specific APIs.For some AVI, MOV, or MP4 files on Windows, using the
readFrame
function to read all of the frames in the file can result in a different number of frames from the value returned by theNumFrames
property of theVideoReader
object.
Tips
On Windows platforms, you cannot modify or delete an AVI file that is referenced by a
VideoReader
object in your workspace. To removeVideoReader
objects from your workspace, use theclear
function.The macOS platform no longer supports certain older video file formats. To read such files using
VideoReader
:Open the video file using the QuickTime player. If the player detects the file to be of an older format, then it automatically converts the file to a newer format.
Save the newly converted video file.
Use
VideoReader
to read this newly converted video file.
Extended Capabilities
C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.
Usage notes and limitations:
Code generation for VideoReader
supports most formats,
syntaxes, methods, and functions with the following limitations.
Video Format Support:
If
filename
is a compile-time constant, then code generation supports all the formats supported in MATLAB. For more information on video formats that MATLAB supports, see Supported Video and Audio File Formats.If
filename
is not a compile-time constant, then code generation supports only video files with data that can be decoded touint8
datatype. Supported video formats include:.MP4
,.MOV
, and.AVI
.
Object Construction:
For MEX targets, partial path to the video file is supported.
For RTW targets, you must provide full or relative path to the video file.
Methods and Functions :
read
andreadFrame
— Code generation does not support the optional positional argumentnative
.VideoReader.getFileFormats
— Code generation does not support this method.saveobj
andloadobj
— Code generation does not support these functions.Property Inspector — Code generation does not support this tool.
Code generation does not support
VideoReader
object display.
Platform Dependencies — If the generated code for
VideoReader
on one specific machine does not work on another machine, then:Ensure that the suitable codecs for your video are available on the target machine.
Add test code to check if the video object created on the target machine is valid. Test code can include checking if the video object has valid height or width. For example:
videoObj = VideoReader(filename); if isnan(videoObj.Height) fprintf('Failed to create video object.\n'); return end
Generate Code That Uses Row-Major Layout — Generate Code That Uses Row-Major Array Layout (MATLAB Coder).
Array Size Restrictions — For code generation, the maximum number of elements of an array is constrained by the code generator and the target hardware. For more information, see Array Size Restrictions for Code Generation (MATLAB Coder).
Video File Location Restrictions — Code generation does not support reading files from remote location.
GPU Code Generation
Generate CUDA® code for NVIDIA® GPUs using GPU Coder™.
Usage notes and limitations:
With MATLAB
Coder™ Support Package for NVIDIA®
Jetson™ and NVIDIA
DRIVE™ Platforms, you can generate CUDA® code for the MATLAB
VideoReader
object to read files containing video data on the
NVIDIA target hardware.
To learn how to generate CUDA code for reading video files on the NVIDIA target by
using the VideoReader
function, see Read Video Files on NVIDIA Hardware (MATLAB Coder).
The generated code uses the GStreamer library API to read the video files. You must install the GStreamer library (v1.0 or higher) on the NVIDIA target platform.
For code generation, only the file (container) formats and codecs that are compatible with GStreamer are supported.
For code generation, the
VideoReader
function requires the full path to the video file on the target hardware.Methods and Functions :
read
andreadFrame
— Code generation does not support the optional positional argumentnative
.VideoReader.getFileFormats
— Code generation does not support this method.
Thread-Based Environment
Run code in the background using MATLAB® backgroundPool
or accelerate code with Parallel Computing Toolbox™ ThreadPool
.
Usage notes and limitations:
This function does not support thread-based environments on Windows platforms when reading data in MPEG-1 format
(.mpg
), Windows Media Video format (.wmv
), or
other formats that use Microsoft®
DirectShow® for decoding.
For more information, see Run MATLAB Functions in Thread-Based Environment.
Version History
Introduced in R2010bR2021b: Support for thread-based environment
You can run VideoReader
in the background using MATLAB
backgroundPool
.
R2021b: Pixel differences in JPEG 2000 images
Pixel value differences might exist between JPEG 2000 images in R2021b and previous releases of MATLAB.
R2019b: Read frames in videos using frame index or time
The VideoReader
object supports interchangeable access to video
frames using frame index or time. Therefore, you can use read
and
readFrame
interchangeably. Previously, you could use only one
type of access at a time. Attempting to read frames interchangeably using
read
and readFrame
resulted in an
error.
R2019b: Improved performance in generated code with row-major layout
For large video files, the generated code for the VideoReader
object with a row-major
layout option shows improved performance. For example, the
timingTest
function shows about a 4x speed-up on a
H.264
video file with a resolution of
1280x720
.
function [t, data] = timingTest(fileName) vidObj = VideoReader(fileName); data = cell(20,1); tic; for cnt = 1:20 data{cnt} = readFrame(vidObj); end t = toc; end
Generate code for the timingTest
function with the row-major
flag. The codegen
command creates a function
timingTest_mex
with the C and C++ generated code.
codegen timingTest-args{coder.typeof('', [1 inf])}-rowmajor
For a H.264
video file with a resolution of
1280x720
, the execution times are:
R2019a: 4.04s
R2019b: 0.95s
The code was timed on a Windows 10, Intel®
Xeon® CPU W-2133 @ 3.6 GHz test system by calling the function
timingTest_mex
. The higher the video file resolution
(measured by frame size), the greater the performance improvement becomes.
R2019b: NumberOfFrames
property is not recommended
The NumberOfFrames
property is not recommended. Use the
NumFrames
property instead. There are no plans to remove
the NumberOfFrames
property.
R2019b: Array of VideoReader
objects is not supported
You can no longer create an array of VideoReader
objects. Update
your code to remove arrays of VideoReader
objects.
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)