OBS Studio WHEP 対応機能¶
注意
この機能を利用する場合は事前にサポートまでご連絡ください
警告
この機能は 実験的機能 のため、正式版では仕様が変更される可能性があります
概要¶
OBS Studio が対応を予定している WHEP を利用したメディアソースに対応しています。
ここでは Sora や OBS の WHEP 仕様について説明します。
注意¶
OBS の WHEP 実装の仕様を正としており RFC ドラフトの WHEP 仕様とは異なる可能性があります
現時点では Sora SDK は WHEP へ対応していません
OBS の WHEP 実装では Opus と H.264 の組み合わせでのみ利用できます
WHEP クライアントのお問い合わせについて¶
WHEP クライアントに関する質問などの報告は Discord の利用をお願いします。
Sora の WHEP クライアントについての質問やバグ報告は Discord の #sora-sdk-faq チャンネルにお願いします。
WHEP とは何か¶
WHEP は WebRTC-HTTP Egress Protocol の略で、 WebRTC では標準化されていないシグナリングをブロードキャスト/ストリーミング系のツール向けに規定した規格です。
WHIP は仕様を小さくして、実装を簡単にすることで配信ツールが取り込みやすくしています。
クライアントが HTTP POST で Offer SDP を送信して、Answer SDP を受け取るというシンプルなシグナリング規格です。
OBS 31.x にて WebRTC/WHEP がサポートされる可能性が高いです。
WHEP のシーケンス図¶
Sora の WHEP のシーケンス図¶
Sora では WHEP エンドポイント、 WHEP リソース、メディアサーバーすべてを Sora が担当します。
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 ソース として利用できるようになります。
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 は WHIP エンドポイントのレスポンスに含まれる 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 でエンコードした文字列です。
WHIP リソース URL 例:
https://sora.example.com/whep-resource/sora/QBF6AFDWZGWM97BNS5YCBSXM54M01D0TFQ48MC9Z3ZJG8YPRQ1Z0
注釈
OBS に Bearer トークンを指定した場合は、WHIP リソースエンドポイント 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¶
true が入ってきます。
metadata¶
sora.conf にて whep_bearer_token_metadata_key に指定した文字列をキーとして metadata に入ってきます。
whep_bearer_token_metadata_key = whip_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: trueaudio_codec_type: "OPUS"video: truevideo_codec_type: "H264"
simulcast¶
注意
現時点では OBS の WHEP 対応はサイマルキャストに未対応です。OBS 側の対応待ちです。
現時点では 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: falsespotlight: falsedata_channel_signaling: falseignore_disconnect_webhook: falseturn_transport_type: udpTURN が利用不可能な WHEP 実装の場合は udp が割り当てられます
TURN が利用可能な WHEP 実装の場合は udp または tcp が適切に割り当てられます
TURN の利用¶
注意
現時点では OBS の WHIP 対応は Link ヘッダーを利用した TURN Urls の払い出しに未対応です。OBS 側の対応待ちです。
sora.conf で sora_conf-turn-whep を有効にすることで 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 ヘッダーにて払い出します。