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.2.0 では WHEP に対応していません。

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

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

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 での利用方法は以下の通りです。

1. シーンのソースに WHEP ソースを追加する

2. WHEP ソースに Sora が提供する WHEP エンドポイント URL を指定する

   • デフォルトでは http://127.0.0.1:5000/whep/<channel_id>

3. 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

  • ただし 2025 年 6 月 現在では OBS WHEP は TURN に対応しておらず、 TURN-TCP にも対応していません

• turn_tls_only

  • ただし 2025 年 6 月 現在では 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 の利用

WHIP と同様の挙動です。 TURN の利用 をご確認ください。

クラスター利用時の挙動

WHIP と同様の挙動です。 クラスター利用時の挙動 をご確認ください。

シーケンス図

シングルノード

        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 終了
    

コンテンツ

• OBS Studio WHEP 対応機能
  • 概要
  • 注意
    • WHEP クライアントのお問い合わせについて
  • WHEP とは何か
    • WHEP のシーケンス図
    • Sora の WHEP のシーケンス図
  • OBS の WHEP 対応について
  • OBS 以外の WHEP クライアントへの対応について
  • Sora での利用方法
    • WHEP
    • Bearer トークンを利用した認証機能を利用する場合
  • OBS での WHEP 利用方法
    • 切断方法
  • Sora の OBS (WHEP) の挙動
  • WHEP エンドポイント URL
    • チャネル ID の指定
  • WHEP リソース URL
  • 認証仕様
  • 認証成功時の払い出し
  • ウェブフック仕様
    • whep
    • ignore_disconnect_websocket
    • metadata
    • multistream
    • role
    • channel_id
    • client_id
    • bundle_id
    • spotlight
    • audio / video
    • simulcast
    • sora_client
    • その他
  • TURN の利用
  • クラスター利用時の挙動
  • シーケンス図
    • シングルノード