OBS Studio WHEP 対応機能¶

注意

この機能を利用する場合は事前にサポートまでご連絡ください

警告

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

概要¶

OBS Studio が対応を予定している WHEP を利用したメディアソースに対応しています。

ここでは Sora や OBS の WHEP 仕様について説明します。

注意¶

OBS の WHEP 実装の仕様を正としており RFC ドラフトの WHEP 仕様とは異なる可能性があります
現時点では Sora SDK は WHEP へ対応していません
OBS の WHEP 実装では Opus と H.264 の組み合わせでのみ利用できます
現時点では WHEP を利用した接続の統計ウェブフックの送信には対応していません

WHEP クライアントのお問い合わせについて¶

WHEP クライアントに関する質問などの報告は Discord の利用をお願いします。

URL:: https://discord.gg/shiguredo

Sora の WHEP クライアントについての質問やバグ報告は Discord の #sora-sdk-faq チャンネルにお願いします。

WHEP とは何か¶

参考

WebRTC-HTTP Egress Protocol (WHEP)

WHEP は WebRTC-HTTP Egress Protocol の略で、 WebRTC では標準化されていないシグナリングをブロードキャスト/ストリーミング系のツール向けに規定した規格です。

WHEP は仕様を小さくして、実装を簡単にすることで配信ツールが取り込みやすくしています。

クライアントが HTTP POST で Offer SDP を送信して、Answer SDP を受け取るというシンプルなシグナリング規格です。

将来的に OBS で WebRTC/WHEP がサポートされる予定です。

WHEP のシーケンス図¶

        sequenceDiagram
  participant OBS as OBS
  participant WE as WHEP Endpoint
  participant MS as Media Server
  participant WS as WHEP Resource
  OBS->>+WE: HTTP POST (SDP Offer)
  WE-->>-OBS: HTTP 201 Created (SDP Answer)
  note over OBS,MS: WebRTC Connection
  OBS->>+WS: HTTP DELETE
  WS->>-OBS: HTTP 200 OK

Sora の WHEP のシーケンス図¶

Sora では WHEP エンドポイント、 WHEP リソース、メディアサーバーすべてを Sora が担当します。

        sequenceDiagram
   participant OBS as OBS
   participant S as Sora
   participant A as App
   OBS->>+S: HTTP POST (SDP Offer)
   S->>+A: 認証ウェブフック
   A-->>-S: 200 OK<br>allowed : true
   S-->>-OBS: HTTP 201 Created (SDP Answer)
   note over OBS,S: WebRTC Connection
   S->>+A: イベントウェブフック<br>connection.created
   A-->>-S: 200 OK
   OBS->>+S: HTTP DELETE
   S->>+A: イベントウェブフック<br>connection.destroyed
   A-->>-S: 200 OK
   S->>-OBS: HTTP 200 OK

OBS の WHEP 対応について¶

警告

OBS の WHEP 対応については Discord https://discord.gg/shiguredo の #sora-sdk-faq にてご相談ください。

OBS 30.1.0 では WHEP に対応していません。

以下の Pull-Request がマージされ、正式リリースされることで WHEP に対応予定です。 https://github.com/obsproject/obs-studio/pull/10353

WHEP は WHEP ソース として利用できるようになります。

https://i.gyazo.com/d201cb2c8eea99d29a02e6f6a57f9180.jpg

OBS 以外の WHEP クライアントへの対応について¶

重要

Sora の WHEP 実装は OBS の WHEP 対応のみをサポートしています。それ以外のクライアントの WHEP 実装には対応していません。

新しい WHEP クライアントへの対応は有償での優先実装として対応を検討できますので、対応希望の WHEP クライアントと優先実装については、サポートまでメールにてご連絡ください。

ブラウザ
GStreamer
FFmpeg

Sora での利用方法¶

WHEP¶

sora.conf にて whep を true に指定してください。

whep = true

Bearer トークンを利用した認証機能を利用する場合¶

sora.conf にて whep_bearer_token_metadata_key を指定してください。

whep_bearer_token_metadata_key = whep_access_token

例えば、 access_token という文字列をした場合、 WHEP 接続時、認証ウェブフックに "metadata": {"access_token": "<bearer_token>""} が入ってきます。 whep_token を指定した場合は "metadata": {"whep_token": "<bearer_token>""} が入ってきます。

whep_bearer_token_metadata_key が未指定の場合は、 Bearer トークンが WHIP/WHEP 接続時に送られてきたとしても Sora は無視して、 metadata も生成しません。

OBS での WHEP 利用方法¶

OBS での利用方法は以下の通りです。

シーンのソースに WHEP ソースを追加する
WHEP ソースに Sora が提供する WHEP エンドポイント URL を指定する
- デフォルトでは http://127.0.0.1:5000/whep/<channel_id>
Bearer トークンには好きな文字列を指定する
- Sora の認証ウェブフックの項目 whep_bearer_token_metadata_key で指定した値をキーとして、 "metadata": {"<whep_bearer_token_metadata_key>": "<bearer_token>""} が認証サーバーに送信されます

切断方法¶

Location ヘッダーに入ってくるリソースエンドポイント URL に DELETE リクエストを送ることで切断できます。

OBS は配信終了することで切断リクエストを送りますので、意識する必要はありません。

Sora の OBS (WHEP) の挙動¶

Sora は WHEP エンドポイント URL を提供します
- デフォルトでは http://127.0.0.1:5000/whep/<channel_id> です
Sora の WHEP エンドポイントからの配信は、マルチストリームかつ視聴のみ(recvonly)として扱われます
Sora の WHEP エンドポイントを利用した配信では、シグナリング通知は現時点では利用できません
Sora の WHEP リソース URL は WHEP エンドポイントのレスポンスに含まれる Location ヘッダーにて払い出されます
同一チャネルに複数の配信が存在する場合、 WHEP での接続を認証前に接続を拒否します
同一チャネルに複数の配信始まった場合、 WHEP での接続を切断します

WHEP エンドポイント URL¶

Sora の OBS (WHEP) 対応は "multistream": true, "role": "recvonly" として機能します。

チャネル ID の指定¶

OBS ではリクエスト時に JSON でチャネル ID を指定することができません。そのため WHEP エンドポイント URL に channel_id を含めて指定します。 channel_id に URL に利用できない文字が含まれている場合は URL エンコードしてください。

HTTP POST https://sora.example.com/whep/<channel_id>

channel_id が sora の WHEP エンドポイント URL 例:

https://sora.example.com/whep/sora

WHEP エンドポイントへの HTTP リクエストに対するレスポンスコードは 201 Created です。

WHEP リソース URL¶

Sora では WHEP リソースエンドポイントは Location ヘッダーに含まれています。

以下は切断する例です。

HTTP DELETE https://sora.example.com/whep-resource/<channel_id>/<secret>

以下は Trickle ICE を利用する例です。

HTTP PATCH https://sora.example.com/whep-resource/<channel_id>/<secret>

<secret> は 32 バイトのランダムな値を base32 でエンコードした文字列です。

WHEP リソース URL 例:

https://sora.example.com/whep-resource/sora/QBF6AFDWZGWM97BNS5YCBSXM54M01D0TFQ48MC9Z3ZJG8YPRQ1Z0

注釈

OBS に Bearer トークンを指定した場合は、WHEP リソースエンドポイント URL にも Bearer トークンは送られます

認証仕様¶

WHEP では認証に Bearer トークンを指定することができます。

OBS でも認証情報に Bearer トークンを指定できます。

Sora は sora.conf で whep_bearer_token_metadata_key に文字列を指定していた場合、 OBS の HTTP POST 時に Authentication ヘッダーで送られてきた Bearer トークンを、認証ウェブフックの metadata に {"<whep_bearer_token_metadata_key>": "<bearer_token>"} を設定して認証サーバーに送信します。

Sora 自体は Bearer トークンのチェックやデコードなどは行いません。これらは認証ウェブフックのリクエストを受信した認証サーバーが行う必要があります。

認証成功時の払い出し¶

WHEP では以下の項目が利用できます。

client_id
bundle_id
event_metadata
connection_lifetime
playout_delay_min_delay
playout_delay_max_delay
turn_tcp_only
- ただし 2024 年 12 月現在では OBS WHEP は TURN に対応しておらず、 TURN-TCP にも対応していません
turn_tls_only
- ただし 2024 年 12 月現在では OBS WHEP は TURN に対応しておらず、 TURN-TLS にも対応していません

ウェブフック仕様¶

whep¶

true が入ってきます。

ignore_disconnect_websocket¶

false が入ってきます。

metadata¶

sora.conf にて whep_bearer_token_metadata_key に指定した文字列をキーとして metadata に入ってきます。

whep_bearer_token_metadata_key = whep_bearer_token

もし文字列を whep_bearer_token にしていた場合は、 "metadata": {"whep_bearer_token": "<bearer-token>"} が送られてきます。

OBS 側に設定した Bearer Token の値がそのまま入ってきます。

multistream¶

true が入ってきます。

role¶

recvonly が入ってきます。

channel_id¶

WHEP エンドポイント URL に渡した値が利用されます。

注釈

URL デコード済みの値が入ります

client_id¶

WHEP エンドポイント URL にクエリ文字列として client_id=<client_id> を指定した場合、その値が利用されます。

注釈

URL デコード済みの値が入ります

bundle_id¶

WHEP エンドポイント URL にクエリ文字列として bundle_id=<bundle_id> を指定した場合、その値が利用されます。

注釈

URL デコード済みの値が入ります

spotlight¶

WHEP エンドポイント URL にクエリ文字列として spotlight=<boolean> を指定した場合、その値が利用されます。

注釈

URL デコード済みの値が入ります

audio / video¶

OBS 側で指定した値を利用します。 OBS では音声は Opus のみ、映像は H.264 が利用できます。

audio: true
audio_codec_type: "OPUS"
video: true
video_codec_type: "H264"

simulcast¶

false が入ってきます。

sora_client¶

OBS WHEP で User-Agent として送られてくる情報を sora_client に含めています。

"sora_client": {
  "raw": "Mozilla/5.0 (OBS-Studio/30.1.0; Mac OS X; ja-JP)",
  "type": "OBS-Studio-WHEP",
  "version": "30.1.0",
  "environment": "environment":"Mozilla/5.0 (OBS-Studio/30.1.0; Mac OS X; ja-JP)"
},

その他¶

e2ee: false
spotlight: false
data_channel_signaling: false
ignore_disconnect_webhook: false
turn_transport_type: udp
- TURN が利用不可能な WHEP 実装の場合は udp が割り当てられます
- TURN が利用可能な WHEP 実装の場合は udp または tcp が適切に割り当てられます

TURN の利用¶

注意

現時点では OBS の WHEP 対応は Link ヘッダーを利用した TURN Urls の払い出しに未対応です。OBS 側の対応待ちです。

sora.conf で whep_turn を有効にすることで Sora は Link ヘッダーに TURN URLs を払い出します。

Sora の仕様として TURN を有効にした場合は TURN のみの通信 を行います、そのため TURN に対応していない OBS が利用できなくなります。

OBS の TURN 機能¶

TURN-UDP のみの対応です。 TURN-TCP や TURN-TLS には対応していません。

クラスター利用時の挙動¶

注意

現時点では OBS の WHEP 対応は Link ヘッダーを利用した TURN Urls の払い出しに未対応です。OBS 側の対応待ちです。

現時点ではクラスター利用時に、接続したノードが指定した channel_id の担当ノードでは無い場合、担当ノードの IP アドレスを Answer SDP に含めます。

OBS の WHEP 対応で TURN へ対応した場合¶

クラスター利用時に、接続したノードが指定した channel_id の担当ノードでは無い場合、担当ノードの TURN URLs を Link ヘッダーにて払い出します。

シーケンス図¶

シングルノード¶

        sequenceDiagram
   participant WHIP as WHIP
   participant WHEP as WHEP
   participant S as Sora
   participant A as App
   note over WHIP, S: WebRTC 確立
   WHEP->>+S: HTTP POST https://sora.example.com/whep/<channel_id><br>Offer SDP
   S->>+A: 認証ウェブフック<br><br>"channel_id": "<channel_id>"<br>"multistream": true<br>"role": "recvonly"
   A-->>-S: "allowed": true
   S-->>-WHEP: HTTP 201 Created<br>Answer SDP

   Note left of S: このタイミングで Link ヘッダーで、<br>TURN URLs を払い出す

   note over WHEP,S: ICE 確立
   note over WHEP,S: DTLS 確立
   note over WHEP,S: WebRTC 確立

   S->>+A: イベントウェブフック<br>"connection.created"
   A-->>-S: HTTP 200 OK

   S-)WHEP: SRTP
   S-)WHEP: SRTP

   WHEP->>+S: HTTP DELETE https://sora.example.com/whep/<channel_id>/<secret>
   S-->>-WHEP: HTTP 200 OK

   note over WHEP,S: WebRTC 終了