Metadata-Version: 2.4
Name: covtl-console
Version: 3.1.10
Summary: COVTL Lab Console — local web interface for covtl-pipeline (G2P preview, SAMPA guard, syllable compiler, continuous polar display)
Author: Frédéric Berthommier
License-Expression: GPL-3.0-or-later
Project-URL: Homepage, https://github.com/FBerthommier/covtl-console
Project-URL: Engine, https://github.com/FBerthommier/covtl-pipeline
Project-URL: SandhiRules, https://github.com/FBerthommier/covtl-sandhi
Keywords: articulatory synthesis,vocal tract,VocalTractLab,phonetics,speech synthesis
Classifier: Intended Audience :: Science/Research
Classifier: Environment :: Web Environment
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
Classifier: Topic :: Scientific/Engineering :: Visualization
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: THIRD_PARTY_NOTICES.md
Requires-Dist: covtl-synth==1.2.2
Requires-Dist: covtl-sandhi==0.1.1
Requires-Dist: fastapi>=0.100
Requires-Dist: uvicorn>=0.20
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: httpx; extra == "dev"
Dynamic: license-file

<!-- SPDX-FileCopyrightText: 2026 Frédéric Berthommier -->
<!-- SPDX-License-Identifier: GPL-3.0-or-later -->

# COVTL Lab Console — local laboratory interface for covtl-pipeline

> ⚡ **Flash install — one command, everything included** (engine +
> liaison rules + bridge, Python 3.9+):
> `pip install git+https://github.com/FBerthommier/covtl-console.git` —
> then run **`covtl-console`** and open http://127.0.0.1:8421 ·
> locked-down box? → `python install_flash.py`

The COVTL Lab Console is a **local web interface** for the open-source
articulatory speech engine [covtl-pipeline](https://github.com/FBerthommier/covtl-pipeline)
(`vtl_synth`, CLI `vtl-synth`), which wraps VocalTractLab 2.4. It gives
phoneticians and students a laboratory bench for the COVTL polar model:
type ordinary text or SAMPA, watch the grapheme-to-phoneme preview and the
live SAMPA guard, **compile** the utterance into the engine's own syllable
blocks, **synthesize** it through VocalTractLab, and follow the utterance on
a **continuous polar (ρ, θ) display that advances anchor by anchor through
the real syltraj trajectory**. The Python engine stays the single source of
truth for every phonetic decision; the browser only previews, displays and
controls. Nothing leaves your machine — no cloud, no telemetry.

```
┌──────────────────────────────────────────────────────────────────────────┐
│ Header: COVTL Lab · state · Language · Speaker/f0 · Backend(health)      │
├────────────┬─────────────────────────────────────────────────────────────┤
│ Controls   │ Stage                                                       │
│ 1 Lang&Spk │  Preview stack: G2P → enriched → final SAMPA (red reject)   │
│ 2 Input    │  Action bar: Preview(P) · Synthesize the framed source(S)   │
│ 3 Timings  │  Syllable compiler: tiles · block sequence · block cards    │
│ 4 Prosody  │  Continuous polar display: Block k/n · A_k→A_k+1 · ρ/θ      │
│ 5 Engine   │  Transport: play · A− A+ · scrub(anchor ticks) · speeds     │
│   & Guard  │  Spectrogram with anchor overlay                            │
│ 6 Display  │  Log (every job echoes the full parameter set)              │
├────────────┴─────────────────────────────────────────────────────────────┤
│ license GPL-3.0-or-later · local only · no cloud · no telemetry          │
└──────────────────────────────────────────────────────────────────────────┘
```

## Features

- **Continuous polar display** — the utterance is the engine's anchor list;
  segments run from one anchor to the next, each carrying its 100 Hz points
  (`t, rho_v, theta_v, rho_c, theta_c`, null = inactive branch). The display
  is **journey-centric**: it shows exactly one journey — the anchor pair the
  head is traveling — as a single vocalic arc from the start anchor to the
  end anchor, with the consonantal excursion (a closed loop attached at both
  anchors: departure vowel → consonant targets → arrival vowel, big.bi §2.1)
  drawn **jointly** when the journey carries a cluster. Everything else is
  eliminated — no watermark of past journeys; the tuilage is a clean switch
  at the anchor boundary. Reduced vowels (`@`, `6`) are figured as hollow
  rings, and the journey's **origin and target anchors are colored** (red
  dot / green ring) so they can never be confused with the white head.
- **Start-early polar-only mode** — the bridge builds the trajectory
  structure (anchors + blocks + `.polar`) *before* the VocalTractLab stage,
  so `polar_ready` flips while the WAV still renders: the display starts on
  its own monotonic clock, then re-anchors on the audio clock. No chunked
  re-synthesis, ever.
- **Syllable block compiler** — `POST /api/compile` runs the engine's own
  anchor walk over your SAMPA blocks (no synthesis): metric tiles
  (syllables · anchors · blocks · C/V · duration), the block sequence as
  labeled chips, and clickable block cards exposing onset clusters with
  their (ρ, θ) targets and vowel plateaus. After synthesis, clicking a card
  seeks the polar display to exactly that segment.
- **Cross-word sandhi (liaison)** — the Prosody group exposes the engine's
  covtl-sandhi level and gateway mode (`g2p · post · pre`), with
  **`standard` preselected by default** (fr liaison `faut il → fo.til`,
  en `a apple → @.na.p@l`, it raddoppiamento, es enlace, pt encadeamento,
  de Glottalversatz). The rules live in the companion
  [covtl-sandhi](https://github.com/FBerthommier/covtl-sandhi) package on
  the engine side — install it with the engine (`pip install covtl-sandhi`
  or `pip install git+https://github.com/FBerthommier/covtl-sandhi.git`);
  the bridge publishes whether it is present on `/api/status` and
  `/api/health` and the UI hint reflects it live. Without it the level
  degrades to `off` with an explicit warning (bit-identical output). The
  engine/API default stays `off`; only the console UI preselects
  `standard`. Nasal hiatuses (`V~.V`) are a separate engine feature
  (V1V2): they compile to a diphthong background arc labeled with the
  run's nasal notation (`a~.a`, `a.a~`, merged `V~.V~` → `a~.a~`) — under
  a liaison level that fires, the inserted consonant carries the
  transition and the hiatus becomes a plain cluster (e.g. `comment
  allez-vous` → `kOma~.ta.le.vu`).
- **Red-reject SAMPA guard** — symbols outside the engine inventory are
  highlighted in red with suggestions (`c` → `k, s`, IPA `ʃ` → `S`, …);
  policies `warn` / `error` / `off`, one-click strip action.
- **Per-language examples** — ready-made example chips for English, French,
  Spanish, German, Italian and Portuguese.
- **Spectrogram with anchor overlay** — FFT spectrogram of the synthesized
  WAV with the same anchor ticks as the scrub bar.
- **WYSIWYG synthesis** — Synthesize always uses exactly the SAMPA shown on
  screen (deterministic ortho path, edited-phonetic path, or compiler output).
- **Result caching** — preview LRU, compile LRU and a synthesis cache keyed
  on the full parameter set *including the engine version* (guard policy
  deliberately excluded; the `error` policy is re-validated on every hit).
  browser simulation of G2P, guard and audio.
- **Single-file standalone build** — `build_standalone.py` inlines every
  module into `covtl-console-standalone.html`, which works from `file://`
  and talks to the bridge on 127.0.0.1:8421 when one is running.

## Robustness & safety (correction round 2026-11-07)

Three audit findings were corrected; the behaviours below are the
contract the tests lock (`tests/test_fixes_n1_n2_n3.py`, engine side:
`covtl-pipeline` `tests/test_speaker_resolution.py`).

**Speaker selector is functional per request (N1).** `speaker` in
`POST /api/synthesize` is validated against the engine's speaker
registry — an unknown name is **422 `UnknownSpeaker`** (no job starts)
instead of the former silent acceptance with jd3 audio. A registered
speaker changes the audio in the same server process through two
layers: the **orthogonal branch** (VS/VO/TRX/TRY/TS3 — the registered
`.speaker` file) and **f0** (the speaker's registry `f0_default`).
Two layers remain process-global by engine design: the
geometry/constants and the **audio anatomy** (the wheel loads its
`.speaker` at DLL import and exposes no hot reload) — a *full* speaker
swap still goes through `install_speaker.py` + restart. `/api/speakers`
publishes this layer split (`speaker_layers`), and the job `echo`
carries a `speaker_note` whenever the requested speaker differs from
the installed one. Case is ignored (`JD3` → `jd3`); requesting the
active speaker is bit-identical to the historical output.

**Long syntheses no longer freeze the console (N2).** The native VTL
synthesis (`synth_block`) holds the GIL for the whole job; it now runs
in a dedicated **worker subprocess** (`max_workers=1`, serialized jobs —
the engine is CPU-bound on one core). `/api/health` answers in the
millisecond range *during* a synthesis (verified: max 0.01 s over 1 400
probes while a ~140 s job ran). The API additionally enforces the
UI's own text cap: **422 `TextTooLong` above 2 000 characters**
(split long texts into sentences). If no process pool can be created,
the bridge falls back to in-process execution and says so in the job
`notes` ("the console may stall during long syntheses"). Ctrl+C is not
held hostage by an in-flight job: the pool is terminated on shutdown.

**Labels cannot escape `out/` (N3).** An explicit `label` becomes a
file stem; it is validated at request time — path separators `/ \ :`,
control characters, Windows reserved device names and labels over 64
characters are **422 `InvalidLabel`** (no job starts) — and the
surviving characters are sanitized exactly like the engine's
`sanitize_label` (everything outside `[A-Za-z0-9_.-]` maps to `_`,
which also neutralizes glob metacharacters `* ? [`; dots stay, as in
the engine's own `label_of`). The engine re-applies the same guard on
its side (defense in depth — the CLI benefits too). `outputDir` keeps
its historical sanitization.

## Requirements

- **Python 3.9 or later** (3.12 recommended) with `pip`
- A browser: Chrome, Edge or Firefox (current versions)
- The engine **covtl-pipeline** installed — `pip install .` from a clone of
  <https://github.com/FBerthommier/covtl-pipeline> (see its
  `INSTALLATION.md` for the VocalTractLab native binaries it manages)
- The **covtl-sandhi** rule package (recommended — the cross-word sandhi
  level is preselected to `standard` in the UI): `pip install covtl-sandhi`
  or `pip install git+https://github.com/FBerthommier/covtl-sandhi.git`.
  Without it every level degrades to `off` with a warning; with it the
  bridge reports the six rule languages on `/api/health`.
- Bridge dependencies: `fastapi` and `uvicorn`


## Flash install

Two equivalent routes to the same result (venv-ready bridge with engine,
liaison rules, UI assets and launcher):

**One command (option B)** — the console is a pip package whose
dependencies resolve the whole chain (the engine wheel embeds the
VocalTractLab binaries; `covtl-sandhi` brings the six rule languages):

```bash
pip install git+https://github.com/FBerthommier/covtl-console.git
covtl-console                # → http://127.0.0.1:8421  (--port/--host available)
```

The UI ships inside the package (`covtl_console/ui/`) and is served by
the bridge itself; synthesis artifacts land in `out/` under the current
working directory.

**Bootstrap script (option A)** — same install, step by step and
tunable, for locked-down machines or portable Python (NuGet) boxes:

```bash
git clone https://github.com/FBerthommier/covtl-console.git
cd covtl-console
python install_flash.py            # creates .venv-covtl + writes run_console.*
python install_flash.py --run      # ... and start it right away
```

`install_flash.py` options: `--python` (interpreter for the venv),
`--venv` (target directory), `--engine` (git URL or a local checkout
path for engine development), `--no-sandhi` (skip the liaison rules —
the UI default `standard` level then degrades to `off` with a warning),
`--run`.
mode below; to install Python itself on a locked-down Windows box, the
NuGet portable package needs no admin rights (see the Windows section).

## Installation — every system

Full matrices live here; [INSTALL.md](INSTALL.md) is the condensed
quick-start. In all cases: clone the engine first, install it into the
Python environment you will use for the console, then start the bridge.

### Windows 10/11 (PowerShell)

```powershell
# 1) engine
git clone https://github.com/FBerthommier/covtl-pipeline.git
cd covtl-pipeline
py -3.12 -m pip install .
# (VocalTractLab natives: follow INSTALLATION.md in the engine repo)

# 1b) cross-word sandhi rules (liaison; recommended — UI default is standard)
py -3.12 -m pip install git+https://github.com/FBerthommier/covtl-sandhi.git

# 2) console
cd ..
git clone https://github.com/FBerthommier/covtl-console.git
cd covtl-console
py -3.12 -m pip install fastapi uvicorn

# 3) run
py -3.12 server.py     # → http://127.0.0.1:8421
```

On machines where the Python installer is not available (locked-down
corporate boxes), portable Python works fine — for example the NuGet
package, which needs no installer and no admin rights:

```powershell
nuget install python.portable -Version 3.12.10 -ExcludeVersion
# interpreter at .\python.portable\tools\python.exe — use it for every
# py -3.12 … line above, and add -m pip as needed
```

### macOS (zsh)

```zsh
# Xcode Command Line Tools may be needed to build engine dependencies:
xcode-select --install

git clone https://github.com/FBerthommier/covtl-pipeline.git
cd covtl-pipeline && python3 -m pip install . && cd ..
pip install git+https://github.com/FBerthommier/covtl-sandhi.git   # sandhi rules (liaison) — recommended

git clone https://github.com/FBerthommier/covtl-console.git
cd covtl-console
python3 -m venv .venv && source .venv/bin/activate
python3 -m pip install fastapi uvicorn
python server.py        # → http://127.0.0.1:8421
```

### Linux — Debian/Ubuntu (bash)

```bash
sudo apt update
sudo apt install -y python3 python3-dev python3-venv python3-pip git
# (portaudio19 / ALSA headers only if the engine's INSTALLATION.md asks
#  for them on your build)

git clone https://github.com/FBerthommier/covtl-pipeline.git
cd covtl-pipeline && python3 -m pip install . && cd ..
pip install git+https://github.com/FBerthommier/covtl-sandhi.git   # sandhi rules (liaison) — recommended

git clone https://github.com/FBerthommier/covtl-console.git
cd covtl-console
python3 -m venv .venv && source .venv/bin/activate
python3 -m pip install fastapi uvicorn
python server.py        # → http://127.0.0.1:8421
```

On Debian/Ubuntu systems where `pip install .` into the system interpreter
is blocked (PEP 668), create the venv **before** installing the engine and
use its `python3 -m pip` for both `pip install` steps.

### Linux — Fedora (bash)

```bash
sudo dnf install -y python3 python3-devel git
# (ALSA/portaudio development packages only if the engine build needs them)

git clone https://github.com/FBerthommier/covtl-pipeline.git
cd covtl-pipeline && python3 -m pip install . && cd ..
pip install git+https://github.com/FBerthommier/covtl-sandhi.git   # sandhi rules (liaison) — recommended

git clone https://github.com/FBerthommier/covtl-console.git
cd covtl-console
python3 -m venv .venv && source .venv/bin/activate
python3 -m pip install fastapi uvicorn
python server.py        # → http://127.0.0.1:8421
```

### The bridge is required

There is **no offline mode**: preview, compile and synthesis are engine
calls served by the bridge. Without the bridge the console stays in an
explicit offline state (amber banner) and engages automatically as soon
as `python -m covtl_console` answers on 127.0.0.1:8421.

### Ports and artifacts

- Live bridge: **127.0.0.1:8421** (localhost only). The v2 workbench port
  8420 is untouched — both consoles can run side by side.
- Synthesis artifacts (`.wav`, `.txt`, `.tract`, `.polar`, `.mp4`) land in
  the `out/` folder under the console folder; the UI displays the resolved
  absolute path (from `/api/status → out_root`).

### Speakers and languages

The engine ships a multi-speaker registry and a six-language pack; the
console only exposes what the engine has installed:

```bash
python setup_lang.py list                  # available + current language
python setup_lang.py install --lang fr     # install/activate French
python setup_lang.py setlang de            # switch language
python install_speaker.py list             # registered + active speaker
python install_speaker.py install m01      # swap speaker (reversible)
python install_speaker.py restore          # back to jd3
```

Language-pack vowels are calibrated on the **jd3** speaker only; picking
another speaker with a non-English language triggers the console's
*unverified combination* warning (audio may differ).

## First run — the three-step flow

1. **Preview** — pick a language, click an example chip (or type text),
   press `P`. The preview stack shows G2P output → enriched string → final
   SAMPA; symbols outside the engine inventory are red with suggestions.
2. **Compile** — press `C`, type or edit SAMPA syllable blocks, press
   Enter. The compiler panel shows metric tiles, the block sequence, and
   clickable cards with (ρ, θ) targets — the engine's own anchor walk, no
   synthesis.
3. **Synthesize** — press `S`: the single button speaks exactly the
   blue-framed source (main input / edited SAMPA / compiler blocks).
   Watch ⏳ progress, then play the result, read
   the spectrogram, follow the polar display anchor by anchor, and download
   artifacts from the downloads menu (`D`).

| Key | Action | Key | Action |
|---|---|---|---|
| `Space` / `K` | Play / pause | `[` / `]` | Previous / next anchor |
| `Shift+S` | Stop (back to start) | `L` | Loop current block |
| `P` | Preview (never synthesizes) | `0–3` | Speed 0.25× / 0.5× / 1× / 2× |
| `S` | **Synthesize the framed source** (main input / edited SAMPA / compiler blocks) | — | — |
| `C` | Focus the compiler (Enter compiles) | `D` | Downloads menu |
| `R` | Reset the input: clears **both** panes, the preview chain, the compiler panel and the synthesis results (a running synthesis is cancelled) | `Esc` | Cancel synthesis / stop playback |
| `?` | Shortcut help | | |

## Documentation

- **User manual** (didactic, no programming background needed):
  [docs/user-manual/user-manual.pdf](docs/user-manual/user-manual.pdf)
- **Technical reference** (bridge API, anchor instrumentation, clock model,
  caching, extension guide):
  [docs/tech-manual/tech-manual.pdf](docs/tech-manual/tech-manual.pdf)
- Change record for v3: [CHANGES_v3.md](CHANGES_v3.md)
- **Conformity certificate COVCONF-3SRC-3706f0c0** — three-source comparison
  audit (arXiv:2307.02299 / covtl-pipeline / covtl-console), the complete
  audit chain re-executed at the frozen versions: **37/37 checks conform**
  (2026-10-29); complements COVCONF-D11-511cf2e. See
  [docs/certificates/](docs/certificates/).
- **Polar display equivalence attestation** — the console's HTML polar
  display vs the pipeline's reference polar plot: parameter ν, its arc
  concavities, and the absence of any inversion, verified by code audit
  and numerical simulations over six phrases. **Equivalence attested**
  (ν respected, zero inversion; max deviation 1.1×10⁻⁴ cm, 2026-11-15):
  [docs/certificates/Polar_Display_Equivalence_Certificate.pdf](docs/certificates/Polar_Display_Equivalence_Certificate.pdf)

## Testing

With covtl-pipeline installed (engine-required tests skip with an explicit
reason otherwise):

```bash
pip install pytest httpx
pytest tests/ -v            # add -m "not slow" to skip long synthesis jobs
```

`tests/test_frontend_checklist.md` is the manual browser series used for
release sign-off.

**Flash install end-to-end** — `tests/flash_e2e.py` proves the pip
package as a user would get it: it builds the wheel from the checkout,
installs it into a scratch venv (engine + covtl-sandhi resolve from
GitHub), starts the installed `covtl-console` entry point on a free
port and replays the live chain over HTTP (health, fr preview with
liaison, compile metrics, start-early synthesis, nasal-hiatus VO
measured inside the engine's own interval windows, uninstall).
Several minutes — the engine wheel build dominates:

```bash
python tests/flash_e2e.py     # log: flash_e2e.log · CI: job "flash"
```

## Licensing

covtl-console is licensed **GPL-3.0-or-later** — the same license as
covtl-pipeline — so it stays linkable with the engine and with
VocalTractLab. See [LICENSE](LICENSE) (verbatim GNU GPL v3) and the SPDX
headers in every source file.

This repository depends on **covtl-pipeline** (GPL-3.0-or-later) and drives
VocalTractLab 2.4 synthesis through it. **No VocalTractLab code or binaries
are redistributed here** — users obtain the engine through covtl-pipeline,
which manages those dependencies. Third-party components used by the engine
(Wikipron lexicons, CC BY-SA 3.0; CMUdict; `vocaltractlab-cython`) are
referenced, not copied: see [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).

## Citing

The console drives the engine — please cite **covtl-pipeline**
(GPL-3.0-or-later, <https://github.com/FBerthommier/covtl-pipeline>) and
the underlying articles of the Berthommier COVTL model, as the engine's
README does:

1. F. Berthommier, "A mathematical model of the vowel space",
   arXiv:2111.00868 [eess.AS], 2021.
   DOI: 10.48550/arXiv.2111.00868 — <https://arxiv.org/abs/2111.00868>
2. F. Berthommier, "Why can big.bi be changed to bi.gbi? A mathematical
   model of syllabification and articulatory synthesis",
   arXiv:2307.02299 [eess.AS], 2023 — the COVTL polar model the console
   displays.
   DOI: 10.48550/arXiv.2307.02299 — <https://arxiv.org/abs/2307.02299>

Please also cite VocalTractLab itself (see the engine's
THIRD_PARTY_NOTICES.md).
