vision.VideoFileReader

(To be removed) Read video frames and audio samples from video file

The vision.VideoFileReader system object will be removed in a future release. Use the VideoReader object instead.

Description

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

Platforms	File Formats
All Platforms	AVI, including uncompressed, indexed, grayscale, and Motion JPEG-encoded video (.avi) Motion JPEG 2000 (.mj2) Note VideoReader does not support remote reading for formats exclusive to Microsoft® DirectShow®.
All Windows®	MPEG-1 (.mpg) Windows Media® Video (.wmv, .asf) 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
Macintosh	Most formats supported by QuickTime Player, including: MPEG-1 (.mpg) MPEG-4, including H.264 encoded video (.mp4, .m4v) Apple QuickTime Movie (.mov) 3GPP 3GPP2 AVCHD DV 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.
Linux®	Any format supported by your installed plug-ins for GStreamer 1.0 or higher, as listed on https://gstreamer.freedesktop.org/documentation/plugins_doc.html, 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?

Creation

Syntax

videoFReader = vision.VideoFileReader(Filename)

videoFReader = vision.VideoFileReader(___,Name,Value)

Description

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)

Properties

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.

Filename — File name

vipmen.avi (default) | character vector

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.

PlayCount — Number of times to play file

1 (default) | positive integer | inf

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

AudioOutputPort — Output audio data

false (default) | true

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.

ImageColorSpace — Image format

RGB (default) | YCbCr 4:2:2 | intensity video

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

VideoOutputDataType — Output video data type

single (default)

Output video data type, specified as one of the data types listed or 'inherit'. This property applies when the input file contains video. When you set this property to 'inherit', the object sets the output data type to the native data type of the input video.

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

AudioOutputDataType — Output audio samples data type

int16 (default)

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

Usage

Syntax

I = videoFReader()

[Y,Cb,Cr] = videoFReader()

[___,audio] = videoFReader()

[___,EOF] = videoFReader()

Description

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

I — Video frame

truecolor | 2-D grayscale image

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

Y, Cb, Cr — YCbCr color channels

numeric matrices

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

audio — One frame of audio samples

.wav | .mp3 | .mp3 | .mp4 | .ogg | .flac | .au | .aiff | .aif | .aifc

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

Platform	Supported File Name Extensions
All Platforms	AVI (.avi)
Windows	Image: .jpg,.bmp
	Video: MPEG (.mpeg) MPEG-2 (.mp2) MPEG-1.mpg 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.
	Audio: 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: .avi 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 http://support.apple.com/kb/HT3775.
	Audio: Uncompressed .avi
Linux	Motion JPEG 2000 (.mj2) Any format supported by your installed plug-ins for GStreamer 0.1 or higher, as listed on https://gstreamer.freedesktop.org/documentation/plugins_doc.html?gi-language=c, 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.

Note

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.

EOF — End-of-file

true | false

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:

release(obj)

Specific to vision.VideoFileReader

info	Information about specified video file
isDone	End-of-file status (logical)

Common to All System Objects

step	Run System object algorithm
release	Release resources and allow changes to System object property values and input characteristics
reset	Reset internal states of System object

Examples

Read and Play a Video File

Load the video using a video reader object.

vidReader = VideoReader('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 hasFrame(vidReader)
    videoFrame = readFrame(vidReader);
    videoPlayer(videoFrame);
    pause(0.1)
end

Release the objects.

release(videoPlayer);

Tips

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

   matlab.video.read.UseHardwareAcceleration('off') 

  Hardware acceleration can be reenabled by typing:

   matlab.video.read.UseHardwareAcceleration('on')  

Extended Capabilities

C/C++ Code Generation

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

Usage notes and limitations:

• Generated code for this function uses a precompiled platform-specific shared library.

• See System Objects in MATLAB Code Generation (MATLAB Coder).

Version History

Introduced in R2012a

R2022b: vision.VideoFileReader system object will be removed in future release

The vision.VideoFileReader system object will be removed in a future release. Use the VideoReader object instead.