readFrame

Read next video frame

Syntax

video = readFrame(v)

video = readFrame(v,'native')

Description

video = readFrame(v) reads the next available video frame from the file associated with v.

video = readFrame(v,'native') returns data in the format specified by the VideoFormat property.

Examples

Create VideoReader Object and Read Video

Create a VideoReader object for the example movie file xylophone.mp4.

v = VideoReader('xylophone.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              

Read Video Frames Starting At Specific Time

Create a video reader object and read video frames starting at a specific time.

Create an object to read the example movie file xylophone.mp4.

v = VideoReader('xylophone.mp4');

Specify the reading to begin 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

Read and Play Back Movie File

Read and play back the sample movie file, xylophone.mp4.

Create a VideoReader object to read data from the sample file. Then, determine the width and height of the video.

xyloObj = VideoReader('xylophone.mp4');

vidWidth = xyloObj.Width;
vidHeight = xyloObj.Height;

Create a movie structure array, mov.

mov = struct('cdata',zeros(vidHeight,vidWidth,3,'uint8'),...
    'colormap',[]);

Read one frame at a time until the end of the video is reached.

k = 1;
while hasFrame(xyloObj)
    mov(k).cdata = readFrame(xyloObj);
    k = k+1;
end

Size a figure based on the width and height of the video. Then, play back the movie once at the video frame rate.

hf = figure;
set(hf,'position',[150 150 vidWidth vidHeight]);

movie(hf,mov,1,xyloObj.FrameRate);

Input Arguments

v — Input VideoReader object

VideoReader object

Input VideoReader object. Use the VideoReader function to create a VideoReader object from your video file.

Output Arguments

video — Video frame data

array

Video frame data, returned as an array. The dimensions and data type of video depend on the VideoFormat property of obj.

The following table lists the data type and dimensions of video for most files. H is the image frame height and W is the image frame width. When the VideoFormat property of obj is 'Indexed', the data type and dimensions of video depend on whether you call read with the 'native' argument.

Value of obj.VideoFormat	Data Type of video	Dimensions of video	Description
'RGB24', with or without specifying 'native'	uint8	H-by-W-by-3	RGB24 image
'Grayscale', without specifying 'native'	uint8	H-by-W-by-1	Grayscale image
'Indexed', without specifying 'native'	uint8	H-by-W-by-3	RGB24 image
'Grayscale' or 'Indexed', specifying 'native'	struct	1-by-1	MATLAB® movie, which is an array of frame structure arrays, each containing the fields cdata and colormap.

For Motion JPEG 2000 files, the data type and dimensions of video are as follows.

Value of obj.VideoFormat	Data Type of video	Dimensions of video	Description
'Mono8'	uint8	H-by-W-by-1	Mono image
'Mono8 Signed'	int8	H-by-W-by-1	Mono signed image
'Mono16'	uint16	H-by-W-by-1	Mono image
'Mono16 Signed'	int16	H-by-W-by-1	Mono signed image
'RGB24'	uint8	H-by-W-by-3	RGB24 image
'RGB24 Signed'	int8	H-by-W-by-3	RGB24 signed image
'RGB48'	uint16	H-by-W-by-3	RGB48 image
'RGB48 Signed'	int16	H-by-W-by-3	RGB48 signed image

'native' — Flag to use format specified in VideoFormat property

character vector | string scalar

Flag to use format specified in VideoFormat property, specified as the character vector or a string scalar, 'native'.

Data Types: char | string

Limitations

• 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 than the value returned by the NumFrames property of the VideoReader object.

Extended Capabilities

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

• Code generation for readFrame does not support the optional positional argument native.

• 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).