--- title: Synapx Speech Markup — le langage de balisage de la parole source: https://synapx.fr/sdk/Ssm/ site: SynapxLab --- # Synapx Speech Markup — la partition qui pilote n'importe quel moteur de voix ## Présentation Synapx Speech Markup (SSM) est une notation ouverte qui décrit *comment* un texte doit être dit — dynamique, rythme, émotion, voix, prononciation, ambiance — sans dépendre d'un moteur de synthèse. Un document SSM reste un Markdown ordinaire, enrichi de directives entre crochets : `[lent]`, `[joie=1.4]`, `[pause=700ms]`. Ce que Markdown est au HTML, SSM l'est à la parole. La spécification fixe la grammaire des directives, leur portée et leur héritage. Deux implémentations de référence la traduisent en audio, `@synapxlab/voice` pour Piper et un compilateur pour l'API OpenAI ; c'est ce second chemin que détaille cette page. ## Le problème des contrôles de voix Chaque moteur de synthèse vocale impose son propre format de contrôle : SSML verbeux pour les uns, balises propriétaires pour les autres, rien du tout ailleurs. Une partition écrite pour un moteur ne se relit pas chez un autre. L'API audio d'OpenAI pousse ce constat à la limite : `gpt-4o-mini-tts` n'accepte ni SSML ni balisage inline, seulement un champ `instructions` en langage naturel, appliqué globalement à toute la requête. Impossible d'y faire varier le ton à l'intérieur d'un même appel. SSM répond en amont du moteur : la partition est écrite une seule fois dans le texte, et un compilateur la découpe en segments dont il traduit l'état de voix en instructions distinctes, un appel par segment. ## La partition Une directive s'ouvre par `[nom]` ou `[nom=valeur]` et se referme par `[/nom]` ou `[/]`. Plusieurs axes peuvent se combiner dans un même crochet, séparés par des virgules : `[piano, lent]texte[/]` équivaut à `[piano][lent]texte[/lent][/piano]`. Des axes différents se cumulent, la plus récente l'emporte sur un même axe, et une directive non fermée se referme automatiquement à la fin du bloc Markdown englobant. ```text Il murmura : [pp, confidence]« Encore une nuit. »[/] [pause=700ms] Puis la lampe s'alluma. [perso=Marie][joie=1.4]« Le bateau est rentré ! »[/joie][/perso] ``` `[pp, confidence]` combine un volume à peine audible et un registre de confidence. `[pause=700ms]` insère un silence explicite entre deux répliques. `[perso=Marie]` assigne un passage à un personnage nommé, et `[joie=1.4]` y superpose une émotion à intensité renforcée — échelle `0.0` à `2.0`, défaut `1.0`. ## Compilation vers l'API OpenAI Le compilateur `OpenAiDirector` traduit chaque état de voix résolu en une phrase d'instruction, préfixée par une consigne de base commune : « Lis ce texte en français, avec une diction naturelle et non robotique. » Les segments consécutifs aux instructions identiques sont fusionnés en un seul appel. | Partition | `input` | `instructions` | |---|---|---| | `[pp]« Encore une nuit. »[/pp]` | « Encore une nuit. » | …Parle à peine audible, presque soufflé. | | `[lent]Le gardien gravit l'escalier.[/lent]` | Le gardien gravit l'escalier. | …Parle lentement. | | `[perso=Marie][joie=1.4]…` | … | …Ce passage est dit par le personnage Marie : garde un timbre stable et reconnaissable pour lui. Colore la voix d'une intention de joie très marquée. | | `[dis:Païpeur]Piper[/dis]` | Païpeur | (inchangé) | | `[pause=700ms]` | aucun appel | silence planifié entre deux segments | Les directives de production — ambiance, bruitage, musique, effets spatiaux — n'apparaissent dans aucune `instructions` : l'API OpenAI n'a aucune prise sur un fond sonore, et le compilateur les écarte plutôt que de tenter de les décrire en mots. ## Compilation vers le moteur local Piper `@synapxlab/voice`, moteur local fondé sur Piper, constitue l'implémentation de référence de niveau L1. Il traduit les mêmes axes de performance — dynamique, tempo, hauteur, prosodie, prononciation — en paramètres directs du moteur : la dynamique par atténuation du gain, le tempo par un facteur de durée, une pause par un silence inséré, une directive de prononciation par une réécriture du texte lu. Cette notation « partition » a précédé SSM : sa généralisation a donné naissance à la spécification indépendante de tout moteur. ## Les deux couches et la dégradation gracieuse La spécification distingue une couche performance, que tout moteur texte-vers-parole peut interpréter seul, d'une couche production, réservée à un moteur de mixage capable de superposer ambiances, bruitages et musique à la voix. Un compilateur vers une API TTS pure, comme celui pour OpenAI, ne rend que la première. Cette distinction s'appuie sur une règle centrale : une directive inconnue ou hors périmètre est ignorée silencieusement, jamais remontée en erreur. Une partition écrite pour un moteur studio complet reste ainsi utilisable telle quelle sur une API plus limitée ; elle y perd seulement ce que cette API ne sait pas rendre. ## Le registre v1.0 Le registre normatif organise les directives par niveau de conformité : - **L1 — Prosodie.** Dynamique, tempo, hauteur, pauses, prononciation, section `# Voice` lue mais retirée des rendus visuels : le socle qu'un TTS pur (Piper, Kokoro, Coqui) doit interpréter. - **L2 — Expressif.** Émotions à intensité réglable, registres de narration, sélection de voix, changement de langue : le niveau d'un moteur expressif ou multi-voix. - **L3 — Studio.** Bruitages, ambiances, musique, effets audio et spatialisation : le niveau d'un moteur de production complet. Les deux implémentations de référence déclarent chacune leur profil : L2 pour le compilateur OpenAI, L1 pour le moteur Piper. ## Écrire une partition avec un modèle de langage Un document SSM reste un Markdown ordinaire : un modèle de langage peut en générer un directement, en respectant trois règles. Les axes se cumulent mais un même axe ne garde que sa valeur la plus récente. Une directive ouverte se referme au plus tard à la fin du paragraphe qui la porte. Enfin, une directive mal orthographiée ou inconnue n'interrompt jamais la génération : elle est simplement ignorée, ce qui rend la notation tolérante aux approximations d'un modèle. ## Spécification et clients de référence La spécification complète et les tableaux de correspondance avec SSML figurent dans le dépôt public `synapxLab/synapx-speech-markup`, sous licence MIT. Deux clients de référence y sont maintenus : PHP (PSR-4, 8.1 et plus) et JavaScript sans dépendance (Node 18 et plus), tous deux capables d'analyser une partition et de la compiler vers l'API audio d'OpenAI.