Web サイト統合

Genvid の公開方法は、すべてのゲームで異なるため、ゲームごとにカスタマイズした Web サイトが必要です。これには、スキン面 (HTML、CSS) と機能面 (JavaScript) のカスタマイズがあります。ブラウザ用 Web アプリケーションをホストする Web サーバーも実行する必要があります。

Web サイトの作成方法は複数存在します。このセクションでは Genvid MILE SDK に共通する手順に限定して説明します。

JavaScript API

Genvid は 2 つのライブラリを提供しています。

  • genvid leaf への接続、ストリームのデコード、ビデオプレイヤーの作成、データとビデオの同期に必要なロジックを含みます。
  • genvid-math WebGL オーバーレイなどを作成するための、様々なジオメトリ演算ユーティリティ関数を提供します。 サンプル で、このライブラリの使用例をご確認ください。

この 2 つのライブラリは、それぞれ 3 つのバンドルに含まれています。

  • NPM パッケージアーカイブ ローカル NPM パッケージ としてインポート可能な gzip 圧縮された tarball ファイル。ES6 構文で依存性アイテムのインポート、好きなメソッドを使用してプロジェクトのバンドルができます。タイプ定義へのアクセスも可能です。
  • ES5 js module これにより、グローバル変数 genvidgenvidMath を公開することで、ライブラリをインポートすることができます (注意: タイプの定義にアクセスできなくなります)。すべての Cube サンプル は、このメソッドを使用する Web サンプル を通過します。
  • UMD js モジュール グローバル変数 genvidgenvidMath の公開など、様々な方法でライブラリのインポートを可能にする UMD モジュール 。タイプ定義へのアクセスはありません。Twitch 拡張機能サンプルだけが、このメソッドを使用します。

注釈

現在、genvidgenvid-math の依存性を使用するための好ましい方法は、ES5 js モジュールをインポートすることです。すべての Cube サンプルWeb サンプル を使用しており、この方法を説明しています。

api/web/legacy_types フォルダに、下位互換性のための古いタイプ定義を提供しています。ただし、新しい Twitch 拡張機能でないプロジェクトの場合は、Web サンプルのメソッドに従うことをお勧めします (Twitch 拡張機能開発サンプル は、UMD js モジュールを使用しています)。

フロントエンドの統合

Genvid のフロントエンドへの統合の最初のステップは、 genvidClient.createGenvidClient() を使用して genvidClient.IGenvidClient() をインスタンス化することです。

let client = genvid.createGenvidClient(streamInfo, websocketURL, websocketToken, video_player_id);

1 つ目のパラメータ streamInfo は、 genvidClient.IStreamInfo() 構造体に対応し、通常は、 POST /disco/stream/join コールからのバックエンドサービスで返されます。

次の 2 つのパラメータ、 websocketURLwebsocketToken は、それぞれ Websocket アドレスとセキュリティトークンを指定する値です。 POST /disco/stream/join コールによりバックエンドで提供されます。

最後のパラメータ video_player_id は、ライブ動画配信プレイヤーを使用する HTML 要素を参照する文字列です。 IGenvidClient() がビデオプレイヤーを作成した時に、この HTML 要素がライブ配信サービスのものに置き換えられます。

onVideoPlayerReady コールバック

プレイヤーの作成時、 IGenvidClient()genvidClient.IGenvidClient.onVideoPlayerReady() で指定された関数を呼び出します。これは通常、オーバーレイの連携に使用します。

client.onVideoPlayerReady( function(elem) { console.log('Create the overlay!'); } );

onAuthenticated コールバック

onAuthenticated() のコールバックは、 IGenvidClient() が Genvid Services にうまく接続できたことを通知します。

client.onAuthenticated( function(succeed) { if (succeeded) { console.log('Connected!'); } });

onStreamsReceived コールバック

onStreamsReceived() コールバックは、Web クライアントが leaf の Web ソケット接続から新しい ゲームデータアノテーション を受信すると すぐに 呼び出されます。onDraw() とは異なり、データは再生中の動画に同期されません。

このコールバックに与えられるデータは、 Genvid_SubmitGameData()Genvid_SubmitAnnotation() を使用してゲームが送信したデータです。

このコールバックは、データがレンダリングされる前にデコードや分析などのコストのかかる処理を行う場合に便利です。各データフレームに対して、一般的には user フィールドを使用して、処理によって変換されたデータを保存することができます。このフィールドには後で onDraw() メソッドでアクセスすることができます。レンダリング時にこの処理を行うことはお勧めしません (onDraw())。オーバーレイに遅延が発生する可能性があるからです。

client.onStreamsReceived((streams) => { myGameOverlay.onStreamsReceived(streams); });

onNotificationsReceived コールバック

このメソッドでは、Web ソケット接続から Leaf への接続を受信した際に 通知 を受信するコールバックを登録することができます。

通知は ゲーム または Webgateway API から送信することができます。

通知 は、情報をできるだけ早く転送するために使用され、 ゲームデータアノテーション とは異なり、ビデオストリームと同期しません。

ネイティブ SDK 関数 Genvid_SubmitNotification() を使用してゲームから送信されます。

client.onNotificationsReceived((notifications) => { myGameOverlay.onNotificationsReceived(notifications); });

onDraw コールバック

onDraw() メソッドは、設定可能なフレームレートで定期的に呼び出されるコールバックを登録することができます (デフォルトは 1 秒間に 30 回)。再生中のビデオストリームに同期した ゲームデータアノテーション を保持します。通常、オーバーレイのレンダリングに必要なゲームデータや、ビデオストリームに同期する必要のあるデータにアクセスするために使用します。

client.onDraw((frame) => { myGameOverlay.onDraw(frame); });

注釈

onStreamsReceived() を使用してデータを変換した場合、変換されたデータには onDraw() コールバックでアクセスすることになります。

onDraw() コールバックが呼び出されると、パラメータとして genvidClient.IDataFrame() オブジェクトを受け取ります。これには、ビデオフレームのタイムコード、接続されているすべてのセッションからのデータストリーム、ビデオ構成に関する情報が含まれています。フレームデータは、以下のように構成されています。

  • セッションメンバーからデータを取得することができます。このメンバーには、ストリームのリストとアノテーションのリストが含まれており、それぞれのセッション ID によって分類されています。
  • genvidClient.IDataFrame() インターフェイスは、そのストリームとアノテーションのメンバーに直接アクセスすることもできます。ただし、これらは非推奨であり、使用すべきではありません。上記のセッションメンバーを使用して、新しいマルチセッションオーダーに対応してください。

コンポジションデータ ( composition.ISourceCompositionData() の配列) は、どのトランスフォーメーションがさまざまなビデオストリームに適用されたかに関する情報です。利用方法としては、ビデオオーバーレイのどのピクセルが、どのビデオソースに対応するかを確認したり、1 つのビデオソースに関連するオーバーレイが、別のビデオに重なることを防ぐためのクリッピング操作を行ったりすることです。

現在のストリームには、各ストリームの最新フレームのみが含まれています。一方、アノテーションは、これまでに蓄積されたすべてのフレームを保持しており、繰り返されることはありません。ストリームとアノテーションの動作は異なりますが、どちらも genvidClient.IDataStreamFrame() インターフェイスにキャストされます。

Genvid MILE SDK は``rawdata`` 、フィールドを使用してバイナリ形式でデータを送信します。これは、JavaScript ArrayBuffer() です。データはどのようにでも読み取ることができますが、SDK はデコードに役立つユーティリティルーチンをいくつか提供しています。

たとえば、ゲームが UTF-8 形式にエンコードされた JSON データを送信する場合、Website のコードは、 rawdata バイナリフィールドを UTF-8 にデコードし、その文字列を JSON として解析する必要があります。アクセサ genvidClient.IDataStreamFrame.data() を使用すると、アクセス時に genvidClient.IDataStreamFrame.rawdata() フィールドを UTF-8 を使用してデコードしようとします。

警告

送信するデータが UTF-8 デコードに対応していない場合、 genvidClient.IDataStreamFrame.data() フィールドにアクセスすると例外が発生します。

onDraw(frame) {
   let stream = frame.streams["position"]
   let datastr = genvid.UTF8ToString(frame.rawdata);
   stream.user = JSON.parse(datastr);
   console.log(stream.user.myPosition);
}

Genvid はデータが繰り返されることがある (たとえば、ストリームのフレームレートが低い場合など) ため、同一データを複数回デコードしてしまうことを防ぐ機能を搭載しています。 IGenvidClient() には onStreamsReceived() 関数が含まれています。これは、データを受け取った時に、 genvidClient.IDataStreams() のコレクションを渡します。データストリームは、ビデオストリームとフレームのコレクションを含み、調整を行って Genvid の同期エンジンに統合することができます。たとえば、予定のイベントを検知するためにコレクション解析したり、コレクションを完全に削除したりなどです。

また、ゲームプロセスからのデータ送信時に使用される形式に違反しないかぎり、 streamId ごとに、デコードするための関数を調整することもできます (ゲームデータのライブ配信 を参照)。

ゲームの Web サイトのコードの準備ができたら、次のコマンドで GenvidClient のライブ配信を開始できます。

client.start();

IGenvidClient() は、設定したコールバックを自動的に使用して、ライブ動画配信と onDraw() で送信されるゲームデータの同期処理を行います。

onDisconnect コールバック

Websocket が閉じたときに、onDisconnect() コールバックが呼び出されます。このコールバックに機能をバインドして、ソケットが閉じたことを通知させることもできます。

client.onDisconnect(() => {this.onDisconnectDetected();});

reconnect コールバック

reconnect() が新しい websocket 接続を確立します。新しいストリーム情報、新しい leaf URI、新しいトークンをパラメータとして受信します。

client.reconnect(info, uri, token);

オーバーレイ

Genvid では厳密なオーバーレイ API は提供されていませんが、オーバーレイを動作させるための IGenvidClient() に必要なものはすべて公開されています。また、すべてのサンプルに使用する WebGL ユーティリティルーチンも公開しています。

オーバーレイのメインエントリポイントは、 onDraw() を使用して設定されたコールバックです。一定間隔で、ゲーム内に存在するすべてのストリームのデータフレームで、指定されたコールバックが呼び出されます。

このコールバックが、すべてのストリームの最新ゲームデータフレームを受け取ります。このデータは、WebGL キャンバスに 3D ハイライトをレンダリングしたり、HTML 要素を変更して現在のゲームの統計情報を表示したり、ボタンの可視性を調整して視聴者参加型ゲームイベントを許可したりなど、自由に処理することができます。

WebGL を簡単にレンダリングできるように、Genvid には、WebGL の反復タスクを簡略化する genvidWebGL.IWebGLContext() class が用意されています。これは、 genvidWebGL.createWebGLContext() メソッドで作成できます。

イベント

イベント は、 IGenvidClient() インスタンスで Genvid サービスに戻すことができます。詳細は、 sendEvent() および sendEventObject() を参照してください。

Genvid サービス内部では、スケーラビリティのために、これらの直接イベントは独自のイベント設定に従って 処理と削減 を行います。設定の例は こちら を参照してください。

その後、ゲームは縮小されたイベントストリームをサブスクライブできるようになります。

例えば、10 万人の視聴者が短時間で「応援」イベントを送った場合、ゲームは、同様に短時間で 10 万通のメッセージを受信する代わりに、10 万通のカウント値を持つ 1 つのオブジェクトを受信することになります。これは、配信を見ている視聴者の数からゲーム機の負荷を切り離すために提供しているソリューションです。

Google Chrome の自動再生サポート

Google Chrome には、ビデオ再生処理関する 特別なポリシー が存在します。弊社 API では、対応するビデオプレイヤーすべてに autoplay のタグセットが存在します。これにより、Firefox などのブラウザや、Media Engagement Index を適切なレベルに設定した Web サイトから自動的に動画再生を開始することが出来ます。

Chrome など、ほとんどのブラウザで自動ビデオ再生を有効にするには、ビデオをミュートに設定することも出来ます。動画をポーズしたときに、画面が停止したまま固まってしまうことを防ぐため、必ずオーバーレイを隠す必要があります。以下にサンプルコードを示します。

client.onVideoPlayerReady( (elem) => {

    // Optional: Set to muted to autostart even on Chrome and also iOS.
    client.videoPlayer.setMuted(true);

    // Always safe to hide the overlay on startup.
    // The PLAYING event below will show it.
    myGameOverlay.hide();

    client.videoPlayer.addEventListener(genvid.PlayerEvents.PAUSE, () => {
      myGameOverlay.hide();
    });

    client.videoPlayer.addEventListener(genvid.PlayerEvents.PLAYING, () => {
      myGameOverlay.show();
    });
});