← Cloudflare Realtime / realtime / sfu / media-transport-adapters

WebSocket adaptér

Streamujte zvuk a video mezi stopami WebRTC a koncovými body WebSocket. Podporuje příjem zvuku ze zdrojů WebSocket a odesílání zvuku a videa WebRTC ke spotřebitelům WebSocket. Výstup videa (egress) je podporován ve formátu JPEG přibližně při 1 FPS.

• Služby AI s WebSocket API pro zpracování zvuku
• Vlastní pipeline pro zpracování zvuku
• Přemostění starších systémů
• Generování a příjem zvuku na straně serveru
• Pořizování snímků z videa a miniatury
• Příjem dat pro počítačové vidění (nízké 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"
		}
	]
}

• Kodek: Opus
• Vzorkovací frekvence: 48 kHz
• Kanály: Stereo

Média využívají Protocol Buffers. Audio používá PCM payloady, video používá JPEG payloady:

• 16-bit signed little-endian PCM
• vzorkovací frekvence 48 kHz
• Stereo (prokládaný levý/pravý kanál)
• Video: payload s obrázkem JPEG (jeden snímek na zprávu)

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

Režim příjmu (buffer): Pouze payload pole se používá a obsahuje části zvukových dat.

Režim streamování (egress):

• Pro zvukové snímky:
  • sequenceNumber: Přírůstkový čítač paketů
  • timestamp: Časové razítko pro synchronizaci
  • payload: Data jednotlivých snímků zvuku PCM
• Pro obrazové snímky (JPEG):
  • timestamp: Časové razítko pro synchronizaci
  • payload: Obrazová data JPEG (jeden snímek na zprávu)
  • Poznámka: sequenceNumber nemusí být u videosnímků nastaveno

• Podporované vstupní kodeky WebRTC: H264, H265, VP8, VP9
• Výstup přes WebSocket: obrázky JPEG přibližně 1 FPS

Připojuje se k vašemu koncovému bodu WebSocket:

1. Handshake při upgradu WebSocket
2. Zabezpečené připojení pro wss:// URL adresy
3. Streamování médií začíná

• Binární zprávy: Zvuková data PCM v částech
• Maximální velikost zprávy: 32 KB na zprávu WebSocket
• Důležité: Při rozdělování zvukových bufferů na části počítejte s režií serializace
• Odesílejte zvuk v malých a častých částech místo velkých dávek

• Binární zprávy: Jednotlivé snímky s metadaty (audio nebo video)
• Zvukové snímky obsahují:
  • Informace o časovém razítku
  • Pořadové číslo
  • Data zvukového rámce PCM
• Snímky videa obsahují:
  • Informace o časovém razítku
  • Obrazová data JPEG
  • Poznámka: pořadové číslo nemusí být u video snímků nastaveno
• Snímky se odesílají jednotlivě tak, jak přicházejí z WebRTC tracku
• Snímky videa se odesílají přibližně s frekvencí 1 FPS

1. Připojuje se ke koncovému bodu WebSocket
2. Streamování zvuku začíná
3. Streamování videa začíná (pokud je nakonfigurováno)
4. Při streamování z WebRTC do WebSocket krátce opakuje pokusy o připojení ke stejnému koncovému bodu po odpojení
5. Připojení se uzavře po ukončení, při chybě nebo po vyčerpání okna pro automatické opětovné připojení

Když použijete WebSocket adaptér v Režim streamování (egress) a odeslat tak živé audio nebo video z SFU do vlastního WebSocket endpointu (WebRTC → WebSocket), SFU se automaticky znovu připojí po krátkém odpojení nebo restartu koncového bodu.

SFU opakuje pokusy o připojení ke stejnému koncovému bodu WebSocket až po dobu 5 sekund. Žádné změny API nejsou nutné. Pokud koncový bod zůstane po uplynutí okna pro opětovné připojení nedostupný, adaptér se uzavře a vaše aplikace musí pro obnovení streamování vytvořit nový adaptér.

Automatické opětovné připojení používá vyrovnávací paměť s prioritou živého přenosu po dobu, kdy je koncový bod WebSocket dočasně nedostupný:

• Vyrovnávací paměť zvuku: SFU udržuje krátkou, omezenou frontu zvukových snímků. Pokud výpadek trvá déle, než tato fronta pokryje, starší zvuk může být zahozen, aby obnovení připojení zůstalo časově omezené.
• Vyrovnávání videa: SFU si ponechává jen poslední dostupný snímek JPEG. Při opětovném připojování novější snímky nahrazují starší, takže video pokračuje téměř v reálném čase místo přehrávání zastaralých snímků.
• Způsob doručování: Ukládání do bufferu snižuje ztrátu médií při krátkých výpadcích, ale nejde o mechanismus přehrávání záznamu a nezaručuje doručení bez výpadků ani přesně jednou.

Automatické opětovné připojení se použije pouze při použití Režim streamování (egress). Opakuje pokus pouze na stejném koncovém bodu a neposkytuje přepnutí na jiné koncové body.

Aktuálně je ve fázi beta a používání je zdarma.

Po dosažení obecné dostupnosti se bude fakturace řídit standardním ceníkem Cloudflare Realtime ve výši $0.05 za GB odchozích dat. Poplatky se účtují pouze za provoz směřující z Cloudflare k WebSocket koncovým bodům. Provoz přijímaný z WebSocket koncových bodů do Cloudflare se neúčtuje.

Využití se počítá do vaší bezplatné úrovně Cloudflare Realtime v objemu 1,000 GB.

• Zavření již zavřené instance vrátí úspěch
• Zavřít při ukončení relace
• Při použití Režim streamování (egress), ošetřete uzavření adaptéru po 5sekundovém okno automatického opětovného připojení je vyčerpán.
• Při příjmu dat z WebSocket do WebRTC implementujte ve svém WebSocket klientovi logiku pro opětovné připojení pro případ výpadku spojení.
• Nastavte koncový bod WebSocket tak, aby byl odolný vůči restartu a dokázal přijímat opětovná připojení na stejnou adresu URL i během krátkých restartů.

• Nasazení WebSocket endpointů blízko Cloudflare edge
• Použijte vhodné velikosti bufferu
• Sledování kvality připojení

• Zabezpečení koncových bodů WebSocket ověřováním
• Použijte wss:// pro produkční prostředí
• Implementujte rate limiting

• Payloady WebSocket: PCM (zvuk) pro příjem a stream; JPEG (video) pro stream
• Stav beta verze: API se může v budoucích verzích změnit
• Podpora videa: Pouze egress (JPEG)
• Snímková frekvence videa: Přibližně 1 FPS (beta, nelze konfigurovat)
• Opětovná připojení při streamování: Při použití Režim streamování (egress), SFU automaticky opakuje pokus na stejném koncovém bodu WebSocket pouze u krátkých výpadků. Na alternativní koncové body nepřepíná.
• Obnovení s nejlepším možným úsilím: Krátká opětovná připojení snižují ztrátu médií, ale nezaručují doručení bez výpadků ani přesně jednou.
• Chování při opětovném připojení videa: Video pokračuje od posledního dostupného snímku JPEG, nikoli přehráváním starších snímků.
• Jednosměrný tok: Každá instance obsluhuje jeden směr

• Zvuk (PCM přes WebSocket): Cloudflare Realtime Examples, ai-tts-stt ↗
• Video (JPEG egress): Cloudflare Realtime Examples, video-to-jpeg ↗

1. Nahraďte vlastní signalizaci voláními adaptérového API
2. Aktualizace endpointů WebSocket pro zpracování formátu PCM
3. Implementujte správu životního cyklu adaptéru
4. Odebrání vlastní konfigurace STUN/TURN

Otázka: Lze stejný adaptér použít pro obousměrný zvuk? Odpověď: Ne, každá instance je jednosměrná. Pro odesílání a příjem vytvořte samostatné adaptéry.

Otázka: Co se stane, když spojení WebSocket vypadne?

Odpověď: Při použití Režim streamování (egress), SFU automaticky opakuje pokus na stejném koncovém bodu WebSocket až po dobu 5 sekund. Pokud se koncový bod v tomto intervalu obnoví, streamování automaticky pokračuje.

Zvuk využívá krátkou omezenou frontu, která snižuje slyšitelné výpadky při krátkých přerušeních. Video pokračuje od posledního dostupného snímku JPEG, místo aby přehrávalo starší snímky.

Pokud koncový bod zůstane nedostupný i po 5sekundovém okno automatického opětovného připojení, adaptér se uzavře a je nutné jej znovu vytvořit.

Při příjmu dat z WebSocket do WebRTC by se měl váš WebSocket klient podle potřeby znovu připojit a znovu vytvořit adaptér.

Otázka: Existuje limit na počet současně běžících adaptérů? Odpověď: Limity odpovídají standardním kvótám Cloudflare Realtime. V případě specifických požadavků kontaktujte podporu.

Otázka: Lze po vytvoření adaptéru změnit formát zvuku? Odpověď: Ne, formát zvuku je pevně daný v okamžiku vytvoření. Pro jiné formáty vytvořte nový adaptér.