WebSocket アダプター

WebRTC トラックと WebSocket エンドポイントの間で音声とビデオをストリーミングします。WebSocket ソースからの音声取り込みと、WebRTC の音声・ビデオの WebSocket コンシューマーへの送信に対応します。ビデオのエグレスは、約 1 FPS の JPEG です。

• 音声処理向け WebSocket API を持つ AI サービス
• カスタムの音声処理パイプライン
• レガシーシステムとのブリッジ
• サーバー側での音声生成と消費
• ビデオのスナップショットとサムネイル
• コンピュータービジョン向けの取り込み（低 FPS）

graph LR
    A[External System] -->|Audio Data| B[WebSocket Endpoint]
    B -->|Adapter| C[Realtime SFU]
    C -->|New Session| D[WebRTC Track]
    D -->|WebRTC| E[WebRTC Clients]

graph LR
    A[WebRTC Source] -->|WebRTC| B[Realtime SFU Session]
    B -->|Adapter| C[WebSocket Endpoint]
    C -->|Media Data| D[External System]

POST /v1/apps/{appId}/adapters/websocket/new

{
  "tracks": [
    {
      "location": "local",
      "trackName": "string",
      "endpoint": "wss://...",
      "inputCodec": "pcm",
      "mode": "buffer"
    }
  ]
}

{
  "tracks": [
    {
      "trackName": "string",
      "adapterId": "string",
      "sessionId": "string",    // New session ID generated
      "endpoint": "string"      // Echo of the requested endpoint
    }
  ]
}

{
  "tracks": [
    {
      "location": "remote",
      "sessionId": "string",
      "trackName": "string",
      "endpoint": "wss://...",
      "outputCodec": "pcm"
    }
  ]
}

{
  "tracks": [
    {
      "trackName": "string",
      "adapterId": "string",
      "sessionId": "string",    // Same as request sessionId
      "endpoint": "string"      // Echo of the requested endpoint
    }
  ]
}

POST /v1/apps/{appId}/adapters/websocket/close

{
	"tracks": [
		{
			"adapterId": "string"
		}
	]
}

• コーデック: Opus
• サンプルレート: 48 kHz
• チャンネル: ステレオ

メディアは Protocol Buffers を使います。音声は PCM ペイロード、ビデオは JPEG ペイロードです。

• 16 ビット符号付きリトルエンディアン PCM
• サンプルレート 48 kHz
• ステレオ（左右インターリーブ）
• ビデオ: JPEG 画像ペイロード（1 メッセージあたり 1 フレーム）

message Packet {
    uint32 sequenceNumber = 1;  // Used in Stream mode only
    uint32 timestamp = 2;       // Used in Stream mode only
    bytes payload = 5;          // Media data
}

取り込みモード（buffer）: payload フィールドのみを使い、音声データのチャンクを入れます。

ストリームモード（エグレス）:

• 音声フレームの場合:
  • sequenceNumber: 増分するパケットカウンター
  • timestamp: 同期用タイムスタンプ
  • payload: 個別の PCM 音声フレームデータ
• ビデオフレーム（JPEG）の場合:
  • timestamp: 同期用タイムスタンプ
  • payload: JPEG 画像データ（1 メッセージあたり 1 フレーム）
  • 注: ビデオフレームでは sequenceNumber が未設定の場合があります

• 対応する WebRTC 入力コーデック: H264、H265、VP8、VP9
• WebSocket 経由の出力: 約 1 FPS の JPEG 画像

次の手順で WebSocket エンドポイントに接続します。

1. WebSocket アップグレードのハンドシェイク
2. wss:// URL の場合はセキュア接続
3. メディアストリーミングを開始します

• バイナリメッセージ: チャンク化した PCM 音声データ
• 最大メッセージサイズ: WebSocket メッセージあたり 32 KB
• 重要: 音声バッファーをチャンク化するときは、シリアライズのオーバーヘッドを見込んでください
• 大きなバッチではなく、小さく頻繁なチャンクで音声を送ります

• バイナリメッセージ: メタデータ付きの個別フレーム（音声またはビデオ）
• 音声フレームに含まれるもの:
  • タイムスタンプ情報
  • シーケンス番号
  • PCM 音声フレームデータ
• ビデオフレームに含まれるもの:
  • タイムスタンプ情報
  • JPEG 画像データ
  • 注: ビデオフレームではシーケンス番号が未設定の場合があります
• フレームは WebRTC トラックから到着し次第、個別に送信されます
• ビデオフレームは約 1 FPS で送出されます

1. WebSocket エンドポイントに接続します
2. 音声ストリーミングを開始します
3. 設定されている場合はビデオストリーミングを開始します
4. WebRTC から WebSocket へのストリーミングでは、切断後に同じエンドポイントへ短時間再試行します
5. クローズ時、エラー時、または自動再接続ウィンドウの経過後に接続を閉じます

ストリームモード（エグレス） の WebSocket アダプターで、SFU から独自の WebSocket エンドポイントへライブの音声またはビデオを送る場合（WebRTC → WebSocket）、エンドポイントの短い切断や再起動後に SFU が自動で再接続します。

SFU は同じ WebSocket エンドポイントへ最大 5 秒間再試行します。API の変更は不要です。再接続ウィンドウ内にエンドポイントが復帰しない場合、アダプターは閉じます。ストリーミングを再開するには、アプリケーション側で新しいアダプターを作成してください。

自動再接続では、WebSocket エンドポイントが一時的に使えない間、ライブ優先のバッファリングを使います。

• 音声のバッファリング: SFU は短く上限のある音声フレームのバックログを保持します。中断がバックログで賄える時間を超えると、再接続の回復が無制限にならないよう、古い音声が破棄される場合があります。
• ビデオのバッファリング: SFU は利用可能な最新の JPEG フレームだけを保持します。再接続中は新しいフレームが古いフレームを置き換えるため、古いフレームを再生せず、ほぼライブの位置から再開します。
• 配信の挙動: バッファリングは短い中断中のメディア損失を減らしますが、リプレイ機構ではなく、途切れなしや exactly-once 配信を保証しません。

自動再接続は ストリームモード（エグレス） でのみ適用されます。同じエンドポイントだけを再試行し、複数エンドポイントへのフェイルオーバーはありません。

現在はベータで、無料で利用できます。

一般提供後の課金は、Cloudflare Realtime の標準料金（エグレス 1 GB あたり $0.05）に従います。課金対象は、Cloudflare から WebSocket エンドポイントへ向かうトラフィックだけです。WebSocket エンドポイントから Cloudflare へ取り込まれるトラフィックは課金されません。

利用量は、Cloudflare Realtime の無料枠 1,000 GB に含まれます。

• すでに閉じたインスタンスを閉じても成功を返します
• セッション終了時に閉じてください
• ストリームモード（エグレス） では、5 秒の 自動再接続ウィンドウ が切れたあとのアダプター閉鎖に対応してください。
• WebSocket から WebRTC へ取り込む場合は、接続が切れたときの再接続ロジックを WebSocket クライアントに実装してください。
• WebSocket エンドポイントは再起動に耐えるようにし、短い再起動中も同じ URL への再接続を受け付けられるようにしてください。

• WebSocket エンドポイントは Cloudflare エッジの近くに配置します
• 適切なバッファーサイズを使います
• 接続品質を監視します

• WebSocket エンドポイントは認証で保護します
• 本番では wss:// を使います
• レート制限を実装します

• WebSocket ペイロード: 取り込みとストリームの音声は PCM。ストリームのビデオは JPEG
• ベータ: 今後のリリースで API が変わる場合があります
• ビデオ対応: エグレスのみ（JPEG）
• ビデオフレームレート: 約 1 FPS（ベータ。設定不可）
• ストリーミングの再接続: ストリームモード（エグレス） では、SFU は短い切断に対して同じ WebSocket エンドポイントだけを自動再試行します。別エンドポイントへのフェイルオーバーはありません。
• ベストエフォートの回復: 短い再接続でメディア損失は減りますが、途切れなしや exactly-once 配信は保証しません。
• ビデオ再接続の挙動: ビデオは古いフレームを再生せず、利用可能な最新の JPEG フレームから再開します。
• 単方向: 各インスタンスは一方向だけを扱います

• 音声（WebSocket 上の PCM）: Cloudflare Realtime Examples – ai-tts-stt ↗
• ビデオ（JPEG エグレス）: Cloudflare Realtime Examples – video-to-jpeg ↗

1. カスタムシグナリングをアダプター API の呼び出しに置き換えます
2. WebSocket エンドポイントを PCM 形式に対応させます
3. アダプターのライフサイクル管理を実装します
4. カスタムの STUN/TURN 設定を削除します

Q: 双方向音声に同じアダプターを使えますか？ A: いいえ。各インスタンスは単方向です。送信と受信で別々のアダプターを作成してください。

Q: WebSocket 接続が切れたらどうなりますか？

A: ストリームモード（エグレス） では、SFU は同じ WebSocket エンドポイントへ最大 5 秒間自動で再試行します。そのウィンドウ内にエンドポイントが復帰すれば、ストリーミングは自動で再開します。

音声は短い中断中の聴感上の損失を減らすため、短く上限のあるバックログを使います。ビデオは古いフレームを再生せず、利用可能な最新の JPEG フレームから再開します。

エンドポイントが 5 秒の 自動再接続ウィンドウ を過ぎても使えない場合、アダプターは閉じます。再開するには再作成が必要です。

WebSocket から WebRTC へ取り込む場合は、WebSocket クライアント側で再接続し、必要に応じてアダプターを再作成してください。

Q: 同時アダプター数に上限はありますか？ A: 上限は Cloudflare Realtime の標準クォータに従います。個別の要件はサポートに問い合わせてください。

Q: アダプター作成後に音声形式を変更できますか？ A: いいえ。音声形式は作成時に固定されます。別の形式が必要な場合は新しいアダプターを作成してください。