WebRTC con WARP

Usa WebRTC Abridged Roundtrip Protocol (WARP) para reducir el tiempo que tarda en iniciarse una sesión de voz con GPT-Live o la Realtime API. WARP combina tres optimizaciones de transporte (DTLS 1.3, SPED y SNAP) con un canal de datos negociado de antemano para establecer la conexión con menos intercambios de ida y vuelta por la red.

También puedes usar estas optimizaciones por separado. Habilita las funciones que admite tu cliente para reducir la latencia de conexión, incluso si no puedes usar WARP en su totalidad. Al usar todas las funciones juntas, se realiza la negociación completa de WARP.

WARP, SPED y SNAP son borradores de especificaciones del IETF, por lo que tanto las especificaciones como la compatibilidad de los clientes pueden cambiar.

GPT-Live y la Realtime API usan las mismas optimizaciones de WebRTC. Configúralas en tu navegador o cliente nativo, independientemente del lenguaje que use tu servidor de aplicaciones. La forma de enviar el ID negociado del canal de datos al crear una sesión varía según la API.

Habilitar WARP en un cliente nativo

Para usar WARP en su totalidad, habilita las optimizaciones de transporte mediante pruebas de campo y negocia de antemano un canal de datos. También puedes realizar cualquiera de los dos pasos por separado.

Habilitar las pruebas de campo

Las versiones actuales de libwebrtc incluyen las optimizaciones de WARP. Si tu cliente nativo usa una compilación compatible de libwebrtc, habilita las siguientes pruebas de campo:

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

Estas pruebas habilitan DTLS 1.3, SNAP y SPED, respectivamente. Incluye solo las pruebas correspondientes a las optimizaciones que quieras habilitar.

Algunas integraciones requieren que combines las pruebas de campo en una sola cadena:

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

Inicializa las pruebas de campo antes de crear la fábrica de conexiones entre pares. Las bibliotecas envolventes pueden ofrecer opciones de configuración más específicas. Por ejemplo, webrtc-sys 0.3.51 habilita SPED en la fábrica y SNAP mediante la configuración de la conexión:

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,
};

Si usas un SDK que encapsula libwebrtc, como un SDK nativo de LiveKit, pasa la misma cadena de pruebas de campo mediante la configuración de WebRTC o las opciones de inicialización del SDK. Si el SDK no da acceso a las pruebas de campo, inicializa la instancia subyacente de libwebrtc antes de que el SDK cree su fábrica de conexiones entre pares, o cambia a una versión de la biblioteca envolvente que permita configurarlas.

Negociar de antemano un canal de datos

Usa el mismo ID de canal en el cliente y en la solicitud de señalización. Estos pasos sirven tanto para clientes nativos como para navegadores, incluso si no habilitaste las tres optimizaciones de transporte:

1. Crea el canal de datos antes de generar la oferta SDP. Establece negotiated en true y asigna a id un ID de canal disponible, como 4. La etiqueta del canal puede ser cualquier cadena.
2. Envía la oferta SDP y el ID del canal a tu servidor de aplicaciones. Luego sigue los pasos que se indican a continuación para tu API.

Conectarse a GPT-Live

Empieza con la guía de inicio rápido de WebRTC para GPT-Live. Configura tu servidor para que incluya el ID del canal en transport.dcid dentro del cuerpo JSON de POST /v1/live/sessions. Mantén transport.type en webrtc y conserva la oferta SDP del cliente como valor de transport.sdp.

Para un canal creado con id: 4, envía este cuerpo JSON a POST /v1/live/sessions. Reemplaza <SDP offer> por la oferta SDP que generó tu cliente:

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

El campo transport.dcid habilita el canal negociado de antemano. Omítelo si usas un canal de datos estándar. No envíes dcid como parámetro de consulta en la URL. GPT-Live rechaza los parámetros de consulta, a diferencia del flujo de la Realtime API que se describe a continuación.

Aplica el valor recibido de transport.sdp como respuesta SDP remota y espera a recibir session.started antes de enviar comandos de la aplicación. La solicitud HTTP inicia la sesión. No envíes session.start por el canal de datos.

Conectarse a la Realtime API

Usa el flujo de conexión unificado de WebRTC. Configura tu servidor para que incluya el ID del canal en el parámetro de consulta dcid al llamar a /v1/realtime/calls. Para un canal creado con id: 4, usa POST /v1/realtime/calls?dcid=4 y conserva el mismo SDP y la misma configuración de sesión en el cuerpo multiparte de la solicitud.

Aplica el SDP recibido como respuesta remota. Omite dcid si usas un canal de datos estándar. El ejemplo completo que aparece más adelante muestra ambas configuraciones.

Habilitar WARP en un navegador

Chrome, Edge y otros navegadores basados en Chromium incluyen libwebrtc, pero las páginas web no pueden configurar sus pruebas de campo. Habilita las funciones de transporte disponibles en tu navegador y luego negocia de antemano un canal de datos con la misma señalización que usarías en un cliente nativo para esa API.

Habilitar las funciones disponibles y las pruebas de origen

Una prueba de origen habilita una función experimental del navegador para un sitio web registrado. Comprueba la disponibilidad de cada función de WARP:

• DTLS 1.3: Chrome admite DTLS 1.3 sin necesidad de una prueba de origen.
• SNAP: las versiones 151 a 156 de Chrome admiten SNAP mediante una prueba de origen. Si usas Edge, comprueba si hay una prueba de origen de SNAP disponible para tu versión y regístrate para obtener un token emitido por Edge.
• SPED: ningún navegador ofrece una prueba de origen para SPED. Vuelve a consultar más adelante si ya se admite SPED. Para usar WARP en su totalidad, el navegador debe tener SPED habilitado de forma predeterminada, o bien debes tener control sobre sus parámetros de inicio y habilitar las pruebas de campo necesarias por tu cuenta.

Habilitar la prueba de origen de SNAP no habilita SPED ni la negociación completa de WARP. Si tu navegador no da acceso a SPED, puedes usar DTLS 1.3 y la prueba de origen de SNAP para aprovechar esas dos optimizaciones.

Consulta las pruebas de origen de tu navegador:

• Pruebas de origen de Google Chrome
• Pruebas de origen de Microsoft Edge

Para habilitar la prueba de origen de SNAP:

1. Abre la página de pruebas de origen de tu navegador y busca WebRTC Data Channel: SCTP Negotiation Acceleration Protocol (SNAP).

2. Selecciona Register e ingresa el origen de tu aplicación, por ejemplo, https://example.com.

3. Agrega el token que recibiste al <head> de tu página, antes del script que crea RTCPeerConnection:

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

4. Vuelve a cargar la página. En Chrome, abre DevTools, selecciona Aplicación y comprueba que WebRtcSctpSnap aparezca en Pruebas de origen.

También puedes enviar el token en un encabezado de respuesta HTTP:

Origin-Trial: YOUR_ORIGIN_TRIAL_TOKEN

Negociar de antemano el canal de datos del navegador

Sigue los pasos anteriores para configurar el canal de datos y luego envía el ID correspondiente según las instrucciones para GPT-Live o la Realtime API. Negociar el canal de antemano no requiere una prueba de origen y puede reducir el tiempo de espera para recibir eventos del servidor, incluso si no puedes usar WARP en su totalidad.

Conectarse con la interfaz unificada

Usa el flujo de conexión unificado de WebRTC para conectarte más rápido a la Realtime API. El navegador envía su oferta SDP y el ID negociado del canal de datos a tu servidor de aplicaciones. Tu servidor reenvía ese mismo ID en el parámetro de consulta dcid al llamar a /v1/realtime/calls.

Configurar tu servidor de aplicaciones

Este servidor de aplicaciones admite WebRTC estándar y WARP. El comentario marcado con WARP only indica dónde se reenvía dcid, un paso necesario para 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
}

Conectarse desde el navegador

Después de habilitar las optimizaciones disponibles en tu navegador, establece useWarp en true. Elige cualquier ID de canal de datos disponible y pasa ese mismo ID al servidor. Los comentarios marcados con WARP only indican qué pasos de configuración y señalización puedes omitir si usas WebRTC estándar:

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);

Usar un cliente sin compatibilidad con WARP

Si tu cliente WebRTC no usa libwebrtc, agrega las optimizaciones de transporte compatibles con WARP a tu pila de WebRTC o usa otro método que admita esa pila. Las especificaciones pertinentes son WARP, SPED, SNAP, DTLS 1.3 y la de establecimiento de canales de datos.

Si esas optimizaciones no están disponibles, usa el flujo estándar de WebRTC para GPT-Live o la interfaz unificada de la Realtime API.