Skip to main content

Utilisation de WebRTC avec qwen3.5-omni-plus-realtime pour les appels en temps réel

Cette rubrique explique comment se connecter à l'API Realtime depuis un navigateur via WebRTC et JavaScript afin d'établir des appels audio et vidéo en temps réel avec le modèle qwen3.5-omni-plus-realtime.

WebRTC convient particulièrement aux scénarios vocaux à faible latence exécutés dans un navigateur. L'audio transite directement par UDP et bénéficie d'une annulation d'écho ainsi que d'une réduction du bruit intégrées. Seul le mode VAD côté serveur (server_vad ou semantic_vad) est pris en charge ; le mode manuel n'est pas disponible.

Prérequis et remarques

  1. Configurez une clé API et définissez-la comme variable d'environnement.
  2. Utilisez un navigateur moderne compatible avec WebRTC (Chrome, Edge, Firefox, Safari, etc.).
  3. Le navigateur doit disposer de l'autorisation d'accéder au microphone. Pour les appels vidéo, l'accès à la caméra est également requis.
  4. En raison des restrictions CORS, les navigateurs ne peuvent pas envoyer directement de requêtes d'échange SDP au serveur. Dans la démo, exécutez la commande curl dans un terminal pour établir la connexion. En production, cette limitation ne s'applique pas lorsque la requête passe par un proxy AppServer.

Mise en œuvre des appels audio/vidéo IA

Le diagramme de séquence suivant illustre le flux complet d'un appel audio/vidéo WebRTC : Diagramme de séquence d'un appel audio/vidéo WebRTC
image

Création de RTCPeerConnection

Appelez le constructeur natif RTCPeerConnection du navigateur pour instancier une connexion. Aucune configuration de serveurs ICE n'est nécessaire, car le serveur gère lui-même la traversée NAT.
pc = new RTCPeerConnection({ iceServers: [ ] });
Enregistrez les callbacks essentiels :
// Connection state listener
pc.onconnectionstatechange = () => {
  if (!pc) return;
  if (pc.connectionState === 'connected') {
    setStatus('Connected, please speak', 'connected');
  } else if (["failed", "closed", "disconnected"].includes(pc.connectionState)) {
    endSession(true);
  }
};

// Receive and play remote audio stream + start recording
pc.ontrack = async (e) => {
  const stream = e.streams[0];
  ensureHiddenAudioEl();
  hiddenRemoteAudioEl.srcObject = stream;
  try { await hiddenRemoteAudioEl.play(); } catch {}
  startRecordingRemoteStream(stream);
};

Obtention des flux médias locaux

Un unique appel à getUserMedia permet de demander l'audio (obligatoire) et la vidéo (facultative). L'activation de la vidéo dépend de la case à cocher Enable video sélectionnée par l'utilisateur.
const wantVideo = !!sendVideoCheckbox.checked;

const constraints = wantVideo
  ? {
      audio: true,
      video: {
        facingMode: { ideal: "user" },
        frameRate: { ideal: 30, max: 30 },
        width: { ideal: 640 },
        height: { ideal: 480 },
      }
    }
  : { audio: true };

localStream = await navigator.mediaDevices.getUserMedia(constraints);
L'audio et la vidéo sont capturés lors d'un unique appel à getUserMedia, et non séparément. La prévisualisation vidéo locale s'effectue à 30 ips pour garantir sa fluidité, tandis que le taux de trames envoyé au serveur est réduit à 2 ips via Canvas.

Ajout des pistes média à PeerConnection

Ajout de la piste audio :
localStream.getAudioTracks().forEach(t => {
  pc.addTrack(t, localStream);
  gatedAudioTracks.push(t);
});
Ajout de la piste vidéo (facultatif, avec réduction Canvas à 2 ips) : Les dimensions du Canvas sont déterminées dynamiquement à partir de la résolution réelle de la caméra plutôt que définies en dur :
const sendFps = 2;
const settings = localStream.getVideoTracks()[0].getSettings();
sendCanvas = document.createElement("canvas");
sendCanvas.width = settings.width || 640;   // Dynamically obtain actual width
sendCanvas.height = settings.height || 480;  // Dynamically obtain actual height
sendCanvasCtx = sendCanvas.getContext("2d", { alpha: false });

sendCanvasStream = sendCanvas.captureStream(sendFps); // 2fps
const lowFpsTrack = sendCanvasStream.getVideoTracks()[0];
pc.addTrack(lowFpsTrack, sendCanvasStream);
gatedVideoTracks.push(lowFpsTrack);

// requestAnimationFrame loop: draw camera frames to Canvas
const pump = () => {
  if (!sendCanvasCtx || !sendCanvas) return;
  try { sendCanvasCtx.drawImage(localVideo, 0, 0, sendCanvas.width, sendCanvas.height); } catch {}
  sendRafId = requestAnimationFrame(pump);
};
sendRafId = requestAnimationFrame(pump);
Contrôle de l'envoi média (critique) : Immédiatement après l'ajout des pistes, bloquez leur envoi afin d'éviter toute transmission de données média avant la réception de l'événement session.created :
// 1. Disable all track.enabled
gateMedia(false);  // track.enabled = false

// 2. Replace sender tracks with null to fully block sending
audioSender = pc.getSenders().find(s => s.track?.kind === 'audio');
videoSender = pc.getSenders().find(s => s.track?.kind === 'video');
audioTrack = audioSender?.track;
videoTrack = videoSender?.track;
await audioSender?.replaceTrack(null);
await videoSender?.replaceTrack(videoTrack ? null : undefined);
Cette opération équivaut à enableSendMediaStream(false) dans d'autres SDK. Ne rétablissez surtout pas l'envoi avant la réception de session.created.

Création du DataChannel

Créez un DataChannel nommé oai-events pour échanger les événements de contrôle de session avec le serveur IA.
const dc = pc.createDataChannel('oai-events');

dc.onopen = () => console.log("DC open");
dc.onmessage = (e) => {
  handleDcMessage(e.data, dc);
};

// Also listen for DataChannels created by the server
pc.ondatachannel = (event) => {
  const ch = event.channel;
  ch.onmessage = (e) => {
    handleDcMessage(e.data, ch);
  };
};

Génération de l'Offer SDP

Appelez createOffer() puis définissez la description locale. Patientez jusqu'à la fin de la collecte ICE avant d'utiliser l'Offer SDP complète.
pc.onicegatheringstatechange = () => {
  if (!pc) return;
  if (pc.iceGatheringState === "complete" && pc.localDescription?.sdp) {
    const sdp = pc.localDescription.sdp;
    // ICE gathering complete, Offer SDP ready
    // Auto-generate curl command for users
  }
};

const offer = await pc.createOffer();
await pc.setLocalDescription(offer);
Attendez que iceGatheringState === "complete" avant d'exploiter le SDP. À ce stade, celui-ci contient toutes les informations relatives aux candidats ICE.

Échange SDP (via commande curl ou AppServer)

Transmettez l'Offer SDP au serveur pour obtenir l'Answer SDP en retour. Dans la démo, cette étape s'effectue au moyen d'une commande curl :
curl -X POST 'https://{endpoint}/api/v1/webrtc/realtime?model=qwen3.5-omni-plus-realtime' \
  -H 'Content-Type: application/sdp' \
  -H 'Authorization: Bearer $DASHSCOPE_API_KEY' \
  --data-binary '<Offer SDP content>'
En production, faites passer cette étape par un proxy AppServer afin d'éviter d'exposer la clé API dans le code front-end. {endpoint} correspond à l'endpoint de l'API Realtime.

Définition de l'Answer SDP pour établir la connexion

Définissez l'Answer SDP renvoyée par le serveur comme description distante afin d'établir la connexion WebRTC. Normalisez au préalable le format du SDP :
function normalizeSdpForSetRemote(sdp) {
  sdp = String(sdp).trim().replace(/\r?\n/g, "\r\n");
  if (!sdp.endsWith("\r\n")) sdp += "\r\n";
  return sdp;
}

const answerSdp = normalizeSdpForSetRemote(txt);
await pc.setRemoteDescription({ type: 'answer', sdp: answerSdp });
La spécification SDP impose des fins de ligne \r\n. La fonction normalizeSdpForSetRemote assure la compatibilité des fins de ligne provenant de sources diverses.

Configuration de la session IA (session.update)

Une fois la connexion établie, le serveur envoie un événement session.created via le DataChannel. Dès sa réception :
  1. Levez le blocage média pour reprendre l'envoi audio/vidéo.
  2. Envoyez session.update pour configurer les paramètres de la session.
Levée du blocage et rétablissement du flux média :
function handleDcMessage(data, channel) {
  let obj;
  try { obj = JSON.parse(data); } catch (err) { return; }

  if (obj?.type === "session.created") {
    // Release gate: restore track.enabled
    gateMedia(true);
    // Restore actual track to sender
    if (audioSender) audioSender.replaceTrack(audioTrack);
    if (videoSender && videoTrack) videoSender.replaceTrack(videoTrack);
    // Send session configuration
    sendUpdate(channel);
  }
}
Corps du message session.update :
const update = {
  event_id: `event_${Date.now()}`,
  type: "session.update",
  session: {
    input_audio_format: "pcm",
    input_audio_transcription: { model: "qwen3-asr-flash-realtime" },
    instructions: "You are a helpful assistant.",
    modalities: ["text", "audio"],
    output_audio_format: "pcm",
    smooth_output: false,
    turn_detection: {
      prefix_padding_ms: 500,
      silence_duration_ms: 800,
      threshold: 0.5,
      type: "server_vad",
    },
  },
};
if (channel && channel.readyState === "open") channel.send(JSON.stringify(update));
Le paramètre turn_detection.type accepte les valeurs server_vad (détection basée sur le volume) ou semantic_vad (détection sémantique). Le mode VAD manuel n'est pas pris en charge avec WebRTC.

Conversation en temps réel

Une fois la connexion active, les flux audio et vidéo transitent en temps réel via RTP. Les réponses vocales de l'IA distante arrivent par le callback ontrack et sont lues immédiatement. MediaRecorder sert à enregistrer ces réponses en vue de leur téléchargement. Réception et enregistrement de l'audio distant :
pc.ontrack = async (e) => {
  const stream = e.streams[0];
  ensureHiddenAudioEl();
  hiddenRemoteAudioEl.srcObject = stream;
  try { await hiddenRemoteAudioEl.play(); } catch {}
  startRecordingRemoteStream(stream); // Start recording
};

function startRecordingRemoteStream(remoteStream) {
  const audioTracks = remoteStream.getAudioTracks();
  if (!audioTracks.length) return;
  const audioStream = new MediaStream(audioTracks);

  recordedChunks = [ ];

  mediaRecorder = new MediaRecorder(audioStream, { mimeType: 'audio/webm' });
  mediaRecorder.ondataavailable = (e) => {
    if (e.data && e.data.size > 0) recordedChunks.push(e.data);
  };
  mediaRecorder.onstop = () => {
    audioBlob = new Blob(recordedChunks, { type: 'audio/webm' });
    // Available for download after recording stops
  };
  mediaRecorder.start();
}
Affichage des événements DataChannel : Tous les événements émis et reçus via le DataChannel (notamment session.created, response.audio_transcript.done, etc.) s'affichent dans le panneau d'événements. Vous pouvez les développer pour consulter le JSON complet :
function pushEventFromDataChannel(eventObj) {
  const ts = eventObj.timestamp || nowTs();
  events.unshift({ event: eventObj, timestamp: ts });
  renderEvents();
}

Fin de session et libération des ressources

Libérez toutes les ressources dans l'ordre approprié lors de la fin d'un appel. Le respect de cette séquence est primordial :
function endSession(silent = false) {
  // 1. Stop Canvas frame-rate reduction loop
  if (sendRafId) cancelAnimationFrame(sendRafId);
  sendRafId = 0;
  if (sendCanvasStream) sendCanvasStream.getTracks().forEach(t => t.stop());
  sendCanvasStream = null; sendCanvasCtx = null; sendCanvas = null;

  // 2. Stop recording
  try { if (mediaRecorder && mediaRecorder.state !== "inactive") mediaRecorder.stop(); } catch {}
  mediaRecorder = null;

  // 3. Stop local media stream
  if (localStream) {
    localStream.getTracks().forEach(t => t.stop());
    localStream = null;
  }

  // 4. Close PeerConnection
  if (pc) { try { pc.close(); } catch {} pc = null; }

  // 5. Clean up remote audio element
  if (hiddenRemoteAudioEl) {
    try { hiddenRemoteAudioEl.pause(); } catch {}
    hiddenRemoteAudioEl.srcObject = null;
    hiddenRemoteAudioEl.remove();
    hiddenRemoteAudioEl = null;
  }
}
Une fois la session terminée, utilisez le bouton Download remote audio pour sauvegarder l'enregistrement de la réponse IA au format WebM.

Remarques importantes

  1. Le blocage média doit être levé après session.created : Toute donnée média envoyée avant que le serveur n'émette session.created sera ignorée. Recourez à replaceTrack(null) pour bloquer intégralement l'envoi jusque-là.
  2. La réduction de la fréquence vidéo repose sur Canvas : La prévisualisation locale tourne à 30 ips, mais seuls 2 ips sont transmis au serveur grâce à captureStream(2). Cette approche préserve la bande passante.
  3. Normalisation du format SDP : Vérifiez que les fins de ligne sont bien \r\n avant d'appliquer l'Answer SDP, faute de quoi setRemoteDescription risque d'échouer.
  4. La vidéo reste optionnelle : Si l'utilisateur ne l'active pas, seule l'autorisation du microphone est demandée ; aucune invite concernant la caméra n'apparaît.
  5. L'audio distant est enregistré automatiquement : MediaRecorder capture le flux audio de réponse de l'IA. Un fichier WebM devient téléchargeable à la fin de la session.
  6. WebRTC ne prend en charge que le VAD côté serveur : Le mode manual n'est pas disponible. Optez pour server_vad (détection par volume) ou semantic_vad (détection sémantique).

Téléchargement de la démo complète

Téléchargez le code exemple complet : webrtc_demo.html.

Documents associés