VideoReader

创建对象以读取视频文件

说明

使用 VideoReader 对象读取包含视频数据的文件。该对象包含有关视频文件的信息，并允许您从视频中读取数据。您可以使用 VideoReader 函数创建 VideoReader 对象，使用对象的属性查询视频信息，然后使用对象函数读取视频。

有关详细信息，请参阅支持的视频和音频文件格式。

创建对象

语法

v = VideoReader(filename)

v = VideoReader(filename,Name,Value)

描述

v = VideoReader(filename) 创建对象 v，用于从名为 filename 的文件读取视频数据。

示例

v = VideoReader(filename,Name,Value) 使用名称-值参量设置属性 CurrentTime、Tag 和 UserData。例如，VideoReader('myfile.mp4','CurrentTime',1.2) 开始读取 1.2 秒的视频。您可以指定多个名称-值参量。用单引号将每个属性名称括起来，后跟对应的值。

示例

输入参量

全部展开

`filename` — 文件名
字符向量 | 字符串标量

文件名，指定为字符向量或字符串标量。

根据文件的位置，filename 可以采用下列形式之一。

位置

形式

当前文件夹

指定 filename 中文件的名称。

示例："myFile.mp4"

其他文件夹

如果该文件不在当前文件夹或 MATLAB^® 路径下的文件夹中，则在 filename 中指定完整或相对路径。

示例："C:\myFolder\myFile.mp4"

示例："myFolder\myFile.mp4"

URL

如果文件是通过 Internet URL 定位的，则 filename 必须包含协议类型，例如 http://。

示例：'http://hostname/path_to_file/myFile.mp4'

远程位置

如果文件存储在远程位置，则 filename 必须包含指定为统一资源定位器 (URL) 形式的文件的完整路径：

scheme_name://path_to_file/filename

根据您的远程位置，scheme_name 可以是下表中的值之一。

远程位置	`scheme_name`
Amazon S3™	`s3`
Windows Azure^® Blob 存储	`wasb`, `wasbs`
HDFS™	`hdfs`

有关详细信息，请参阅处理远程数据。

示例："s3://myBucket/myFolder/myFile.avi"

注意

VideoReader 不支持从远程位置读取 Motion JPEG 2000 (.mj2) 文件。

有关详细信息，请参阅支持的视频和音频文件格式。

数据类型: char | string

属性

全部展开

VideoReader 对象的属性中包含有关视频文件的信息。除 CurrentTime、Tag 和 UserData 之外，属性均为只读。您可以在创建对象后查看或修改属性的值。例如，此命令查找 VideoReader 对象 v 的 Duration 属性的值。

D = v.Duration;

`BitsPerPixel` — 视频数据的每像素的位数
只读: 数值标量

此属性为只读。

视频数据的每像素的位数，指定为数值标量。

数据类型: double

`CurrentTime` — 要读取的视频帧的时间戳
数值标量

要读取的视频帧的时间戳，指定为数值标量。时间戳以距视频文件开头的秒数形式指定。CurrentTime 的值介于零和视频持续时间之间。

在某些平台上，当创建 VideoReader 对象时，'CurrentTime' 属性可能包含一个接近但不等于零的值。'CurrentTime' 属性值的这种差异是各个平台处理和读取视频的方式不同而导致的。

示例: 5.6

数据类型: double

`Duration` — 文件的长度
只读: 数值标量

此属性为只读。

文件的长度（以秒为单位），指定为数值标量。

数据类型: double

`FrameRate` — 每秒的视频帧数
只读: 数值标量

此属性为只读。

每秒的视频帧数，指定为数值标量。对于可变帧速率视频，FrameRate 是平均帧速率。

注意：对于 OS X Yosemite（10.10 版）和更高版本来说，使用 VideoWriter 编写的 MPEG-4/H.264 文件能正常播放，但显示的帧速率不精确。

数据类型: double

`Height` — 视频帧的高度
只读: 数值标量

此属性为只读。

视频帧的高度（以像素为单位），指定为数值标量。

数据类型: double

`Name` — 文件名
只读: 字符向量 | 字符串标量

此属性为只读。

文件名，指定为字符向量或字符串标量。

数据类型: char | string

`NumFrames` — 视频流中的帧数
只读: 数值标量

此属性为只读。

视频流中的帧数，指定为数值标量。

注意

对于某些长度的视频，NumFrames 属性的值并不会立即可用。要获取 NumFrames 属性，请在命令行中键入 v.NumFrames。

数据类型: double

`Path` — 视频文件的完整路径
只读: 字符向量 | 字符串标量

此属性为只读。

与 reader 对象相关联的视频文件的完整路径，指定为字符向量或字符串标量。

数据类型: char | string

`Tag` — 常规文本
`''` (默认) | 字符向量 | 字符串标量

常规文本，指定为字符向量或字符串标量。

示例: 'Experiment 109'

数据类型: char | string

`UserData` — 用户定义的数据
`[]` (默认) | 任意数据类型

用户定义的数据，指定为任意数据类型的值。

`VideoFormat` — 视频格式的 MATLAB 表示
只读: 字符向量 | 字符串标量

此属性为只读。

视频格式的 MATLAB 表示形式，指定为字符向量或字符串标量。

除 Motion JPEG 2000 文件之外的文件类型具有下列 VideoFormat 值之一。

视频格式	`VideoFormat` 的值
包含 RGB24 视频的 AVI 或 MPEG-4 文件	`'RGB24'`
包含索引视频的 AVI 文件	`'Indexed'`
包含灰度视频的 AVI 文件	`'Grayscale'`

Motion JPEG 2000 文件具有下列 VideoFormat 值之一。

图像数据格式	`VideoFormat` 的值
单波段 `uint8`	`'Mono8'`
单波段 `int8`	`'Mono8 Signed'`
单波段 `uint16`	`'Mono16'`
单波段 `int16`	`'Mono16 Signed'`
三波段 `uint8`	`'RGB24'`
三波段 `int8`	`'RGB24 Signed'`
三波段 `uint16`	`'RGB48'`
三波段 `int16`	`'RGB48 Signed'`

数据类型: char | string

`Width` — 视频帧的宽度
只读: 数值标量

此属性为只读。

视频帧的宽度（以像素为单位），指定为数值标量。

数据类型: double

对象函数

`hasFrame`	确定是否有视频帧可供读取
`read`	读取一个或多个视频帧
`readFrame`	读取下一个视频帧
`VideoReader.getFileFormats`	`VideoReader` 支持的文件格式

示例

全部折叠

创建 `VideoReader` 对象并读取视频

打开实时脚本

为示例视频文件 xylophone_video.mp4 创建一个 VideoReader 对象。

v = VideoReader("xylophone_video.mp4");

读取视频中的所有帧，一次一帧。

while hasFrame(v)
    frame = readFrame(v);
end

显示 readFrame 返回的最后一帧的有关信息。

whos frame

  Name         Size                Bytes  Class    Attributes

  frame      240x320x3            230400  uint8

清除 VideoReader 对象。

clear v

从特定时间开始读取视频帧

打开实时脚本

为示例视频文件 xylophone_video.mp4 创建一个 VideoReader 对象。

v = VideoReader("xylophone_video.mp4");

指定在距视频开头 2.5 秒的位置开始读取帧。

v.CurrentTime = 2.5;

创建一个 axes 对象来显示该帧。然后，继续读取和显示视频帧，直到没有可供读取的帧为止。

currAxes = axes;
while hasFrame(v)
    vidFrame = readFrame(v);
    image(vidFrame,"Parent",currAxes)
    currAxes.Visible = "off";
    pause(1/v.FrameRate)
end

Figure contains an axes object. The hidden axes object contains an object of type image.

清除 VideoReader 对象。

clear v

使用帧索引读取视频帧

打开实时脚本

为示例视频文件 xylophone_video.mp4 创建一个 VideoReader 对象。

v = VideoReader("xylophone_video.mp4");

只读取第一个视频帧。

firstFrame = read(v,1);

只读取最后一个视频帧。

lastFrame = read(v,Inf);

读取第 5 帧到第 10 帧。

earlyFrames = read(v,[5 10]);

从第 50 帧开始读取到视频文件结束。

lateFrames = read(v,[50 Inf]);

显示视频帧变量的大小和类型信息。

whos *Frame*

  Name               Size                     Bytes  Class    Attributes

  earlyFrames      240x320x3x6              1382400  uint8              
  firstFrame       240x320x3                 230400  uint8              
  lastFrame        240x320x3                 230400  uint8              
  lateFrames       240x320x3x92            21196800  uint8

清除 VideoReader 对象。

clear v

使用帧索引和时间交替读取视频

打开实时脚本

通过指定帧索引从视频中读取一帧，然后以一次一帧的方式读取视频的其余帧。

创建一个 VideoReader 对象，并显示 CurrentTime 属性的值。CurrentTime 属性的零值表示没有从视频中读取任何帧。

vidObj = VideoReader("xylophone_video.mp4");
vidObj.CurrentTime

ans = 
0

通过指定帧索引从视频中读取第 20 帧。然后显示 CurrentTime 属性的值。read 方法会自动更新 CurrentTime 属性，以反映已读到第 20 帧。

frame20 = read(vidObj,20);
vidObj.CurrentTime

ans = 
0.6667

在此点，调用 readFrame 函数将返回第 21 帧。

使用 readFrame 方法读取视频的其余帧。readFrame 方法返回对应于 CurrentTime 属性中时间的帧。例如，以下代码读取并显示从第 21 帧开始的帧，并持续到没有更多帧可读取为止。

while(hasFrame(vidObj))
    frame = readFrame(vidObj);
    imshow(frame)
    title(sprintf("Current Time = %.3f sec",vidObj.CurrentTime))
    pause(2/vidObj.FrameRate)
end

Figure contains an axes object. The hidden axes object with title Current Time = 4.700 sec contains an object of type image.

清除 VideoReader 对象。

clear vidObj

限制

对于某些 MP4 文件，NumFrames 属性可能在 Windows^®、Mac 和 Linux^® 平台中返回不同值。这种差异是由底层平台特定 API 的差异造成的。
对于 Windows 上的某些 AVI、MOV 或 MP4 文件，使用 readFrame 函数读取文件中的所有帧可能会导致帧数不同于 VideoReader 对象的 NumFrames 属性返回的值。

提示

在 Windows 平台上，您无法修改或删除由工作区中的 VideoReader 对象引用的 AVI 文件。要从工作区中删除 VideoReader 对象，请使用 clear 函数。
macOS 平台不再支持某些早期视频文件格式。要使用 VideoReader 读取此类文件，请：
- 使用 QuickTime 播放器打开视频文件。如果播放器检测到文件的格式较旧，则会自动将该文件转换为较新格式。
- 保存新转换的视频文件。
- 使用 VideoReader 读取此新转换的视频文件。

扩展功能

全部展开

C/C++ 代码生成
使用 MATLAB® Coder™ 生成 C 代码和 C++ 代码。

用法说明和限制：

VideoReader 的代码生成支持大多数格式、语法、方法和函数，但有以下限制。

视频格式支持：
- 如果 filename 是编译时常量，则代码生成支持 MATLAB 中支持的所有格式。有关 MATLAB 支持的视频格式的详细信息，请参阅支持的视频和音频文件格式。
- 如果 filename 不是编译时常量，则代码生成仅支持数据可解码为 uint8 数据类型的视频文件。支持的视频格式包括：.MP4、.MOV 和 .AVI。
对象构造：
- 对于 MEX 目标，支持视频文件的部分路径。
- 对于 RTW 目标，您必须提供视频文件的完整或相对路径。
方法和函数：
- read 和 readFrame - 代码生成不支持可选的位置参量 native。
- VideoReader.getFileFormats - 代码生成不支持此方法。
- saveobj 和 loadobj - 代码生成不支持这些函数。
- 属性检查器 - 代码生成不支持此工具。
- 代码生成不支持 VideoReader 对象显示。
平台依赖关系 - 如果在一台特定计算机上为 VideoReader 生成的代码在另一台计算机上不起作用，则请：
- 确保目标计算机上有适合您视频的编解码器。
- 添加测试代码以检查在目标计算机上创建的视频对象是否有效。测试代码可以包括检查视频对象是否具有有效的高度或宽度。例如：
  videoObj = VideoReader(filename); if isnan(videoObj.Height) fprintf('Failed to create video object.\n'); return end
生成使用行优先布局的代码 - Generate Code That Uses Row-Major Array Layout (MATLAB Coder)。
数组大小限制 - 对于代码生成，数组元素的最大数量受代码生成器和目标硬件的限制。有关详细信息，请参阅代码生成的数组大小限制 (MATLAB Coder)。
视频文件位置限制 - 代码生成不支持从远程位置读取文件。

GPU 代码生成
使用 GPU Coder™ 为 NVIDIA® GPU 生成 CUDA® 代码。

用法说明和限制：

使用 MATLAB Coder™ Support Package for NVIDIA^® Jetson™ 和 NVIDIA DRIVE™ 平台，您可以为 MATLAB VideoReader 对象生成 CUDA^® 代码，以读取 NVIDIA 目标硬件上包含视频数据的文件。

要了解如何使用 VideoReader 函数生成读取 NVIDIA 目标上视频文件的 CUDA 代码，请参阅Read Video Files on NVIDIA Hardware (MATLAB Coder)。

生成的代码使用 GStreamer 库 API 读取视频文件。您必须在 NVIDIA 目标平台上安装 GStreamer 库（v1.0 或更高版本）。
对于代码生成，仅支持与 GStreamer 兼容的文件（容器）格式和编解码器。
对于代码生成，VideoReader 函数需要目标硬件上视频文件的完整路径。
方法和函数：
- read 和 readFrame - 代码生成不支持可选的位置参量 native。
- VideoReader.getFileFormats - 代码生成不支持此方法。

基于线程的环境
使用 MATLAB® `backgroundPool` 在后台运行代码或使用 Parallel Computing Toolbox™ `ThreadPool` 加快代码运行速度。

用法说明和限制：

当读取 MPEG-1 格式 (.mpg) 数据、Windows Media 视频格式 (.wmv) 数据或使用 Microsoft^® DirectShow^® 进行解码的其他格式的数据时，此函数不支持 Windows 平台上基于线程的环境。

有关详细信息，请参阅在基于线程的环境中运行 MATLAB 函数。

版本历史记录

在 R2010b 中推出

全部展开

R2021b: 支持基于线程的环境

您可以使用 MATLAB backgroundPool 在后台运行 VideoReader。

R2021b: JPEG 2000 图像中的像素差异

R2021b 中的 JPEG 2000 图像和以前版本的 MATLAB 之间可能存在像素值差异。

R2019b: 使用帧索引或时间读取视频中的帧

VideoReader 对象支持使用帧索引或时间对视频帧进行可互换访问。因此，您可以交替使用 read 和 readFrame。以前，一次只能使用一种类型的访问。尝试混用 read 和 readFrame 读取帧会导致错误。

R2019b: 提高了具有行优先布局的生成的代码的性能

对于大型视频文件，使用行优先布局选项针对 VideoReader 对象生成的代码显示出更高的性能。例如，timingTest 函数对分辨率为 1280x720 的 H.264 视频文件的处理速度可提高 4 倍。

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

使用行优先标志为 timingTest 函数生成代码。codegen 命令创建由生成的 C 和 C++ 代码组成的函数 timingTest_mex。

codegen timingTest-args{coder.typeof('', [1 inf])}-rowmajor

对于分辨率为 1280x720 的 H.264 视频文件，执行时间为：

R2019a：4.04 秒

R2019b：0.95 秒

代码是在运行 Windows 10 的 Intel^® Xeon^® CPU W-2133 @ 3.6 GHz 测试系统上通过调用函数 timingTest_mex 进行计时的。视频文件的分辨率越高（以帧大小衡量），性能改进就越大。

R2019b: 不推荐使用 `NumberOfFrames` 属性

不推荐使用 NumberOfFrames 属性。请改用 NumFrames 属性。目前没有删除 NumberOfFrames 属性的计划。

R2019b: 不支持 `VideoReader` 对象的数组

您无法再创建 VideoReader 对象数组。请更新您的代码以删除 VideoReader 对象的数组。

另请参阅

VideoWriter | mmfileinfo | 导入数据

主题

读取视频文件

VideoReader

说明

创建对象

语法

描述

输入参量

filename — 文件名 字符向量 | 字符串标量

属性

BitsPerPixel — 视频数据的每像素的位数 只读: 数值标量

CurrentTime — 要读取的视频帧的时间戳 数值标量

Duration — 文件的长度 只读: 数值标量

FrameRate — 每秒的视频帧数 只读: 数值标量

Height — 视频帧的高度 只读: 数值标量

Name — 文件名 只读: 字符向量 | 字符串标量

NumFrames — 视频流中的帧数 只读: 数值标量

Path — 视频文件的完整路径 只读: 字符向量 | 字符串标量

Tag — 常规文本 '' (默认) | 字符向量 | 字符串标量

UserData — 用户定义的数据 [] (默认) | 任意数据类型

VideoFormat — 视频格式的 MATLAB 表示 只读: 字符向量 | 字符串标量

Width — 视频帧的宽度 只读: 数值标量

对象函数

示例

创建 VideoReader 对象并读取视频

从特定时间开始读取视频帧

使用帧索引读取视频帧

使用帧索引和时间交替读取视频

限制

提示

扩展功能

C/C++ 代码生成 使用 MATLAB® Coder™ 生成 C 代码和 C++ 代码。

GPU 代码生成 使用 GPU Coder™ 为 NVIDIA® GPU 生成 CUDA® 代码。

基于线程的环境 使用 MATLAB® backgroundPool 在后台运行代码或使用 Parallel Computing Toolbox™ ThreadPool 加快代码运行速度。

版本历史记录

R2021b: 支持基于线程的环境

R2021b: JPEG 2000 图像中的像素差异

R2019b: 使用帧索引或时间读取视频中的帧

R2019b: 提高了具有行优先布局的生成的代码的性能

R2019b: 不推荐使用 NumberOfFrames 属性

R2019b: 不支持 VideoReader 对象的数组

另请参阅

主题

`filename` — 文件名
字符向量 | 字符串标量

`BitsPerPixel` — 视频数据的每像素的位数
只读: 数值标量

`CurrentTime` — 要读取的视频帧的时间戳
数值标量

`Duration` — 文件的长度
只读: 数值标量

`FrameRate` — 每秒的视频帧数
只读: 数值标量

`Height` — 视频帧的高度
只读: 数值标量

`Name` — 文件名
只读: 字符向量 | 字符串标量

`NumFrames` — 视频流中的帧数
只读: 数值标量

`Path` — 视频文件的完整路径
只读: 字符向量 | 字符串标量

`Tag` — 常规文本
`''` (默认) | 字符向量 | 字符串标量

`UserData` — 用户定义的数据
`[]` (默认) | 任意数据类型

`VideoFormat` — 视频格式的 MATLAB 表示
只读: 字符向量 | 字符串标量

`Width` — 视频帧的宽度
只读: 数值标量

创建 `VideoReader` 对象并读取视频

C/C++ 代码生成
使用 MATLAB® Coder™ 生成 C 代码和 C++ 代码。

GPU 代码生成
使用 GPU Coder™ 为 NVIDIA® GPU 生成 CUDA® 代码。

基于线程的环境
使用 MATLAB® `backgroundPool` 在后台运行代码或使用 Parallel Computing Toolbox™ `ThreadPool` 加快代码运行速度。

R2019b: 不推荐使用 `NumberOfFrames` 属性

R2019b: 不支持 `VideoReader` 对象的数组