# WHEP 機能




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

> **警告**
>
> この機能は [実験的機能](EXPERIMENTAL.html) のため、正式版では仕様が変更される可能性があります

## 概要

Sora は [WHEP](https://datatracker.ietf.org/doc/html/draft-ietf-wish-whep) で定義されている WHEP (WebRTC-HTTP Egress Protocol) の仕様に準拠した WHEP 機能を提供しています。

ただし、 [OBS Studio](https://obsproject.com/) での WHEP での動作を優先しています。そのため、 [WHEP](https://datatracker.ietf.org/doc/html/draft-ietf-wish-whep) で定義されている WHEP の仕様とは異なる場合があります。

## 注意

- OBS Studio の WHEP での動作を優先しており RFC ドラフトの WHEP 仕様とは異なる可能性があります
- Sora SDK は WHEP へ対応していません
- OBS Studio の WHEP 実装では Opus と **H.264** の組み合わせでのみ利用できます
- 現時点では WHEP を利用した接続の統計ウェブフックの送信には対応していません
- Sora の WHEP 対応は `406 Not Acceptable` を利用したサーバーからのカウンター Offer には現時点では対応していません

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

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

**URL**: 

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

## WHEP とは何か

> **参考**
>
> [WebRTC-HTTP Egress Protocol (WHEP)](https://datatracker.ietf.org/doc/html/draft-ietf-wish-whep)

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

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

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

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

### WHEP のシーケンス図

```mermaid
sequenceDiagram
  participant OBS as "OBS Studio"
  participant WE as WHEP Endpoint
  participant MS as Media Server
  participant WS as WHEP Session
  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 が担当します。

```mermaid
sequenceDiagram
   participant OBS as "OBS Studio"
   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 Studio の WHEP 対応について

> **警告**
>
> OBS Studio の WHEP 対応については Discord  の #sora-sdk-faq にてご相談ください。

2026 年 6 月 時点での最新版である [OBS Studio 32.1](https://github.com/obsproject/obs-studio/releases/tag/32.1.0) では WHEP に対応していません。

以下の Pull-Request がマージされ、正式リリースされることで WHEP に対応予定です。

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

![image](https://i.gyazo.com/d201cb2c8eea99d29a02e6f6a57f9180.jpg)

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

> **重要**
>
> Sora の WHEP 実装は OBS Studio の WHEP 対応を優先しています。

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

## Sora での利用方法

### WHEP

`sora.conf` にて [whep](SORA_CONF.html#5a91bb) を `true` に指定してください。

```ini
whep = true
```

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

`sora.conf` にて [whep_bearer_token_metadata_key](SORA_CONF.html#f857c6) を指定してください。

```ini
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 Studio での WHEP 利用方法

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


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 Studio は配信終了することで切断リクエストを送りますので、意識する必要はありません。

## Sora の OBS Studio (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 Studio (WHEP) 対応は `"role": "recvonly"` として機能します。

### チャネル ID の指定

OBS Studio ではリクエスト時に 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 セッション URL は WHEP エンドポイントのレスポンスに含まれる Location ヘッダーにて払い出されます。

以下は切断する例です。

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

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

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

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

WHEP セッション URL 例:

```
https://sora.example.com/whep-session/sora/QBF6AFDWZGWM97BNS5YCBSXM54M01D0TFQ48MC9Z3ZJG8YPRQ1Z0
```

> **注釈**
>
> OBS Studio に Bearer トークンを指定した場合は、WHEP セッション URL にも Bearer トークンは送られます

## 認証仕様

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

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

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

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

## 認証成功時の払い出し

基本的には OBS Studio で指定した値がそのまま利用されますので、
以下の値以外は指定しないでください。

- client_id
- bundle_id
- event_metadata
- connection_lifetime
- playout_delay_min_delay
- playout_delay_max_delay
- turn_tcp_only- ただし 2026 年 6 月 現在では OBS Studio WHEP は TURN-TCP には対応していません
- turn_tls_only- ただし 2026 年 6 月 現在では OBS Studio WHEP は TURN-TLS には対応していません

## ウェブフック仕様

### whep

`true` が入ってきます。

### ignore_disconnect_websocket

`false` が入ってきます。

### metadata

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

```ini
whep_bearer_token_metadata_key = whep_bearer_token
```

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

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

### 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 Studio 側で指定した値を利用します。
OBS Studio では音声は Opus のみ、映像は H.264 が利用できます。

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

### simulcast

`false` が入ってきます。

### sora_client

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

```javascript
"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": "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](WHIP.html) と同様の挙動です。 [TURN の利用](WHIP.html#bc676e) をご確認ください。

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

[WHIP](WHIP.html) と同様の挙動です。 [クラスター利用時の挙動](WHIP.html#2e159a) をご確認ください。

## シーケンス図

### シングルノード

```mermaid
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>"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 終了
```