Skip to main content

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 (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 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):

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 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:

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
  • 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:

  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).

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)

Source distribution for covtl-console 3.1.9
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)

Table of built distributions (wheels) for covtl-console 3.1.9
File Interpreter ABI Platform Actions
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.

Release history Release notifications | RSS feed

This release

3.1.9 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page