スポットライト機能

警告

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

重要

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

重要

この機能は 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 の最新版に対応しています。

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

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

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

    • 2021 年 6 月時点では Chrome と Edge と Safari のみです

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

  • スポットライトレガシーでは接続時にフォーカスする数の ontrack が上がりましたが、スポットライトでは参加時に ontrack が上がります

  • スポットライトレガシーでは、フォーカスされていない人の映像は配信されませんでしたが、スポットライトではフォーカスされていない人の映像も、デフォルトで低画質&低フレームレートで配信されます

  • スポットライトレガシーでは、フォーカスされている人の映像はその本人にも配信されましたが、スポットライトではフォーカスされている人の映像は本人には配信されません

スポットライトレガシーの詳細は スポットライトレガシー機能 をご確認ください

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

マルチストリームのサイマルキャストを利用する場合、受信する映像の種類を切り替えるには 指定した視聴者の受信する RTP ストリームの rid をリクエストする API を利用する必要があります。

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

例えば、音声がない場合は rid は r0 、音声がある場合は rid は r1 のように、他の参加者が受信する映像の rid を切り替えます。

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

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

SDK 対応状況

  • 最新版の JavaScript SDK

    • 対応済みです

  • 最新版の iOS SDK

    • 対応済みです

  • 最新版の Android SDK

    • 対応済みです

  • 最新版の Unity SDK

    • 対応済みです

sora.conf

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

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

spotlight_legacy = false

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

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

カスタマイズの設定

フォーカスする配信数

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

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

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

遅延フォーカス

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

default_spotlight_delayed_focus

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

default_spotlight_delayed_focus_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 です。

シグナリング

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

    • これは必須です

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

    • これはオプションです

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

"type": "connect"

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.confdefault_spotlight_focus_riddefault_spotlight_unfocus_rid を指定することで、個別ではなくサーバー全体の設定も可能です。

シグナリング通知

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

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

イベントウェブフック

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

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

API

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

© Copyright 2021, Shiguredo Inc Created using Sphinx 4.1.1