1) Arbo & prérequis

webrtc-realtime-starter/
  .env                      # OPENAI_API_KEY=sk-...
  server/
    package.json
    server.ts
    tools.ts
    verifySignature.ts
  web/
    package.json
    src/VoiceRealtime.tsx
    src/main.tsx
    index.html

• Node 18+, pnpm/npm au choix.
• ffmpeg non requis (l’audio transite direct WebRTC).
• .env (côté serveur uniquement) :

OPENAI_API_KEY=sk-xxxxx
OPENAI_PROJECT=proj_xxxxx        # si vous segmentez par projet
OPENAI_WEBHOOK_SECRET=whsec_xxx  # si vous activez les webhooks

3) Front React — connexion WebRTC directe au Realtime

web/package.json

{
  "name": "webrtc-realtime-web",
  "type": "module",
  "scripts": { "dev": "vite" },
  "dependencies": { "react": "^18.3.1", "react-dom": "^18.3.1" },
  "devDependencies": { "vite": "^5.3.1", "@types/react": "^18.3.3", "@types/react-dom": "^18.3.0" }
}

web/src/VoiceRealtime.tsx

import { useEffect, useRef, useState } from "react";

export default function VoiceRealtime() {
  const pcRef = useRef<RTCPeerConnection | null>(null);
  const audioRef = useRef<HTMLAudioElement | null>(null);
  const [ready, setReady] = useState(false);
  const [speaking, setSpeaking] = useState(false);

  useEffect(() => {
    (async () => {
      // 1) Obtenir un secret client éphémère depuis notre bridge
      const sess = await fetch("/session", { method: "POST" }).then(r => r.json());

      // 2) Créer la PeerConnection
      const pc = new RTCPeerConnection();
      pcRef.current = pc;

      // 3) Piste distante (TTS du modèle)
      pc.ontrack = (e) => {
        if (!audioRef.current) {
          audioRef.current = new Audio();
          audioRef.current.autoplay = true;
        }
        audioRef.current.srcObject = e.streams[0];
      };

      // 4) Micro local
      const stream = await navigator.mediaDevices.getUserMedia({ audio: true, video: false });
      stream.getAudioTracks().forEach(t => pc.addTrack(t, stream));

      // (Optionnel) DataChannel pour envoyer des commandes (ex: "reset", "persona")
      pc.createDataChannel("client-events");

      // 5) SDP offer
      const offer = await pc.createOffer({ offerToReceiveAudio: true });
      await pc.setLocalDescription(offer);

      // 6) Envoyer l’offer au Realtime API (WebRTC)
      // ⚠️ Ajustez l’URL/headers selon votre doc (OpenAI/Azure)
      const r = await fetch("https://api.openai.com/v1/realtime?model=gpt-realtime", {
        method: "POST",
        headers: {
          Authorization: `Bearer ${sess.client_secret}`,
          "Content-Type": "application/sdp"
        },
        body: offer.sdp
      });

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

      setReady(true);
    })();

    return () => pcRef.current?.close();
  }, []);

  return (
    <div className="p-4">
      <div>Session: {ready ? "connectée" : "init..."}</div>
      <button
        onClick={() => setSpeaking(s => !s)}
        disabled={!ready}
        style={{ marginTop: 12 }}
      >
        {speaking ? "⏸️ Pause" : "🎙️ Parler"}
      </button>
      {/* Pour un vrai barge-in : vous pouvez couper/relancer la capture ou envoyer des client events */}
    </div>
  );
}

Le flux offer/answer SDP + Bearer token éphémère suit le guide WebRTC Realtime officiel. Pour personnaliser la session (instructions, voix, transcriptions-only, etc.), utilisez les server-side controls / client events décrits dans la doc. OpenAI Platform+1

5) Sécurité & prod (checklist)

• Tokens éphémères (TTL court), jamais de clé API dans le navigateur. OpenAI Platform
• Signer/valider les webhooks (horodatage + HMAC), rate limiting et WAF côté bridge. OpenAI Platform
• Barge-in : côté UI, si l’utilisateur reparle, coupez la lecture et laissez Realtime gérer le turn-taking (client events). OpenAI Platform
• Observabilité : logguez latence aller/retour, événements session (création, tool_call, tool_result), erreurs.
• Modèles : vérifiez la disponibilité GA de gpt-realtime et les dépréciations (ex-previews). OpenAI+2OpenAI+2

2) Front React — UI audio complète (vu-mètre, mute, volume, Répéter, transcription)

web/src/VoiceRealtime.tsx

import { useEffect, useRef, useState } from "react";

type Mode = "voice" | "transcription"; // transcription-only (on coupe la sortie vocale)

export default function VoiceRealtime() {
  const pcRef = useRef<RTCPeerConnection | null>(null);
  const remoteAudioRef = useRef<HTMLAudioElement | null>(null);
  const localStreamRef = useRef<MediaStream | null>(null);
  const analyserRef = useRef<AnalyserNode | null>(null);
  const rafRef = useRef<number | null>(null);
  const [connected, setConnected] = useState(false);
  const [muted, setMuted] = useState(false);
  const [volume, setVolume] = useState(1); // 0..1
  const [level, setLevel] = useState(0); // 0..100
  const [mode, setMode] = useState<Mode>("voice");
  const [transcript, setTranscript] = useState<string>("");

  // "Répéter" : on enregistre à la volée le flux TTS distant dans un buffer circulaire
  const remoteReplayChunks = useRef<Blob[]>([]);
  const remoteMediaRecorder = useRef<MediaRecorder | null>(null);
  const lastReplyBlob = useRef<Blob | null>(null);

  // DataChannel pour recevoir texte / événements (si le modèle envoie des transcripts)
  const dataChannelRef = useRef<RTCDataChannel | null>(null);

  useEffect(() => {
    (async () => {
      // 1) Token éphémère
      const sess = await fetch("/session", { method: "POST" }).then(r => r.json());

      // 2) PeerConnection
      const pc = new RTCPeerConnection();
      pcRef.current = pc;

      // 3) Canal data pour recevoir du texte (optionnel)
      pc.ondatachannel = (e) => {
        const ch = e.channel;
        ch.onmessage = (ev) => {
          try {
            const msg = JSON.parse(String(ev.data));
            if (msg.type === "transcript.delta") {
              setTranscript(prev => prev + msg.text);
            } else if (msg.type === "transcript.reset") {
              setTranscript("");
            }
          } catch {
            // fallback: concat brut
            setTranscript(prev => prev + " " + String(ev.data));
          }
        };
      };

      // 4) Piste distante (TTS du modèle)
      pc.ontrack = (e) => {
        if (!remoteAudioRef.current) {
          remoteAudioRef.current = new Audio();
          remoteAudioRef.current.autoplay = true;
        }
        remoteAudioRef.current.srcObject = e.streams[0];
        // Enregistreur pour "Répéter"
        remoteMediaRecorder.current?.stop();
        remoteReplayChunks.current = [];
        remoteMediaRecorder.current = new MediaRecorder(e.streams[0], { mimeType: "audio/webm" });
        remoteMediaRecorder.current.ondataavailable = (ev) => {
          if (ev.data.size) {
            remoteReplayChunks.current.push(ev.data);
            // Ne gardez que ~15 s
            const MAX = 60; // 60 * 250ms ≈ 15s si timeslice=250
            if (remoteReplayChunks.current.length > MAX) remoteReplayChunks.current.shift();
            lastReplyBlob.current = new Blob(remoteReplayChunks.current, { type: "audio/webm" });
          }
        };
        remoteMediaRecorder.current.start(250);
        updateOutput();
      };

      // 5) Micro local + vu-mètre
      const stream = await navigator.mediaDevices.getUserMedia({ audio: true, video: false });
      localStreamRef.current = stream;
      stream.getAudioTracks().forEach(t => pc.addTrack(t, stream));
      setupVUMeter(stream);

      // 6) DataChannel côté client pour commandes (optionnel)
      const ch = pc.createDataChannel("client-events");
      dataChannelRef.current = ch;

      // 7) SDP
      const offer = await pc.createOffer({ offerToReceiveAudio: true });
      await pc.setLocalDescription(offer);
      const r = await fetch("https://api.openai.com/v1/realtime?model=gpt-realtime", {
        method: "POST",
        headers: { Authorization: `Bearer ${sess.client_secret}`, "Content-Type": "application/sdp" },
        body: offer.sdp
      });
      const answerSDP = await r.text();
      await pc.setRemoteDescription({ type: "answer", sdp: answerSDP });

      setConnected(true);
    })();

    return () => {
      if (rafRef.current) cancelAnimationFrame(rafRef.current);
      remoteMediaRecorder.current?.stop();
      pcRef.current?.close();
    };
  }, []);

  function setupVUMeter(stream: MediaStream) {
    const ctx = new AudioContext();
    const src = ctx.createMediaStreamSource(stream);
    const analyser = ctx.createAnalyser();
    analyser.fftSize = 512;
    src.connect(analyser);
    analyserRef.current = analyser;

    const data = new Uint8Array(analyser.frequencyBinCount);
    const loop = () => {
      analyser.getByteTimeDomainData(data);
      // amplitude RMS approx
      let sum = 0;
      for (let i = 0; i < data.length; i++) {
        const v = (data[i] - 128) / 128;
        sum += v * v;
      }
      const rms = Math.sqrt(sum / data.length);
      setLevel(Math.min(100, Math.round(rms * 140)));
      rafRef.current = requestAnimationFrame(loop);
    };
    loop();
  }

  function updateOutput() {
    if (!remoteAudioRef.current) return;
    remoteAudioRef.current.muted = muted || mode === "transcription";
    remoteAudioRef.current.volume = volume; // 0..1
  }

  // UI actions
  const toggleMute = () => { setMuted(m => { const v = !m; setTimeout(updateOutput, 0); return v; }); };
  const onVolume = (e: any) => { const v = Number(e.target.value); setVolume(v); setTimeout(updateOutput, 0); };

  const onModeChange = (m: Mode) => {
    setMode(m);
    setTranscript("");
    // Optionnel: envoyer un event au modèle si vous avez un switch "no_speech_output"
    dataChannelRef.current?.send(JSON.stringify({ type: "client.mode", mode: m }));
    updateOutput();
  };

  const onRepeat = async () => {
    if (!lastReplyBlob.current) return;
    const url = URL.createObjectURL(lastReplyBlob.current);
    const a = new Audio(url);
    a.play();
  };

  return (
    <div className="p-4 space-y-3" style={{ maxWidth: 420 }}>
      <div>Connexion: {connected ? "OK" : "…"} </div>

      {/* Vu-mètre */}
      <div style={{ height: 8, background: "#eee", borderRadius: 4, overflow: "hidden" }}>
        <div style={{ width: `${level}%`, height: "100%" }} />
      </div>

      {/* Contrôles audio */}
      <div className="space-x-2">
        <button onClick={toggleMute}>{(muted || mode==="transcription") ? "🔇 Unmute" : "🔊 Mute"}</button>
        <label style={{ marginLeft: 8 }}>
          Volume
          <input type="range" min={0} max={1} step={0.01} value={volume} onChange={onVolume} style={{ width: 160, verticalAlign: "middle", marginLeft: 8 }} />
        </label>
        <button onClick={onRepeat} title="Répéter la dernière réponse">🔁 Répéter</button>
      </div>

      {/* Mode voice vs transcription-only */}
      <div className="space-x-2">
        <label>
          <input type="radio" checked={mode==="voice"} onChange={() => onModeChange("voice")} /> Voix
        </label>
        <label>
          <input type="radio" checked={mode==="transcription"} onChange={() => onModeChange("transcription")} /> Transcription-only
        </label>
      </div>

      {/* Zone transcript (si le modèle émet du texte via datachannel) */}
      <textarea value={transcript} readOnly rows={6} style={{ width: "100%" }} placeholder="Transcription en direct…" />
    </div>
  );
}

Notes UI

• Vu-mètre : Web Audio API (AnalyserNode) sur le micro local.
• Mute/Volume : agit sur la piste distante (TTS). Le mode transcription-only coupe l’audio et laisse le texte (si le modèle envoie des delta transcripts via data channel — vous pouvez aussi afficher le texte d’un tool dédié).
• Répéter : on enregistre en boucle la piste distante avec un MediaRecorder pour rejouer la dernière réponse.
• DataChannel : pour recevoir du texte (transcripts ou “assistant thinking”), et envoyer des commandes (ex. client.mode).

4) À adapter selon vos besoins

• Personna & voix : configurez dans /session (instructions, voix, langue).

• Transcripts : si vous voulez toujours le texte, créez un tool “emit_transcript” qui pousse les deltas via votre bridge (SSE/WebSocket) ou via data channel si supporté par votre setup.

• Barge-in : côté front, si l’utilisateur reparle, vous pouvez baisser remoteAudioRef.current.volume à 0 (ou mute) pour éviter le double-talk ; le turn-taking est géré par Realtime.