V/G Controller

Kollus VG ControllerはVideogatewayで提供されるメディアの一部機能を外部から制御するためのJavascript libraryとなります。Kollus VG Controllerは以下の目的で提供しています。

Playerの種類に関わらず同一コードで制御することが可能
インストール・使用が比較的に簡単
Playerの感知・実行が不要 (Videogatewayから自動で感知・呼出)
3rd party Javascript libraryが不要

メソッドとイベントリスト名に表記するFlash, V2, V3, V4 Playerは対応しているPlayerの種類となります。
※注意: V2, V3 PlayerはKolllus VODで暗号化されたコンテンツの再生に使用されるKollus security playerとなり、インストールが必要です。

Flash: 非暗号化ファイルの場合、HTML5 Playerが起動しない環境ではFlash Playerが起動します。[^1]
V2: 暗号化されたファイルの場合、IE(ActiveX), Chrome・Firefox(NPAPI)環境でV2 Playerが起動します。[^2]
V3: 暗号化されたファイルの場合、Edge・Chrome 45以降のブラウザ環境でV3 Player(HTML5基盤暗号化Player)が起動します。
V4: 非暗号化ファイルの場合、基本的にV4 Player(標準 HTML5 Player)が起動します。

メソッド・イベントにPlayerバージョンの表記がないものは全てのPlayerが対応

[^1]: Adobe社から2020年以降にFlash Playerの対応中止を公表しています。

https://blogs.adobe.com/conversations/2017/07/adobe-flash-update.html

[^2]: Chrome 42+ / Firefox 52+ バージョンではNPAPI対応を中止しました。

セットアップ

VgControllerClient

(顧客のhtml pageに挿入)

...
<script src="https://file.kollus.com/vgcontroller/vg-controller-client.latest.min.js"></script>
<script>
    window.onload = function() {
    try {
        var controller = new VgControllerClient({
        	target_window: document.getElementById('child').contentWindow
        });
        // ここからイベントリスナーを登録したり、ウェブページElementにメソッドをbindしてください。
        } catch(e) {
            // Videogateweay Controller Libraryは window.postMessage APIを使用するため、
            // 該当機能に対応していないブラウザでは動作しません。
            // ここに適切なfail-overコードを追加してください。
        }
    };
</script>
<body>
	<iframe id="child" src="http://v.jp..."></iframe>
</body>
...

VgControllerClient 生成の際にパラメータで転送するtarget_windowには、Webページに添付しているKollus Videogateway iframeのHTMLElementにcontentWindow属性を入力します。
このスクリプトはwindow.postMessage API を使ってPlayerとの通信を行うため、該当機能に対応していないブラウザでは動作しません。
Web Page内部に複数のiframeをembedしている場合、制御するiframe毎にVgControllerClient を生成する必要があります。
以前バージョンとの互換性を考慮して(v0.5以前) new VgControllerClient()の代わりにnew Kollus.VideogatewayController()を使用しても正常に動作します。
try-catch文のException code listは以下のようになります。

VgControllerServer

(Kollus VG view html pageに挿入)

...
<script src="/path/to/vg-controller-server.1.1.6.min.js"></script>
<script>
window.onload = function() {
	try {
		var player = [PLAYER オブジェクト Element (v2, v3, v4, flash player)];
		var controller = VgControllerServer(player, {
			player_type: 'v4', //[v2, v3, v4, flash]
 			target_window: window.parent,
			media_info: {media_info_object} //1.1.4バージョンにて字幕関連メソッドを使用する際に必要です。
 		});
 		//player オブジェクトの生成及び初期化が完了されてからイベントを登録してください。
 		//player オブジェクトが初期化されてない状態で setEventListeners メソッドを呼出す場合、
 		//VG-Controllerが正常に動作しない可能性があります。
 		controller.setEventListeners();
 	} catch(e) {
 		// VG Controllerは window.postMessage APIを使用しているため、
 		// 該当機能に対応していないブラウザでは動作しません。
 		// ここに適切な fail-over コードを追加してください。
 	}
};
</script>
...

CDN

Vg-Controller Client LibraryをCDNで提供します。最新バージョンのライブラリを使用するには以下のリンクを挿入してください。

http://file.kollus.com/vgcontroller/vg-controller-client.latest.min.js

以前バージョンのライブラリを使用するにはlatestの代わりにバージョン名を入力してください。

http://file.kollus.com/vgcontroller/vg-controller-client.1.1.4.min.js

VR Contents (mobile device)

iframe 内部で呼び出す360 VR コンテンツの場合、Android・iOS デバイスで再生する際に正常に動作しません。

Androidの場合にはOrientation値が正常に適用されないため左/右の方向が逆になることがあります。
iOSの場合にはiOS 13以降からGyroscopeを正常に動作させるためにはDeviceMotion権限を取得する必要がありますが、
- この権限がiframe内部では取得することができないため正常に動作しません。(iOS 13 未満のバージョンではsafari設定から'動作と方向へのアクセス'オプションを変更しなければなりません。)

上記Android・iOSの動作問題を解決するためにはVG-Controller 1.1.10+ を設置する必要があり、VG-Controller ClientからDeviceMotion イベントを自動で登録してVG-Controller Serverとの通信を行います。(周期的にiframe 外部のイベントをiframe内部に転送します。)

iOSの場合には上記の内容の上、更にController.set_vr_overlay() メソッドを実行させる必要があります。詳しい内容は以下のメソッド項目からset_vr_overlayメソッドを参考にしてください。

※Known Issue: iOS 13.4 バージョンでは権限を取得しても DeviceMotionの rotationRate値が正常に発生しないエラーが報告されています。

Intent Scheme Call Bug (iframe in Android)

Player ページがiframe内部からVGを呼出す構造になっている場合、稀にAndroidデバイスでKollus security player (Android Player アプリ)が実行されない現象があります。

Android OSでは Intent Schemeを使用して呼出していますが、Chrome + iframe 環境で正常に動作していません。

この場合にはVG-Controller 1.1.15+を使用してください。（VG-Controllerが自動で感知・処理します。）

イベントリスニング

Playerのイベントが発生した際に使用者が定義したcallback関数を実行するためのイベントリスナー(EventListener)を登録する方法となります。

controller.on('event_name', function(param) {
// イベントリスナー
});

単一イベントに複数のリスナーを登録することができます。この場合、イベントが発生すると登録されている全てのリスナーが実行されます。

controller.on('event_name', function(param) {
	// 1番目のリスナー
});
controller.on('event_name', function(param) {
	// 2番目のリスナー
});
// イベント発生の際に1番目、2番目リスナーが全て実行
// 但し、JAVA Scriptイベントループとcallback関数の実行方式によって
// リスナーが順番通りに実行されない可能性があります。

イベントリスナーを登録する関数である「on」はメソッドチェイニング(Method chaining)に対応しています。

controller.on('event_name_1', function(param) {
	// 1番目のリスナー
}).on('event_name_2', function(param) {
	// 2番目のリスナー
});

メソッド使用

Videogateway Controller Libraryが対応するメソッドを呼び出す方法となります。

controller.play();

上記の記載だけで呼び出すことができますが、場合によってはパラメーターが必要なメソッドもあります。

controller.set_volume(90);

参考事項

メソッドリスト

on(event_name, callback_function)

イベントリスナーを登録します。

controller.on('event_name', function(param) {
	// event_nameに該当するイベントが発生したとき、2番目の因子であるcallback functionを実行
});

Parameters:

event_name String callback functionをbindするイベント名
callback_function Function イベント発生する際に実行されるcallback functionとなります。場合によってcallback functionにはパラメータが付与されることがあります。

Return:

Object VG-Controller Client オブジェクトをリターンします。

off(event_name)

登録されたイベントリスナーを削除します。

controller.off('event_name');

Parameters:

event_name String callback functionでbindされたイベント名

Return:

Object VG-Controller Client オブジェクトをリターンします。

get_progress()

再生進行中の位置情報をリターンします。

Parameters:

No parameter

Return:

Object percent, position, durationをpropertyで持つobjectをリターンします。各入力値の説明はprogressイベントを参考にしてください。

play([start_at])

コンテンツを再生します。

controller.play();

特定時点から再生する場合、以下のように再生する位置をパラメータで入力してください。

controller.play(10); // 10秒時点から再生

Parameters:

start_at Integer (Optional) 再生を開始する位置：省略した場合最初から再生開始

Return:

No return

pause()

コンテンツ再生を一時停止します。

Parameters:

No parameter

Return:

No return

set_volume(volume)

音量を変更します。音量は 0 <= volume <= 100 の間のIntegerタイプの値を入力します。範囲外の値は0か100に調整されます。

Parameters:

volume Integer 変更する音量

Return:

No return

get_volume()

現在設定された音量値をリターンします。

Parameters:

No parameter

Return:

Integer 現在設定されている音量

mute()

ミュートをOn/Offにします。On/Offはスイッチ方式で作動します。(呼出す度に状態が変更)

Parameters:

No parameter

Return:

No return

ff()

set_jumpstep メソッドで設定された入力値の通りに現在の再生位置から後ろに移動します。初期値は10秒です。

Parameters:

No parameter

Return:

No return

rw()

set_jumpstep メソッドで設定された入力値の通りに現在の再生位置から前に移動します。初期値は10秒です。

Parameters:

No parameter

Return:

No return

set_current_time(current_time)

current_time 位置に移動します。play(start_at) メソッドは該当位置に移動後即時に再生を開始しますが、set_current_time(current_time) メソッドは現在のplaying/paused状態を維持します。

Parameters:

current_time Integer 移動する時間

Return:

No return

get_current_time()

現在の位置をリターン

Parameters:

No parameter

Return:

Number 現在の位置 (小数点5桁まで)

set_screen() V2 V3 V4

全体画面をOn/Offします。On/Offはスイッチ方式で作動します。(呼出す度に状態が変更)

Flash Player 対応不可
IE, Firefox対応不可

Parameters:

No parameter

Return:

No return

get_screen()

現在画面モードをリターン：set_screenの対応有無(V2, V3, V4 Player)に関係なくget_screen関数は全てのPlayerから画面モードをリターンします。

全体画面Off : windowed
全体画面On : fullscreen

Parameters:

No parameter

Return:

String リターンされる現在の画面モード：windowed, fullscreenのいずれかの値

set_jumpstep(jumpstep)

ff メソッド、または rw メソッドで移動する位置を設定します。位置は「秒単位の定数」で入力します。

Parameters:

jumpstep Integer 移動する時間値

Return:

No return

get_jumpstep()

現在設定されている移動する時間値をリターン

Parameters:

No parameter

Return:

Integer リターンされる時間値

set_control_visibility(visibility)

Player Control panelの表示・非表示を設定：trueは表示、falseは非表示

Parameters:

visibility Boolean Control panelの表示有無

Return:

No return

get_control_visibility()

layer Control panelの表示・非表示設定をリターン

Parameters:

No parameter

Return:

Boolean Control panelの表示有無

set_video_visibility(visibility) `V3 V4`

Video 画面の表示・非表示を設定 (Audioには影響なし)パラメータをtrueにすると表示、falseにすると非表示になります。

Parameters:

visibility Boolean Video 表示設定

Return:

No return

set_speed(speed) `V2 V3 V4`

倍速範囲を設定します。(0.5 <= speed <= 4) 最大倍速はPlayerの設定により変更することがあります。倍速は0.1刻みで調整することができます。範囲外の値を入力する場合範囲の最低、最大値(0.5と4)で固定されます。

Parameters:

speed Integer 設定する倍速値

Return:

No return

get_speed() `V2 V3 V4`

設定された倍速値をリターン: Javascriptには明確なFloatタイプがないため、小数点を表現するためにStringタイプでリターンします。

Parameters:

No parameter

Return:

String 設定された倍速値。定数(1, 2, 3, 4)の場合、小数点を表示します。(1.0, 2.0, 3.0, 4.0)

set_playback_rates(playback_rates) `V3 V4`

倍速値のグループを設定：Array typeとなり順番は無視されます。(Player側で整列してUIを構成)二重配列形態で表示される場合、UIから見られる倍速値グループの行数を設定することができます。この場合、最初の因子は倍速値の配列となり2番目の因子は行数を意味します。ex) [[0.5, 1, 1.5, 2, 2.5, 3, 3.5, 4], 2]

Parameters:

playback_rates Array 設定する倍速値グループの配列

Return:

No return

get_playback_rates() `V3 V4`

倍速値グループの配列をリターン

Parameters:

No parameter

Return:

Array 設定された倍速値グループの配列

set_topmost(topmost) `V2`

ウィンドウの最上位配置を設定: 最上位に設定した場合、閲覧中のブラウザがバックグラウンドに入っても他のウィンドウより前面に表示されます。

Parameters:

No parameter

Return:

No return

get_topmost() `V2`

ウィンドウの最上位配置設定をリターン: V2 Player以外のPlayerから呼出された場合falseをリターンします。

Parameters:

topmost Boolean trueは設定on, falseは設定off

Return:

Boolean 設定内容

set_brightness(brightness) `V2`

映像の明るさを設定します。この設定はV2 Playerのみ対応します。映像の明るさは -50 <= brightness <= 50となります。範囲外の値を入力する場合範囲の最低、最大値(-50と50)で固定されます。

Parameters:

brightness Integer 明るさ設定値

Return:

No return

get_brightness() `V2`

明るさ設定値をリターン: V2 Player以外の場合常に0をリターンします。

Parameters:

No parameter

Return:

Integer 明るさ設定値

set_contrast(contrast) `V2`

映像のコントラストを設定します。この設定はV2 Playerのみ対応します。映像のコントラストは -50 <= contrast <= 50となります。範囲外の値を入力する場合範囲の最低、最大値(-50と50)で固定されます。

Parameters:

contrast Integer コントラスト設定値

Return:

No return

get_contrast() `V2`

コントラスト設定値をリターン: V2 Player以外には常に0をリターンします。

Parameters:

No parameter

Return:

Integer コントラスト設定値

set_saturation(saturation) `V2`

映像の色調を設定します。この設定はV2 Playerのみ対応します。映像の色調は -50 <= saturation <= 50となります。範囲外の値を入力する場合範囲の最低、最大値(-50と50)で固定されます。

Parameters:

saturation Integer 色調設定値

Return:

No return

get_saturation() `V2`

色調設定値をリターン: V2 Player以外には常に0をリターンします。

Parameters:

No parameter

Return:

Integer 色調設定値

set_repeat_start([position])

リピート再生の開始位置を設定します。因子なしで呼び出す場合現在の位置を開始位置として設定します。

controller.set_repeat_start();

因子で位置(秒)値を入力すると指定した位置をリピート再生の開始位置として設定します。

controller.set_repeat_start(10); // 10秒時点を開始位置に設定

設定されている終了位置より開始位置が後になる場合、終了位置が解除されます。

Parameters:

position Integer (Optional) 開始位置値

Return:

No return

set_repeat_end([position])

リピート再生の終了位置を設定します。因子なしで呼び出す場合現在の位置を終了位置として設定します。

controller.set_repeat_end();

因子で位置(秒)値を入力すると指定した位置をリピート再生の終了位置として設定します。

controller.set_repeat_end(20); // 20秒時点を開始位置に設定

設定されている開始位置より終了位置が前になる場合、開始位置が解除されます。

Parameters:

position Integer (Optional) 終了位置値

Return:

No return

unset_repeat()

リピート再生設定を解除

Parameters:

No parameter

Return:

No return

get_repeat() `V2 V3 V4`

リピート再生設定状態をリターン: V3, V4 Playerは状態の文字列と時間がリターンします。V2 Playerの場合状態の文字列のみリターンします。状態文字列はcancel, start, endの3種類となります。

Parameters:

No parameter

Return:

No return

refresh_bookmark()

Playerのbookmarkリストを更新

Parameters:

No parameter

Return:

No return

enable_fullscreen_button() `V3 V4`

Playerの全体画面ボタンを有効にします。(IE バージョン10 以前のバージョンはfullscreen 機能に対応していないためfullscreen buttonは自動で無効になります。)

Parameters:

No parameter

Return:

No return

get_player_id() `V2 V3`

PlayerのユニークIDをリターンします。この関数は「ready」イベントが呼出されるまでにはnullをリターンします。

Parameters:

No parameter

Return:

String PlayerのユニークID

get_hardware_id() `V2 V3`

ハードウェアユニークIDをリターンします。この関数は「ready」イベントが呼出されるまでにはnullをリターンします。

Parameters:

No parameter

Return:

String ハードウェアユニークID

get_player_type()

現在のPlayer Typeをリターン：Flash, V2, V3, V4

Parameters:

No parameter

Return:

String 現在のPlayer Type

set_subtitle_visibility(visibility)

字幕表示を設定

Parameters:

visibility Boolean 表示設定

Return:

No return

set_subtitle_shadow_rect(is_rect)

字幕の背景スタイルを設定：パラメータがtrueならblock形の不透明背景となり、falseなら文字の陰影として設定されます。

Parameters:

is_rect Boolean 字幕の背景スタイルがBlock形であるかの有無

Return:

No return

get_subtitle_shadow_rect()

字幕の背景スタイルがBlock形の不透明背景に設定されているかをリターンします。

Parameters:

V/G Controller

V/G Controller

セットアップ

VgControllerClient

VgControllerServer

CDN

VR Contents (mobile device)

Intent Scheme Call Bug (iframe in Android)

イベントリスニング

メソッド使用

参考事項

メソッドリスト

on(event_name, callback_function)

off(event_name)

get_progress()

play([start_at])

pause()

set_volume(volume)

get_volume()

mute()

ff()

rw()

set_current_time(current_time)

get_current_time()

set_screen() V2 V3 V4

get_screen()

set_jumpstep(jumpstep)

get_jumpstep()

set_control_visibility(visibility)

get_control_visibility()

set_video_visibility(visibility) V3 V4

set_speed(speed) V2 V3 V4

get_speed() V2 V3 V4

set_playback_rates(playback_rates) V3 V4

get_playback_rates() V3 V4

set_topmost(topmost) V2

get_topmost() V2

set_brightness(brightness) V2

get_brightness() V2

set_contrast(contrast) V2

get_contrast() V2

set_saturation(saturation) V2

get_saturation() V2

set_repeat_start([position])

set_repeat_end([position])

unset_repeat()

get_repeat() V2 V3 V4

refresh_bookmark()

enable_fullscreen_button() V3 V4

get_player_id() V2 V3

get_hardware_id() V2 V3

get_player_type()

set_subtitle_visibility(visibility)

set_subtitle_shadow_rect(is_rect)

get_subtitle_shadow_rect()

set_video_visibility(visibility) `V3 V4`

set_speed(speed) `V2 V3 V4`

get_speed() `V2 V3 V4`

set_playback_rates(playback_rates) `V3 V4`

get_playback_rates() `V3 V4`

set_topmost(topmost) `V2`

get_topmost() `V2`

set_brightness(brightness) `V2`

get_brightness() `V2`

set_contrast(contrast) `V2`

get_contrast() `V2`

set_saturation(saturation) `V2`

get_saturation() `V2`

get_repeat() `V2 V3 V4`

enable_fullscreen_button() `V3 V4`

get_player_id() `V2 V3`

get_hardware_id() `V2 V3`