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

Syntax

v = VideoReader(filename)

v = VideoReader(filename,Name,Value)

Description

v = VideoReader(filename) creates object v to read video data from the file named filename.

v = VideoReader(filename,Name,Value) sets the properties 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 filename. Example: "myFile.mp4"
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 filename. Example: "C:\myFolder\myFile.mp4" Example: "myFolder\myFile.mp4"
URL	If the file is located by an internet URL, then filename must contain the protocol type such as, http://. Example: 'http://hostname/path_to_file/myFile.mp4'
Remote location	If the file is stored at a remote location, then filename must contain the full path of the file specified as a uniform resource locator (URL) of the form: scheme_name://path_to_file/filename Based on your remote location, scheme_name can be one of the values in this table. Remote Location scheme_name Amazon S3™ s3 Windows Azure® Blob Storage wasb, wasbs HDFS™ hdfs For more information, see Work with Remote Data. Example: "s3://myBucket/myFolder/myFile.avi" Note VideoReader does not support reading Motion JPEG 2000 (.mj2) files from remote location.

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 VideoFormat
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 VideoFormat
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 the NumFrames property of the VideoReader object.

Tips

• On Windows platforms, you cannot modify or delete an AVI file that is referenced by a VideoReader object in your workspace. To remove VideoReader objects from your workspace, use the clear 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 to uint8 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 and readFrame — Code generation does not support the optional positional argument native.

  • VideoReader.getFileFormats — Code generation does not support this method.

  • saveobj and loadobj — 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 and readFrame — Code generation does not support the optional positional argument native.

  • 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 R2010b

R2021b: 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.