スポットライト機能

警告

スポットライト機能は実験的機能のため正式版では仕様が変更される可能性があります

重要

この機能は Chrome 、 Edge 、Safari でのみ利用可能です

重要

この機能は VP8 または H.264 でのみ利用可能です

概要

WebRTC SFU サーバを利用して 20 名で会議を行う場合、各参加者は自分以外の 19 名分の音声と映像を常に受信し続ける必要があります。 また、WebRTC SFU サーバも、常に 19 名分の音声や映像を受信し、配信し続ける必要があります。

ところが実際は 19 名の会議であっても、ひとつのトピックに対して発言している人はせいぜい 2 名から 3 名で、 また、映像も常に参加者全員のものでなくとも、その時点でアクティブに発言している人の音声と映像のみで十分というケースも多いです。

この スポットライト機能 は、一定の音量を超えて音声を発している参加者の音声や高画質映像を配信する機能です。 それ以外の参加者は音声のない低画質映像で配信します。

この仕組を使うことでクライアントの負荷を抑え、同時に 19 人を画面に表示することが可能になります。

配信されている参加者が参加者の中でスポットライトがあたっているような形になることから、スポットライト機能と名付けました。

スポットライトレガシーとの違い

スポットライトレガシーとは以下の点で異なります

  • サイマルキャストに対応しているブラウザで利用可能です

    • 2020 年 12 月時点では Chrome と Edge と Safari のみです

  • 利用できるコーデックが VP8 または H.264 となります

  • スポットライトレガシーでは接続時にアクティブ数の ontrack が上がりましたが、スポットライトでは参加時に ontrack が上がります

  • スポットライトレガシーではアクティブではない人は受信していませんでしたが、スポットライトでは低画質&低 FPS での映像のみを受信します

  • スポットライトレガシーでは自分の映像が自分がアクティブになった際に配信されていましたが、スポットライトでは自分の映像は配信されません

マルチストリームのサイマルキャストとの違い

マルチストリームのサイマルキャストでは映像の種類を切り替えるには API をたたく必要があります。

スポットライトは配信しているここの音声の音量を見て、他の参加者が受信する映像の種類を自動で切り替えます。

仕組み

開始前に、アクティブな人数の最大を決めます。映像の切り替わりなどを考えると 2-3 人あたりが無難だと思います。

ここではアクティブな人数を 2 人とします。

この機能を利用した場合は、音声を発していない参加者の映像は低画質で配信され、音声は配信されません。

最初に A さんが、一定の音量を超えて発言したタイミングで、A さんの映像が高画質になって配信されます。

次に B さんが、一定の音量を超えて発言したタイミングで、B さんの映像も高画質になって配信されます。

次に一定の音量を超えて発言したのが C さんであれば、A さんと B さんの話していた時間が 少ないほうが低画質に戻り、音声が配信されなくなり、 C さんの映像が高画質になって配信され、音声が配信されます。

その後は同じように、直近で (一定の音量を超えて) 発言した 2 人分の映像が高画質で配信され、音声が配信されます。 それ以外の参加者の映像は低画質、音声はなしで配信されます。

注意

サイマルキャストを利用します

デフォルトであれば解像度が VGA 以上のサイズであれば2つの画質の映像を配信します。

  • 高画質

    • 解像度の縮小比が 1 で 30 fps

  • 低画質

    • 解像度の縮小比が 4 で 1 fps

Chrome 、 Edge 、 Safari で動作します

現時点では Chrome と Edge と Safari の最新版に対応しています。

SDK への対応

現時点では JavaScript のみが対応しており、 iOS、Android、Unity の SDK は対応中です。

sora.conf

sora.config にて spotlight_legacyfalse に設定してください。

この設定をした場合はスポットライトレガシーは利用できなくなります。

spotlight_legacy = false

スポットライト利用時の映像の種類のデフォルト

Sora ではスポットライトで配信する映像の種類にデフォルト値を設定しています。

[
    {"rid": "r0", "active": true, "maxFramerate":  1.0, "scaleResolutionDownBy": 4.0},
    {"rid": "r1", "active": true, "maxFramerate": 30.0, "scaleResolutionDownBy": 1.0},
    {"rid": "r2", "active": false}
]

r0

rid が r0 の場合は通常の解像度から解像度(一辺) が 1/4 で、 フレームレートが 1 になるようなエンコードがされるように設定されています。

r1

rid が r1 の場合は通常の解像度のままで、 フレームレートが 30 でエンコードがされるように設定されています。

r2

rid が r2 の場合はエンコードがされないように設定されています。

スポットライト利用時の映像のエンコーディングパラメータのカスタマイズ

Sora ではスポットライトでの映像のエンコーディングパラメータを自由に設定することができます。

  • sora.conf のファイルで指定することで全体のスポットライトのエンコーディングパラメータが指定できます

  • 認証成功時に spotlight_encodings で払い出すことで個別にスポットライトのエンコーディングパラメータが指定できます

sora.conf でファイル指定

sora.conf にて スポットライトの場合は spotlight_encodings_file で JSON を指定してください。

spotlight_encodings_file = etc/spotlight_encodings.json

sora.conf で指定する JSON ファイルの記述方法

[
    {"rid": "r0", "active": true, "scaleResolutionDownBy": 4.0, "maxFramerate": 5.0},
    {"rid": "r1", "active": true, "scaleResolutionDownBy": 1.0, "maxFramerate": 10.0},
    {"rid": "r2", "active": true, "scaleResolutionDownBy": 1.0, "maxFramerate": 30.0}
]

認証成功時に spotlight_encodings で払い出す記述方法

{
    "allowed": true,
    "spotlight_encodings": [
        {"rid": "r0", "active": true, "scaleResolutionDownBy": 2.0, "maxFramerate": 5.0},
        {"rid": "r1", "active": true, "scaleResolutionDownBy": 2.0, "maxFramerate": 20.0},
        {"rid": "r2", "active": true, "scaleResolutionDownBy": 1.0, "maxFramerate": 30.0}
    ]
}

カスタマイズの設定

アクティブな配信数

アクティブな配信数はチャネル ID ごとに 1 から 8 までのいずれかを選択可能です。

デフォルトのアクティブ数は 3 です。

シグナリング

  • シグナリングの type: connectmultistreamsimulcastspotlighttrue に設定してください

    • これは必須です

  • シグナリングの type: connectspotlight_number で 1 ~ 8 の値を指定してください

    • これはオプションです

その他の項目は シグナリング を参照ください。以下に シグナリング type: connect の例を示します。

"type": "connect"

アクティブ数はデフォルトの 3

{
    "type": "connect",
    "channel_id": "sora",
    "role": "sendrecv",
    "spotlight": true,
    "simulcast": true,
    "multistream": true,
    "video": {
        "codec_type": "VP8",
        "bit_rate": 800
    }
}

アクティブ数は指定した値の 5

{
    "type": "connect",
    "channel_id": "sora",
    "role": "sendrecv",
    "spotlight": true,
    "spotlight_number": 5,
    "simulcast": true,
    "multistream": true,
    "video": {
        "codec_type": "VP8",
        "bit_rate": 800
    }
}

シグナリング通知

シグナリング通知の詳細は スポットライト機能のシグナリング通知 をご確認ください。

フォーカスされたタイミングとフォーカスが外れたタイミングでシグナリング通知をクライアントに送ります。 クライアントはこの通知を利用することで、配信が切り替わったことを知ることが可能になります。

イベントウェブフック

フォーカスされたタイミングとフォーカスが外れたタイミングでウェブフックが通知されます。

sora.confignore_spotlight_changed_webhook にて指定可能です。 デフォルトではイベントウェブフックでの通知は無効になっています。

API

API の詳細は スポットライト API をご確認ください。

  • 指定した参加者にスポットライトをフォーカスし続ける API

  • 指定した参加者にスポットライトをフォーカスする API

  • 指定した参加者からスポットライトのフォーカスを外す API

  • スポットライトのフォーカス数を変更する API

  • 指定した参加者の受信している映像ストリームのクオリティを変更する API

  • 指定した参加者の受信している映像ストリームのクオリティをリセットする API