documents

H2MDドキュメント

はじめに

本ドキュメントは弊社が提供するH2MD SDK内のエンコーダ及びデコードライブラリのドキュメントとなります。評価版SDKなどをご希望のお客様は下記ページよりお問い合わせくださいCONTACTページ

H2MDの概要

H2MDは、HTML5に対応したブラウザのWEBページ内で動画を再生できるソフトウェアライブラリです。videoタグで再生出来るH.264やMPEG-4とは異なり、ページ内再生・自動再生・アルファチャンネルの活用・複数同時再生を行うことができます。また、動き予測を利用した圧縮によって、JPEG連番であるMotion JPEGよりも少ないデータサイズに動画を圧縮可能です。

H2MD SDKについて

H2MD SDKは、H2MDを使用したアプリケーションを開発するためのソフトウェアスイートです。H2MD SDKには以下が含まれます。

項目 概要 SDKパッケージ対応ファイル
コマンドライン
エンコーダ
動画からH2MDファイルに変換するためのツールです。
Windows、Macに対応しています。
tools/win/h2md_enc_c.exe
tools/win64/h2md_enc_c.exe
tools/mac/h2md_enc_c
プレビューツール H2MDファイルをプレビューするためのツールです。
ツールはローカルPCのブラウザ上で動作します。
preview/h2md_view.html preview/h2md_view.js
JavaScriptライブラリ HTML5でH2MDを再生するためのライブラリです。 library/h2md.min.js
library/h2md.webgl.min.js
サンプルプログラム ライブラリの使用例です。 sample/sample.html

動作確認済のプラットフォーム

動作確認済のプラットフォームは以下となります。デコード速度としては、AndroidよりもiOSの方が高速なことが確認されています。尚、iOS7.1では、色差が大きい場合にブロック境界にノイズが出ることがありますが、iOS8で解消されていることを確認しています。

OS ブラウザ
iOS 7以降 Mobile Safari , Chrome
Android 4.4以降 標準ブラウザ(*) , Chrome
Windows 7 IE11 , Chrome , Firefox
Windows 8.1 IE11 (RT)
Mac Chrome , Firefox

(*)端末によってはデコードパフォーマンスが低下する場合があります。
その他のブラウザについてはお問い合わせください

H2MDファイルの作成

H2MD エンコーダ

任意の動画からH2MDファイルに変換することができます。ここでは入力ファイル名と、出力ファイル名、画質を次のように与えます。エンコードが行われ、out.h2md.*.b64とout.h2md.*.jpgが出力されます。

$ h2md_enc_c -i in.avi -o out.h2md -q 75

コマンドライン引数に-aオプションを与えることで、アルファチャンネル付きでエンコードすることもできます。アルファチャンネル付きの場合は追加でout.h2md.*.pngが出力されます。

$ h2md_enc_c -i in.avi -o out.h2md -q 75 -a 4

コマンドライン引数に-fオプションを与えることで、出力ファイルを1つのフォルダにまとめることができます。次のように指定すると、folder/out.h2md.*が出力されます。

$ h2md_enc_c -i in.avi -o out.h2md -f folder

コマンドラインオプション

H2MDのエンコーダには以下のオプションがあります。

オプション 機能
--input , -i 入力ファイルを指定します。
AVIなどの動画ファイルや連番BMPフォルダなどが指定可能です。
--output , -o 出力ファイルを指定します。
拡張子はh2mdにして下さい。
--folder, -f 出力先フォルダを指定します。
フォルダが存在しない場合はフォルダを作成します。
--quality , -q RGBチャンネルの品質を0~100で指定します。大きいほど高画質です。
デフォルト値は50です
--alpha_bit , -a アルファチャンネルのビット数を0~8で指定します。大きいほど高画質です。
アルファチャンネルが不要な場合は0を指定して下さい。
デフォルト値は0です。
--block_size , -b ブロックサイズを8、16、32、64で指定します。
大きいほどデコード速度は向上しますが、主観画質が低下します。
デフォルト値は16です。
--fps フレームレートを指定します。
大きいほど滑らかになりますが、デコード負荷が上がります。
デフォルトでは入力ファイルのフレームレートを使用します。
--gop_frames GOPを挿入する間隔を指定します。
0を指定するとシーンチェンジに合わせて自動的に設定します。
デフォルト値は0です。
--gop_list GOPを挿入するフレームをリストファイルで指定します。
--frames エンコードするフレーム数を指定します。
動画の一部をエンコードする場合に指定します。
--resize_w 入力画像を指定の横幅に拡縮します。
--resize_h 入力画像を指定の縦幅に拡縮します。
--resize_ratio_w 入力画像を指定の割合(%単位)に拡縮します。
--resize_ratio_h 入力画像を指定の割合(%単位)に拡縮します。
--keep_aspect 縦横比を保ちながら拡縮します。
--jsonp .b64ファイルではなく.jsファイルにデータを書き出します。
クロスドメインを超える必要がある場合に使用します。
--psy-rd 符号量よりも主観画質を優先してエンコードします。

GOPリストの入力

GOPリストを入力することで、指定したフレームへのシークを高速化することができます。

$ h2md_enc_c -i in.mp4 -o out.h2md --gop_list gop_list.txt

gop_list.txtには、以下のように、GOPを挿入するフレーム番号を行単位で記述します。この例では、0フレームと10フレームにGOPを設定します。GOPを設定したフレームは、Iフレームとなります。

0
10

動画の読み込みでエラーが発生する場合

Windows版のH2MDエンコーダでは、動画の読み込みにDirect Showを使用しています。mp4の読み込みでエラーが発生する場合には、Haali Media Splitterなど、mp4に対応したSplitterをインストールする必要があります。

Mac版のH2MDエンコーダでは、動画の読み込みにFFMPEGを使用しています。mp4の読み込みでエラーが発生する場合には、FFMPEGをインストールする必要があります。FFMPEGがインストールされているかどうかは、コマンドラインでffmpegと入力することで確認することができます。

H2MDファイルのプレビュー

H2MDビューワー

H2MDビューワを使用することで、エンコードしたH2MDファイルの画質を確認することができます。H2MDビューワを使用するには、viewer/h2md_view.htmlをブラウザで開き、再生したいH2MDファイルをウィンドウにドロップします。

使用例

sample/movie/にある以下のH2MDファイルをエクスプローラで選択します。

エクスプローラで選択

preview/h2md_view.htmlを開いているブラウザにドロップすると、H2MDファイルを再生することができます。

JavaScript API

プロジェクトへのインポート

libraryフォルダにあるh2md.min.jsを読み込んで下さい。
クロスドメインポリシーから、h2md.min.jsと動画ファイルは同じドメインに存在する必要があります。
クロスドメインを超える必要がある場合は、JSONP APIを使用して下さい。

API仕様

H2MDインスタンスは次のAPIを持ちます。

再生制御API
API 引数 返値 説明
open(url,callback) url : String
callback : Function()
- URLから動画を開きます。成功した場合は引数に与えたコールバックを、失敗した場合はerror APIで指定したコールバックを呼び出します。openしたインスタンスを別の動画で再利用することはできません。
play() - 成功時はtrue、
失敗時はfalse
動画を再生します。再生に失敗した場合はfalseを返します。再生中に内部エラーが発生した場合は、error APIで指定したコールバックを呼び出します。
stop() - - 再生を停止します。
pause() - - 再生を一時停止します。
seek(frame) frame : Number 成功時はtrue、失敗時はfalse 指定したフレーム番号にシークします。
playing() - 再生中はtrue、再生していない場合はfalse 再生しているかどうかを取得します。
info() - Info 動画の情報をオブジェクトで取得します。openに成功した後に呼び出すことができます。失敗した場合はnullを返します。
position() - Position 動画の再生位置をオブジェクトで取得します。openに成功した後に呼び出すことができます。失敗した場合はnullを返します。
再生設定API
API 引数 返値 説明
canvas(canvas_id) canvas_id : String 成功時はtrue、
失敗時はfalse
動画の描画先キャンバスのIDを指定します。
stretch(dx,dy,dw,dh) dx : Number
dy : Number
dw : Number
dh : Number
- 動画の描画先キャンバスの描画先座標と描画サイズを指定します。デフォルトでは(dx,dy)=(0,0)、(dw,dh)=(movie_width,movie_height)となります。
loop(loop_frame) loop_frame : Number 成功時はtrue、失敗時はfalse ループ再生時のループ先のフレーム番号を指定します。-1を指定するとループしません。デフォルト値は-1です。
streaming(flag) flag : Boolean - falseに設定するとプログレッシブダウンロードで再生します。trueに設定するとストリーミングで再生します。デフォルトはfalseです。
コールバック設定API
API 引数 返値 説明
error(callback) callback : Function(error_message:String) - エラー発生時に呼び出すコールバックを指定します。
done(callback) callback : Function() - 最後のフレームまで再生が終了したタイミングで呼び出すコールバックを指定します。
buffered(callback) callback : Function() - 全フレームのデータの読み込みが完了したタイミングで呼び出すコールバックを指定します。
request(callback) callback : Function() - データをサーバにリクエストするタイミングで呼び出すコールバックを指定します。
timeupdate(callback) callback : Function() - 再生位置が更新されたタイミングで呼び出すコールバックを指定します。
キャッシュ制御 API
API 引数 返値 説明
nonce_url(nonce) nonce : Boolean - trueに設定することで、画像のリクエストURLにタイムスタンプを付加し、キャッシュを無効化します。デフォルト値はfalseです。
JSONP API
API 引数 返値 説明
jsonp(jsonp) jsonp : Boolean - trueに設定することで、JSONPを使用してデータを読み込みます。エンコード時に.jsonpオプションを使用して、.b64を.jsに書き出す必要があります。また、エンコード後のファイル名は、ページ内でユニークである必要があります。
ローレベルAPI
API 引数 返値 説明
decode(frame) frame : Number Canvas 引数に与えたフレームの画像をデコードしてCanvasオブジェクトで返します。読み込みが完了していないフレーム番号が指定された場合はnullを返します。返値のCanvasオブジェクトは内部バッファへの参照となり、再利用されるため、破壊してはいけません。また、別のdecode命令を実行すると、Canvasオブジェクトの内容は変化します。

Infoオブジェクトは次のメンバを持ちます。

メンバ 概要
width 画像の横幅
height 画像の高さ
fps フレームレート
frames 総フレーム数

Positionオブジェクトは次のメンバを持ちます。

メンバ 概要
frames 総フレーム数
current_frame 現在の再生フレーム
buffered_frame バッファリングの完了したフレーム数

使用手順

まず、H2MDのインスタンスを作成します。

instance = new H2MD ();

次に、URLから動画を開きます。
第一引数にはエンコーダで生成されたファイルのURLを指定します。
URLには.h2md以降の数値と拡張子を除いた形式で指定します。
第二引数には、成功時に呼び出されるコールバックを指定します。

instance.open("out.h2md",success_callback);

open APIに成功した後、play APIで任意のキャンバスで再生することができます。

instance.canvas("canvas_id");
instance.play(); 

エラー発生時に呼び出すコールバックを指定するには、error APIでコールバックを設定します。

instance.error(function (error){alert(error);});

フレーム数などの情報はinfo APIでオブジェクトの形式で取得することができます。

info = instance.info();
var width = info.width;

再生位置などの情報はposition APIでオブジェクトの形式で取得することができます。

position = instance.position();
var frame = position.current_frame;

フレーム番号を指定して直接、デコード画像を取得することもできます。
取得したcanvas_objectはHTML5のdrawImage APIで描画することができます。
取得した画像は32ピクセルの倍数にパディングされますので、必要に応じてクリップして下さい。

canvas_object = instance.decode(frame);

プログレッシブダウンロードとストリーミング

プログレッシブダウンロードは、動画データを先頭から順次読み込み、デコーダにキャッシュします。プログレッシブダウンロードは、短い動画や、ループ再生、過去へのシークが発生するコンテンツに最適です。また、フレーム間の同期が必要で、buffered APIを使用する場合にも、プログレッシブダウンロードを使用する必要があります。 ストリーミングは、圧縮データを必要なフレームから読み込み、デコードが完了したフレームの圧縮データはキャッシュせずに削除します。ストリーミングは、長尺の動画や、メモリの少ない環境に適しています。
H2MDは、デフォルトではプログレッシブダウンロードを使用します。ストリーミングに設定する場合は、以下のように、openの前にstreaming APIを呼び出して下さい。

instance.streaming(true);
instance.open("out.h2md",success_callback);

リクエストコールバックの利用

リクエストコールバックを使用することで、サーバへのリクエストをフックして、FILE APIやローカルストレージを活用することができます。利用例は以下のようになります。

instance.request(function(url,callback){ 
  data="urlに応じたデータの取得"
  callback(data) 
});

要求されたURLがb64の場合は、実データを返す必要があります。要求されたURLがjpgもしくはpngの場合は、Data URIもしくはURLを返す必要があります。

WebGLによるアクセラレーション(Experimental)

h2md.min.jsを読み込む前に、h2md.webgl.min.jsを読み込ませることで、WebGLによるアクセラレーションが有効になります。


<script type="text/javascript" src="../library/h2md.webgl.min.js"></script>
<script type="text/javascript" src="../library/h2md.min.js"></script>
              

WebGLによるアクセラレーションを有効にすると、PCとAndroidのGoogle Chromeでは、大きくデコード速度が改善する場合があります。iOSやFirefoxでは、逆にデコード速度が低下することが確認されており、現状、Google Chromeの場合のみ、アクセラレーションが有効になります。
WebGLを使用した場合、画像に対するクロスドメイン制約が付加されるため、クロスドメインを超えることはできません。

サンプルプログラム

sampleフォルダのsample.htmlのJavaScriptコードを参照して下さい。sample.htmlでは、../libraryフォルダのh2md.min.jsを参照します。

音声との同期

概要

H2MDには音声データは含まれていませんが、audio要素などの再生位置を取得することで、簡単に同期再生することができます。

音声と同期するスクリプトの例

次の例では、audio要素を再生しながら、定期的にcurrentTimeを取得し、現在の時間に対応したH2MDのフレームをデコードし、描画しています。


  <audio src="sample.mp3" id="audio"></audio> 
  <canvas id="canvas" width="768" height="460" onClick="document.getElementById('audio')
  .play();">
  </canvas> 
   
  <script> 
   var h2md_movie=new H2MD(); 
   h2md_movie.error(function(error){ alert(error); }); 
   h2md_movie.open("movie/sample.h2md",function(){ 
    setInterval(function(){ 
     var audio=document.getElementById("audio"); 
     var movie_info=h2md_movie.info(); 
     var idx=audio.currentTime*movie_info.fps; 
     var src_canvas=h2md_movie.decode(Math.floor(idx)); 
     if(!src_canvas) { return; } //loading 
     var dst_canvas=document.getElementById("canvas").getContext("2d"); 
     dst_canvas.drawImage(src_canvas,0,0); 
    },10); 
   }); 
  </script> 
            

パフォーマンスと画質の最適化

ブロックサイズの変更

H2MDの画質が十分でない場合は、エンコード時に --block_size 8 を指定して下さい。デフォルトのblock_size 16に比べて、デコードのパフォーマンスは低下しますが、ブロックノイズが小さくなり、主観画質が改善します。 H2MDのデコードで十分なパフォーマンスが出ない場合は、--block_size 32もしくは 64 を指定して下さい。デフォルトの--block_size 16に比べて、おおよそ4~ 16倍のパフォーマンスを得ることができますが、主観画質は低下します。

シークの削減

H2MDではフレーム間予測を行っているため、GOP先頭以外のフレームへのシークには時間がかかります。フレーム番号が連続でない場合、複数のデコーダインスタンスを使用してフレーム番号を連続にするか、--gop_framesに小さな値を指定して下さい。ただし、--gop_framesに小さな値を指定すると、圧縮率は低下します。

H2MDに関するお問い合わせ
  • INTRODUCTION
  • DOCUMENTS
  • FAQ
  • H2MDforWEB
  • H2MDforUNITY
  • PrivacyPolicy