このページの内容は最新ではありません。最新版の英語を参照するには、ここをクリックします。

VideoReader

ビデオ ファイルを読み取るオブジェクトの作成

説明

VideoReader オブジェクトは、ビデオ データを含むファイルの読み取りに使用します。このオブジェクトにはビデオ ファイルに関する情報が格納されており、ビデオからデータを読み取ることができます。関数 VideoReader を使用して VideoReader オブジェクトを作成し、オブジェクトのプロパティを使用してビデオに関する情報をクエリしてから、オブジェクト関数を使用してビデオを読み取ることができます。

詳細については、ビデオおよびオーディオ ファイルのサポート形式を参照してください。

作成

構文

v = VideoReader(filename)

v = VideoReader(filename,Name,Value)

説明

v = VideoReader(filename) は、filename という名前のファイルからビデオ データを読み取るオブジェクト v を作成します。

v = VideoReader(filename,Name,Value) は、名前と値の引数を使用して CurrentTime、Tag、UserData の各プロパティを設定します。たとえば、VideoReader('myfile.mp4','CurrentTime',1.2) は、ビデオの先頭から 1.2 秒後に読み取りを開始します。名前と値の引数は複数指定することができます。各プロパティの名前を一重引用符で囲み、その後に対応する値を指定します。

入力引数

filename — ファイル名

文字ベクトル | string スカラー

ファイル名。文字ベクトルまたは string スカラーとして指定します。

詳細については、ビデオおよびオーディオ ファイルのサポート形式を参照してください。

例: 'myFile.mp4'

例: '../dir/videos/myFile.avi'

データ型: char | string

プロパティ

VideoReader オブジェクトには、ビデオ ファイルに関する情報を格納するプロパティがあります。プロパティは、CurrentTime、Tag および UserData を除いて読み取り専用です。プロパティの値はオブジェクトの作成後に表示や変更が可能です。たとえば、次のコマンドで VideoReader オブジェクト v の Duration プロパティの値を確認します。

D = v.Duration;

BitsPerPixel — ビデオ データのピクセルあたりのビット数

数値スカラー

この プロパティ は読み取り専用です。

ビデオ データのピクセルあたりのビット数。数値スカラーとして指定します。

データ型: double

CurrentTime — 読み取るビデオ フレームのタイムスタンプ

数値スカラー

読み取るビデオ フレームのタイムスタンプ。数値スカラーとして指定します。タイムスタンプはビデオ ファイルの始まりからの秒数で指定されます。CurrentTime の値は、ゼロからビデオの継続時間までの間の値です。

プラットフォームによっては、VideoReader オブジェクトを作成するときに、'CurrentTime' プロパティに正確に 0 ではないが、0 に近い値が含まれる場合があります。'CurrentTime' プロパティのこの値の変動は、各プラットフォームがビデオを処理し読み取る方法の違いに起因します。

例: 5.6

データ型: double

Duration — ファイルの長さ

数値スカラー

この プロパティ は読み取り専用です。

ファイルの長さ (秒単位)。数値スカラーとして指定します。

データ型: double

FrameRate — 1 秒あたりのビデオ フレーム数

数値スカラー

この プロパティ は読み取り専用です。

1 秒あたりのビデオ フレーム数。数値スカラーとして指定します。可変フレーム レートのビデオの場合、FrameRate は平均フレーム レートを示します。

メモ: OS X Yosemite (Version 10.10) 以降では、VideoWriter を使用して書き込まれた MPEG-4/H.264 ファイルは正しく再生されますが、不正確なフレーム レートが表示されます。

データ型: double

Height — ビデオ フレームの高さ

数値スカラー

この プロパティ は読み取り専用です。

ビデオ フレームの高さ (ピクセル単位)。数値スカラーとして指定します。

データ型: double

Name — ファイル名

文字ベクトル | string スカラー

この プロパティ は読み取り専用です。

ファイル名。文字ベクトルまたは string スカラーとして指定します。

データ型: char | string

NumFrames — ビデオ ストリームのフレーム数

数値スカラー

この プロパティ は読み取り専用です。

ビデオ ストリームのフレーム数。数値スカラーとして指定します。

メモ

特定の長さのビデオでは、NumFrames プロパティ値をすぐに使用できない場合があります。NumFrames プロパティを取得するには、コマンド ラインに v.NumFrames を入力します。

データ型: double

Path — ビデオ ファイルの絶対パス

文字ベクトル | string スカラー

この プロパティ は読み取り専用です。

リーダー オブジェクトに関連付けられているビデオ ファイルの絶対パス。文字ベクトルまたは string スカラーとして指定します。

データ型: char | string

Tag — 汎用テキスト

'' (既定値) | 文字ベクトル | string スカラー

汎用テキスト。文字ベクトルまたは string スカラーとして指定します。

例: 'Experiment 109'

データ型: char | string

UserData — ユーザー定義データ

[] (既定値) | 任意のデータ型

ユーザー定義データ。任意のデータ型の値として指定します。

VideoFormat — MATLAB^® でのビデオ形式の表現

文字ベクトル | string スカラー

この プロパティ は読み取り専用です。

MATLAB でのビデオ形式の表現。文字ベクトルまたは string スカラーとして指定します。

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'
3 帯域 uint8	'RGB24'
3 帯域 int8	'RGB24 Signed'
3 帯域 uint16	'RGB48'
3 帯域 int16	'RGB48 Signed'

データ型: char | string

Width — ビデオ フレームの幅

数値スカラー

この プロパティ は読み取り専用です。

ビデオ フレームの幅 (ピクセル単位)。数値スカラーとして指定します。

データ型: double

オブジェクト関数

hasFrame	ビデオ フレームが読み取り可能かどうかを判別
read	1 つ以上のビデオ フレームの読み取り
readFrame	次のビデオ フレームの読み取り
VideoReader.getFileFormats	VideoReader でサポートされているファイル形式

例

VideoReader オブジェクトの作成とビデオの読み取り

サンプル ビデオ ファイル xylophone_video.mp4 の VideoReader オブジェクトを作成します。

v = VideoReader("xylophone_video.mp4");

ビデオから、1 フレームずつすべてのフレームを読み取ります。

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

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

フレーム インデックスと時間を互換的に使用してビデオを読み取る

フレーム インデックスを指定してビデオから 1 フレームを読み取り、次にビデオの残りのフレームを 1 フレームずつ読み取ります。

VideoReader オブジェクトを作成し、CurrentTime プロパティ値を表示します。CurrentTime プロパティ値 0 は、ビデオからフレームが読み取られていないことを示します。

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

ans = 0

フレーム インデックスを指定して、ビデオから 20 番目のフレームを読み取ります。次に、CurrentTime プロパティ値を表示します。read メソッドは、20 番目のフレームが読み取られたことを反映して、CurrentTime プロパティを自動的に更新します。

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

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

• 行優先のレイアウトを使用するコードを生成 — 行優先の配列レイアウトを使用するコードの生成 (MATLAB Coder)

• 配列サイズの制限 — コードを生成する場合、配列の最大要素数は、コード ジェネレーターとターゲット ハードウェアによって制限されます。詳細については、コード生成における配列サイズの制限 (MATLAB Coder)を参照してください。

GPU コード生成

GPU Coder™ を使用して NVIDIA® GPU のための CUDA® コードを生成します。

使用上の注意事項および制限事項:

MATLAB Coder™ Support Package for NVIDIA^® Jetson™ and NVIDIA DRIVE™ Platforms を使用して、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 Video 形式 (.wmv)、または Microsoft^® DirectShow^® を使用する他の形式のデータを読み取る場合、Windows プラットフォーム上のスレッドベースの環境はサポートされません。

詳細については、スレッドベースの環境での MATLAB 関数の実行を参照してください。

バージョン履歴

R2010b で導入

R2021b: スレッドベースの環境のサポート

MATLAB backgroundPool を使用して、バックグラウンドで VideoReader を実行できます。

R2021b: JPEG 2000 イメージでのピクセルの違い

R2021b 以前のリリースの MATLAB では、JPEG 2000 イメージ間でピクセル値が異なる可能性があります。

R2019b: フレーム インデックスまたは時間を使用したビデオ フレームの読み取り

VideoReader オブジェクトは、フレーム インデックスまたは時間を使用した、ビデオ フレームへの相互交換可能なアクセスをサポートします。そのため、read と readFrame を同義的に使用できます。これまでは、一度に 1 つのタイプのアクセスのみ使用できました。read および readFrame を同義的に使用してフレームを読み取ろうとすると、エラーが発生していました。

R2019b: 行優先のレイアウトを使用した生成コードのパフォーマンスが向上

大規模なビデオ ファイルについて、行優先のレイアウト オプションを使用した VideoReader オブジェクトの生成コードのパフォーマンスが向上しました。たとえば、解像度が 1280x720 の H.264 ビデオ ファイルで関数 timingTest を使用した場合、約 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 | データのインポート

トピック

• ビデオ ファイルの読み取り