## API vocale – Guide d'intégration client

Cette documentation explique comment intégrer la partie **vocale** de l'API côté client (web ou autre) :

- établir une **connexion WebRTC** avec le serveur,
- envoyer l'**audio du micro** et recevoir la **réponse audio** de l'agent,
- récupérer l'**historique de transcription texte** de la conversation,
- configurer les **paramètres VAD** (Voice Activity Detection) à la connexion et en cours de session.

### Choix du transport via capabilities

Le client doit interroger `GET /voice/capabilities` (avec Bearer JWT) pour savoir quel transport est disponible. Le champ `daily_available` dépend de la présence de `DAILY_API_KEY` côté serveur.

| `daily_available` | Action recommandée |
|-------------------|--------------------|
| `true` | Utiliser `POST /voice/daily-start` (recommandé en cloud, HF Spaces) |
| `false` | Utiliser `POST /voice/offer` (SmallWebRTC) |

```javascript
// 1. Obtenir le transport disponible
const capRes = await fetch("/voice/capabilities", {
  headers: { "Authorization": "Bearer " + jwt },
});
const { daily_available } = await capRes.json();

// 2. Choisir l'endpoint
if (daily_available) {
  // Flux Daily : POST /voice/daily-start → room_url + token → SDK Daily
  const res = await fetch("/voice/daily-start?model=...", {
    method: "POST",
    headers: { "Content-Type": "application/json", "Authorization": "Bearer " + jwt },
    body: JSON.stringify({}),
  });
  const { room_url, token } = await res.json();
  // Joindre avec Daily.createCallObject() ou createFrame()
} else {
  // Flux SmallWebRTC : GET /voice/ice-servers → POST /voice/offer → PATCH /voice/offer
  // Voir section 1
}
```

### Choix du transport (référence)

| Transport      | Endpoint principal      | Page de test           | Contexte recommandé                           |
|----------------|-------------------------|------------------------|-----------------------------------------------|
| **SmallWebRTC** | `POST /voice/offer`     | `GET /voice-test`      | Réseau local, connectivité directe            |
| **Daily.co**   | `POST /voice/daily-start` | `GET /voice-daily`     | Hugging Face Spaces, cloud, NAT strict        |
| **Daily minimal** | `POST /voice/daily-start` | `GET /voice-daily-minimal` | Même que Daily, mais sans iframe, UI intégrée |

### Endpoints principaux

- `POST /auth/token` – obtenir un JWT (authentification).
- `GET /voice/capabilities` – savoir si Daily est disponible. Réponse : `{ "daily_available": bool }` (selon `DAILY_API_KEY`).
- **SmallWebRTC** : `GET /voice/ice-servers`, `POST /voice/offer`, `PATCH /voice/offer` – WebRTC direct.
- **Daily.co** : `POST /voice/daily-start` – créer une room Daily et rejoindre (recommandé pour HF Spaces).
- `GET /voice/transcript/{conversation_id}` – lecture des transcriptions (valide pour tous les transports).

---

## 1bis. Connexion via Daily.co (recommandé pour HF Spaces)

Sur Hugging Face Spaces ou environnements cloud, la connexion WebRTC directe (SmallWebRTC) peut échouer (timeout ICE, NAT). **Daily.co** gère le routage média et le NAT traversal côté infrastructure, ce qui permet à la voix de fonctionner sans serveur TURN dédié.

### 1bis.1. Prérequis

- Compte Daily.co et clé API (`DAILY_API_KEY` configurée côté serveur).
- SDK `@daily-co/daily-js` :

```html
<script src="https://unpkg.com/@daily-co/daily-js"></script>
```

- Pages de test : `GET /voice-daily` (avec iframe) ou `GET /voice-daily-minimal` (sans iframe).

### 1bis.2. Flux côté client

1. Obtenir un JWT via `POST /auth/token`.
2. Appeler `POST /voice/daily-start` avec `Authorization: Bearer <token>` et (optionnel) `?model=...&project_id=...`.
3. La réponse contient `room_url`, `token` et `conversation_id`.
4. Joindre la room Daily avec le SDK `@daily-co/daily-js` – soit avec `createFrame()` (iframe Prebuilt, §1bis.4), soit avec `createCallObject()` (mode minimal, §1bis.5).

```javascript
const res = await fetch("/voice/daily-start?model=mistral-large-latest", {
  method: "POST",
  headers: { "Content-Type": "application/json", "Authorization": "Bearer " + jwt },
  body: JSON.stringify({}),  // ou { request_data: { vad_stop_secs: 0.8 } } pour VAD
});
const { room_url, token, conversation_id } = await res.json();
// Utiliser room_url et token pour Daily.createFrame() ou Daily.createCallObject()
```

### 1bis.3. Endpoint `POST /voice/daily-start`

- **Auth** : Bearer JWT.
- **Query** : `model`, `project_id` (optionnels).
- **Body** : `{ "request_data": { vad_stop_secs, vad_start_secs, ... } }` (optionnel, pour les paramètres VAD).
- **Réponse** : `{ room_url, token, conversation_id }`.

### 1bis.4. Mode Prebuilt (avec iframe Daily)

Utiliser l'interface préfabriquée Daily pour un test rapide :

```javascript
const { room_url, token } = await res.json();
const callFrame = window.Daily.createFrame(containerElement, {
  showLeaveButton: true,
  iframeStyle: { width: "100%", height: "400px", border: "0" },
});
await callFrame.join({ url: room_url, token });
```

### 1bis.5. Mode minimal (sans iframe, votre propre UI)

Pour intégrer dans votre propre UI sans le module Prebuilt, utilisez `Daily.createCallObject()` et attachez la piste audio du bot à un élément `<audio>` :

- **Page de test** : `GET /voice-daily-minimal` → `static/voice_daily_minimal.html`

```javascript
const { room_url, token } = await res.json();
const callObject = window.Daily.createCallObject();

function attachBotAudio(track) {
  const el = document.getElementById("bot-audio");
  if (!track || el.srcObject) return;
  el.srcObject = new MediaStream([track]);
  el.play().catch(() => {});
}

callObject.on("participant-updated", (event) => {
  if (event.participant.local) return;
  const track = event.participant.tracks?.audio?.persistentTrack;
  if (track) attachBotAudio(track);
});

callObject.on("participant-joined", (event) => {
  if (event.participant.local) return;
  const track = event.participant.tracks?.audio?.persistentTrack;
  if (track) attachBotAudio(track);
});

await callObject.join({
  url: room_url,
  token,
  subscribeToTracksAutomatically: true,
  startAudioOff: false,
  startVideoOff: true,
});
```

```html
<audio id="bot-audio" autoplay></audio>
```

Le micro est activé par défaut (`startAudioOff: false`), ce qui permet au bot de recevoir votre voix. L'audio du bot est joué via l'élément `<audio>`.

---

## 1. Connexion WebRTC

### 1.1. Pré‑requis côté client

- Savoir faire :
  - des requêtes HTTP (`fetch`, `axios`, etc.),
  - du WebRTC (`RTCPeerConnection`, `getUserMedia` ou équivalent natif),
  - décoder des réponses JSON.
- Le client doit disposer d'un **JWT** valide (obtenu via `POST /auth/token` ou équivalent dans ton application).

### 1.2. Récupérer un token (exemple JS)

```javascript
const tokenRes = await fetch("/auth/token", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({}), // adapter selon ton auth
});
if (!tokenRes.ok) throw new Error("Impossible d'obtenir le token");
const { access_token: token } = await tokenRes.json();
```

### 1.3. Récupérer les serveurs ICE (STUN/TURN)

Pour que WebRTC fonctionne derrière des NAT/firewalls (cloud, Hugging Face Spaces, réseaux d'entreprise), le client doit utiliser les mêmes serveurs ICE que le backend. L'API expose un endpoint qui retourne la liste des serveurs configurés (STUN, TURN avec credentials si nécessaire).

- **Endpoint** : `GET /voice/ice-servers`
- **Authentification** : header `Authorization: Bearer <token>`

```javascript
// À appeler AVANT de créer la RTCPeerConnection
const iceRes = await fetch("/voice/ice-servers", {
  headers: { "Authorization": "Bearer " + token },
});
const iceServers = iceRes.ok ? await iceRes.json() : [{ urls: "stun:stun.l.google.com:19302" }];
```

En cas d'échec (401, erreur réseau), utiliser un fallback STUN minimal pour ne pas bloquer les développements locaux.

**Pourquoi ?** En production (Hugging Face Spaces, cloud), la connexion directe P2P échoue souvent. Un serveur **TURN** relaie alors le flux audio. Le backend est configuré (Metered, etc.) et expose ces serveurs via `/voice/ice-servers`. Client et serveur doivent utiliser la même configuration ICE.

### 1.4. Créer la `RTCPeerConnection`

```javascript
// 1. Récupérer les serveurs ICE (voir § 1.3)
const iceRes = await fetch("/voice/ice-servers", {
  headers: { "Authorization": "Bearer " + token },
});
const iceServers = iceRes.ok ? await iceRes.json() : [{ urls: "stun:stun.l.google.com:19302" }];

// 2. Créer la connexion avec les serveurs ICE
const pc = new RTCPeerConnection({ iceServers });
```

### 1.5. Brancher la sortie audio sur un `<audio>`

```javascript
const remoteAudio = document.getElementById("remote-audio");

pc.ontrack = (event) => {
  remoteAudio.srcObject = event.streams[0];
};
```

### 1.6. Gérer les ICE candidates → `PATCH /voice/offer`

```javascript
pc.onicecandidate = async (event) => {
  if (!event.candidate || !pc.pc_id) return;

  await fetch("/voice/offer", {
    method: "PATCH",
    headers: {
      "Content-Type": "application/json",
      "Authorization": "Bearer " + token,
    },
    body: JSON.stringify({
      pc_id: pc.pc_id,
      candidates: [
        {
          candidate: event.candidate.candidate,
          sdp_mid: event.candidate.sdpMid,
          sdp_mline_index: event.candidate.sdpMLineIndex,
        },
      ],
    }),
  });
};
```

### 1.7. Envoyer l'offre SDP → `POST /voice/offer`

1. Autoriser le micro et ajouter les transceivers :

```javascript
const stream = await navigator.mediaDevices.getUserMedia({ audio: true });

pc.addTransceiver(stream.getAudioTracks()[0], { direction: "sendrecv" });
pc.addTransceiver("video", { direction: "sendrecv" }); // pour compatibilité WebRTC
```

2. Créer l'offre et l'envoyer au backend :

```javascript
await pc.setLocalDescription(await pc.createOffer());

const url = new URL("/voice/offer", window.location.origin);
// Paramètres optionnels :
// url.searchParams.set("model", "mistral-large-latest");
// url.searchParams.set("project_id", "my-project-id");
// url.searchParams.set("mode", "classic");

const res = await fetch(url.toString(), {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer " + token,
  },
  body: JSON.stringify({
    sdp: pc.localDescription.sdp,
    type: pc.localDescription.type,
  }),
});

if (!res.ok) {
  const errText = await res.text();
  throw new Error(`Offer failed: ${res.status} ${errText}`);
}

const answer = await res.json();
pc.pc_id = answer.pc_id;                       // identifiant serveur pour les PATCH ICE
const conversationId = answer.conversation_id; // clé pour les transcripts
await pc.setRemoteDescription(answer);
```

3. Surveiller l'état de la connexion :

```javascript
pc.onconnectionstatechange = () => {
  switch (pc.connectionState) {
    case "connected":
      console.log("WebRTC connecté, audio temps réel prêt.");
      break;
    case "disconnected":
    case "failed":
    case "closed":
      console.log("WebRTC déconnecté.");
      // Nettoyage / reconnexion éventuelle
      break;
  }
};
```

À ce stade :

- le micro du client est envoyé au serveur (via la transceiver audio),
- l'agent répond en audio, reçu sur `ontrack` et joué dans le `<audio>`.

---

## 2. Utilisation du micro + réponse audio

Une fois la connexion établie :

- **Entrée** : l'audio du micro est envoyé en continu vers le serveur via la connexion WebRTC.
- **Sortie** : le serveur renvoie un flux audio (voix de l'agent) que vous jouez simplement avec un `<audio autoplay>` ou l'équivalent natif.

Il n'y a **aucun appel HTTP supplémentaire** à faire pour l'audio : tout passe par la même `RTCPeerConnection`.

Exemple HTML minimal :

```html
<audio id="remote-audio" autoplay></audio>
```

Le code JS montré plus haut suffit à l'alimenter via `pc.ontrack`.

---

## 3. Récupération des transcriptions texte

Les transcriptions sont exposées via un endpoint HTTP séparé, basé sur le `conversation_id` renvoyé par `POST /voice/offer` (SmallWebRTC) ou `POST /voice/daily-start` (Daily).

- Endpoint : `GET /voice/transcript/{conversation_id}`
- Authentification : header `Authorization: Bearer <token>` (même JWT que pour `/voice/offer`).

### 3.1. Appel de l'endpoint (JS)

```javascript
async function fetchTranscript() {
  if (!conversationId) return;

  const res = await fetch(`/voice/transcript/${conversationId}`, {
    headers: {
      "Authorization": "Bearer " + token,
    },
  });
  if (!res.ok) {
    console.warn("Impossible de charger le transcript:", res.status);
    return;
  }

  const data = await res.json();
  // data = { conversation_id: string, messages: [{ role, text, timestamp }, ...] }
  renderTranscript(data.messages);
}
```

La réponse ressemble à :

```json
{
  "conversation_id": "c7d3a5e2-...",
  "messages": [
    {
      "role": "user",
      "text": "Bonjour, j'ai une question sur la formation X...",
      "timestamp": "2026-02-26T14:37:12.123456+00:00"
    },
    {
      "role": "assistant",
      "text": "Bien sûr, dites-moi ce que vous cherchez précisément.",
      "timestamp": "2026-02-26T14:37:13.654321+00:00"
    }
  ]
}
```

### 3.2. Afficher l'historique côté client (mode "chat")

Exemple de rendu basique :

```javascript
function renderTranscript(messages) {
  const el = document.getElementById("transcript");
  el.innerHTML = "";

  for (const msg of messages) {
    const roleLabel = msg.role === "assistant" ? "Agent" : "Vous";

    const wrapper = document.createElement("div");
    wrapper.style.display = "flex";
    wrapper.style.justifyContent =
      msg.role === "assistant" ? "flex-start" : "flex-end";

    const bubble = document.createElement("div");
    bubble.style.maxWidth = "80%";
    bubble.style.padding = "6px 10px";
    bubble.style.borderRadius = "12px";
    bubble.style.fontSize = "0.8rem";
    bubble.style.whiteSpace = "pre-wrap";
    bubble.style.background =
      msg.role === "assistant" ? "#f3f4f6" : "#e5f0ff";
    bubble.textContent = `${roleLabel}: ${msg.text || ""}`;

    wrapper.appendChild(bubble);
    el.appendChild(wrapper);
  }

  el.scrollTop = el.scrollHeight;
}
```

HTML associé :

```html
<div id="transcript" style="max-height:260px; overflow-y:auto;"></div>
```

### 3.3. Polling pendant la session (optionnel)

Pour avoir un affichage quasi temps réel des transcriptions :

```javascript
let transcriptTimer = null;

function startTranscriptPolling() {
  if (transcriptTimer) return;
  transcriptTimer = setInterval(fetchTranscript, 1500);
}

function stopTranscriptPolling() {
  if (transcriptTimer) {
    clearInterval(transcriptTimer);
    transcriptTimer = null;
  }
}
```

**SmallWebRTC** – démarrer au moment de la connexion :

```javascript
pc.onconnectionstatechange = () => {
  if (pc.connectionState === "connected") startTranscriptPolling();
  else if (["disconnected", "failed", "closed"].includes(pc.connectionState)) stopTranscriptPolling();
};
```

**Daily** – démarrer au `joined-meeting` :

```javascript
callObject.on("joined-meeting", () => startTranscriptPolling());
callObject.on("left-meeting", () => stopTranscriptPolling());
```

### 3.4. Segments temps réel en mode `trigger_on_push`

En mode `trigger_on_push`, le serveur bufferise les segments STT jusqu'au `flush`, mais en parallèle il renvoie chaque segment **dès qu'il est reconnu** via le canal applicatif du transport.

Pour déclencher ce `flush`, le client doit envoyer un **message applicatif JSON avec `type` égal à `"flush"`** sur le même canal que les autres messages applicatifs :

- Côté SmallWebRTC : via le data channel `pipecat-app` :

  ```javascript
  dc.send(JSON.stringify({ type: "flush" }));
  ```

- Côté Daily : via un app-message :

  ```javascript
  callObject.sendAppMessage({ type: "flush" }, "*");
  ```

> ⚠️ D'autres valeurs comme `"trigger_flush"` ne sont **pas** interprétées par le serveur et ne déclenchent pas le flush.

- Côté SmallWebRTC : les segments sont envoyés sur le **data channel** `pipecat-app`.
- Côté Daily : les segments arrivent sous forme d'**app-messages** (`callObject.on("app-message")`).

Le format des messages est identique dans les deux cas :

```json
{
  "type": "buffered_transcript",
  "text": "segment de transcription",
  "segment_index": 3,
  "conversation_id": "uuid-de-la-conversation"
}
```

#### SmallWebRTC – écouter les segments sur le data channel

```javascript
const dc = pc.createDataChannel("pipecat-app");

dc.onmessage = (event) => {
  try {
    const msg = JSON.parse(event.data);
    if (msg.type === "buffered_transcript") {
      // Afficher le segment au fil de l'eau
      displaySegment(msg.text, msg.segment_index);
    }
  } catch (e) {
    console.warn("Message datachannel non JSON:", event.data);
  }
};
```

#### Daily – écouter les segments via `app-message`

```javascript
const callObject = window.Daily.createCallObject();

callObject.on("app-message", (ev) => {
  const msg = ev.data;
  if (!msg || typeof msg !== "object") return;

  if (msg.type === "buffered_transcript") {
    displaySegment(msg.text, msg.segment_index);
  }
});
```

Ici `displaySegment(text, index)` est une fonction de votre UI (par exemple, ajouter une ligne dans une zone de transcript en temps réel).  

Le polling HTTP sur `GET /voice/transcript/{conversation_id}` reste recommandé pour :

- reconstruire l'historique complet (messages `user` / `assistant`),
- recharger une conversation plus tard,
- exporter les transcriptions.

### 3.5. Segments de réponse agent en temps réel

Les réponses de l'agent sont également découpées en plusieurs segments texte côté serveur (dans `LangGraphProcessor`) et envoyées au client au fur et à mesure de leur synthèse vocale.

Le format des messages est :

```json
{
  "type": "assistant_segment",
  "text": "phrase de la reponse agent",
  "segment_index": 2,
  "total_segments": 5,
  "conversation_id": "uuid-de-la-conversation"
}
```

#### SmallWebRTC – écouter les segments de réponse

```javascript
const dc = pc.createDataChannel("pipecat-app");

dc.onmessage = (event) => {
  try {
    const msg = JSON.parse(event.data);
    if (!msg || typeof msg !== "object") return;

    if (msg.type === "buffered_transcript") {
      displayUserSegment(msg.text, msg.segment_index);
    } else if (msg.type === "assistant_segment") {
      displayAssistantSegment(msg.text, msg.segment_index, msg.total_segments);
    }
  } catch (e) {
    console.warn("Message datachannel non JSON:", event.data);
  }
};
```

#### Daily – écouter les segments de réponse

```javascript
const callObject = window.Daily.createCallObject();

callObject.on("app-message", (ev) => {
  const msg = ev.data;
  if (!msg || typeof msg !== "object") return;

  if (msg.type === "buffered_transcript") {
    displayUserSegment(msg.text, msg.segment_index);
  } else if (msg.type === "assistant_segment") {
    displayAssistantSegment(msg.text, msg.segment_index, msg.total_segments);
  }
});
```

Comme pour les segments STT, ces messages sont complémentaires au polling HTTP :

- les segments `assistant_segment` offrent une vue temps réel, synchronisée grossièrement avec la voix,
- l'endpoint `GET /voice/transcript/{conversation_id}` fournit l'historique complet structuré `user` / `assistant`.

---

## 4. Paramètres VAD (Voice Activity Detection)

Les paramètres VAD contrôlent la détection de la parole et la fin de phrase. Ils peuvent être définis :

1. **À la connexion** – via `request_data` dans le body du `POST /voice/offer` (SmallWebRTC) ou `POST /voice/daily-start` (Daily).
2. **En cours de session** (SmallWebRTC uniquement) – via le **data channel** WebRTC et des messages de type `update_vad`.

### 4.1. Paramètres disponibles

| Paramètre       | Clé JSON          | Bornes      | Défaut | Description                                                                 |
|-----------------|-------------------|-------------|--------|-----------------------------------------------------------------------------|
| Silence fin     | `vad_stop_secs`   | 0.2 – 2.0 s | 0.2    | Durée de silence avant de considérer que l'utilisateur a fini de parler.   |
| Début parole    | `vad_start_secs`  | 0.1 – 0.5 s | 0.2    | Durée de parole minimale avant de confirmer le début.                      |
| Confiance       | `vad_confidence`  | 0.5 – 0.95  | 0.7    | Seuil de confiance pour la détection de voix (0–1).                        |
| Volume minimal  | `vad_min_volume`  | 0.3 – 0.9   | 0.6    | Seuil de volume minimal pour la détection de parole (0–1).                 |

**Conseils** : Pour éviter que le STT se déclenche trop tôt (couper la parole), augmenter `vad_stop_secs` (par ex. 0.8 ou 1.0 s).

### 4.2. À la connexion : `request_data` dans le POST

**SmallWebRTC** : inclure un objet `request_data` dans le body du `POST /voice/offer`.

**Daily** : inclure `request_data` dans le body du `POST /voice/daily-start` :

```javascript
await fetch("/voice/daily-start?model=...", {
  method: "POST",
  headers: { "Content-Type": "application/json", "Authorization": "Bearer " + jwt },
  body: JSON.stringify({
    request_data: { vad_stop_secs: 0.8, vad_start_secs: 0.2, vad_confidence: 0.7, vad_min_volume: 0.6 },
  }),
});
```

**SmallWebRTC – exemple complet** :

```javascript
const body = {
  sdp: pc.localDescription.sdp,
  type: pc.localDescription.type,
};

// Paramètres VAD optionnels (valeurs par défaut si absents)
body.request_data = {
  vad_stop_secs: 0.8,
  vad_start_secs: 0.2,
  vad_confidence: 0.7,
  vad_min_volume: 0.6,
};

const res = await fetch("/voice/offer", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer " + token,
  },
  body: JSON.stringify(body),
});
```

**Format alternatif** : les paramètres peuvent aussi être imbriqués sous `vad` :

```javascript
body.request_data = {
  vad: {
    vad_stop_secs: 0.8,
    vad_start_secs: 0.2,
  },
};
```

### 4.3. Pendant la session : data channel + `update_vad`

Pour modifier les paramètres VAD sans se reconnecter :

1. **Créer un data channel** avant `createOffer()` :

```javascript
const dc = pc.createDataChannel("pipecat-app");

let dataChannel = null;
dc.onopen = () => { dataChannel = dc; };
dc.onerror = (e) => console.warn("Data channel error", e);
dc.onclose = () => { dataChannel = null; };

await pc.setLocalDescription(await pc.createOffer());
```

2. **Envoyer un message de mise à jour** une fois le data channel ouvert :

```javascript
function sendVadUpdate(params) {
  if (!dataChannel || dataChannel.readyState !== "open") return;

  const message = {
    type: "update_vad",
    params: params,
  };
  dataChannel.send(JSON.stringify(message));
}

// Exemple : augmenter le silence requis pour fin de phrase
sendVadUpdate({
  vad_stop_secs: 1.0,
  vad_start_secs: 0.2,
  vad_confidence: 0.7,
  vad_min_volume: 0.6,
});
```

Les paramètres partiels sont acceptés : seuls les champs présents sont mis à jour, les autres restent inchangés.

```javascript
sendVadUpdate({ vad_stop_secs: 1.2 }); // Met à jour uniquement vad_stop_secs
```

### 4.4. Validation et bornes côté client (recommandé)

Pour éviter des valeurs hors bornes, valider et contraindre avant envoi :

```javascript
function clamp(val, min, max, fallback) {
  const n = parseFloat(val);
  return isNaN(n) ? fallback : Math.min(max, Math.max(min, n));
}

function buildVadParams(formValues) {
  return {
    vad_stop_secs: clamp(formValues.stop, 0.2, 2.0, 0.8),
    vad_start_secs: clamp(formValues.start, 0.1, 0.5, 0.2),
    vad_confidence: clamp(formValues.confidence, 0.5, 0.95, 0.7),
    vad_min_volume: clamp(formValues.volume, 0.3, 0.9, 0.6),
  };
}
```

### 4.5. Exemple d'UI complète (HTML + JS)

```html
<div class="vad-section">
  <label>VAD – Paramètres</label>
  <div>
    <label for="vad-stop-secs">Silence fin phrase (s)</label>
    <input id="vad-stop-secs" type="number" min="0.2" max="2" step="0.1" value="0.8">
  </div>
  <div>
    <label for="vad-start-secs">Début parole (s)</label>
    <input id="vad-start-secs" type="number" min="0.1" max="0.5" step="0.05" value="0.2">
  </div>
  <div>
    <label for="vad-confidence">Confiance</label>
    <input id="vad-confidence" type="number" min="0.5" max="0.95" step="0.05" value="0.7">
  </div>
  <div>
    <label for="vad-min-volume">Volume min.</label>
    <input id="vad-min-volume" type="number" min="0.3" max="0.9" step="0.05" value="0.6">
  </div>
  <button id="btn-update-vad">Appliquer VAD</button>
</div>
```

```javascript
const vadInputs = {
  stop: document.getElementById("vad-stop-secs"),
  start: document.getElementById("vad-start-secs"),
  confidence: document.getElementById("vad-confidence"),
  volume: document.getElementById("vad-min-volume"),
};

function buildRequestData() {
  return buildVadParams({
    stop: vadInputs.stop?.value,
    start: vadInputs.start?.value,
    confidence: vadInputs.confidence?.value,
    volume: vadInputs.volume?.value,
  });
}

document.getElementById("btn-update-vad")?.addEventListener("click", () => {
  sendVadUpdate(buildRequestData());
});
```

---

## 5. Intégration dans d'autres types de clients

Les mêmes principes s'appliquent à d'autres environnements :

- **Web** : SmallWebRTC (`/voice/offer`) ou Daily (`/voice/daily-start`) selon la connectivité.
- **Mobile natif** (iOS/Android) :
  - **SmallWebRTC** : librairie WebRTC native, peer connection, ICE, `/voice/offer`, data channel `pipecat-app` pour les mises à jour VAD.
  - **Daily** : SDK Daily natif (`daily-co/react-native-daily-js` ou équivalent), `/voice/daily-start`.
- **Applications desktop / backend** : idem, tant que le client sait établir une connexion WebRTC (ou rejoindre une room Daily) et faire des appels HTTP.

La partie serveur encapsule toute la logique Pipecat (STT, LangGraph, TTS, transcripts, VAD).  
Le client n'a besoin que :

- d'une implémentation WebRTC (ou du SDK Daily pour le transport Daily),
- d'un client HTTP pour `POST /auth/token`, `POST /voice/offer` ou `POST /voice/daily-start`, et `GET /voice/transcript/{conversation_id}`,
- de suivre les étapes décrites ci‑dessus.