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 runcovtl-consoleand 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
(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, sopolar_readyflips 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/compileruns 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), withstandardpreselected by default (fr liaisonfaut il → fo.til, ena apple → @.na.p@l, it raddoppiamento, es enlace, pt encadeamento, de Glottalversatz). The rules live in the companion covtl-sandhi package on the engine side — install it with the engine (pip install covtl-sandhiorpip install git+https://github.com/FBerthommier/covtl-sandhi.git); the bridge publishes whether it is present on/api/statusand/api/healthand the UI hint reflects it live. Without it the level degrades tooffwith an explicit warning (bit-identical output). The engine/API default staysoff; only the console UI preselectsstandard. 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~, mergedV~.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, …); policieswarn/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
errorpolicy is re-validated on every hit). browser simulation of G2P, guard and audio. - Single-file standalone build —
build_standalone.pyinlines every module intocovtl-console-standalone.html, which works fromfile://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 itsINSTALLATION.mdfor the VocalTractLab native binaries it manages) - The covtl-sandhi rule package (recommended — the cross-word sandhi
level is preselected to
standardin the UI):pip install covtl-sandhiorpip install git+https://github.com/FBerthommier/covtl-sandhi.git. Without it every level degrades tooffwith a warning; with it the bridge reports the six rule languages on/api/health. - Bridge dependencies:
fastapianduvicorn
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):
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:
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 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)
# 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:
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)
# 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)
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)
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 theout/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:
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
- 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. - 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. - 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
- Technical reference (bridge API, anchor instrumentation, clock model, caching, extension guide): docs/tech-manual/tech-manual.pdf
- Change record for v3: 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/.
- 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
Testing
With covtl-pipeline installed (engine-required tests skip with an explicit reason otherwise):
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:
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 (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.
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:
- 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
- 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).
Metadata
Release files for covtl-console 3.1.9
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| covtl_console-3.1.9.tar.gz | 141.2 kB | Without provenance | Details for covtl_console-3.1.9.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| covtl_console-3.1.9-py3-none-any.whl | Python 3 | none | any | Details for covtl_console-3.1.9-py3-none-any.whl |
Total release size: 261.8 kB
Release files / covtl_console-3.1.9.tar.gz
| Download URL | covtl_console-3.1.9.tar.gz |
|---|---|
| Size | 141.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
0599bb6fe282e8b5a47a1deea277129d41de9e8de8dbdc3a2f3ac709d16e1f8c
|
|
BLAKE2b-256 checksum How to use checksums |
f254f59dae6f92ee1d75aff2f4d3ddf637fca2beec63f17e69e27a107ed00c7e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.10
|
Release files / covtl_console-3.1.9-py3-none-any.whl
| Download URL | covtl_console-3.1.9-py3-none-any.whl |
|---|---|
| Size | 120.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
445341f43b9821d865fdda328999d8c1c9e4c733bd42a3b313e689d5b7fe1ae5
|
|
BLAKE2b-256 checksum How to use checksums |
d0dc52064074cad75e58e56d337bec5500efefd0099cfe0308752cb6be4cf582
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.10
|
Security for covtl-console 3.1.9
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.