> ## Documentation Index
> Fetch the complete documentation index at: https://docs.syntheo.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Dépannage

> Résoudre les problèmes courants : serveurs de transcription et de synthèse injoignables, HTTPS, liste de modèles vide, audio sous Linux et Windows, installation.

Choisissez votre symptôme dans le vérificateur ci-dessous. Il liste les points à vérifier et ouvre l'écran concerné de l'application : la carte du serveur, l'écran « Autorisations », la section « Audio » des réunions, ou une note en écoute. Pour « La transcription s'arrête pendant la réunion », changez la cause simulée, puis cliquez sur « Rétablir le réseau ». Les sections de la page détaillent chaque cas.

## Le serveur de transcription ou de synthèse est injoignable

Syntheo ne contient aucun modèle : il dépend entièrement des serveurs dont vous avez saisi l'adresse dans **Paramètres → Transcription** et **Paramètres → Synthèse**.

Commencez par cliquer sur « Tester la connexion » dans la carte du serveur. La pastille d'état et le message affiché disent quoi vérifier : « Injoignable », « Clé refusée » ou « Adresse invalide ». Voir [La carte serveur](https://docs.syntheo.studio/ai-setup.md#la-carte-serveur).

Vérifiez dans l'ordre :

1. **Le serveur tourne.** Depuis l'ordinateur où Syntheo est installé, interrogez-le directement :

   ```bash theme={null}
   curl http://localhost:8000/v1/models
   ```

   Remplacez l'URL par celle de votre serveur. Ajoutez `-H "Authorization: Bearer <clé>"` si votre serveur exige une clé.

2. **L'URL de base est complète.** Pour un serveur OpenAI-compatible, elle se termine en général par `/v1` (par exemple `http://localhost:8000/v1`), sans `/models` ni `/chat/completions` à la fin. Pour un serveur NVIDIA NIM, indiquez l'adresse du serveur, par exemple `http://localhost:9000/v1/realtime`.

3. **L'URL ne contient ni identifiant, ni paramètre.** Syntheo refuse une URL de la forme `https://utilisateur:motdepasse@…` ou contenant `?…`. Saisissez la clé dans le champ prévu.

4. **La clé d'API est la bonne.** Si le serveur répond 401 ou 403, la pastille indique « Clé refusée ». Vérifiez la clé dans « Avancé », puis relancez le test.

5. **Aucun pare-feu, VPN ou proxy ne bloque le port** entre votre poste et le serveur.

Si le serveur de synthèse répond mais que le modèle choisi échoue, **Paramètres → Synthèse** affiche « Le modèle choisi n'a pas répondu : » suivi de la cause.

## Syntheo exige HTTPS

Syntheo accepte une URL en `http://` uniquement pour un serveur situé sur votre poste ou sur un réseau privé :

* `localhost`, `127.x.x.x` et `[::1]` ;
* les noms se terminant par `.local` ;
* les adresses privées `10.x.x.x`, `172.16.x.x` à `172.31.x.x` et `192.168.x.x` ;
* la plage `100.64.x.x` à `100.127.x.x` (utilisée notamment par Tailscale) ;
* les noms Tailscale (MagicDNS) se terminant par `.ts.net`.

Pour toute autre adresse, y compris un nom de domaine interne comme `serveur.entreprise.lan`, utilisez `https://`. Sinon, Syntheo refuse l'URL avec le message « Utilisez HTTPS : le HTTP n'est accepté que sur cette machine ou un réseau privé. ». Placez votre serveur derrière un proxy inverse avec un certificat (Caddy, nginx, Traefik), ou utilisez directement son adresse IP privée.

## La liste des modèles est vide

Syntheo lit les modèles de votre serveur dans `/v1/models` quand vous cliquez sur « Tester la connexion ». Tant que le test n'a pas réussi, la carte affiche « Testez la connexion pour lister les modèles servis. ».

* **Le test échoue.** Reprenez la première section de cette page. Syntheo attend la réponse 8 secondes au plus.
* **Le test réussit, mais aucun modèle n'apparaît.** Vérifiez qu'un modèle est bien chargé, par exemple avec `curl <adresse>/models`. Avec Ollama, téléchargez un modèle avant de le sélectionner. Avec LM Studio, chargez-en un dans le serveur local.
* **Votre modèle n'est pas dans la liste.** Cliquez sur « Saisir un autre nom » et tapez l'identifiant exact du modèle servi par votre déploiement.

Un serveur NVIDIA NIM ne publie pas sa liste de modèles. Syntheo propose les identifiants connus (`nemotron-asr-streaming`, `parakeet-tdt-0.6b-v3`…) ; choisissez celui de votre déploiement.

## La transcription s'arrête pendant la réunion

Si le serveur de transcription se coupe ou devient injoignable, Syntheo affiche en bas de la marge de transcription un message qui donne la cause probable, par exemple :

> Transcription en direct en pause : vous êtes hors ligne. Aucun audio n'est conservé : ce passage manquera à la transcription. Reconnexion…

Les causes possibles sont : vous êtes hors ligne, le serveur a refusé votre clé d'API, il a refusé les réglages de transcription, il subit une panne, Syntheo ne parvient pas à le joindre, ou il n'envoie plus de texte.

* **Coupure réseau ou panne du serveur** : Syntheo tente de se reconnecter automatiquement. Quand le flux revient, il affiche brièvement « Transcription en direct reprise. ».
* **Clé ou réglages refusés** : Syntheo ne retente pas la connexion. Le message se termine par « Vérifiez les réglages du serveur de transcription. ». Corrigez la clé ou le modèle dans **Paramètres → Transcription**, puis relancez l'écoute.

Syntheo ne conserve pas l'audio. Ce qui a été dit pendant la coupure ne peut donc pas être transcrit après coup. Au-dessus de la transcription, un bandeau indique les périodes manquantes, par exemple « Transcription interrompue 14:32–14:35. ». Si les horaires ne sont pas connus, le bandeau indique « Cette transcription est incomplète. ».

Pour limiter ces trous, vérifiez la stabilité du réseau entre votre poste et le serveur, ainsi que la charge du serveur (mémoire GPU, nombre de sessions simultanées).

## Il manque du son : microphone ou audio système

Ouvrez l'écran « Autorisations » :

<ol />

Sous Linux et Windows, la section « Audio » affiche deux lignes :

* « Microphone » : votre voix ;
* « Audio système » : la voix des autres participants.

Syntheo teste réellement chaque source audio. Une ligne en rouge signifie que le test a échoué. Corrigez la cause, puis cliquez sur la flèche de la ligne pour relancer le test. Sous Linux et Windows, ce bouton n'ouvre pas les réglages du système.

Vérifiez ensuite la section « Audio » de l'écran « Réunions » :

<ol />

* « Microphone » et « Son système » indiquent le micro et la sortie captés, avec leur niveau sonore en direct. Choisissez sous « Son système » la sortie où vous entendez les autres participants ; « Capturé en ce moment : » donne la sortie réellement captée. Le choix s'applique à la prochaine écoute. Voir [Enregistrer une réunion](https://docs.syntheo.studio/meetings.md), section « Choisir le micro et la sortie captée ».
* Si une source a été coupée pendant l'écoute, son icône est barrée sur fond rouge dans la capsule. Rétablissez-la d'un clic, ou avec  (micro) et  (son système).

> [tab] Linux
>
> Syntheo capte l'audio système via **PipeWire**, ou via **PulseAudio** si PipeWire n'est pas disponible.
>
> * Vérifiez que le serveur son tourne :
>
>   ```bash theme={null}
>   pactl info
>   ```
>
>   Sur une distribution récente, la ligne « Server Name » mentionne PipeWire. Si la commande échoue, installez et démarrez `pipewire-pulse` (ou PulseAudio).
>
> * Syntheo capte le retour (« Monitor of… ») de la sortie choisie sous « Son système », ou de la sortie par défaut si vous n'en choisissez pas. Avec PipeWire, il suit la sortie par défaut quand elle change, par exemple quand vous branchez un casque. Si Syntheo capte la mauvaise sortie (HDMI de la carte graphique, par exemple), choisissez la bonne sous « Son système ».
>
> * Vérifiez que le microphone et la source de retour de la sortie audio (« Monitor of… ») existent :
>
>   ```bash theme={null}
>   pactl list short sources
>   ```
>
> * Si le microphone n'apparaît pas, vérifiez qu'il n'est pas coupé ou attribué à une autre carte son, par exemple avec `pavucontrol`.
>
> * Si l'audio fonctionne dans d'autres applications mais pas dans Syntheo, notez la distribution, l'environnement de bureau et la version de Syntheo pour le signalement.

> [tab] Windows
>
> * Ouvrez **Paramètres Windows → Confidentialité et sécurité → Microphone**. Activez l'accès au microphone, puis « Autoriser les applications de bureau à accéder à votre microphone ».
> * Vérifiez dans **Paramètres → Système → Son** que le bon périphérique d'entrée est sélectionné et qu'il capte du son.
> * L'audio système est capté par bouclage (loopback) sur la sortie choisie sous « Son système », ou sur la sortie par défaut si vous n'en choisissez pas. Si la sortie choisie est débranchée, Syntheo bascule sur la sortie par défaut, puis revient à la sortie choisie quand elle est rebranchée, sans interrompre l'écoute. Si les autres participants restent absents, vérifiez que l'application de réunion joue le son sur cette sortie, et qu'il passe bien par un périphérique audio de Windows (et pas par un pilote propriétaire qui le contourne).

## Windows affiche un avertissement SmartScreen

L'installeur Windows `.exe` est signé. Windows SmartScreen peut tout de même afficher « Windows a protégé votre ordinateur » tant que la signature n'a pas acquis assez de réputation auprès de Microsoft.

1. Vérifiez que vous avez téléchargé le fichier depuis la [page des versions GitHub](https://github.com/WillIsback/Syntheo/releases/latest).
2. Cliquez sur **Informations complémentaires** et vérifiez l'éditeur affiché.
3. Cliquez sur **Exécuter quand même**.

N'installez jamais un installeur obtenu par un autre canal.

## L'application ne s'ouvre pas après l'installation sous Linux

Rendez l'AppImage exécutable avant de la lancer :

```bash theme={null}
chmod +x ./syntheo-*.AppImage
```

Pour Debian ou Ubuntu, installez le paquet avec `sudo apt install ./syntheo-*.deb` afin que le gestionnaire de paquets résolve les dépendances. Voir [Installer l'application](https://docs.syntheo.studio/desktop-installation.md).

## Sous Linux, la fenêtre reste noire

Au premier lancement, Syntheo ouvre l'accueil guidé, sur un fond clair (ou sombre, selon votre thème) avec le titre « Bienvenue sur Syntheo ». Si la fenêtre s'ouvre mais reste entièrement noire, sans aucun texte, WebKitGTK n'a en général pas réussi à la dessiner, le plus souvent sous Wayland avec une carte NVIDIA.

Syntheo utilise l'accélération graphique de WebKit, bien plus fluide. Sur certaines combinaisons de carte graphique et de compositeur, le rendu DMA-BUF de WebKit peut laisser une fenêtre noire. Lancez alors :

```bash theme={null}
WEBKIT_DISABLE_DMABUF_RENDERER=1 ./syntheo-*.AppImage
```

Si elle reste encore noire, désactivez aussi la composition :

```bash theme={null}
WEBKIT_DISABLE_DMABUF_RENDERER=1 WEBKIT_DISABLE_COMPOSITING_MODE=1 ./syntheo-*.AppImage
```

Signalez-nous le problème en indiquant votre carte graphique, la version de son pilote et votre environnement de bureau.

La même variable fonctionne avec la commande `syntheo` installée par le paquet `.deb`.

## Aucun compte rendu n'apparaît

Un compte rendu nécessite un serveur de synthèse. Ouvrez **Paramètres → Synthèse**, vérifiez que la pastille indique « Connecté », puis choisissez un modèle sous « Modèle ». Si le serveur est injoignable, reprenez la première section de cette page.

## Un fichier importé ne donne rien

Les imports audio acceptent WAV, MP3, OGG, MP4, M4A, FLAC, WebM et AAC. Les imports de transcription acceptent SRT et VTT.

Pour un fichier audio, votre serveur de transcription doit être configuré. Avec le moteur « OpenAI · temps réel et par lots », il doit exposer `/v1/audio/transcriptions`. Avec « NVIDIA NIM · WebSocket », l'import passe par le flux en temps réel `/v1/realtime` : comptez au moins un quart de la durée de l'enregistrement. Voir [Importer un enregistrement](https://docs.syntheo.studio/import-recordings.md).

## Obtenir de l'aide

[Ouvrez une issue GitHub](https://github.com/WillIsback/Syntheo/issues) en indiquant :

* votre système d'exploitation et sa version ;
* la version de Syntheo ;
* le message d'erreur exact ;
* ce que vous attendiez, et les étapes les plus courtes pour reproduire le problème ;
* pour un problème d'IA, le type de serveur (vLLM, Ollama, NIM…) et le modèle utilisé.

Si besoin, joignez le journal `app.log` de l'application, situé dans le dossier `logs` des données de l'application (sous Windows : `%LOCALAPPDATA%\fr.willisback.syntheo\logs`). Relisez-le avant de le partager.

Les messages de la console de l'interface y apparaissent sous la forme `webview_console_event`, sans leur contenu : seuls le nombre d'arguments, l'étiquette du module qui les émet (par exemple `diagnostic="[speaker-context] error=Error(ERR_SQLITE_ERROR)"`) ainsi que le type et le code d'une erreur sont conservés. Le texte du message, celui des erreurs et toute autre valeur ne sont jamais écrits dans le journal.

> [!WARNING]
>
> Ne publiez jamais de clé API, de contenu de réunion ni l'adresse interne de vos serveurs dans une issue publique.

Pour les erreurs de la CLI et du serveur MCP, consultez la [référence des erreurs](https://docs.syntheo.studio/reference/errors.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.