こちらの製品の販売は終了しました。


概要

TMPGEnc Reader SDK for Unity は、MP4(H.264/AAC) ファイルなど一般的なファイルをMovieTexture を経由することなく、Unity 上で直接再生させることができるアセットです。映像、音声ファイルの読み込み、デコードには Microsoft Media Foundationを利用する為、汎用的なフォーマットをCodec 不要で利用可能です。

  • MP4(H.264/AAC) など汎用的な動画ファイルを直接再生可能
  • 映像は Texture2D 、音声は AudioClip として入力されるので、 Unity 上で容易に取り扱いが可能
  • ハードウェア支援による高速なレンダリングを実現　*GPUに依存
  • GPL/LGPL などCopyleft なライセンスは含まれておりません。

デモ動画

対応環境

サポートプラットフォーム

  • Windows 7 / Windows 8.1 / Windows 10 (x86 / x64)
    • Windows Runtime (UWP) は非対応。
    • Visual C++ 2015 ランタイムのインストールが必要 (インストーラー用マージモジュールは同梱)。
  • Unity 5.3.5f1 以降
    • Graphics API は Direct3D 11 専用です。

サポートファイルフォーマット

  • Microsoft Media Foundation が対応しているフォーマット
    • Video - H.264, H.265 (Windows 10), WMV など
    • Audio - AAC, WMA など
    • System - MP4, MKV (Windows 10), ASF など
　

*映像、音声はそれぞれ第 1 ストリームのみの対応となります。

使用方法

導入

  1. Unity Editor を Direct3D11 モードで起動します。
  2. PlayerSettings (Edit > Project Settings > Player > PlayerSettings > Ohter Settings) で Graphics API を Direct3D11 のみに設定します。
  3. 任意の Unity プロジェクトにプラグインの unitypackage をインポートします。 　
    • プラグインとして必要なファイルは "Plugins"、 "TMPGEncReaderSDK/Scripts" フォルダー以下のものです。この2つのフォルダーをインポートしてください。
    • unitypackage には簡易サンプルアプリの Scene ファイルが含まれています。不要な場合は "TMPGEncReaderSDK/Samples" と "StreamingAssets" フォルダーをインポート対象から除外してください。
    • "TMPGEncReaderSDK/Redist" には Visual C++ ランタイムのマージモジュールが含まれています。作成されたアプリケーションの頒布時にインストーラーに組み込んでください。
  4. "AVReaderPluginManager" の GameObject を生成します。
    GameObject > TMPGEnc Reader > AVReaderPluginManager を選択し、 GameObject を生成します。
    • AVReaderPluginManager は OS のビデオエンジンの初期化／開放などの手続きを簡略化するためのものです。
    • AVReaderPluginManager は AVPlayer を最初に使用するシーンかその前に読み込まれるシーンに 1 つ配置してください。アプリケーション開始時のシーンに配置することを推奨します。
    • DontDestroyOnLoad が適用されるためアプリケーション起動中は存在し続けます。
　　　　　 　　　　　　　

ムービーを再生する

　　　　　
  1. "AVPlayer" の GameObject を生成します。 GameObject > TMPGEnc Reader > AVPlayer を選択し、 GameObject を生成します。
  2. スクリプト開始時にソースファイルを開く場合は下記設定を行います。
    * 任意のタイミングで開く場合は、別途スクリプトから OpenAsync メソッドを実行してください。
    1. "Load Source File on Start" にチェックを入れます。
    2. Inspector の "AV Player" の "Source File Path" で再生するソースファイル名を指定します。 　
      • "Load from StreamingAssets Folder" にチェックをいれると、"StreamingAssets" フォルダー以下のファイルを相対パスとして登録します。
    3. コールバックイベントの実装を行います。任意の MonoBehavior スクリプトに最低でも下記2つのイベントハンドラーの実装、登録が必要になります。
      • OnOpenSource(AVPlayer, OpenResult) イベント : ソースを開く処理が完了したら通知されるイベントです。 OpenResult が Success だった場合、描画ターゲットとなる GameObject に対して Material の設定をするコードを実装します。 "AV Player" からは映像が更新された Texture やフォーマット情報が取得できます。
      • "OnPreviewCloseSource(AVPlayer)" イベント : ソースを閉じる処理が行われる直前に通知されるイベントです。 Open 時に設定した Texture への参照を外してください。ソースが閉じられるとプラグイン内部で保持している Texture が破棄されるため、参照を外しておかないと以降の Unity の動作が不安定になります。
    4. ソースファイルを開き、且つ再生も開始する場合は "Start Playback after Source File Loading" にチェックを入れてください。
    　　　　　　
　　　　　　　 　　　　　　　

Texture について

プラグインから渡される Texture の映像は UV 座標 (0.0, 0.0) が左上、 (1.0, 1.0) が右下になります。
適用先の Mesh の頂点設定によっては意図せずに回転、反転して表示される場合もありますが、そのような場合は適切な Mesh にするか、 Shader で補正をしてください。 また、映像のアスペクト比補正は行われませんので、映像のサイズとピクセル比を考慮して描画位置の補正を行ってください。詳細は API リファレンスをご確認ください。
Texture が有効なのは Open 〜 Close 間のみです。 Texture への参照管理は十分注意してください。

API リファレンス

高レベル API

MonoBehaviour を継承し、直接 GameObject で使用できるクラスです。


Pegasys.AVReader.AVReaderPluginManager

プラグインが有効な状態を維持します。
(Awake で PluginLoader.AVReaderInitialize を、 OnDestroy で AVReaderFinalize を実行する)
また、 AVReaderPluginSetting に対する設定を Inspector で行うことができます。


Field / Property

AllowHardwareDecoder

ハードウェアデコーダーの使用を許容するかどうかを指定します。
詳細は "Pegasys.AVReader.AVReaderPluginSetting" を参照してください。


AllowDirect3D11Video

ビデオ API として Direct3D 11 Video API を許容するかどうかを指定します。
詳細は "Pegasys.AVReader.AVReaderPluginSetting" を参照してください。


AudioBufferLengthSec

音声バッファの長さを秒単位で指定します。
詳細は "Pegasys.AVReader.AVReaderPluginSetting" を参照してください。

　　　　　

LogType

Unity Console に出力するデバッグ用のログの設定を指定します。
詳細は "Pegasys.AVReader.LogType" を参照してください。

　　　　　

Method

AVReaderInitialize

プラグインの初期化を行います。
何度でも実行は可能ですが、実際の初期化処理は最初の一回のみとなります。 初期化処理が行われた状態でのみ、プラグインの機能が利用可能になります。

　　　　　

AVReaderFinalize

プラグインの解放処理を行います。
AVReaderInitialize を実行した回数と同じ回数を実行する必要があります。 最後の AVReaderFinalize が呼ばれた際に実際の解放処理が行われます。

　　　　　

Pegasys.AVReader.AVPlayer

ムービープレイヤーのクラスです。
映像は Unity の Texture としてレンダリングされます。
音声は AudioClip として入力されたソースを AudioSource で再生します。
AudioSource に依存しているため、GameObject に AudioSource が登録されている必要があります。


Field / Property

OpenOnStart

Start イベントが呼ばれた際にソースファイルを開くかどうかを設定します。


OpenOnStartSourcePath

OpenOnStart = true 時、開くソースのパス。


OpenOnStartLoadFromStreamingAssets

OpenOnStartSourcePath で指定したパスが "StreamingAssets" 下のパスかどうかを指定します。
true にした場合、 StreamingAssets 下のファイルとして扱い、相対パスとして開きます。
false にした場合はソースパスを絶対パスとして指定する必要があります。
アプリケーション内のムービーを再生する場合は "StreamingAssets" 下にムービーファイルを配置し、 true にした上で相対パスを OpenOnStartSourcePath に指定してください。


OpenOnStartRequestVideo

OpenOnStart = true 時、指定する RequestVideo フラグ。
詳細は OpenAsync メソッドを参照。


OpenOnStartRequestAudio

OpenOnStart = true 時、指定する RequestAudio フラグ。
詳細は OpenAsync メソッドを参照。


OnOpenSource

OpenAsync メソッドの処理結果を通知するためのイベントハンドラーを登録します。
成功／失敗に関わらず通知されます。
映像を表示する場合、このイベントで Material の設定等を行ってください。


OnPreviewCloseSource

CloseAsync メソッドなど、ソースを閉じる処理をこれから行うことを通知するイベントハンドラーを登録します。
Close をキャンセルすることはできません。 このイベントで VideoTexture への参照を外してください。
ソースを閉じる処理は OnDestroy からも呼ばれますが、その場合でもこのイベントは通知されます。


OnCloseSource

CloseAsync メソッドなど、ソースを閉じる処理を行ったことを通知するイベントハンドラーを登録します。
ソースを閉じる処理は OnDestroy からも呼ばれますが、その場合でもこのイベントは通知されます。


OnEndOfSource

再生しているソースが終端に到達した際に通知されるコールバックを登録します。
Loop = true に設定がされていても通知されます (通知後にループ) 。


PlayOnOpenSucceed

ムービーのオープンに成功した場合、再生も開始するかどうかを指定します。


Loop

ムービーをループ再生するかどうかを指定します。


IsOpened

ファイルが開かれているかどうかを取得します。


OpenResult

ファイルオープンの結果を取得します。ファイルが開かれていない時は HasValue = false となります。


HasVideo

映像ソースの有無を取得します。requestVideo = false で開いた場合、実際のファイルに映像ソースがあったとしても false になります。


HasAudio

音声ソースの有無を取得します。requestAudio = false で開いた場合、実際のファイルに音声ソースがあったとしても false になります。


CurrentStatus

現在のプレイヤーの状態を取得します。


IsSeeking

現在シーク処理中かどうかを取得します。


CurrentPosition

再生中の現在位置 (時間) を取得します。設定はできません。* 設定は、SeekAsync メソッドで行います。


Duration

ソースの長さを取得します。


VideoFormat

映像フォーマットを取得します。


AudioFormat

音声フォーマットを取得します。


VideoTexture

映像のテクスチャ。このテクスチャにデコードした映像が更新されます。 　　　　　　　

    　　　　　　　
  • VideoTexture はソースが閉じられると内部的には破棄されています。参照した場合は OnPreviewCloseSource イベントで必ず参照を外してください。
  • テクスチャサイズはソースのピクセル数がそのまま適用されます。
    例えば 1440x1080, 16:9 ソースの場合、 1920x1080 のテクスチャではなくそのまま 1440x1080 のテクスチャになります。
  • アスペクト比は VideoFormat から取得できます. 当該パラメータを元に任意の方法で適正な表示になるように補正してください。
    * VideoFormat で取得されるアスペクト比はピクセルアスペクト比です。
    • 　　　　　　　


AudioClip

音声ソースの AudioClip を取得します。音声サンプルを取得して別途処理を行いたい場合に使用します。


Method

OpenAsync

ソースファイルを開きます。動作は非同期になります。結果は OnOpenSource フィールドに定義するコールバックへ非同期で通知されます。

  • sourcePath: ソースファイルパス。フルパスで指定します。
  • requestVideo: 映像ソースを要求するかどうかを設定します。映像を含むソースファイルで音声だけを開く場合は false を指定します。
  • requestAudio: 音声ソースを要求するかどうかを設定します。音声を含むソースファイルで映像だけを開く場合は false を指定します。


CloseAsync

ソースファイルを閉じます。処理は非同期になります。実際に閉じる直前に OnPreviewCloseSource フィールドに定義するコールバックへ、また閉じた後に OnCloseSoure フィールドに定義するコールバックへそれぞれ非同期で通知されます。


SeekAsync

指定した時間に再生位置を移動します。動作は非同期になります。

  • pos: 移動先時間


PlayAsync

再生を開始します。動作は非同期になります。


Pause

再生を一時停止します。


低レベル API

MonoBehaviour を継承しない クラス です。通常は高レベル API を利用してください。


Pegasys.AVReader.AVReaderPluginSetting

プラグイン全体に関する設定を行うクラスです。実際のアクセスは Default プロパティから取得できる参照から行います。


Field / Property

IsAvailablePlugin

プラグインが有効かどうかを取得します。有効にならない条件は下記のものなどが考えられます。

  • 初期化が行われていない。 AVReaderPluginManager が存在しない場合など。
  • Unity の Graphics API が Direct3D 11 になっていない。
  • システムが必要な要件を満たしていない場合


AllowHardwareDecoder

ハードウェアデコーダーの使用を許容するかどうかを指定します。

  • true の場合、ハードウェアデコーダー機能が利用ができる場合は利用します。
  • false の場合は常にハードウェアアクセラレーションを無効とし、強制的にソフトウェアデコーダーを利用するようにします。
通常は true を設定してください。


AllowDirect3D11Video

ビデオ API として Direct3D 11 Video API を許容するかどうかを指定します。

  • true の場合、 Direct3D 11 Video API が利用ができる場合は利用します。
  • false の場合は常に Direct3D 9 Video API を利用するようにします。
パフォーマンスとしては Direct3D 11 Video API の方がよいため通常は true を設定してください。
Windows 7 の場合は Direct3D 11 Video API は使用できないため常に Direct3D 9 Video API を使用します。


AudioBufferLengthSec

音声バッファの長さを秒単位で指定します。
リーダー内部でデコードした音声サンプルを保持するバッファ長で、デコードしたサンプルを何も処理せずにそのまま保持し続けられるサイズになります。
AVPlayer を利用している場合、通常はそのままで問題ありません。


LogType

Unity Console に出力するデバッグ用のログの設定を指定します。
設定はビットフラグにより複数項目を ON/OFF できます。
通常は Error, Warning, Trace_Initialize をセットしてください。
Trace_GetSample と Trace_Render は非常に高頻度で呼ばれるため Unity 自体が非常に重くなります。

  • Warning: 警告を出力します。 AVReader 動作中のエラーは警告として出力されます。
  • Trace_Initialize: 初期化、解放処理時のトレースログを出力します。
  • Trace_GetSample: AVReader が動作中の状態でサンプル取得に関する処理のトレースログを出力します。
  • Trace_Render: AVReader が動作中の状態で映像レンダリングに関する処理のトレースログを出力します。


Default

AVReaderPluginSetting のインスタンスを取得します。


Pegasys.AVReader.AVReader

ムービーファイルからソースの読み込み、デコード処理を行うクラスです。 ネイティブプラグインの直接のラッパーとなっています。
全てのメソッドは同期呼び出しになっていますので、非同期化する場合は別途対応が必要です。AVPlayer は非同期対応が行われていますので通常は AVPlayer を使用してください。


Field / Property

　　

IsOpened

ソースファイルが開かれているかどうかを取得します。


　　

Duration

ソースの長さを取得します。


　　

HasVideo

映像ソースの有無を取得します。requestVideo = false で開いた場合、実際のファイルに映像ソースがあったとしても false になります。


　　

HasAudio

音声ソースの有無を取得します。requestAudio = false で開いた場合、実際のファイルに音声ソースがあったとしても false になります。


　　

VideoFormat

映像フォーマットを取得します。


　　

AudioFormat

音声フォーマットを取得します。


　　

CachedVideoSampleCount

現在デコードしてキャッシュされている映像サンプル数。


　　

CachedAudioSampleCount

現在デコードしてキャッシュされている音声サンプル数。


Open

ソースファイルを開きます。メインスレッド外から呼び出し可能です。

  • sourcePath: ソースファイルパス。フルパスで指定します。
  • requestVideo: 映像ソースを要求するかどうかを設定します。映像を含むソースファイルで音声だけを開く場合は false を指定します。
  • requestAudio: 音声ソースを要求するかどうかを設定します。音声を含むソースファイルで映像だけを開く場合は false を指定します。
  • 戻り値: 処理結果


　　

Close

ソースファイルを閉じます。


　　

GetNativeRenderTargetTexture

プラグインネイティブの Texture を取得します。
Open 後の初回呼び出し時に内部で Texture 生成が行われます。
メインスレッド外で呼び出すと不正な状態になる可能性があります。 通常は使用せず、 CreateRenderTargetTexture を使用してください。


　　

CreateRenderTargetTexture

映像のレンダリング用 Texture を生成します。
Open に成功後、映像ソースがあった時のみ実行可能です。


　　

Seek

指定した時間にシークし、以後その位置からサンプル取得を行います。
キャッシュは全てクリアされます。メインスレッド外から呼び出し可能です。


　　

SetRenderVideoPosition

描画する映像サンプルの時間を指定します。
ここで指定した時間に対応する映像が RenderVideo メソッドでテクスチャに反映されます。メインスレッド外から呼び出し可能です。


　　

NextVideoSample

ソースファイルから映像サンプルをデコード、取得し、キャッシュに格納します。キャッシュが最大取得状態の場合は何も行いません。
戻り値が true の場合はソース終端ではないので継続して NextVideoSample が実行可能です。 メインスレッド外から呼び出し可能です。


　　

NextAudioSample

ソースファイルから音声サンプルをデコード、取得し、キャッシュに格納します。キャッシュバッファからあふれる可能性があるので、そうならないように ReadAudioSample で適宜読みだしておく必要があります。
戻り値が true の場合はソース終端ではないので継続して NextAudioSample が実行可能です。false の場合はソース終端かキャッシュバッファがあふれた場合です。 メインスレッド外から呼び出し可能です。


　　

RenderVideo

SetRenderVideoPosition で指定した時間に対応する映像でテクスチャ更新を行います。 また、指定時間より前のサンプルなど、もう参照しないサンプルをキャッシュから破棄する処理も行われます。


　　

ReadAudioSample

音声サンプルをキャッシュから読み出します。
サンプルはキャッシュの先頭から読み出され、一度読みだしたサンプルはキャッシュから消去されます。 メインスレッド外から呼び出し可能です。

  • dst: 格納先の配列
  • offsetSampleCount: dst 配列の読み出し開始位置のオフセットを指定
  • readSampleCount: 読み出しサンプル数


著作権情報

　　　　　　

Copyright (c) Pegasys Inc, All rights reserved.

The sample movie contained within the SDK is from the Elephants Dream licensed under the Creative Commons Attribution 2.5. Copyright 2006, Blender Foundation / Netherlands Media Art Institute / www.elephantsdream.org

© Copyright · Pegasys Inc. , All Rights Reserved.