WebRTC avec WARP

Utilisez le protocole WebRTC Abridged Roundtrip Protocol (WARP) pour démarrer plus rapidement une session vocale avec GPT-Live ou la Realtime API. WARP associe trois optimisations du transport (DTLS 1.3, SPED et SNAP) à un canal de données négocié à l’avance pour établir la connexion en moins d’allers-retours sur le réseau.

Vous pouvez aussi utiliser ces optimisations séparément. Activez les fonctionnalités prises en charge par votre client pour réduire la latence de connexion, même si vous ne disposez pas de toutes les fonctionnalités de WARP. En les activant toutes, vous bénéficiez de la procédure complète d’établissement de connexion WARP.

WARP, SPED et SNAP sont des projets de spécifications de l’IETF (Internet-Drafts). Leurs spécifications et leur prise en charge par les clients peuvent donc évoluer.

GPT-Live et la Realtime API utilisent les mêmes optimisations WebRTC. Configurez-les dans votre navigateur ou votre client natif, quel que soit le langage de votre serveur d’application. La façon de transmettre l’identifiant négocié du canal de données à la création d’une session dépend de l’API.

Activer WARP dans un client natif

Pour activer toutes les fonctionnalités de WARP, activez les optimisations du transport à l’aide des paramètres expérimentaux de WebRTC (field trials) et négociez un canal de données à l’avance. Vous pouvez aussi effectuer chacune de ces étapes indépendamment.

Activer les paramètres expérimentaux

Les versions actuelles de libwebrtc intègrent les optimisations WARP. Si votre client natif utilise une version compatible de libwebrtc, activez les paramètres expérimentaux suivants :

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

Ces paramètres activent respectivement DTLS 1.3, SNAP et SPED. Incluez uniquement les paramètres correspondant aux optimisations que vous souhaitez activer.

Certaines intégrations exigent que vous regroupiez ces paramètres dans une seule chaîne :

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

Initialisez les paramètres expérimentaux avant de créer la fabrique de connexions entre pairs. Certaines couches d’intégration proposent des options plus ciblées. Par exemple, avec webrtc-sys 0.3.51, activez SPED sur la fabrique et SNAP dans la configuration de la connexion :

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 vous utilisez un SDK qui encapsule libwebrtc, comme un SDK natif de LiveKit, transmettez la même chaîne via la configuration WebRTC ou les options d’initialisation du SDK. Si le SDK ne donne pas accès aux paramètres expérimentaux, initialisez l’instance sous-jacente de libwebrtc avant que le SDK ne crée sa fabrique de connexions entre pairs, ou passez à une version de la couche d’intégration qui permet de configurer ces paramètres.

Négocier un canal de données à l’avance

Utilisez le même identifiant de canal dans votre client et dans la requête de signalisation. Les étapes suivantes s’appliquent aux clients natifs comme aux navigateurs, même si vous n’avez activé qu’une partie des optimisations du transport, voire aucune des trois :

1. Créez le canal de données avant l’offre SDP. Définissez negotiated sur true et attribuez à id un identifiant de canal disponible, par exemple 4. Le libellé du canal peut être n’importe quelle chaîne de caractères.
2. Envoyez l’offre SDP et l’identifiant du canal à votre serveur d’application, puis suivez les étapes ci-dessous pour votre API.

Se connecter à GPT-Live

Commencez par le guide de démarrage rapide de GPT-Live avec WebRTC. Configurez votre serveur pour qu’il transmette l’identifiant du canal dans le champ transport.dcid du corps JSON de la requête POST /v1/live/sessions. Conservez transport.type à la valeur webrtc et transport.sdp à la valeur de l’offre SDP du client.

Pour un canal créé avec id: 4, envoyez le corps JSON suivant dans la requête POST /v1/live/sessions. Remplacez <SDP offer> par l’offre SDP générée par votre client :

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

Le champ transport.dcid active le canal négocié à l’avance. Omettez-le si vous utilisez un canal de données standard. Ne transmettez pas dcid dans les paramètres de requête de l’URL. GPT-Live rejette ces paramètres, contrairement à la Realtime API dans la procédure ci-dessous.

Appliquez la valeur de transport.sdp renvoyée par le serveur comme réponse SDP distante et attendez session.started avant d’envoyer des commandes applicatives. La requête HTTP démarre la session. N’envoyez pas session.start sur le canal de données.

Se connecter à la Realtime API

Suivez la procédure de connexion WebRTC via l’interface unifiée. Configurez votre serveur pour qu’il transmette l’identifiant du canal dans le paramètre de requête dcid lorsqu’il appelle /v1/realtime/calls. Pour un canal créé avec id: 4, utilisez POST /v1/realtime/calls?dcid=4 et conservez la même offre SDP et la même configuration de session dans le corps multipart de la requête.

Appliquez le SDP renvoyé par le serveur comme réponse distante. Omettez dcid si vous utilisez un canal de données standard. L’exemple complet ci-dessous présente les deux configurations.

Activer WARP dans un navigateur

Chrome, Edge et les autres navigateurs basés sur Chromium intègrent libwebrtc, mais une page web ne peut pas en configurer les paramètres expérimentaux. Activez les fonctionnalités de transport disponibles dans votre navigateur, puis négociez un canal de données à l’avance en suivant la même procédure de signalisation que pour un client natif, selon l’API utilisée.

Activer les fonctionnalités disponibles et les essais par origine

Un essai par origine permet à un site web inscrit d’utiliser une fonctionnalité expérimentale du navigateur. Vérifiez la disponibilité de chaque fonctionnalité WARP :

• DTLS 1.3 : Chrome prend en charge DTLS 1.3 sans essai par origine.
• SNAP : les versions 151 à 156 de Chrome prennent en charge SNAP dans le cadre d’un essai par origine. Pour Edge, vérifiez si un essai SNAP est disponible pour votre version et inscrivez-vous pour obtenir un jeton émis par Edge.
• SPED : aucun navigateur ne propose d’essai par origine pour SPED. Consultez cette page ultérieurement pour savoir si SPED est pris en charge. Pour utiliser toutes les fonctionnalités de WARP, il faut que le navigateur active SPED par défaut ou que vous ayez accès à ses options de démarrage et activiez vous-même les paramètres expérimentaux nécessaires.

L’activation de l’essai SNAP n’active ni SPED ni l’ensemble des fonctionnalités de WARP. Si votre navigateur ne donne pas accès à SPED, vous pouvez tout de même utiliser DTLS 1.3 et l’essai SNAP pour bénéficier de ces deux optimisations.

Consultez les essais par origine proposés pour votre navigateur :

• Essais par origine de Google Chrome
• Essais par origine de Microsoft Edge

Pour activer l’essai par origine de SNAP :

1. Ouvrez la page des essais par origine de votre navigateur et recherchez WebRTC Data Channel: SCTP Negotiation Acceleration Protocol (SNAP).

2. Sélectionnez Register et saisissez l’origine de votre application, par exemple https://example.com.

3. Ajoutez le jeton obtenu dans la section <head> de votre page, avant le script qui crée RTCPeerConnection :

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

4. Rechargez la page. Dans Chrome, ouvrez les outils de développement, sélectionnez Application et vérifiez que WebRtcSctpSnap figure dans la section Origin Trials.

Vous pouvez également transmettre le jeton dans un en-tête de réponse HTTP :

Origin-Trial: YOUR_ORIGIN_TRIAL_TOKEN

Négocier à l’avance le canal de données du navigateur

Suivez les étapes de configuration du canal de données décrites plus haut, puis transmettez l’identifiant correspondant en suivant les instructions pour GPT-Live ou la Realtime API. La négociation préalable du canal ne nécessite pas d’essai par origine et peut raccourcir le délai de réception des événements du serveur, même si vous ne disposez pas de toutes les fonctionnalités de WARP.

Se connecter via l’interface unifiée

Suivez la procédure de connexion WebRTC via l’interface unifiée pour vous connecter plus rapidement à la Realtime API. Le navigateur envoie son offre SDP et l’identifiant négocié du canal de données à votre serveur d’application. Votre serveur transmet ce même identifiant dans le paramètre de requête dcid lorsqu’il appelle /v1/realtime/calls.

Configurer votre serveur d’application

Ce serveur d’application prend en charge WebRTC standard et WARP. Le commentaire WARP only indique où transmettre dcid pour utiliser 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
}

Se connecter depuis votre navigateur

Après avoir activé les optimisations disponibles dans votre navigateur, définissez useWarp sur true. Choisissez un identifiant de canal de données disponible et transmettez ce même identifiant au serveur. Les commentaires WARP only indiquent les étapes de configuration et de signalisation dont WebRTC standard n’a pas besoin :

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

Utiliser un client sans prise en charge de WARP

Si votre client WebRTC n’utilise pas libwebrtc, ajoutez à votre pile WebRTC les optimisations du transport compatibles avec WARP ou utilisez une autre méthode prise en charge par cette pile. Consultez les spécifications de WARP, de SPED, de SNAP, de DTLS 1.3 et de l’établissement des canaux de données.

Si ces optimisations ne sont pas disponibles, utilisez la procédure de connexion WebRTC standard pour GPT-Live ou l’interface unifiée de la Realtime API.