WebRTC com WARP

Use o WebRTC Abridged Roundtrip Protocol (WARP) para reduzir o tempo necessário para iniciar uma sessão de voz com o GPT-Live ou a Realtime API. O WARP combina três otimizações de transporte (DTLS 1.3, SPED e SNAP) com um canal de dados pré-negociado para estabelecer a conexão com menos idas e voltas pela rede.

Você também pode usar essas otimizações individualmente. Ative os recursos compatíveis com seu cliente para reduzir a latência da conexão, mesmo quando o WARP completo estiver indisponível. Com todos os recursos ativos, a conexão usa o handshake completo do WARP.

WARP, SPED e SNAP são especificações preliminares da IETF (Internet-Drafts). Tanto as especificações quanto o suporte nos clientes podem mudar.

O GPT-Live e a Realtime API usam as mesmas otimizações de WebRTC. Configure essas otimizações no navegador ou no cliente nativo, independentemente da linguagem do servidor da aplicação. As APIs diferem na forma de enviar o ID negociado do canal de dados ao criar uma sessão.

Ative o WARP em um cliente nativo

Para usar o WARP completo, ative as otimizações de transporte por meio de testes de campo e pré-negocie um canal de dados. Você também pode executar cada etapa de forma independente.

Ative os testes de campo

As versões atuais da libwebrtc incluem as otimizações do WARP. Se o cliente nativo usar uma compilação compatível da libwebrtc, ative os seguintes testes de campo:

WebRTC-ForceDtls13/Enabled/
WebRTC-Sctp-Snap/Enabled/
WebRTC-IceHandshakeDtls/Enabled/

Esses testes ativam DTLS 1.3, SNAP e SPED, respectivamente. Inclua apenas os testes correspondentes às otimizações que você quer ativar.

Algumas integrações exigem que você combine os testes de campo em uma única string:

WebRTC-ForceDtls13/Enabled/WebRTC-Sctp-Snap/Enabled/WebRTC-IceHandshakeDtls/Enabled/

Inicialize os testes de campo antes de criar a fábrica de conexões entre pares. Alguns wrappers oferecem opções de configuração mais restritas. Por exemplo, na versão 0.3.51 do webrtc-sys, você ativa o SPED na fábrica de conexões entre pares e o SNAP na configuração da conexão:

1
2
3
4
5
6
7
8
9
10
11
12
13use webrtc_sys::peer_connection::ffi::{
    ContinualGatheringPolicy, IceTransportsType, RtcConfiguration,
};
use webrtc_sys::peer_connection_factory::ffi::create_peer_connection_factory_with_options;

// The wrapper enables SPED on the factory; SNAP is an immutable connection option.
let factory = create_peer_connection_factory_with_options(false, true);
let configuration = RtcConfiguration {
    ice_servers: vec![],
    continual_gathering_policy: ContinualGatheringPolicy::GatherOnce,
    ice_transport_type: IceTransportsType::All,
    enable_sctp_snap: true,
};

Se você usar um SDK que encapsula a libwebrtc, como um SDK nativo do LiveKit, passe a mesma string de testes de campo nas opções de configuração ou inicialização do WebRTC oferecidas pelo SDK. Se o SDK não expuser os testes de campo, inicialize a instância da libwebrtc antes que o SDK crie a fábrica de conexões entre pares ou atualize o wrapper para uma versão que ofereça essa configuração.

Pré-negocie um canal de dados

Use o mesmo ID de canal no cliente e na solicitação de sinalização. As etapas a seguir se aplicam tanto a clientes nativos quanto a navegadores, mesmo que você ainda não tenha ativado as três otimizações de transporte:

1. Crie o canal de dados antes de gerar a oferta SDP. Defina negotiated como true e atribua a id um ID de canal disponível, como 4. O rótulo do canal pode ser qualquer string.
2. Envie a oferta SDP e o ID do canal ao servidor da aplicação e siga as etapas abaixo para a API que você usa.

Conecte-se ao GPT-Live

Comece pelo guia de início rápido do GPT-Live com WebRTC. Configure o servidor para incluir o ID do canal no campo transport.dcid do corpo JSON de POST /v1/live/sessions. Mantenha transport.type definido como webrtc e transport.sdp com a oferta SDP do cliente.

Para um canal criado com id: 4, envie o corpo JSON a seguir para POST /v1/live/sessions. Substitua <SDP offer> pela oferta SDP gerada pelo cliente:

12345678910{
  "session": {
    "model": "gpt-live-1"
  },
  "transport": {
    "type": "webrtc",
    "sdp": "<SDP offer>",
    "dcid": 4
  }
}

O campo transport.dcid ativa o canal pré-negociado. Omita esse campo ao usar um canal de dados padrão. Não envie dcid como parâmetro de consulta na URL. O GPT-Live rejeita parâmetros de consulta, ao contrário do fluxo da Realtime API descrito abaixo.

Aplique o valor retornado em transport.sdp como resposta remota e aguarde o evento session.started antes de enviar comandos da aplicação. A solicitação HTTP inicia a sessão. Não envie session.start pelo canal de dados.

Conecte-se à Realtime API

Use o fluxo unificado de conexão WebRTC. Configure o servidor para incluir o ID do canal no parâmetro de consulta dcid ao chamar /v1/realtime/calls. Para um canal criado com id: 4, use POST /v1/realtime/calls?dcid=4 e mantenha o mesmo SDP e a mesma configuração de sessão no corpo multipart da solicitação.

Aplique o SDP retornado como resposta remota. Omita dcid ao usar um canal de dados padrão. O exemplo completo abaixo mostra as duas configurações.

Ative o WARP em um navegador

O Chrome, o Edge e outros navegadores baseados no Chromium incluem a libwebrtc, mas uma página da Web não pode configurar os testes de campo dessa biblioteca. Ative os recursos de transporte disponíveis no navegador. Em seguida, pré-negocie um canal de dados usando a mesma sinalização específica da API que você usaria em um cliente nativo.

Ative os recursos disponíveis e os testes de origem

Um teste de origem ativa um recurso experimental do navegador para um site cadastrado. Verifique a disponibilidade de cada recurso do WARP:

• DTLS 1.3: o Chrome oferece suporte a DTLS 1.3 sem exigir um teste de origem.
• SNAP: as versões 151 a 156 do Chrome oferecem suporte ao SNAP por meio de um teste de origem. No Edge, verifique se há um teste de origem do SNAP disponível para sua versão e cadastre-se para receber um token emitido pelo Edge.
• SPED: nenhum navegador oferece um teste de origem para o SPED. Consulte esta página mais tarde para verificar se já há suporte. Para usar o WARP completo, o navegador precisa ativar o SPED por padrão, ou você precisa ter controle sobre os parâmetros de inicialização do navegador e ativar os testes de campo necessários.

Ativar o teste de origem do SNAP não ativa o SPED nem o WARP completo. Se o navegador não disponibilizar o SPED, você ainda poderá usar o DTLS 1.3 e o teste de origem do SNAP para aproveitar os benefícios de cada uma dessas otimizações.

Consulte os testes de origem do seu navegador:

• Testes de origem do Google Chrome
• Testes de origem do Microsoft Edge

Para ativar o teste de origem do SNAP:

1. Abra a página de testes de origem do navegador e localize WebRTC Data Channel: SCTP Negotiation Acceleration Protocol (SNAP).

2. Selecione Register e informe a origem da aplicação, como https://example.com.

3. Adicione o token emitido ao <head> da página, antes do script que cria RTCPeerConnection:

   <meta http-equiv="origin-trial" content="YOUR_ORIGIN_TRIAL_TOKEN" />

4. Recarregue a página. No Chrome, abra o DevTools, selecione Aplicativo e confirme que WebRtcSctpSnap aparece em Testes de origem.

Você também pode enviar o token em um cabeçalho da resposta HTTP:

Origin-Trial: YOUR_ORIGIN_TRIAL_TOKEN

Pré-negocie o canal de dados do navegador

Siga as etapas de configuração do canal de dados descritas acima e envie o ID correspondente conforme as instruções do GPT-Live ou da Realtime API. A pré-negociação do canal dispensa o teste de origem e pode reduzir o tempo de espera pelos eventos do servidor mesmo quando o WARP completo estiver indisponível.

Conecte-se pela interface unificada

Use o fluxo unificado de conexão WebRTC para estabelecer conexões mais rapidamente com a Realtime API. O navegador envia a oferta SDP e o ID negociado do canal de dados ao servidor da aplicação. O servidor encaminha o mesmo ID no parâmetro de consulta dcid ao chamar /v1/realtime/calls.

Configure o servidor da aplicação

Este servidor de aplicação oferece suporte ao WebRTC padrão e ao WARP. O comentário marcado com WARP only indica onde o servidor encaminha o parâmetro dcid exigido pelo WARP:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51import express from "express";

const app = express();

// Parse raw SDP payloads posted from the browser
app.use(express.text({ type: ["application/sdp", "text/plain"] }));

const sessionConfig = JSON.stringify({
  type: "realtime",
  model: "gpt-realtime-2.1",
  audio: { output: { voice: "marin" } },
});

// An endpoint which creates a Realtime API session.
app.post("/session", async (req, res) => {
  const fd = new FormData();
  fd.set("sdp", req.body);
  fd.set("session", sessionConfig);

  const endpoint = new URL("https://api.openai.com/v1/realtime/calls");

  // WARP only: forward the negotiated data-channel ID to the Realtime API.
  if (typeof req.query.dcid === "string") {
    endpoint.searchParams.set("dcid", req.query.dcid);
  }

  try {
    const r = await fetch(endpoint, {
      method: "POST",
      headers: {
        Authorization: `Bearer ${process.env.OPENAI_API_KEY}`,
        "OpenAI-Safety-Identifier": "hashed-user-id",
      },
      body: fd,
    });
    // Send back the SDP we received from the OpenAI REST API
    const sdp = await r.text();
    res.set(
      "Content-Type",
      r.ok ? "application/sdp" : (r.headers.get("Content-Type") ?? "text/plain")
    );
    const location = r.headers.get("Location");
    if (location) res.set("Location", location);
    res.status(r.status).send(sdp);
  } catch (error) {
    console.error("Session creation error:", error);
    res.status(500).json({ error: "Failed to create session" });
  }
});

app.listen(3000);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47func handler(client openai.Client) http.Handler {
	mux := http.NewServeMux()
	mux.HandleFunc("POST /session", func(w http.ResponseWriter, r *http.Request) {
		offer, err := io.ReadAll(http.MaxBytesReader(w, r.Body, 64*1024))
		if err != nil || strings.TrimSpace(string(offer)) == "" {
			http.Error(w, "A valid SDP offer is required", http.StatusBadRequest)
			return
		}
		opts := []option.RequestOption{
			option.WithHeader("OpenAI-Safety-Identifier", "hashed-user-id"),
		}
		// Forward the browser's negotiated data-channel ID when WARP is enabled.
		if dcid := r.URL.Query().Get("dcid"); dcid != "" {
			id, err := strconv.Atoi(dcid)
			if err != nil || id < 0 || id > 65534 {
				http.Error(w, "Invalid data-channel ID", 400)
				return
			}
			opts = append(opts, option.WithQuery("dcid", dcid))
		}
		response, err := client.Realtime.Calls.New(r.Context(), realtime.CallNewParams{
			Sdp: string(offer),
			Session: realtime.RealtimeSessionCreateRequestParam{
				Model: "gpt-realtime-2.1",
				Audio: realtime.RealtimeAudioConfigParam{
					Output: realtime.RealtimeAudioConfigOutputParam{
						Voice: realtime.RealtimeAudioConfigOutputVoiceUnionParam{
							OfString: openai.String("marin"),
						},
					},
				},
			},
		}, opts...)
		if err != nil {
			http.Error(w, "Could not create Realtime call", http.StatusBadGateway)
			return
		}
		defer response.Body.Close()
		w.Header().Set("Content-Type", "application/sdp")
		w.Header().Set("Location", response.Header.Get("Location"))
		w.WriteHeader(response.StatusCode)
		if _, err := io.Copy(w, response.Body); err != nil {
			log.Print("Could not write SDP answer")
		}
	})
	return mux
}

Conecte-se pelo navegador

Depois de ativar as otimizações disponíveis no navegador, defina useWarp como true. Escolha um ID de canal de dados disponível e passe o mesmo ID ao servidor. Os comentários marcados com WARP only indicam a configuração e a sinalização que o WebRTC padrão dispensa:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51// WARP only: set to true after enabling the supported WARP optimizations.
const useWarp = false;

// WARP only: choose any available data-channel ID.
const dataChannelId = 4;

// Create a peer connection
const pc = new RTCPeerConnection();

// Set up to play remote audio from the model
audioElement.current = document.createElement("audio");
audioElement.current.autoplay = true;
pc.ontrack = (e) => (audioElement.current.srcObject = e.streams[0]);

// Add local audio track for microphone input in the browser
const ms = await navigator.mediaDevices.getUserMedia({
  audio: true,
});
pc.addTrack(ms.getTracks()[0]);

// Set up the event channel using any channel label.
// WARP only: pre-negotiate the channel using the selected data-channel ID.
const dc = pc.createDataChannel(
  "events",
  useWarp ? { negotiated: true, id: dataChannelId } : undefined,
);

// Start the session using the Session Description Protocol (SDP)
const offer = await pc.createOffer();
await pc.setLocalDescription(offer);

const endpoint = new URL("/session", window.location.origin);

// WARP only: include the matching data-channel ID in the session request.
if (useWarp) {
  endpoint.searchParams.set("dcid", String(dataChannelId));
}

const sdpResponse = await fetch(endpoint, {
  method: "POST",
  body: offer.sdp,
  headers: {
    "Content-Type": "application/sdp",
  },
});

const answer = {
  type: "answer",
  sdp: await sdpResponse.text(),
};
await pc.setRemoteDescription(answer);

Use um cliente sem suporte ao WARP

Se o cliente WebRTC não usar a libwebrtc, adicione à sua pilha WebRTC as otimizações de transporte compatíveis com o WARP ou use outra abordagem compatível com essa pilha. Consulte as especificações de WARP, SPED, SNAP, DTLS 1.3 e estabelecimento de canais de dados.

Se essas otimizações estiverem indisponíveis, use o fluxo WebRTC padrão do GPT-Live ou a interface unificada da Realtime API.