@mostajs/prononciation 0.0.0-stage → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,43 @@
+# Changelog — @mostajs/prononciation
+
+**Auteur** : Dr Hamid MADANI <drmdh@msn.com>
+Format : Keep a Changelog ; versions : SemVer.
+
+## [0.2.0] — 2026-10-25
+
+### Ajouté
+- **Le service de reconnaissance** (`service/`, Python ≥ 3.10), livré avec le module :
+  - `POST /reconnaitre` sert le contrat de `reconnaisseurHttp` ; `GET /sante` le décrit ;
+  - wav2vec2 phonémique à révision figée, et dépendances figées (`requirements.txt`) ;
+  - alignement forcé CTC et 8 traits par son attendu, repris d'`extraire_gop.py`.
+- **Refus nommés** : ATTENDUS, AUDIO_ABSENT, LONGUEUR, TROP_GROS, TROP_LONG, FORMAT, CHEMIN, METHODE, INTERNE.
+- **Fonctionnement** : écoute locale par défaut, une inférence à la fois. L'audio n'est jamais écrit, et le journal ne contient que des comptes et des durées.
+- **`service/installer.sh`** : rejouable, il vérifie que le modèle se charge sans réseau.
+- **Essais** :
+  - T-SRV-1 à 9 (unittest). Parité avec l'apprentissage sur cinq phrases : écart de traits **nul**.
+  - T-PRO-23 : le service réel derrière `reconnaisseurHttp` rend la note de Python.
+
+### Corrigé
+- Quand l'audio a moins de trames que de sons attendus, le partage égal débordait de l'audio, et un trait se calculait sur un segment vide. Les segments sont désormais ramenés sur la dernière trame. Les cas du corpus ne changent pas : la parité le vérifie.
+
+### Points ouverts
+- Le WebM/Opus enregistré par les navigateurs n'est pas lu. Il faut l'enregistreur WAV de `@mostajs/media` (B-03).
+- Le débit reste à mesurer sur le serveur de production (amia).
+
+## [0.1.0] — 2026-10-25
+
+### Ajouté
+- `createPrononciation({ lexique, reconnaisseur, note?, seuils?, regle?, limites? })`, avec `evaluer({ texte, audio })` et `attendus(texte)`.
+- Lexiques : `creerLexique` (IPA ou ARPAbet), `lexiqueCmudict`, `combinerLexiques` ; `arpaVersIpa`, `motsDe`.
+- Alignement `aligner` : états juste, faux, omis ; sons en face ; insertions. Règles `stricte-2` et `tolerante-2`, et `normaliserJetons` pour les sorties d'espeak. Parité avec l'aligneur Python mesuré, sur 600 cas.
+- Note simple, et note apprise `NOTE_APPRISE_1` : réseau 64-64-1 par son, ridge par phrase. Parité avec Python à 10⁻³ près. Seuils par défaut : 7,5, 1,5 et 1,5.
+- `resistances(resultats, { minEssais })`.
+- Adaptateurs `reconnaisseurFixe` et `reconnaisseurHttp` (contrat HTTP fixé).
+- `ErreurPrononciation`, `CODES`, `LIBELLES` : huit codes nommés.
+- Bornes : taille de l'audio et nombre de mots.
+- Exemple de vérification `examples/verifier.mjs` : trois phrases de speechocean762.
+
+### Points ouverts
+- Le service Python de reconnaissance (wav2vec2, traits GOP) est prévu pour la 0.2.0.
+- Les poids sont appris sur des voix chinoises : remesure sur des voix algériennes (lot 0, tâche 0.4).
+- Les renvois `ne_fait_pas` vers `@mostajs/voix`, `prononciation-ui` et `consentement` visent des modules prévus, pas encore créés.

package/LICENSE

@@ -0,0 +1,15 @@
+@mostajs/prononciation
+Copyright (C) 2026 Dr Hamid MADANI <drmdh@msn.com>
+
+This program is free software: you can redistribute it and/or modify it under
+the terms of the GNU Affero General Public License as published by the Free
+Software Foundation, either version 3 of the License, or (at your option) any
+later version.
+
+This program is distributed in the hope that it will be useful, but WITHOUT
+ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more
+details.
+
+You should have received a copy of the GNU Affero General Public License
+along with this program. If not, see <https://www.gnu.org/licenses/agpl-3.0.html>.

package/README.md

@@ -1,3 +1,73 @@
-# Temporary Holding Version
+# @mostajs/prononciation
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Auteur** : Dr Hamid MADANI <drmdh@msn.com> · AGPL-3.0-or-later · zéro dépendance · Node ≥ 18
+
+Ce module dit si une voix a prononcé un texte connu, et où elle s'en écarte, son par son. Il fournit :
+- une note par son, par mot et par phrase ;
+- un verdict au seuil ;
+- la liste des sons qui résistent dans une classe.
+
+## Installer
+
+```bash
+npm install @mostajs/prononciation
+bash node_modules/@mostajs/prononciation/service/installer.sh   # le service de reconnaissance (0.2.0), voir service/README.md
+```
+
+Le service de reconnaissance (Python, wav2vec2) est livré avec le module, dans `service/`. Il écoute en local, et `reconnaisseurHttp` en est le client.
+
+## Exemple minimal
+
+```js
+import { createPrononciation, lexiqueCmudict, combinerLexiques, creerLexique,
+         reconnaisseurHttp, NOTE_APPRISE_1, resistances } from '@mostajs/prononciation';
+import { readFileSync } from 'node:fs';
+
+const p = createPrononciation({
+  lexique: combinerLexiques(creerLexique({ BOUMERDES: 'b u m ɛ ɹ d ɛ s' }),
+                            lexiqueCmudict(readFileSync('cmudict.dict', 'utf8'))),
+  reconnaisseur: reconnaisseurHttp({ url: 'http://127.0.0.1:8762/reconnaitre', type: 'audio/wav' }),
+  note: NOTE_APPRISE_1,
+});
+
+const r = await p.evaluer({ texte: 'I would like a cup of tea.', audio });   // audio : Uint8Array
+r.verdict;                                             // 'accepte' | 'a-reprendre'
+r.mots.filter((m) => m.etat === 'a-reprendre');        // les mots à reprendre, avec leurs sons
+resistances(resultatsDeLaClasse, { minEssais: 3 });    // [{ phoneme: 'θ', essais, echecs, taux }, …]
+```
+
+Sans `note`, le module emploie la **note simple**, c'est-à-dire la part des sons retrouvés. Le résultat dit toujours le `mode` utilisé.
+
+## Ce qu'on injecte
+
+| port | forme | fourni par |
+|---|---|---|
+| `lexique` | `{ phonemes(mot) → string[] \| null }` | `creerLexique`, `lexiqueCmudict` (fichier BSD-2 fourni par l'application), `combinerLexiques` |
+| `reconnaisseur` | `{ reconnaitre({ audio, attendus }) → { entendus, traits?, duree? } }` | `reconnaisseurHttp` (service de reconnaissance local), `reconnaisseurFixe` (essais) |
+
+## Ce que vaut la note
+
+Mesures sur la partie test de speechocean762, faite de 2 500 phrases et de locuteurs absents de l'apprentissage (Pearson avec la note des juges) :
+
+| | note simple | note apprise | GOPT (ICASSP 2022) |
+|---|---|---|---|
+| phrase | 0,54 | **0,72** | 0,714 |
+| mot | — | **0,54** | 0,533 |
+| son | 0,35 | **0,56** | 0,612 |
+
+Les poids sont appris sur des voix d'apprenants chinois. Il faut les remesurer sur la population servie.
+
+## Vérifier
+
+```bash
+npm test                    # 23 essais (mjs-unit) + 9 essais du service (Python), parités comprises
+node examples/verifier.mjs  # trois vraies phrases, par le vrai adaptateur HTTP
+```
+
+## Attribution
+
+Les poids `note-apprise-1` sont appris sur **speechocean762** (Zhang et al., 2021), sous licence CC BY 4.0 : https://www.openslr.org/101. Le modèle acoustique visé est `facebook/wav2vec2-lv-60-espeak-cv-ft` (Apache-2.0).
+
+## Référence
+
+L'API complète est dans `llms.txt`.

package/llms.txt

@@ -0,0 +1,79 @@
+# @mostajs/prononciation 0.1.0 — fiche LLM
+# Auteur : Dr Hamid MADANI <drmdh@msn.com> · AGPL-3.0-or-later · N1 générique, forme moteur, zéro dépendance
+
+RÔLE
+Comparer une voix à un texte CONNU. Le module :
+- tire du texte les sons attendus (lexique injecté) ;
+- obtient du reconnaisseur injecté les sons entendus, et éventuellement les traits GOP ;
+- aligne les deux suites ;
+- note chaque son (0-2), chaque mot (0-2) et la phrase (0-10) ;
+- rend un verdict au seuil ;
+- agrège les sons qui résistent.
+Le module ne garde rien : pas de dépôt, pas de table, pas d'audio.
+
+QUESTION
+Cette phrase a-t-elle été bien dite, et quel son faut-il reprendre ?
+
+EXPORTS (src/index.js)
+createPrononciation({ lexique, reconnaisseur, note?, seuils?, regle?, limites? }) → { evaluer, attendus, seuils, regle, mode }
+  evaluer({ texte, audio }) → Promise<Resultat>      attendus(texte) → [{ mot, phonemes }]
+creerLexique(table)   table { MOT: 'k ʌ p' | 'K AH1 P' | ['k','ʌ','p'] } ; IPA ou ARPAbet détecté
+lexiqueCmudict(texte) texte du fichier CMUdict (BSD-2), fourni par l'application ; 1re variante gardée
+combinerLexiques(...lexiques)  le premier qui connaît le mot l'emporte (mots de l'enseignant d'abord)
+arpaVersIpa('AH0') → 'ʌ0'   normaliserJetons(jetons espeak) → classes   egal(attendu, entendu, regle)
+motsDe(texte) → ['I\'D', 'LIKE', …]
+aligner(attendus, entendus, { regle }) → { etats, entendus (en face, null si omis), insertions [{ apres, entendu }] }
+appliquerNote(note, { phonemes, etats, traits, nEntendus, duree }) → { notes (brutes), note (brute) }
+noteSimple(etats)   validerNote(note)
+resistances(resultats, { minEssais }) → [{ phoneme, essais, echecs, taux }] trié
+reconnaisseurFixe(reponse | ({ audio, attendus }) => reponse)          — essais
+reconnaisseurHttp({ url, fetch?, delaiMs = 15000, type? })              — client du service de reconnaissance
+NOTE_APPRISE_1 (aussi '@mostajs/prononciation/poids/note-apprise-1')   ErreurPrononciation, CODES, LIBELLES
+ARPA, PHONEMES (39 classes), REGLES ['stricte-2', 'tolerante-2']
+
+TYPES
+Resultat = { verdict: 'accepte'|'a-reprendre', note: 0-10, mode: 'apprise'|'simple', regle, seuils, poids?,
+             mots: [{ mot, note: 0-2, etat: 'juste'|'a-reprendre', insertions: string[],
+                      phonemes: [{ attendu, entendu|null, note: 0-2, etat: 'juste'|'faux'|'omis', aReprendre }] }],
+             attendus, entendus, duree? }
+Port lexique       { phonemes(mot) → string[] | null }   (sons IPA ; suffixe 0 = non accentué, AH0/IY0)
+Port reconnaisseur { reconnaitre({ audio, attendus }) → Promise<{ entendus: string[], traits?: number[8][], duree?: s }> }
+  traits par son ATTENDU : gop_moy, gop_max, fenetre_max, lpr_moy, lpr_max, duree (trames), fenetre (trames), blanc_moy
+Contrat HTTP : POST <url>, corps = octets de l'audio ; en-tête x-attendus = encodeURIComponent(JSON des sons attendus) ;
+  réponse 200 JSON { entendus, traits?, duree? }.
+
+SERVICE DE RECONNAISSANCE (0.2.0, service/, Python ≥ 3.10)
+Installer : bash service/installer.sh (venv, dépendances FIGÉES, wav2vec2 à la révision ae45363b ; PRONONCIATION_HF_HOME)
+Lancer    : HF_HOME=… service/.venv/bin/python service/serveur.py --local-seulement  → écoute http://127.0.0.1:8762
+  options --hote 127.0.0.1, --port 8762 (0 = libre), --fils 2, --octets 2000000, --secondes 15
+POST /reconnaitre → { entendus, traits, duree, regle: 'stricte-2', modele } ; GET /sante → { ok, modele, revision, regle, classes }
+Refus { erreur, message } : ATTENDUS 400, AUDIO_ABSENT 400 (vide ou < 0,25 s), LONGUEUR 411, TROP_GROS 413,
+  TROP_LONG 413, FORMAT 415 (WAV/FLAC/OGG ; pas WebM), CHEMIN 404, METHODE 405, INTERNE 500 → côté JS : RECONNAISSEUR 502
+Une inférence à la fois ; audio jamais écrit ; journal = comptes et durées seulement.
+Parité : traits identiques à l'apprentissage (T-SRV-9, écart 0) ; note de Python de bout en bout (T-PRO-23).
+Piège : la révision du modèle et les versions sont figées — en changer, c'est changer la note.
+
+NOTES ET SEUILS
+- Simple (aucune note configurée) : son = 2 si retrouvé, sinon 0 ; phrase = 10 × part retrouvée. Seuils : phrase 6, mot 1, son 1.
+- Apprise (note: NOTE_APPRISE_1) :
+  - par son, traits + état glouton + identité du son → réseau 64-64-1 ;
+  - par phrase, 9 agrégats → ridge ;
+  - seuils : phrase 7,5 ; mot 1,5 ; son 1,5.
+  Accord avec les juges sur la partie test de speechocean762 : phrase 0,72, mot 0,54, son 0,56 (GOPT publié : 0,714, 0,533, 0,612).
+- Un mot est « a-reprendre » si la moyenne de ses sons est sous seuils.mot ; un son est aReprendre sous seuils.phoneme.
+
+ERREURS (R-I) — ErreurPrononciation { code, statut }
+CONFIGURATION 400 · TEXTE_VIDE 400 · TEXTE_TROP_LONG 413 · MOT_INCONNU 422 (e.mots : tous les inconnus)
+AUDIO_ABSENT 400 · AUDIO_TROP_LONG 413 · RECONNAISSEUR 502 · TRAITS 502
+
+PIÈGES
+- Note apprise sans traits ni durée → TRAITS. Il n'y a JAMAIS de repli silencieux sur la note simple : lire r.mode.
+- Les poids note-apprise-1 sont appris sur des voix CHINOISES (speechocean762) : à remesurer sur la population servie.
+- Les sons entendus doivent être des CLASSES (normaliserJetons pour espeak) ; un symbole hors classe compte faux.
+- Bornes par défaut : 480 000 octets d'audio, 40 mots. Les fixer dans limites selon l'enregistreur.
+- Le module n'efface ni ne stocke l'audio : c'est à l'application de le faire.
+- Attribution : les poids dérivent de speechocean762 (CC BY 4.0, https://www.openslr.org/101). Citer le corpus.
+
+NE FAIT PAS
+faire entendre une phrase → @mostajs/voix · capter l'audio → @mostajs/media · ranger l'audio → @mostajs/storage
+enregistrer une note → @mostajs/gradebook · écrans → @mostajs/prononciation-ui · consentement → @mostajs/consentement

package/package.json

@@ -1,6 +1,79 @@
 {
   "name": "@mostajs/prononciation",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Compare une voix à un texte connu : sons attendus par un lexique injecté, sons entendus par un reconnaisseur injecté, alignement, note par son, mot et phrase (note apprise ou simple), verdict, et les sons qui résistent. Avec son service de reconnaissance (Python, wav2vec2), local.",
+  "license": "AGPL-3.0-or-later",
+  "author": "Dr Hamid MADANI <drmdh@msn.com>",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./poids/note-apprise-1": "./src/poids/note-apprise-1.js"
+  },
+  "files": [
+    "src",
+    "service",
+    "!service/.venv",
+    "!service/**/__pycache__",
+    "llms.txt",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "bash test-scripts/run-tests.sh"
+  },
+  "keywords": [
+    "mostajs",
+    "prononciation",
+    "pronunciation",
+    "pronunciation-assessment",
+    "goodness-of-pronunciation",
+    "gop",
+    "phoneme",
+    "speech",
+    "english",
+    "cmudict",
+    "wav2vec2",
+    "speech-recognition"
+  ],
+  "dependencies": {},
+  "devDependencies": {
+    "@mostajs/mjs-unit": "0.10.0"
+  },
+  "mostajs": {
+    "niveau": "N1",
+    "nature": "generique",
+    "reutilisabilite": "transverse",
+    "depend_de": [],
+    "question": "Cette phrase a-t-elle été bien dite, et quel son faut-il reprendre ?",
+    "forme": "moteur",
+    "entites": [],
+    "verbes": [
+      "evaluer",
+      "attendus",
+      "aligner",
+      "resistances",
+      "creerLexique",
+      "lexiqueCmudict",
+      "reconnaisseurHttp"
+    ],
+    "interop": [
+      "IPA (Alphabet phonétique international)",
+      "ARPAbet / CMUdict",
+      "speechocean762 (échelles de notes 0-2 par son, 0-10 par phrase)",
+      "HTTP : POST /reconnaitre (x-attendus), GET /sante — service/README.md"
+    ],
+    "ne_fait_pas": {
+      "faire entendre une phrase": "@mostajs/voix",
+      "capter l'audio dans le navigateur": "@mostajs/media",
+      "ranger l'audio": "@mostajs/storage",
+      "enregistrer une note": "@mostajs/gradebook",
+      "rendre les écrans": "@mostajs/prononciation-ui",
+      "recueillir un consentement": "@mostajs/consentement"
+    }
+  }
+}

package/service/README.md

@@ -0,0 +1,75 @@
+# Service de reconnaissance de `@mostajs/prononciation`
+
+**Auteur** : Dr Hamid MADANI <drmdh@msn.com> · AGPL-3.0-or-later · Python ≥ 3.10
+
+Il reçoit l'audio d'un élève et les sons attendus. Il rend les sons entendus, 8 traits par son attendu et la durée, exactement comme pour l'apprentissage de `note-apprise-1`. `reconnaisseurHttp` en est le client.
+
+## Installer
+
+```bash
+bash node_modules/@mostajs/prononciation/service/installer.sh
+# ou, pour ranger le modèle (≈ 1,2 Go) ailleurs que dans ~/.cache/huggingface :
+PRONONCIATION_HF_HOME=/srv/modeles bash node_modules/@mostajs/prononciation/service/installer.sh
+```
+
+L'installeur fait trois choses :
+- il crée `service/.venv` et y installe les dépendances **figées** (`requirements.txt` : torch 2.4.1 CPU, transformers 4.44.2…) ;
+- il télécharge `facebook/wav2vec2-lv-60-espeak-cv-ft` à sa **révision figée** (`ae45363b`) ;
+- il vérifie que le modèle se charge sans réseau.
+
+Une autre version des dépendances ou du modèle donne d'autres traits, et la note apprise ne vaut plus ses 0,72.
+
+## Lancer
+
+```bash
+HF_HOME=/srv/modeles service/.venv/bin/python service/serveur.py --local-seulement
+# écoute http://127.0.0.1:8762
+```
+
+| option | défaut | rôle |
+|---|---|---|
+| `--hote` | `127.0.0.1` (`PRONONCIATION_HOTE`) | écoute locale : seule l'application le joint |
+| `--port` | `8762` (`PRONONCIATION_PORT`) | `0` : un port libre, annoncé sur la sortie |
+| `--fils` | `2` (`PRONONCIATION_FILS`) | fils de calcul du modèle |
+| `--octets` | `2000000` | taille maximale du corps |
+| `--secondes` | `15` | durée maximale de l'audio |
+| `--local-seulement` | non | ne rien télécharger ; sortie 3 si le modèle manque |
+
+Côté application :
+
+```js
+reconnaisseurHttp({ url: 'http://127.0.0.1:8762/reconnaitre', type: 'audio/wav' })
+```
+
+## Le contrat
+
+- `POST /reconnaitre` : le corps est l'audio (WAV, FLAC ou OGG, de 0,25 à 15 s) ; l'en-tête `x-attendus` porte les sons attendus, en JSON encodé. Réponse 200 : `{ entendus, traits, duree, regle, modele }`.
+- `GET /sante` : `{ ok, modele, revision, regle, classes }`.
+- Refus `{ erreur, message }` :
+
+| code | statut | quand |
+|---|---|---|
+| `ATTENDUS` | 400 | `x-attendus` absent, illisible, vide, plus de 400 sons, ou un son de plus de 4 signes |
+| `AUDIO_ABSENT` | 400 | corps vide, ou moins de 0,25 s |
+| `LONGUEUR` | 411 | pas de `content-length` |
+| `TROP_GROS` | 413 | corps au-delà de `--octets` (refusé sans être lu) |
+| `TROP_LONG` | 413 | audio au-delà de `--secondes` |
+| `FORMAT` | 415 | audio illisible (le WebM/Opus des navigateurs ne l'est pas : enregistrer en WAV) |
+| `CHEMIN`, `METHODE` | 404, 405 | autre adresse, autre méthode |
+| `INTERNE` | 500 | toute autre faute |
+
+## Ce qu'il ne garde pas
+
+L'audio est lu en mémoire et n'est jamais écrit. Le journal, sur la sortie d'erreur, ne porte que des comptes et des durées : jamais l'audio, jamais les sons attendus (essai T-SRV-8).
+
+## Débit
+
+Une inférence à la fois ; les requêtes suivantes attendent. Mesure du 25/10/2026, poste de développement, 2 fils : **1,5 à 2 s de calcul pour 3 s d'audio**. Le débit sur le serveur de production reste à mesurer.
+
+## Essais
+
+```bash
+PRONONCIATION_PYTHON=service/.venv/bin/python npm test   # 23 essais JS + 9 essais du service
+```
+
+T-SRV-9 compare les traits du vrai modèle à ceux de l'apprentissage, sur cinq phrases de speechocean762 : l'écart est **nul**. T-PRO-23 lance le service et note trois phrases de bout en bout, par `reconnaisseurHttp` : on retrouve la note de Python.

package/service/audio.py

@@ -0,0 +1,38 @@
+"""
+@mostajs/prononciation — service de reconnaissance : octets → onde mono à 16 kHz, en mémoire.
+
+@author Dr Hamid MADANI <drmdh@msn.com>
+@license AGPL-3.0-or-later
+
+libsndfile lit WAV, FLAC, OGG. Rien n'est écrit sur le disque : la voix d'un élève ne quitte pas la mémoire du
+processus, et le journal n'en garde que la durée.
+"""
+import io
+
+import soundfile as sf
+import torch
+import torchaudio.functional as AF
+
+from erreurs import ErreurService
+
+TAUX = 16000
+SECONDES_MIN = 0.25          # en deçà, le modèle n'a pas assez de trames pour un mot
+
+
+def lire_audio(octets, secondes_max=15.0):
+    try:
+        with sf.SoundFile(io.BytesIO(octets)) as f:
+            if f.frames / f.samplerate > secondes_max:
+                raise ErreurService('TROP_LONG', f'audio de {f.frames / f.samplerate:.1f} s ; au plus {secondes_max:g} s')
+            if f.frames / f.samplerate < SECONDES_MIN:
+                raise ErreurService('AUDIO_ABSENT', f'audio de {f.frames / f.samplerate:.2f} s ; au moins {SECONDES_MIN:g} s')
+            onde, sr = f.read(dtype='float32'), f.samplerate
+    except ErreurService:
+        raise
+    except Exception:
+        raise ErreurService('FORMAT', 'audio illisible (WAV, FLAC ou OGG attendu)') from None
+    if onde.ndim > 1:
+        onde = onde.mean(axis=1)
+    if sr != TAUX:
+        onde = AF.resample(torch.from_numpy(onde), sr, TAUX).numpy()
+    return onde

package/service/erreurs.py

@@ -0,0 +1,19 @@
+"""
+@mostajs/prononciation — service de reconnaissance : les refus nommés (plan §8.3).
+
+@author Dr Hamid MADANI <drmdh@msn.com>
+@license AGPL-3.0-or-later
+"""
+
+STATUTS = {
+    'ATTENDUS': 400, 'AUDIO_ABSENT': 400, 'LONGUEUR': 411, 'TROP_GROS': 413, 'TROP_LONG': 413,
+    'FORMAT': 415, 'CHEMIN': 404, 'METHODE': 405, 'INTERNE': 500,
+}
+
+
+class ErreurService(Exception):
+    """Un refus du service : un code nommé, son statut HTTP, un message en français."""
+
+    def __init__(self, code, message):
+        super().__init__(message)
+        self.code, self.statut, self.message = code, STATUTS[code], message

package/service/installer.sh

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+#
+# @mostajs/prononciation — installe le service de reconnaissance (rejouable, plan §8.2).
+# Auteur : Dr Hamid MADANI <drmdh@msn.com>
+#
+#   bash service/installer.sh
+#   PRONONCIATION_HF_HOME=/srv/modeles bash service/installer.sh    # où ranger le modèle (≈ 1,2 Go)
+#
+# Crée service/.venv (Python ≥ 3.10), y installe les dépendances figées, télécharge le modèle à sa révision figée,
+# puis vérifie qu'il se charge sans réseau. Rien d'autre n'est écrit.
+set -euo pipefail
+ICI="$(cd "$(dirname "$0")" && pwd)"
+PY="${PYTHON:-python3}"
+"$PY" -c 'import sys; sys.exit(0 if sys.version_info >= (3, 10) else 1)' || { echo "✗ Python ≥ 3.10 requis ($PY)"; exit 1; }
+[ -x "$ICI/.venv/bin/python" ] || "$PY" -m venv "$ICI/.venv"
+"$ICI/.venv/bin/pip" install -q --upgrade pip
+"$ICI/.venv/bin/pip" install -q -r "$ICI/requirements.txt"
+[ -n "${PRONONCIATION_HF_HOME:-}" ] && export HF_HOME="$PRONONCIATION_HF_HOME"
+cd "$ICI"
+.venv/bin/python - <<'PY'
+from huggingface_hub import hf_hub_download
+import moteur
+for f in moteur.FICHIERS:
+    hf_hub_download(moteur.MODELE, f, revision=moteur.REVISION)
+assert moteur.modele_installe(), 'modèle absent après téléchargement'
+m = moteur.Moteur(local_seulement=True)
+print(f'✓ modèle {moteur.MODELE}@{moteur.REVISION[:8]} chargé : {m.classes} classes de sons, règle {m.regle}')
+PY
+echo "✓ installé. Lancer : ${PRONONCIATION_HF_HOME:+HF_HOME=$PRONONCIATION_HF_HOME }$ICI/.venv/bin/python $ICI/serveur.py --local-seulement"

package/service/moteur.py

@@ -0,0 +1,74 @@
+"""
+@mostajs/prononciation — service de reconnaissance : le modèle acoustique, chargé une fois.
+
+@author Dr Hamid MADANI <drmdh@msn.com>
+@license AGPL-3.0-or-later
+
+wav2vec2 phonémique (Apache-2.0), à la révision qui a servi à apprendre note-apprise-1. Une inférence à la fois :
+deux en parallèle sur les mêmes cœurs se ralentissent l'une l'autre (dossier produit, 11 §3).
+"""
+import json
+import threading
+import time
+
+import torch
+from huggingface_hub import hf_hub_download
+from transformers import Wav2Vec2FeatureExtractor, Wav2Vec2ForCTC
+from transformers.utils import logging as journal_transformers
+
+# transformers 4.44 annonce à tort des poids « réinitialisés » (weight_g/weight_v → parametrizations) : ils sont bien
+# chargés — T-SRV-9 retrouve les traits d'apprentissage à l'identique. L'avertissement égarerait l'exploitant.
+journal_transformers.set_verbosity_error()
+
+import sons
+import traits
+
+MODELE = 'facebook/wav2vec2-lv-60-espeak-cv-ft'
+REVISION = 'ae45363bf3413b374fecd9dc8bc1df0e24c3b7f4'
+FICHIERS = ('config.json', 'preprocessor_config.json', 'vocab.json', 'pytorch_model.bin')
+
+
+def modele_installe():
+    """Vrai si la révision figée du modèle est dans le cache local (HF_HOME), sans réseau."""
+    try:
+        for f in FICHIERS:
+            hf_hub_download(MODELE, f, revision=REVISION, local_files_only=True)
+        return True
+    except Exception:
+        return False
+
+
+class Moteur:
+    modele, revision, regle = MODELE, REVISION, sons.REGLE
+
+    def __init__(self, fils=2, local_seulement=False):
+        torch.set_num_threads(fils)
+        o = {'revision': REVISION, 'local_files_only': local_seulement}
+        vocab = json.load(open(hf_hub_download(MODELE, 'vocab.json', **o), encoding='utf-8'))
+        self.noms, self.membre, self.matrice, self.blanc = sons.classes_du_vocabulaire(vocab)
+        self.classes = len(self.noms)
+        self.id2tok = {i: t for t, i in vocab.items()}
+        self.proc = Wav2Vec2FeatureExtractor.from_pretrained(MODELE, **o)
+        self.model = Wav2Vec2ForCTC.from_pretrained(MODELE, **o).eval()
+        self.verrou = threading.Lock()
+
+    def reconnaitre(self, onde, attendus):
+        """onde : float32 mono 16 kHz ; attendus : sons → { entendus, traits, duree, calcul }."""
+        with self.verrou:
+            t0 = time.perf_counter()
+            with torch.inference_mode():
+                logits = self.model(self.proc(onde, sampling_rate=16000, return_tensors='pt').input_values).logits[0]
+            lp = torch.log_softmax(logits, dim=-1)
+            lp_cls = torch.log(lp.exp() @ self.matrice + 1e-12)
+            lp_blanc = lp[:, self.blanc]
+            bruts, prec = [], None
+            for i in torch.argmax(logits, dim=-1).tolist():     # décodage glouton
+                if i != prec and i != self.blanc:
+                    tk = self.id2tok.get(i, '')
+                    if tk.strip() and tk not in sons.SPECIAUX:
+                        bruts.append(tk)
+                prec = i
+            r = {'entendus': sons.entendre(bruts), 'traits': traits.caracteristiques(lp_cls, lp_blanc, attendus, self.membre),
+                 'duree': len(onde) / 16000}
+            r['calcul'] = time.perf_counter() - t0
+            return r

package/service/requirements.txt

@@ -0,0 +1,10 @@
+# @mostajs/prononciation — service de reconnaissance : dépendances FIGÉES (plan §8.2).
+# Ce sont celles qui ont produit les traits d'apprentissage de note-apprise-1 : une autre version est une autre mesure.
+# Auteur : Dr Hamid MADANI <drmdh@msn.com>
+--extra-index-url https://download.pytorch.org/whl/cpu
+torch==2.4.1+cpu
+torchaudio==2.4.1+cpu
+transformers==4.44.2
+huggingface_hub==0.24.6
+numpy==1.26.4
+soundfile==0.12.1