スポットライト機能¶

重要

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

概要¶

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

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

この スポットライト機能 を利用すると、発言していない大多数の参加者の音声は配信せず、低画質の映像のみを配信できます。ある参加者が発言し始めると、自動でその参加者の音声の配信を開始し、さらにあらかじめ設定した秒数が経過すると、映像の画質も自動で高画質に切り替えることができます。

この仕組を使うことで、クライアントやサーバーの負荷を抑えながら大人数で会議を行うことが可能になります。

この機能は、発言している参加者のみの音声と高画質の映像が配信されることから、スポットライトが当たるイメージに見立てて、スポットライト機能と名付けています。

仕組み¶

開始前に、フォーカスする人数を決めます。フォーカスする人数とは、会議の参加者のうち、最大何人分の映像を高画質で配信するかの数です。

ここではフォーカスする人数を 1 人とします。

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

最初に A さんが発言し始めると、 A さんの映像が高画質になって配信されます。

次に B さんが発言すると、 B さんの映像が高画質になって配信されます。このタイミングで A さんの映像は低画質になります。

その後は同じように、直近で発言した 1 人分の映像が高画質で配信され、音声も配信されます。それ以外の参加者の映像は低画質で配信され、音声は配信されません。

このように、高画質で配信する人数を限定することで、クライアントやサーバーの負荷を抑えながら大人数での会議が実現できます。

ただし、上記のような自動切り替えでは、参加者の映像が頻繁に入れ替わると逆に負荷が高くなってしまいます。それを抑えるため、Sora では、参加者が発言し始めるとまずは音声だけを配信し始め、映像の切り替えはしばらく時間が経ってから行うことが可能です。

この時、映像が切り替わる前に、先に音声を配信することをフォーカスなし音声配信と呼びます。これにより、映像の切り替わりの有無に関わらず、短い発言、あいづちなども配信し、スムーズな会話を成立させられます。

また、音声よりも遅れて映像を切り替えることを遅延フォーカスと呼びます。映像の切り替えを遅延させることにより、ちょっとした雑音や短い発言のたびに映像が切り替わることを抑制することが可能です。

これらのフォーカスなし音声配信や遅延フォーカス機能を利用すれば、スポットライト機能でフォーカスする人数は 1 〜 2 人で十分です。多くても 3 人です。

注意¶

スポットライト機能はサイマルキャスト機能を活用した機能です¶

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

高画質
- 解像度の縮小比が 1 で 30 fps
低画質
- 解像度の縮小比が 4 で 5 fps

Chrome 、 Edge 、 Safari で動作します¶

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

注釈

Firefox ではサイマルキャスト機能ができないため、 Firefox を利用する場合はサイマルキャスト機能を無効にして接続する必要があります。

詳細はサイマルキャスト機能を無効にして接続するをご確認ください。

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

マルチストリームのサイマルキャストを利用する場合、受信する映像の種類を切り替えるには RequestRtpStream API を利用する必要があります。

スポットライトはこの API の切り替え部分を Sora が自動で判断します。判断には参加者の音量を利用します。

例えば、音量が閾値を下回った場合は rid は r0 、閾値を超えた場合は rid は r1 のように、他の参加者が受信する映像の rid を切り替えます。

マルチストリームの詳細はマルチストリーム機能をご確認ください

サイマルキャストの詳細はサイマルキャスト機能をご確認ください

SDK 対応状況¶

最新版の JavaScript SDK
- 対応済みです
最新版の iOS SDK
- 対応済みです
最新版の Android SDK
- 対応済みです
最新版の Unity SDK
- 対応済みです
最新版の C++ SDK
- 対応済みです

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

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

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

r0¶

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

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}
    ]
}

カスタマイズの設定¶

rid
- 必須
- string (r0 / r1 / r2)
- https://www.w3.org/TR/webrtc/#dom-rtcrtpcodingparameters-rid
active
- このエンコーディングパラメータを有効にします
- オプション
- boolean
- https://www.w3.org/TR/webrtc/#dom-rtcrtpencodingparameters-active
scaleResolutionDownBy
- オプション
- 1 以上の number (float または integer)
- https://www.w3.org/TR/webrtc/#dom-rtcrtpencodingparameters-scaleresolutiondownby
maxBitrate
- オプション
- 最大ビットレートを指定する
- 0 以上の integer
- https://www.w3.org/TR/webrtc/#dom-rtcrtpencodingparameters-maxbitrate
maxFramerate
- オプション
- 最大フレームレートを指定する
- 0 以上の number (float または integer)
- https://w3c.github.io/webrtc-extensions/#dom-rtcrtpencodingparameters-maxframerate
adaptivePtime
- この設定は Chrome でしか利用できません
- オプション
- boolean
- https://w3c.github.io/webrtc-extensions/#dom-rtcrtpencodingparameters-adaptiveptime

フォーカスする配信数¶

フォーカスする配信数はチャネル ID ごとに 1 から 8 までのいずれかを選択できます。

デフォルトのフォーカス数は 1 です。

遅延フォーカスやフォーカスなしでの音声配信を有効にしていればフォーカス数は 1 で十分です。

遅延フォーカス¶

ちょっとした物音でフォーカスをしないようにするため、フォーカスを遅延させる機能です。この機能を有効にした場合、フォーカスされる場合に一定時間以上、音が出続けている必要があります。

default_spotlight_delayed_focus ¶

sora.conf で遅延フォーカスを有効にするかどうかを指定してください。デフォルトで true です。

default_spotlight_delayed_focus_interval ¶

sora.conf でフォーカスを遅延させる時間を指定してください。デフォルトは 2000 ms です。

遅延アンフォーカス¶

スポットライトの数が少ないときに、フォーカスの奪い合いが発生しないように、フォーカスが発生してからアンフォーカスするまで遅延させる機能です。

default_spotlight_focus_min_interval ¶

sora.conf でフォーカスしてからアンフォーカスされるまでの最低時間間隔を指定します。デフォルトは 2000 ms です。

フォーカスなし音声配信¶

フォーカスがない状態でも音声を配信するかを指定する機能です。この機能を有効にすると、フォーカスが他の配信者にとられても音声を配信し続けます。

配信するレートの上限も指定できます。

default_spotlight_unfocus_audio ¶

sora.conf でフォーカスなし音声を有効にするかどうかを指定してください。デフォルトで true です。

default_spotlight_unfocus_audio_rate_limit ¶

sora.conf でフォーカスなし音声を配信する上限レートを指定してください。デフォルトは 2 です。

レートの単位は 1 音声ストリーム = 50 packets / s です。

自動アンフォーカス¶

無音状態が一定時間続くとフォーカスを自動で外す機能です。この機能を利用するとフォーカス数が 0 になることもあります。

クライアントが受信するパケット、Sora が配信するパケットを減らすことができます。

default_spotlight_auto_unfocus ¶

sora.conf で音がない場合に自動でアンフォーカスするかどうかを指定してください。デフォルトは true です。

default_spotlight_auto_unfocus_interval ¶

sora.conf で自動でアンフォーカスする無音時間を指定してください。デフォルトは 10 s です。

サイマルキャスト機能を無効にして接続する¶

スポットライト機能でサイマルキャスト機能を無効にして利用することも可能です。

無効にする場合はシグナリング接続時または認証成功時に "simulcsat": "false" を指定する必要があります。

サイマルキャスト機能を無効にてスポットライトを利用した場合、そのクライアントは常にフォーカスされている状態となります。そのため spotlight_focus_rid や spotlight_unfocus_rid の影響も受けません。

サイマルキャスト機能を無効にした利用は、画面共有やサイマルキャストが利用できないクライアントでの利用を想定しています。

シグナリング¶

シグナリングの "type": "connect" で multistream と spotlight を true に設定してください
- これは必須です
シグナリングの "type": "connect" で simulcast を設定してください
- これはオプションです
- サイマルキャストを無効にする場合はサイマルキャスト機能を無効にして接続するをご確認ください
シグナリングの "type": "connect" で spotlight_number で 1 ~ 8 の値を指定してください
- 1 から 3 の間がお勧めです
- これはオプションです

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

"type": "connect"¶

simulcast: false¶

サイマルキャスト無効。

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

spotlight_number¶

フォーカス数はデフォルトの 1

{
    "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
    }
}

spotlight_focus_rid / spotlight_unfocus_rid¶

シグナリング接続時、認証成功時にフォーカスした場合とフォーカスしていない場合に受信する映像の rid を接続毎に指定できます。

例えば、映像は特に受け取らなくていい場合は、両方の設定で none を指定することで参加者全員の映像を受信しなくなります。

また、話している人は rid は r1 で受信し、それ以外は受信しない (rid に none を指定) といった設定も可能です。

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

sora.conf で default_spotlight_focus_rid と default_spotlight_unfocus_rid を指定することで、個別ではなくサーバー全体の設定も可能です。

シグナリング通知¶

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

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

イベントウェブフック¶

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

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

API¶

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

FocusSpotlightFixed API
- 特定のクライアントにフォーカスし続ける API
FocusSpotlight API
- 特定のクライアントにフォーカスする API
UnfocusSpotlight API
- 特定のクライアントからアンフォーカスする API
ChangeSpotlightNumber API
- フォーカスする数を変更する API
RequestSpotlightRid API
- 特定のクライアントのフォーカス/アンフォーカス時の rid を変更する API
ResetSpotlightRid API
- 特定のクライアントのフォーカス/アンフォーカス時の rid をリセットする API
BatchRequestSpotlightRid API
- フォーカス/アンフォーカス時の rid を一括で変更する API

スポットライト機能¶

概要¶

仕組み¶

注意¶

スポットライト機能はサイマルキャスト機能を活用した機能です¶

Chrome 、 Edge 、 Safari で動作します¶

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

SDK 対応状況¶

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

r0¶

r1¶

r2¶

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

sora.conf でファイル指定¶

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

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

カスタマイズの設定¶

フォーカスする配信数¶

遅延フォーカス¶

default_spotlight_delayed_focus¶

default_spotlight_delayed_focus_interval¶

遅延アンフォーカス¶

default_spotlight_focus_min_interval¶

フォーカスなし音声配信¶

default_spotlight_unfocus_audio¶

default_spotlight_unfocus_audio_rate_limit¶

自動アンフォーカス¶

default_spotlight_auto_unfocus¶

default_spotlight_auto_unfocus_interval¶

サイマルキャスト機能を無効にして接続する¶

シグナリング¶

"type": "connect"¶

simulcast: false¶

spotlight_number¶

spotlight_focus_rid / spotlight_unfocus_rid¶

シグナリング通知¶

イベントウェブフック¶

API¶

シーケンス図¶

default_spotlight_delayed_focus ¶

default_spotlight_delayed_focus_interval ¶

default_spotlight_focus_min_interval ¶

default_spotlight_unfocus_audio ¶

default_spotlight_unfocus_audio_rate_limit ¶

default_spotlight_auto_unfocus ¶

default_spotlight_auto_unfocus_interval ¶