Upload folder using huggingface_hub

.gitattributes

@@ -33,3 +33,11 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+samples/sample_0.wav filter=lfs diff=lfs merge=lfs -text
+samples/sample_1.wav filter=lfs diff=lfs merge=lfs -text
+samples/sample_2.wav filter=lfs diff=lfs merge=lfs -text
+samples/sample_3.wav filter=lfs diff=lfs merge=lfs -text
+samples/sample_4.wav filter=lfs diff=lfs merge=lfs -text
+samples/sample_5.wav filter=lfs diff=lfs merge=lfs -text
+samples/sample_6.wav filter=lfs diff=lfs merge=lfs -text
+samples/sample_7.wav filter=lfs diff=lfs merge=lfs -text

LICENSE

@@ -0,0 +1,29 @@
+MIT License
+
+Copyright (c) 2026 MicroTTS contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+The files under microtts/g2p/g2p_data/ are third-party assets under the
+Apache License 2.0 (the bundled US English pronunciation dictionaries and the
+graphemes-to-phonemes fallback model). See microtts/g2p/g2p_data/NOTICE.md
+for details. The Apache-2.0 license text for those assets is included as
+microtts/g2p/g2p_data/LICENSE.apache-2.0.txt.

README.md

@@ -0,0 +1,403 @@
+---
+license: mit
+library_name: pytorch
+pipeline_tag: text-to-speech
+tags:
+  - tts
+  - text-to-speech
+  - speech
+  - speech-synthesis
+  - tiny
+  - tiny-model
+  - low-resource
+  - distillation
+  - english
+  - pytorch
+  - cpu
+  - real-time
+language: en
+---
+
+# Vocetta2 1M
+
+A complete English text-to-speech system in **1,031,754 parameters** that
+scores **SCOREQ 4.04** on the standard 24-sentence diverse held-out set, runs
+at **~90x faster than real time on a CPU** (RTF 0.011), and needs nothing but
+Python and three pip packages to use.
+
+| | |
+|---|---|
+| **Params** | 1,031,754 (duration 5,344 + acoustic 438,516 + decoder 587,894) |
+| **Audio** | 24 kHz mono |
+| **Speed** | ~90x real time on CPU (RTF 0.011); no GPU required |
+| **Intelligibility** | WER 0.083 on a 24-sentence diverse held-out set (12/24 exact) |
+| **Naturalness** | SCOREQ 4.04, DNSMOS-OVRL 3.44, DNSMOS-SIG 3.64, UTMOS 3.97 |
+| **License** | MIT (runtime and weights); bundled G2P data is Apache-2.0 |
+
+Listen to `samples/` first. Those eight files were rendered by this exact
+checkpoint.
+
+This is the largest release in the Vocetta2 family: 147K, 276K, 500K, and now
+1M. Each step up doubles the budget and distills from a larger teacher TTS
+through the same three-stage design. This release is the one that crossed
+SCOREQ 4.0, which this family's earlier trajectory (1.48 at 147K, 2.04 at
+276K, 2.70 at 500K) had suggested would land near 3.0 to 3.3 at this size. The
+section "How it reached 4.0" explains what actually made that possible, and
+most of it was procedure, not size.
+
+## How it works
+
+Text becomes audio through four stages:
+
+```
+text ──► G2P ──► phoneme ids
+                  │
+      duration.pt │  ids ──────────────► frame count per phoneme
+                  │
+      acoustic.pt │  ids + durations ───► mel spectrogram [100 bands, T frames]
+                  │
+      decoder.pt  │  mel + noise ───────► complex spectrum ──► iSTFT ──► audio
+```
+
+**G2P** (`microtts/g2p/`). A dictionary-first English front end: words are
+looked up in bundled pronunciation dictionaries (gold and silver), and words
+the dictionaries miss go through a small bundled neural fallback model. NumPy
+only, no espeak, no torch, no network access. The output is a string of IPA
+phonemes, mapped to a frozen 62-symbol vocabulary (`<bos>` and `<eos>` bracket
+each utterance).
+
+**Duration student** (`duration.pt`, 5,344 params). A 3-layer 1D convolutional
+network over the phoneme sequence. It predicts how many mel frames each phoneme
+occupies, using learned position, sequence-length and duration features. The
+shipped checkpoint is the third stage of a short pacing chain: a base run
+followed by two fine-tunes at lower learning rates. Pacing is a real quality
+lever on the full system: at the champion stage the two fine-tunes moved the
+system from 3.886 to 3.940 (+0.02, then +0.03) with nothing else changed.
+
+**Acoustic student** (`acoustic.pt`, 438,516 params). Embed phoneme ids,
+refine them with token-context convolutions, expand them to the frame grid by
+repeating each phoneme its predicted number of frames, then run a second stack
+of convolutions over frames and project to 100 mel bands. Width 72 and depth 5
+for this model. Trained against teacher mels with an L1 + spectral-convergence
+objective plus anti-smoothing (normalized-L1, temporal-delta,
+channel-statistics) terms and a hinge PatchGAN critic.
+
+**Decoder** (`decoder.pt`, 587,894 params). Mel to waveform. A ConvNeXt1D stack
+(depthwise conv, LayerNorm, two pointwise layers with a GELU between them,
+residual) maps the mel to a complex spectrum of 513 bins, which the iSTFT turns
+into audio. The magnitude head is exponential with bin 0 and the Nyquist bin
+zeroed, and a DC-blocking filter removes the remaining offset. The decoder is
+noise-fed: a 4-channel noise input is projected and added to the mel embedding.
+**At inference, zero noise is the best choice**, measured on every metric.
+
+A 100-value `tilt.npy` ships alongside the weights as a per-band mel
+correction. For this checkpoint the shipped vector is all zeros: zero tilt
+measured best for this acoustic, so applying it is a no-op. The file and the
+tool that computes it (`train/compute_tilt.py`) are kept so the convention
+stays explicit and a retrained acoustic has a defined home for its own vector.
+
+## The budget choice
+
+| component | params | share |
+|---|---:|---:|
+| duration | 5,344 | 0.5% |
+| acoustic | 438,516 | 42.5% |
+| decoder | 587,894 | 57% |
+
+Under a 1M total, the split went mostly to the decoder, which matches the
+family's pattern: decoder capacity dominated every comparison made while
+building these models. The acoustic side earned its share too. Two measured
+levers shaped it:
+
+**Depth 5 on the acoustic was the single biggest architecture find in this
+project: about +0.42 gate SCOREQ** over depth 3 at matched width. The value
+came from the reference recipe this family distills from; earlier work on this
+line had inherited depth 3 and never tested it. Depth 7 lost, and raising the
+token-stage depth also lost, so 5 is a measured optimum, not a default.
+
+**Ablations settled the shapes.** The decoder depth was saturated at 4 blocks
+(deeper cost 100K parameters for a WER tie and a worse metallic profile),
+h72 was chosen over h80/h96 by full-system comparison, and the deployment-pack
+recipe (below) made the decoder's job well defined.
+
+Family line: 147,532 params reaches SCOREQ 1.48, 276,765 reaches 2.04, 499,528
+reaches 2.70, and this release reaches 4.04. The largest single jump in that
+line (500K to 1M: +1.34) came from a stack of measured changes rather than
+from size alone: depth-5 acoustics (about +0.42 gate), full schedules on
+rented compute after years of undersized local ones, deployment-pack decoder
+training, duration pacing, and checkpoint averaging. Size alone would not
+have gotten there.
+
+## How it reached 4.0
+
+The line's first full system scored 3.49, and it climbed to 4.04 in two very
+different phases. The first phase was ordinary training work: longer decoder
+schedules (115k to 410k steps, +0.26), an acoustic polish and a
+spectral-convergence adjustment (system 3.75 to 3.89), and duration pacing
+(3.89 to 3.94). The second phase, the final night, is where the last 0.09 came
+from, and it used two ideas that were not training at all.
+
+### The gate: measure the ceiling, not the system
+
+Rendering the acoustic student's own mels through the full teacher vocoder and
+scoring that audio (the "gate") measures how much quality the acoustic is
+leaving on the table, independent of the small decoder. For this line the
+system score tracks roughly **0.92 x gate**, and that ratio stayed remarkably
+stable across configs. Gate evaluations take minutes at the 24-sentence set
+while full system evaluations take longer and depend on the decoder, so the
+gate became the fast signal for where to spend effort.
+
+Gate history on this model:
+
+| stage | gate SCOREQ |
+|---|---:|
+| base acoustic, depth 5 | 4.083 |
+| + polish fine-tune | 4.123 |
+| + sc-weight bite | 4.239 |
+| + averaging with one polish sibling | 4.333 |
+| + five-way blend with three fresh twins | **4.372** |
+
+### Averaging, the free lever
+
+The biggest discovery of the final session: same-recipe checkpoints, diverged
+by nothing but training noise and a short continuation, average into a model
+that beats every member. Every averaging move paid, and every training move
+past that point regressed. The final night's ladder, in which the only trained
+artifacts were six short acoustic twins (about 10 GPU-minutes each):
+
+```
+3.9462  champion decoder + base acoustic
+3.9528  + 12k-step decoder continuation on a rebuilt pack
+3.9709  + decoder checkpoint soup (average of two continuations)
+3.9931  + acoustic soup (gate raised to 4.333)
+3.9954  + cross-regime decoder soup
+4.0286  + three fresh acoustic twins in the gate blend (gate 4.372)
+4.0377  + four-member decoder soup
+4.0384  + soup of the two best soups (the shipped decoder)
+```
+
+Twelve distinct configurations in this budget score 4.0 or better; the shipped
+one is the best measured. The shipped weights are weight averages all the way
+down (see `train/README.md` for the full composition), which is why the
+`train/average_checkpoints.py` script is part of this release.
+
+### What did not work (all measured, do not retry)
+
+- **Retraining the decoder on the new acoustic** (capture re-adaptation):
+  3.9714 against 3.9931 for the un-adapted soup. The decoder transfers to an
+  improved acoustic without retraining.
+- **Larger training pools**: 10k rows scored 3.9328, 20k scored 3.9528, and
+  41.8k scored 3.9223 at matched settings. 20k is a genuine sweet spot.
+- **Training longer**: past about 600k total decoder steps the score regresses.
+- **Every single-knob ablation**: adversarial weight, quiet-ceiling weight,
+  high-band weight, hint weight, crop length, discriminator learning rate,
+  betas, and start-step variants were all run as isolated arms, and all landed
+  at or below the incumbent. The recipe values were already at their optimum.
+
+### Honest notes on the numbers
+
+- The campaign's SCOREQ for this configuration is 4.0384. The released files
+  re-measure at 4.0375 with a locally installed scorer build. The renders are
+  bit-identical; the difference is scorer version noise. Both are above 4.0.
+- SCOREQ, DNSMOS and UTMOS are automatic predictors. They were used alongside
+  WER and listening at every decision point, and a checkpoint once gamed
+  SCOREQ while being unintelligible (WER 1.0), which is why no single metric
+  was trusted.
+- 4.0 was reached at this scale. The margin is thin (about 0.04), and the next
+  ceiling question (what would a 2M or 4M version of this recipe reach) is
+  untested.
+
+## Use it from scratch
+
+Download this repository, install the runtime dependencies, and run the
+script below. Two commands do the download; pick whichever tool you have:
+
+```bash
+# either the Hugging Face CLI (install it if you don't have it)
+pip install -U huggingface_hub
+hf download VantoraLabs/Vocetta2-1m --local-dir vocetta2-1m
+
+# or git-lfs (install git-lfs first: https://git-lfs.com)
+git lfs install && git clone https://huggingface.co/VantoraLabs/Vocetta2-1m
+
+cd vocetta2-1m
+pip install -r requirements.txt          # numpy, torch, soundfile
+```
+
+Then, from inside that folder:
+
+```python
+from microtts import MicroTTS
+
+tts = MicroTTS.load(".")                  # reads duration.pt / acoustic.pt / decoder.pt / tilt.npy
+wav = tts.synthesize("Hello world.")      # float32 numpy array, 24 kHz
+tts.save("out.wav", wav)                  # saves RMS-normalized to -26 dBFS
+```
+
+`MicroTTS.load` accepts `device="cpu"` (default) or `"cuda"`. The full
+pipeline loads in well under a second and needs no network access. If you
+already have phoneme ids, call `tts.synthesize_ids(ids)` directly and skip the
+G2P.
+
+Two practical notes:
+
+- **Loudness.** `synthesize` returns the raw output; its loudness is not
+  normalized. `MicroTTS.normalize(wav)` applies RMS normalization (0.05, about
+  -26 dBFS), and `MicroTTS.save` does it for you.
+- **Noise.** `synthesize(..., noise_scale=0.0)` is the default and gives the
+  best measured quality; nonzero noise costs quality on every metric.
+
+Python 3.10+, CPU is enough. Everything in `benchmark/` runs on the same
+machine with the dependencies from `requirements.txt` (the WER script also
+needs `transformers` and `jiwer`, installed on first use in the same
+environment).
+
+## Benchmarks
+
+Measured on this exact checkpoint through the shipped runtime. Word errors use
+Whisper small as the judge; naturalness scores use the standard open scorers
+(SCOREQ, DNSMOS, UTMOS) on the raw rendered audio, normalized to RMS 0.05.
+
+**Intelligibility (word error rate, lower is better)**
+
+| set | WER | sentences exactly right |
+|---|---|---|
+| 24-sentence diverse held-out set | **0.083** | 12 / 24 |
+
+**Naturalness (higher is better, 24-sentence diverse set)**
+
+| setting | SCOREQ | DNSMOS-OVRL | DNSMOS-SIG | UTMOS |
+|---|---|---|---|---|
+| noise_scale = 0.0, shipped tilt (recommended) | **4.04** | **3.44** | **3.64** | **3.97** |
+
+DNSMOS-SIG catches metallic distortion; 3.64 says the output is not buzzy.
+UTMOS 3.97 is the same automatic MOS estimator several other released TTS
+systems report, which makes it the most portable single number here.
+
+**Speed** (24 diverse sentences, warm-up excluded, CPU)
+
+| device | RTF | real-time factor |
+|---|---|---|
+| CPU | 0.0098 to 0.0121 across runs | 83x to 102x (~90x typical) |
+| GPU (GTX 750, legacy card) | 0.012 | 83x |
+
+RTF includes the duration, acoustic and decoder forwards; the G2P adds a few
+milliseconds per sentence on top. A GPU does not meaningfully help this model:
+at this size the per-operation launch overhead dominates the real arithmetic,
+which is why both rows land within noise of each other. Ship it on CPU.
+
+**Reproducing the scores.** `benchmark/rtf.py` and `benchmark/wer.py` are
+included and reproduce the tables above (`wer.py` needs `transformers` and
+`jiwer`). Naturalness: `pip install scoreq speechmos` and score each rendered
+wav with the libraries' own defaults, plus UTMOS from
+`torch.hub ("tarepan/SpeechMOS:v1.2.0")` in a separate interpreter (the two
+packages disagree about the module name `speechmos`, so they cannot share a
+process). The 24 sentences are in `benchmark/eval_sentences.txt`.
+
+## How it compares
+
+Parameters are inference-time and exclude the grapheme-to-phoneme front end,
+matching the convention of the tables below. This model is 1.03M in that
+count.
+
+**Against the small-TTS field, on the same metric suite.** The following rows
+come from the published comparison table of the sanoTTS release
+([huggingface.co/ampixa/sanoTTS](https://huggingface.co/ampixa/sanoTTS)),
+which scores a diverse 24-sentence set with SCOREQ / UTMOS / DNSMOS-SIG. This
+model was evaluated with the same scorer suite on the same 24 sentences, so
+the columns are directly comparable even though each system renders with its
+own runtime:
+
+| System | Params | SCOREQ | UTMOS | DNS-SIG |
+|---|---:|---:|---:|---:|
+| sanoTTS (amy) | 1.46 M | **4.13** | **4.10** | 3.61 |
+| **Vocetta2 1M (this model)** | **1.03 M** | 4.04 | 3.97 | **3.64** |
+| TinyTTS | 1.62 M | 3.94 | 3.65 | 3.62 |
+| Inflect Nano | 4.63 M | 3.81 | 3.65 | 3.58 |
+| Kitten TTS nano | 15 M | 3.02 | 3.58 | 3.43 |
+| sanoTTS (heart-nano) | 0.29 M | 2.29 | 2.45 | 3.35 |
+| Piper (large teacher) | ~15 M | 4.71 | 4.47 | 3.65 |
+| Kokoro (large teacher) | 82 M | 4.89 | 4.52 | 3.69 |
+
+Among sub-2M systems in that table this model is second on SCOREQ and UTMOS
+(behind a system 1.4x its size) and first on DNSMOS-SIG. The gap to the large
+teachers (Piper at about 15x the size, Kokoro at about 80x) remains wide and
+this release does not claim to close it.
+
+**Against a mid-size classic architecture.** SupraTTS-0.1-Beta
+([huggingface.co/SupraLabs/SupraTTS-0.1-Beta](https://huggingface.co/SupraLabs/SupraTTS-0.1-Beta))
+is a Glow-TTS + HiFi-GAN system, about 44M parameters across its acoustic
+model and vocoder, trained on LJSpeech. On its own evaluation protocol
+(10 out-of-domain plus 10 held-out LJSpeech sentences, 5 seeds, UTMOS as the
+automatic MOS estimate) it reports UTMOS 3.59 +/- 0.07 and WER 3.64%. This
+model's UTMOS on its own set is 3.97 at about 1/43rd of the parameters. The
+protocols differ (different sets, different seeds, different language
+material), so read that as a directional comparison, not a controlled one. The
+parameter ratio is the robust part.
+
+**Within the family.** Each row measured on its own release, same scorer
+suite:
+
+| model | params | SCOREQ | WER |
+|---|---:|---:|---:|
+| Vocetta2-147k | 147,532 | 1.48 | 0.105 |
+| Vocetta2-276K | 276,765 | 2.04 | 0.101 |
+| Vocetta2-500k | 499,528 | 2.70 | 0.117 |
+| **Vocetta2 1M (this)** | **1,031,754** | **4.04** | **0.083** |
+
+The family's word accuracy was flat between 147K and 500K (0.101 to 0.117)
+while naturalness climbed; this release is the first to improve both at once.
+
+## What is in this folder
+
+```
+duration.pt, acoustic.pt, decoder.pt   the weights (~4.0 MB total, fp32)
+tilt.npy                               per-band mel correction (all zeros for this model)
+model.safetensors                      same weights, prefixed keys (dur./ac./dec.),
+                                       fp32 (auto-detected by HF Hub so the params
+                                       count shows on the repo card)
+config.json                            model metadata + architecture sizes; also the
+                                       file that makes download counting work
+microtts/                              runtime package (frontend, models, g2p)
+  g2p/g2p_data/                        dictionaries + fallback model, Apache-2.0
+samples/                               eight rendered examples
+train/                                 the training scripts + the full recipe table
+benchmark/                             RTF + WER scripts, eval sentences, results
+README.md, LICENSE, requirements.txt
+```
+
+## Reproduction on your own machine
+
+Two levels, both spelled out in `train/README.md`:
+
+- **Inference**: a laptop CPU, Python 3.10+, three pip packages. About 90x
+  real time. This is what the "Use it from scratch" section above is.
+- **Full retrain**: the `train/` scripts are teacher-agnostic (you supply a
+  text corpus and a teacher TTS that reports phonemes, audio and durations)
+  and reproduce every stage: pack build, duration chain, acoustic chain,
+  deployment pack, decoder, and the checkpoint averaging that produced the
+  final weights. Total GPU time was roughly a GPU-day on an RTX 3090-class
+  card, decoder stages dominating. The recipe table lists the exact commands,
+  steps, batch sizes and learning rates per stage.
+
+## Limits, stated plainly
+
+- English only. The G2P dictionaries are US English.
+- One voice. This is a single-voice model; there is no speaker conditioning.
+- Utterances cap at ~207 phoneme tokens and 2400 mel frames (~25 s).
+- Free-form conversational text is harder than templated text. On the diverse
+  set above, WER is 0.083 and 12 of 24 sentences come out perfect; expect a
+  few word errors on unusual names and rare words.
+- No text normalization beyond the front end's number handling. Unusual
+  punctuation or markup should be stripped before synthesis.
+- The bundled G2P fallback (used only for words missing from the dictionaries)
+  is shared family infrastructure and is not counted in the 1,031,754, same
+  convention as the comparison tables above.
+- The 4.0 margin is thin and the number comes from automatic predictors. Listen
+  before trusting any single figure, including these.
+
+## Credits
+
+Runtime, weights and training scripts: MIT (this release). The bundled
+grapheme-to-phoneme dictionaries and the fallback model are Apache-2.0; see
+`microtts/g2p/g2p_data/NOTICE.md`.

acoustic.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:3ae454be917f0631e0f88c5e2e33730d55128210e8747754a68cffd4d835f629
+size 1765923

benchmark/eval_sentences.txt

@@ -0,0 +1,24 @@
+From those willing to join in establishing this hoped-for period of peace,
+the fatal consequences whereof might be prevented if the justices of the peace were duly authorized
+Hill had both feet on the car and was climbing aboard to assist President and Mrs. Kennedy.
+yet he could not overcome the strange fascination it had for him, and remained by the side of the corpse till the stretcher came.
+Roger D. Craig, a deputy sheriff of Dallas County,
+Even the Caslon type when enlarged shows great shortcomings in this respect:
+that he could only testify with certainty that the print was less than three days old.
+who came from his room ready dressed, a suspicious circumstance, as he was always late in the morning.
+and improve the morals of the prisoners, and shall insure the proper measure of punishment to convicted offenders.
+On the seventh July, eighteen thirty-seven,
+The first physician to see the President at Parkland Hospital was Dr. Charles J. Carrico, a resident in general surgery.
+Mr. Wakefield winds up his graphic but somewhat sensational account by describing another religious service, which may appropriately be inserted here.
+At last, in the twentieth month,
+seeing that since the establishment of the Central Criminal Court, Newgate received prisoners for trial from several counties,
+reached the same conclusion as Latona that the prints found on the cartons were those of Lee Harvey Oswald.
+This is the approximate time he entered the roominghouse, according to Earlene Roberts, the housekeeper there.
+This plan of mine is no attack on the Court;
+is closely reproduced in the life-history of existing deer. Or, in other words,
+he was reported to have fallen away to a shadow.
+long narrow rooms -- one thirty-six feet, six twenty-three feet, and the eighth eighteen,
+during the morning of November twenty-two prior to the motorcade.
+together with a great increase in the payrolls, there has come a substantial rise in the total of industrial profits
+contracted with sheriffs and conveners to work by the job.
+The inadequacy of the jail was noticed and reported upon again and again by the grand juries of the city of London,

benchmark/results.json

@@ -0,0 +1,44 @@
+{
+  "model": "Vocetta2-1M",
+  "params": 1031754,
+  "params_breakdown": {
+    "duration": 5344,
+    "acoustic": 438516,
+    "decoder": 587894
+  },
+  "sample_rate": 24000,
+  "wer": {
+    "diverse24": {
+      "wer": 0.0826,
+      "perfect": 12,
+      "n": 24
+    }
+  },
+  "naturalness_diverse24": {
+    "scoreq": 4.0375,
+    "scoreq_source_evaluation": 4.0384,
+    "dnsmos_ovrl": 3.4438,
+    "dnsmos_sig": 3.6430,
+    "utmos": 3.9651,
+    "noise_scale": 0.0,
+    "tilt": "zeros (the shipped vector; zero tilt measured best for this acoustic)"
+  },
+  "speed": {
+    "cpu_desktop": {
+      "rtf": 0.0108,
+      "realtime_factor": 93,
+      "note": "benchmark/rtf.py runs ranged 0.0098 to 0.0121 (102x to 83x); typical ~0.011"
+    },
+    "gpu_gtx750_legacy": {
+      "rtf": 0.0121,
+      "realtime_factor": 83,
+      "note": "CPU is competitive at this size; per-op launch overhead dominates on small GPUs"
+    }
+  },
+  "notes": [
+    "Params and WER re-measured on this exact release folder; WER reproduced bit-exact against the source evaluation (0.0826, 12/24 perfect).",
+    "Naturalness re-measured on this release's renders (24 sentences, RMS-normalized to 0.05, 24 kHz). Two SCOREQ measurement runs are listed: 4.0384 on the source instance, 4.0375 on the released files; the difference is scorer build noise.",
+    "WER uses Whisper small as the judge on benchmark/eval_sentences.txt.",
+    "Naturalness uses the standard open scorers (SCOREQ, DNSMOS, UTMOS) on the raw renders."
+  ]
+}

benchmark/rtf.py

@@ -0,0 +1,52 @@
+"""Measure real-time factor (RTF) for the shipped model.
+
+    python benchmark/rtf.py --model . [--device cpu]
+
+RTF = compute seconds / audio seconds. Lower is better; 0.01 means 100x faster
+than real time. Warm-up renders are excluded. The measurement includes the
+tilt correction, since that is part of the shipped inference path.
+"""
+import argparse
+import json
+import os
+import sys
+import time
+
+import numpy as np
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--model", default=".")
+    ap.add_argument("--device", default="cpu")
+    ap.add_argument("--sentences", default=os.path.join(os.path.dirname(__file__), "eval_sentences.txt"))
+    args = ap.parse_args()
+
+    from microtts import MicroTTS
+
+    texts = [l.strip() for l in open(args.sentences, encoding="utf-8") if l.strip()]
+    tts = MicroTTS.load(args.model, device=args.device)
+
+    # warm-up
+    for s in texts[:2]:
+        tts.synthesize(s)
+
+    total_audio = 0.0
+    total_time = 0.0
+    for s in texts:
+        t0 = time.time()
+        wav = tts.synthesize(s)
+        total_time += time.time() - t0
+        total_audio += len(wav) / 24000
+
+    rtf = total_time / total_audio
+    print(f"device {args.device}: {total_audio:.1f}s audio in {total_time:.2f}s "
+          f"-> RTF {rtf:.4f} ({1/rtf:.0f}x realtime)")
+    print(json.dumps({"device": args.device, "rtf": round(rtf, 4),
+                      "realtime_factor": round(1 / rtf, 1)}))
+
+
+if __name__ == "__main__":
+    main()

benchmark/scores_release.json

@@ -0,0 +1,9 @@
+{
+  "vocetta2-1m": {
+    "n": 24,
+    "scoreq": 4.0375,
+    "dnsmos_ovrl": 3.4438,
+    "dnsmos_sig": 3.6430,
+    "utmos": 3.9651
+  }
+}

benchmark/wer.py

@@ -0,0 +1,57 @@
+"""Measure word error rate: render sentences, transcribe with Whisper small.
+
+    python benchmark/wer.py --model . --sentences benchmark/eval_sentences.txt
+
+Requires `transformers` and (for the first run) network access to fetch the
+Whisper checkpoint. WER is computed against the input text after lower-casing
+and stripping punctuation. ASR runs on CUDA when available, else CPU.
+"""
+import argparse
+import os
+import re
+import sys
+
+import numpy as np
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+
+
+def norm(s):
+    return re.sub(r"[^a-z0-9 ]", "", s.lower()).strip()
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--model", default=".")
+    ap.add_argument("--device", default="cpu")
+    ap.add_argument("--sentences", default=os.path.join(os.path.dirname(__file__), "eval_sentences.txt"))
+    args = ap.parse_args()
+
+    from microtts import MicroTTS
+    import soundfile as sf
+    import torch
+    from transformers import pipeline
+    import jiwer
+
+    texts = [l.strip() for l in open(args.sentences, encoding="utf-8") if l.strip()]
+    tts = MicroTTS.load(args.model, device=args.device)
+    asr = pipeline("automatic-speech-recognition", model="openai/whisper-small",
+                   device=0 if torch.cuda.is_available() else -1)
+
+    errs = []
+    for i, s in enumerate(texts):
+        wav = tts.synthesize(s)
+        sf.write("_wer_tmp.wav", MicroTTS.normalize(wav), 24000)
+        hyp = asr("_wer_tmp.wav")["text"].strip()
+        errs.append(jiwer.wer(norm(s), norm(hyp)))
+        print(f"[{i:3d}] WER {errs[-1]:.4f} | {s[:60]!r}", flush=True)
+    try:
+        os.remove("_wer_tmp.wav")
+    except OSError:
+        pass
+
+    print(f"\nmean WER {np.mean(errs):.4f} | perfect {sum(1 for e in errs if e == 0)}/{len(errs)}")
+
+
+if __name__ == "__main__":
+    main()

config.json

@@ -0,0 +1,23 @@
+{
+  "model_type": "vocetta2",
+  "sample_rate": 24000,
+  "params": 1031754,
+  "architecture": [
+    "DurationStudent",
+    "AcousticStudent",
+    "DecoderStudent"
+  ],
+  "architecture_dims": {
+    "duration_hidden": 12,
+    "duration_depth": 3,
+    "acoustic_hidden": 72,
+    "acoustic_depth": 5,
+    "acoustic_token_depth": 3,
+    "decoder_dim": 130,
+    "decoder_pw": 337,
+    "decoder_blocks": 4,
+    "noise_channels": 4,
+    "n_mels": 100
+  },
+  "library_name": "pytorch"
+}

decoder.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:b27e12c433c6bab9b3e21715c489bcc72232477e3539ce2325e7306fd26820ea
+size 2364164

duration.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:a932662ae68f8a35be0b1cd7ef13348cb0f5cc6b3d1f5eb3aea20f31602b979b
+size 27242

microtts/__init__.py

@@ -0,0 +1,24 @@
+"""Vocetta2 1M — a 1,031,754-parameter English text-to-speech system.
+
+    from microtts import MicroTTS
+    tts = MicroTTS.load(".")           # dir with duration.pt / acoustic.pt / decoder.pt
+    wav = tts.synthesize("Hello world.")
+    # wav: float32 numpy array, 24 kHz mono
+
+Three tiny networks run in sequence:
+
+    text -> english G2P -> phoneme ids
+    duration.pt  (5,344 params)      ids -> per-phoneme frame counts
+    acoustic.pt  (438,516 params)    ids + durations -> mel [100, T]
+    decoder.pt   (587,894 params)    mel + noise -> waveform
+
+The grapheme-to-phoneme front end is numpy-only; the three students need
+PyTorch (they are small, CPU inference is fine). Architecture sizes come from
+the shipped config.json, so this runtime also loads the smaller siblings in
+the family without edits.
+"""
+
+from .synthesize import MicroTTS
+
+__all__ = ["MicroTTS"]
+__version__ = "1.0.0"

microtts/frontend.py

@@ -0,0 +1,72 @@
+"""The frozen 62-symbol vocabulary and the phoneme-string -> id helper.
+
+The vocabulary maps IPA symbols (as produced by the G2P in `g2p/`) to the ids
+the three student networks were trained on. `<bos>` and `<eos>` bracket each
+sequence; `<pad>` is reserved.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+DEFAULT_VOCABULARY: dict[str, int] = {
+    "<pad>": 0, "<bos>": 1, "<eos>": 2,
+    " ": 3, "!": 4, '"': 5, "(": 6, ")": 7, ",": 8, ".": 9, ":": 10, ";": 11,
+    "?": 12, "A": 13, "I": 14, "O": 15, "T": 16, "W": 17, "Y": 18, "b": 19,
+    "d": 20, "f": 21, "h": 22, "i": 23, "j": 24, "k": 25, "l": 26, "m": 27,
+    "n": 28, "p": 29, "s": 30, "t": 31, "u": 32, "v": 33, "w": 34, "z": 35,
+    "æ": 36, "ð": 37, "ŋ": 38, "ɐ": 39, "ɑ": 40,
+    "ɔ": 41, "ə": 42, "ɛ": 43, "ɜ": 44, "ɡ": 45,
+    "ɪ": 46, "ɹ": 47, "ʃ": 48, "ʊ": 49, "ʌ": 50,
+    "ʒ": 51, "ʤ": 52, "ʧ": 53, "ˈ": 54, "ˌ": 55,
+    "θ": 56, "ᵊ": 57, "ᵻ": 58, "—": 59, "“": 60,
+    "”": 61,
+}
+
+SPECIAL_IDS = {"<pad>": 0, "<bos>": 1, "<eos>": 2}
+DEFAULT_MAX_TOKENS = 207  # the sequence length the students were trained on
+
+
+class FrontendError(RuntimeError):
+    """`kind` separates an expected rejection (empty / too_long) from a bug."""
+
+    def __init__(self, kind: str, message: str) -> None:
+        super().__init__(message)
+        self.kind = kind
+
+
+def phonemes_to_token_ids(phonemes: str, vocabulary: dict[str, int] | None = None,
+                          max_tokens: int = DEFAULT_MAX_TOKENS) -> tuple[list[int], str]:
+    """IPA string -> (ids, dropped). Unknown symbols are dropped, not fatal."""
+    vocab = vocabulary or DEFAULT_VOCABULARY
+    if max_tokens < 2:
+        raise FrontendError("config", "max_tokens must allow BOS and EOS")
+    kept: list[str] = []
+    dropped: list[str] = []
+    for ch in phonemes:
+        if ch in vocab:
+            if ch not in SPECIAL_IDS:
+                kept.append(ch)
+        else:
+            dropped.append(ch)
+    if not kept:
+        raise FrontendError("empty", "phonemization produced no symbols in the packaged vocabulary")
+    ids = [SPECIAL_IDS["<bos>"], *(int(vocab[c]) for c in kept), SPECIAL_IDS["<eos>"]]
+    if len(ids) > max_tokens:
+        raise FrontendError(
+            "too_long",
+            f"phoneme sequence has {len(ids)} tokens including BOS/EOS; maximum is {max_tokens}",
+        )
+    return ids, "".join(dropped)
+
+
+def vocabulary_for(meta: dict[str, Any]) -> dict[str, int]:  # pragma: no cover
+    """Compatibility shim: the packaged vocabulary is the only one this model uses."""
+    expected = int(meta.get("vocab_size", len(DEFAULT_VOCABULARY)))
+    if expected != len(DEFAULT_VOCABULARY):
+        raise FrontendError(
+            "frontend",
+            f"package declares vocab_size {expected} but the built-in table has "
+            f"{len(DEFAULT_VOCABULARY)} symbols",
+        )
+    return dict(DEFAULT_VOCABULARY)

microtts/g2p/__init__.py

@@ -0,0 +1,11 @@
+"""English grapheme-to-phoneme for MicroTTS.
+
+    from microtts.g2p import phonemize
+    ids, dropped = phonemize("Hello world")
+
+Needs numpy only: no espeak-ng, no torch, no network.
+"""
+
+from .english import EnglishG2P, phonemize, phonemize_to_string, shared_g2p
+
+__all__ = ["phonemize", "phonemize_to_string", "shared_g2p", "EnglishG2P"]

microtts/g2p/english.py

@@ -0,0 +1,1394 @@
+"""English text -> phoneme ids.
+
+The front end is dictionary-first: words are looked up in the bundled US gold
+and silver pronunciation dictionaries, and words the dictionaries do not cover
+are phonemized by a small bundled neural fallback model. Inference needs no
+espeak-ng and no torch: numpy only, like the rest of the runtime.
+
+    text -> tokenise + tag -> dictionary lookup
+         -> neural fallback for out-of-vocabulary words
+         -> the 62-symbol tokenisation the model vocabulary defines
+
+The bundled data files are third-party assets redistributed under the Apache
+License 2.0; see g2p_data/NOTICE.md.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import unicodedata
+from dataclasses import dataclass, replace
+from pathlib import Path
+from typing import Any, Callable
+
+from ..frontend import (
+    DEFAULT_MAX_TOKENS,
+    FrontendError,
+    phonemes_to_token_ids,
+)
+from .oov import OOVModelError, OOVPhonemizer, shared_phonemizer
+
+DATA_DIR = Path(__file__).resolve().parent / "g2p_data"
+GOLD_PATH = DATA_DIR / "us_gold.json"
+SILVER_PATH = DATA_DIR / "us_silver.json"
+
+# --------------------------------------------------------------------------
+# Constants ported verbatim from the reference lexicon/en.py . Names are kept so
+# the two files can be diffed line by line when the reference lexicon moves.
+# --------------------------------------------------------------------------
+
+DIPHTHONGS = frozenset("AIOQWYʤʧ")
+SUBTOKEN_JUNKS = frozenset("',-._‘’/")
+PUNCTS = frozenset(';:,.!?—…"“”')
+NON_QUOTE_PUNCTS = frozenset(p for p in PUNCTS if p not in '"“”')
+
+PUNCT_TAGS = frozenset([".", ",", "-LRB-", "-RRB-", "``", '""', "''", ":", "$", "#", "NFP"])
+PUNCT_TAG_PHONEMES = {"-LRB-": "(", "-RRB-": ")", "``": chr(8220), '""': chr(8221),
+                      "''": chr(8221)}
+
+LEXICON_ORDS = frozenset([39, 45, *range(65, 91), *range(97, 123)])
+CONSONANTS = frozenset("bdfhjklmnpstvwzðŋɡɹɾʃʒʤʧθ")
+US_TAUS = frozenset("AIOWYiuæɑəɛɪɹʊʌ")
+
+CURRENCIES = {"$": ("dollar", "cent"), "£": ("pound", "pence"), "€": ("euro", "cent")}
+ORDINALS = frozenset(["st", "nd", "rd", "th"])
+ADD_SYMBOLS = {".": "dot", "/": "slash"}
+SYMBOLS = {"%": "percent", "&": "and", "+": "plus", "@": "at"}
+
+US_VOCAB = frozenset("AIOWYbdfhijklmnpstuvwzæðŋɑɔəɛɜɡɪɹɾʃʊʌʒʤʧˈˌθᵊᵻʔ")
+
+STRESSES = "ˌˈ"
+SECONDARY_STRESS = STRESSES[0]
+PRIMARY_STRESS = STRESSES[1]
+VOWELS = frozenset("AIOQWYaiuæɑɒɔəɛɜɪʊʌᵻ")
+
+# the chunk cap KModel enforces, and the punctuation
+# classes en_tokenize falls back through when it has to split a long input.
+MAX_PS_CHARS = 510
+WATERFALL = ["!.?…", ":;", ",—"]
+WATERFALL_BUMPS = [")", "”"]
+
+
+# --------------------------------------------------------------------------
+# Token
+# --------------------------------------------------------------------------
+
+
+@dataclass
+class Token:
+    """The fields of the reference lexicon's `MToken` that the English pipeline actually reads.
+
+    the reference lexicon stores the second group on an `addict.Dict` under `_`; flattening
+    them here drops a dependency and changes nothing about the algorithm.
+    """
+
+    text: str
+    tag: str
+    whitespace: str
+    phonemes: str | None = None
+    is_head: bool = True
+    alias: str | None = None
+    stress: float | None = None
+    currency: str | None = None
+    num_flags: str = ""
+    prespace: bool = False
+    rating: int | None = None
+
+
+def stress_weight(ps: str | None) -> int:
+    """stress_weight."""
+    return sum(2 if c in DIPHTHONGS else 1 for c in ps) if ps else 0
+
+
+def merge_tokens(tokens: list[Token], unk: str | None = None) -> Token:
+    """merge_tokens."""
+    if not tokens:
+        raise ValueError("merge_tokens needs at least one token")
+    stresses = {tk.stress for tk in tokens if tk.stress is not None}
+    currencies = {tk.currency for tk in tokens if tk.currency is not None}
+    ratings = {tk.rating for tk in tokens}
+    if unk is None:
+        phonemes = None
+    else:
+        phonemes = ""
+        for tk in tokens:
+            if tk.prespace and phonemes and not phonemes[-1].isspace() and tk.phonemes:
+                phonemes += " "
+            phonemes += unk if tk.phonemes is None else tk.phonemes
+    return Token(
+        text="".join(tk.text + tk.whitespace for tk in tokens[:-1]) + tokens[-1].text,
+        tag=max(tokens, key=lambda tk: sum(1 if c == c.lower() else 2 for c in tk.text)).tag,
+        whitespace=tokens[-1].whitespace,
+        phonemes=phonemes,
+        is_head=tokens[0].is_head,
+        alias=None,
+        stress=next(iter(stresses)) if len(stresses) == 1 else None,
+        currency=max(currencies) if currencies else None,
+        num_flags="".join(sorted({c for tk in tokens for c in tk.num_flags})),
+        prespace=tokens[0].prespace,
+        rating=None if None in ratings else min(r for r in ratings if r is not None),
+    )
+
+
+def apply_stress(ps: str | None, stress: float | None) -> str | None:
+    """apply_stress."""
+
+    def restress(text: str) -> str:
+        indexed: list[tuple[float, str]] = list(enumerate(text))
+        moved = {
+            i: next(j for j, v in indexed[int(i):] if v in VOWELS)
+            for i, p in indexed if p in STRESSES
+        }
+        for i, j in moved.items():
+            indexed[int(i)] = (j - 0.5, indexed[int(i)][1])
+        return "".join(p for _, p in sorted(indexed, key=lambda pair: pair[0]))
+
+    if ps is None or stress is None:
+        return ps
+    if stress < -1:
+        return ps.replace(PRIMARY_STRESS, "").replace(SECONDARY_STRESS, "")
+    if stress == -1 or (stress in (0, -0.5) and PRIMARY_STRESS in ps):
+        return ps.replace(SECONDARY_STRESS, "").replace(PRIMARY_STRESS, SECONDARY_STRESS)
+    if stress in (0, 0.5, 1) and all(s not in ps for s in STRESSES):
+        if all(v not in ps for v in VOWELS):
+            return ps
+        return restress(SECONDARY_STRESS + ps)
+    if stress >= 1 and PRIMARY_STRESS not in ps and SECONDARY_STRESS in ps:
+        return ps.replace(SECONDARY_STRESS, PRIMARY_STRESS)
+    if stress > 1 and all(s not in ps for s in STRESSES):
+        if all(v not in ps for v in VOWELS):
+            return ps
+        return restress(PRIMARY_STRESS + ps)
+    return ps
+
+
+def is_digit(text: str) -> bool:
+    """is_digit."""
+    return bool(re.match(r"^[0-9]+$", text))
+
+
+# --------------------------------------------------------------------------
+# Sub-tokeniser
+# --------------------------------------------------------------------------
+
+# the reference lexicon/en.py builds this with the `regex` module so it can use \p{L}, \p{Lu}
+# and \p{Ll}. `re` has no Unicode property classes, so: \p{L} becomes
+# [^\W\d_], which is exactly "word character that is neither digit nor
+# underscore", i.e. any Unicode letter; the two case-sensitive alternatives
+# become ASCII ranges. That narrowing only affects CamelCase splitting of
+# non-ASCII words, and a non-ASCII word cannot be in the lexicon anyway
+# (LEXICON_ORDS is ASCII), so it goes to the neural fallback either way.
+_LETTER = r"[^\W\d_]"
+_QUOTES = "'‘’"
+_SUBTOKEN_RE = re.compile(
+    rf"^[{_QUOTES}]+"
+    rf"|[A-Z](?=[A-Z][a-z])"
+    rf"|(?:^-)?(?:\d?[,.]?\d)+"
+    rf"|[-_]+"
+    rf"|[{_QUOTES}]{{2,}}"
+    rf"|{_LETTER}*?(?:[{_QUOTES}]{_LETTER})*?[a-z](?=[A-Z])"
+    rf"|{_LETTER}+(?:[{_QUOTES}]{_LETTER})*"
+    rf"|[^\w{_QUOTES}-]"
+    rf"|[{_QUOTES}]+$"
+)
+
+
+def subtokenize(word: str) -> list[str]:
+    """subtokenize (the SUBTOKEN_REGEX findall)."""
+    return _SUBTOKEN_RE.findall(word)
+
+
+# --------------------------------------------------------------------------
+# Numbers: the English subset of the number library that the reference lexicon asks for
+# --------------------------------------------------------------------------
+
+_ONES = ("zero", "one", "two", "three", "four", "five", "six", "seven", "eight", "nine",
+         "ten", "eleven", "twelve", "thirteen", "fourteen", "fifteen", "sixteen",
+         "seventeen", "eighteen", "nineteen")
+_TENS = ("", "", "twenty", "thirty", "forty", "fifty", "sixty", "seventy", "eighty", "ninety")
+_SCALES = ("", "thousand", "million", "billion", "trillion", "quadrillion")
+
+_ORDINAL_WORDS = {"one": "first", "two": "second", "three": "third", "five": "fifth",
+                  "eight": "eighth", "nine": "ninth", "twelve": "twelfth"}
+
+
+class NumberError(ValueError):
+    """A number this reimplementation cannot spell; never silently ignored."""
+
+
+def _under_hundred(value: int) -> str:
+    if value < 20:
+        return _ONES[value]
+    tens, ones = divmod(value, 10)
+    return _TENS[tens] if ones == 0 else f"{_TENS[tens]}-{_ONES[ones]}"
+
+
+def _under_thousand(value: int) -> str:
+    hundreds, rest = divmod(value, 100)
+    if hundreds == 0:
+        return _under_hundred(rest)
+    head = f"{_ONES[hundreds]} hundred"
+    return head if rest == 0 else f"{head} and {_under_hundred(rest)}"
+
+
+def cardinal_words(value: int) -> str:
+    """the number library(value) for English integers, including its comma/'and' rules.
+
+    Groups of three are joined with ", ", except that a final group below one
+    hundred is joined with " and " -- which is why the number library gives "one
+    thousand, one hundred" but "one thousand and one".
+    """
+    if value < 0:
+        return f"minus {cardinal_words(-value)}"
+    if value < 1000:
+        return _under_thousand(value)
+    groups: list[int] = []
+    rest = value
+    while rest:
+        rest, group = divmod(rest, 1000)
+        groups.append(group)
+    if len(groups) > len(_SCALES):
+        raise NumberError(f"{value} is larger than this spell-out table covers")
+    parts = [
+        f"{_under_thousand(group)} {_SCALES[power]}".strip()
+        for power, group in reversed(list(enumerate(groups))) if group
+    ]
+    if len(parts) == 1:
+        return parts[0]
+    tail = groups[0]
+    if 0 < tail < 100:
+        return ", ".join(parts[:-1]) + " and " + parts[-1]
+    return ", ".join(parts)
+
+
+def ordinal_words(value: int) -> str:
+    """the number library(value, to='ordinal'): the cardinal with its last word ordinalised."""
+    words = cardinal_words(value)
+    match = re.search(r"[a-z]+$", words)
+    if match is None:
+        raise NumberError(f"cannot ordinalise the spelling of {value}: {words!r}")
+    return words[: match.start()] + _ordinalise(match.group())
+
+
+def _ordinalise(word: str) -> str:
+    if word in _ORDINAL_WORDS:
+        return _ORDINAL_WORDS[word]
+    if word.endswith("y"):
+        return word[:-1] + "ieth"
+    return word + "th"
+
+
+def year_words(value: int) -> str:
+    """the number library(value, to='year'): two-digit pairs unless the pattern is 00XX/X00X."""
+    if value < 0:
+        raise NumberError("negative years are not supported")
+    high, low = divmod(value, 100)
+    if high == 0 or (high % 10 == 0 and low < 10) or high >= 100:
+        return cardinal_words(value)
+    if low == 0:
+        return f"{cardinal_words(high)} hundred"
+    if low < 10:
+        return f"{cardinal_words(high)} oh-{cardinal_words(low)}"
+    return f"{cardinal_words(high)} {cardinal_words(low)}"
+
+
+def decimal_words(text: str) -> str:
+    """the number library(float(text)): integer part, then 'point', then digit by digit."""
+    whole, _, frac = text.partition(".")
+    head = cardinal_words(int(whole)) if whole else "zero"
+    if not frac:
+        return head
+    return head + " point " + " ".join(_ONES[int(d)] for d in frac)
+
+
+# --------------------------------------------------------------------------
+# Lexicon
+# --------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class TokenContext:
+    """TokenContext."""
+
+    future_vowel: bool | None = None
+    future_to: bool = False
+
+
+class Lexicon:
+    """Lexicon, for American English only (british=False).
+
+    The British tables are not vendored: this model is American English
+    and shipping gb_gold/gb_silver would add 6.5 MB nothing reads.
+    """
+
+    cap_stresses = (0.5, 2)
+
+    def __init__(self, gold_path: Path = GOLD_PATH, silver_path: Path = SILVER_PATH) -> None:
+        self.golds = Lexicon.grow_dictionary(_load_dictionary(gold_path))
+        self.silvers = Lexicon.grow_dictionary(_load_dictionary(silver_path))
+        for word, value in self.golds.items():
+            if isinstance(value, dict):
+                if "DEFAULT" not in value:
+                    raise FrontendError(
+                        "lexicon", f"gold entry {word!r} is tag-keyed but has no DEFAULT"
+                    )
+                for variant in value.values():
+                    _check_vocab(word, variant)
+            else:
+                _check_vocab(word, value)
+
+    @staticmethod
+    def grow_dictionary(entries: dict[str, Any]) -> dict[str, Any]:
+        """Lexicon.grow_dictionary."""
+        grown: dict[str, Any] = {}
+        for key, value in entries.items():
+            if len(key) < 2:
+                continue
+            if key == key.lower():
+                if key != key.capitalize():
+                    grown[key.capitalize()] = value
+            elif key == key.lower().capitalize():
+                grown[key.lower()] = value
+        grown.update(entries)
+        return grown
+
+    def get_NNP(self, word: str) -> tuple[str | None, int | None]:
+        """Lexicon.get_NNP -- spell the word out letter by letter."""
+        letters = [self.golds.get(c.upper()) for c in word if c.isalpha()]
+        if not letters or None in letters:
+            return None, None
+        spelled = apply_stress("".join(str(p) for p in letters), 0)
+        if spelled is None:
+            return None, None
+        head, _, tail = spelled.rpartition(SECONDARY_STRESS)
+        if not head:
+            return spelled, 3
+        return head + PRIMARY_STRESS + tail, 3
+
+    def get_special_case(self, word: str, tag: str, stress: float | None,
+                         ctx: TokenContext) -> tuple[str | None, int | None]:
+        """Lexicon.get_special_case."""
+        if tag == "ADD" and word in ADD_SYMBOLS:
+            return self.lookup(ADD_SYMBOLS[word], None, -0.5, ctx)
+        if word in SYMBOLS:
+            return self.lookup(SYMBOLS[word], None, None, ctx)
+        if ("." in word.strip(".") and word.replace(".", "").isalpha()
+                and len(max(word.split("."), key=len)) < 3):
+            return self.get_NNP(word)
+        if word in ("a", "A"):
+            return ("ɐ" if tag == "DT" else "ˈA"), 4
+        if word in ("am", "Am", "AM"):
+            if tag.startswith("NN"):
+                return self.get_NNP(word)
+            if ctx.future_vowel is None or word != "am" or (stress is not None and stress > 0):
+                return self.golds["am"], 4
+            return "ɐm", 4
+        if word in ("an", "An", "AN"):
+            if word == "AN" and tag.startswith("NN"):
+                return self.get_NNP(word)
+            return "ɐn", 4
+        if word == "I" and tag == "PRP":
+            return SECONDARY_STRESS + "I", 4
+        if word in ("by", "By", "BY") and Lexicon.get_parent_tag(tag) == "ADV":
+            return "bˈI", 4
+        if word in ("to", "To") or (word == "TO" and tag in ("TO", "IN")):
+            return {None: self.golds["to"], False: "tə", True: "tʊ"}[ctx.future_vowel], 4
+        if word in ("in", "In") or (word == "IN" and tag != "NNP"):
+            prefix = PRIMARY_STRESS if ctx.future_vowel is None or tag != "IN" else ""
+            return prefix + "ɪn", 4
+        if word in ("the", "The") or (word == "THE" and tag == "DT"):
+            return ("ði" if ctx.future_vowel is True else "ðə"), 4
+        if tag == "IN" and re.match(r"(?i)vs\.?$", word):
+            return self.lookup("versus", None, None, ctx)
+        if word in ("used", "Used", "USED"):
+            if tag in ("VBD", "JJ") and ctx.future_to:
+                return self.golds["used"]["VBD"], 4
+            return self.golds["used"]["DEFAULT"], 4
+        return None, None
+
+    @staticmethod
+    def get_parent_tag(tag: str | None) -> str | None:
+        """Lexicon.get_parent_tag."""
+        if tag is None:
+            return tag
+        if tag.startswith("VB"):
+            return "VERB"
+        if tag.startswith("NN"):
+            return "NOUN"
+        if tag.startswith("ADV") or tag.startswith("RB"):
+            return "ADV"
+        if tag.startswith("ADJ") or tag.startswith("JJ"):
+            return "ADJ"
+        return tag
+
+    def is_known(self, word: str, tag: str | None) -> bool:
+        """Lexicon.is_known."""
+        if word in self.golds or word in SYMBOLS or word in self.silvers:
+            return True
+        if not word.isalpha() or not all(ord(c) in LEXICON_ORDS for c in word):
+            return False
+        if len(word) == 1:
+            return True
+        if word == word.upper() and word.lower() in self.golds:
+            return True
+        return word[1:] == word[1:].upper()
+
+    def lookup(self, word: str, tag: str | None, stress: float | None,
+               ctx: TokenContext | None) -> tuple[str | None, int | None]:
+        """Lexicon.lookup."""
+        is_NNP = None
+        if word == word.upper() and word not in self.golds:
+            word = word.lower()
+            is_NNP = tag == "NNP"
+        entry: Any = self.golds.get(word)
+        rating: int | None = 4
+        if entry is None and not is_NNP:
+            entry, rating = self.silvers.get(word), 3
+        if isinstance(entry, dict):
+            if ctx is not None and ctx.future_vowel is None and "None" in entry:
+                tag = "None"
+            elif tag not in entry:
+                tag = Lexicon.get_parent_tag(tag)
+            entry = entry.get(tag, entry["DEFAULT"])
+        if entry is None or (is_NNP and PRIMARY_STRESS not in entry):
+            spelled, spelled_rating = self.get_NNP(word)
+            if spelled is not None:
+                return spelled, spelled_rating
+        return apply_stress(entry, stress), rating
+
+    def _s(self, stem: str | None) -> str | None:
+        """Lexicon._s (the -s suffix)."""
+        if not stem:
+            return None
+        if stem[-1] in "ptkfθ":
+            return stem + "s"
+        if stem[-1] in "szʃʒʧʤ":
+            return stem + "ᵻz"
+        return stem + "z"
+
+    def stem_s(self, word: str, tag: str | None, stress: float | None,
+               ctx: TokenContext | None) -> tuple[str | None, int | None]:
+        """Lexicon.stem_s."""
+        if len(word) < 3 or not word.endswith("s"):
+            return None, None
+        if not word.endswith("ss") and self.is_known(word[:-1], tag):
+            stem = word[:-1]
+        elif ((word.endswith("'s") or (len(word) > 4 and word.endswith("es")
+                                       and not word.endswith("ies")))
+              and self.is_known(word[:-2], tag)):
+            stem = word[:-2]
+        elif len(word) > 4 and word.endswith("ies") and self.is_known(word[:-3] + "y", tag):
+            stem = word[:-3] + "y"
+        else:
+            return None, None
+        stem_ps, rating = self.lookup(stem, tag, stress, ctx)
+        return self._s(stem_ps), rating
+
+    def _ed(self, stem: str | None) -> str | None:
+        """Lexicon._ed (the -ed suffix)."""
+        if not stem:
+            return None
+        if stem[-1] in "pkfθʃsʧ":
+            return stem + "t"
+        if stem[-1] == "d":
+            return stem + "ᵻd"
+        if stem[-1] != "t":
+            return stem + "d"
+        if len(stem) < 2:
+            return stem + "ɪd"
+        if stem[-2] in US_TAUS:
+            return stem[:-1] + "ɾᵻd"
+        return stem + "ᵻd"
+
+    def stem_ed(self, word: str, tag: str | None, stress: float | None,
+                ctx: TokenContext | None) -> tuple[str | None, int | None]:
+        """Lexicon.stem_ed."""
+        if len(word) < 4 or not word.endswith("d"):
+            return None, None
+        if not word.endswith("dd") and self.is_known(word[:-1], tag):
+            stem = word[:-1]
+        elif (len(word) > 4 and word.endswith("ed") and not word.endswith("eed")
+              and self.is_known(word[:-2], tag)):
+            stem = word[:-2]
+        else:
+            return None, None
+        stem_ps, rating = self.lookup(stem, tag, stress, ctx)
+        return self._ed(stem_ps), rating
+
+    def _ing(self, stem: str | None) -> str | None:
+        """Lexicon._ing (the -ing suffix)."""
+        if not stem:
+            return None
+        if len(stem) > 1 and stem[-1] == "t" and stem[-2] in US_TAUS:
+            return stem[:-1] + "ɾɪŋ"
+        return stem + "ɪŋ"
+
+    def stem_ing(self, word: str, tag: str | None, stress: float | None,
+                 ctx: TokenContext | None) -> tuple[str | None, int | None]:
+        """Lexicon.stem_ing."""
+        if len(word) < 5 or not word.endswith("ing"):
+            return None, None
+        if len(word) > 5 and self.is_known(word[:-3], tag):
+            stem = word[:-3]
+        elif self.is_known(word[:-3] + "e", tag):
+            stem = word[:-3] + "e"
+        elif (len(word) > 5 and re.search(r"([bcdgklmnprstvxz])\1ing$|cking$", word)
+              and self.is_known(word[:-4], tag)):
+            stem = word[:-4]
+        else:
+            return None, None
+        stem_ps, rating = self.lookup(stem, tag, stress, ctx)
+        return self._ing(stem_ps), rating
+
+    def get_word(self, word: str, tag: str | None, stress: float | None,
+                 ctx: TokenContext) -> tuple[str | None, int | None]:
+        """Lexicon.get_word."""
+        ps, rating = self.get_special_case(word, tag or "", stress, ctx)
+        if ps is not None:
+            return ps, rating
+        lowered = word.lower()
+        if (len(word) > 1 and word.replace("'", "").isalpha() and word != lowered
+                and (tag != "NNP" or len(word) > 7)
+                and word not in self.golds and word not in self.silvers
+                and (word == word.upper() or word[1:] == word[1:].lower())
+                and (lowered in self.golds or lowered in self.silvers
+                     or any(fn(lowered, tag, stress, ctx)[0]
+                            for fn in (self.stem_s, self.stem_ed, self.stem_ing)))):
+            word = lowered
+        if self.is_known(word, tag):
+            return self.lookup(word, tag, stress, ctx)
+        if word.endswith("s'") and self.is_known(word[:-2] + "'s", tag):
+            return self.lookup(word[:-2] + "'s", tag, stress, ctx)
+        if word.endswith("'") and self.is_known(word[:-1], tag):
+            return self.lookup(word[:-1], tag, stress, ctx)
+        for stemmer, stem_stress in ((self.stem_s, stress), (self.stem_ed, stress),
+                                     (self.stem_ing, 0.5 if stress is None else stress)):
+            stemmed, rating = stemmer(word, tag, stem_stress, ctx)
+            if stemmed is not None:
+                return stemmed, rating
+        return None, None
+
+    @staticmethod
+    def is_currency(word: str) -> bool:
+        """Lexicon.is_currency."""
+        if "." not in word:
+            return True
+        if word.count(".") > 1:
+            return False
+        cents = word.split(".")[1]
+        return len(cents) < 3 or set(cents) == {"0"}
+
+    @staticmethod
+    def is_number(word: str, is_head: bool) -> bool:
+        """Lexicon.is_number."""
+        if all(not is_digit(c) for c in word):
+            return False
+        for suffix in ("ing", "'d", "ed", "'s", *ORDINALS, "s"):
+            if word.endswith(suffix):
+                word = word[: -len(suffix)]
+                break
+        return all(is_digit(c) or c in ",." or (is_head and i == 0 and c == "-")
+                   for i, c in enumerate(word))
+
+    def get_number(self, word: str, currency: str | None, is_head: bool,
+                   num_flags: str) -> tuple[str | None, int | None]:
+        """Lexicon.get_number, with cardinal_words for the number library."""
+        match = re.search(r"[a-z']+$", word)
+        suffix = match.group() if match else None
+        if suffix:
+            word = word[: -len(suffix)]
+        result: list[tuple[str | None, int | None]] = []
+        if word.startswith("-"):
+            result.append(self.lookup("minus", None, None, None))
+            word = word[1:]
+
+        def extend_num(num: str, first: bool = True, escape: bool = False) -> None:
+            splits = re.split(r"[^a-z]+", num if escape else cardinal_words(int(num)))
+            for i, part in enumerate(splits):
+                if not part:
+                    continue
+                if part != "and" or "&" in num_flags:
+                    if first and i == 0 and len(splits) > 1 and part == "one" and "a" in num_flags:
+                        result.append(("ə", 4))
+                    else:
+                        result.append(
+                            self.lookup(part, None, -2 if part == "point" else None, None)
+                        )
+                elif part == "and" and "n" in num_flags and result:
+                    result[-1] = ((result[-1][0] or "") + "ən", result[-1][1])
+
+        if is_digit(word) and suffix in ORDINALS:
+            extend_num(ordinal_words(int(word)), escape=True)
+        elif not result and len(word) == 4 and currency not in CURRENCIES and is_digit(word):
+            extend_num(year_words(int(word)), escape=True)
+        elif not is_head and "." not in word:
+            num = word.replace(",", "")
+            if num[0] == "0" or len(num) > 3:
+                for digit in num:
+                    extend_num(digit, first=False)
+            elif len(num) == 3 and not num.endswith("00"):
+                extend_num(num[0])
+                if num[1] == "0":
+                    result.append(self.lookup("O", None, -2, None))
+                    extend_num(num[2], first=False)
+                else:
+                    extend_num(num[1:], first=False)
+            else:
+                extend_num(num)
+        elif word.count(".") > 1 or not is_head:
+            first = True
+            for num in word.replace(",", "").split("."):
+                if not num:
+                    pass
+                elif num[0] == "0" or (len(num) != 2 and any(n != "0" for n in num[1:])):
+                    for digit in num:
+                        extend_num(digit, first=False)
+                else:
+                    extend_num(num, first=first)
+                first = False
+        elif currency in CURRENCIES and Lexicon.is_currency(word):
+            pairs = [(int(num) if num else 0, unit) for num, unit
+                     in zip(word.replace(",", "").split("."), CURRENCIES[currency])]
+            if len(pairs) > 1:
+                if pairs[1][0] == 0:
+                    pairs = pairs[:1]
+                elif pairs[0][0] == 0:
+                    pairs = pairs[1:]
+            for i, (num, unit) in enumerate(pairs):
+                if i > 0:
+                    result.append(self.lookup("and", None, None, None))
+                extend_num(str(num), first=i == 0)
+                result.append(
+                    self.stem_s(unit + "s", None, None, None)
+                    if abs(num) != 1 and unit != "pence"
+                    else self.lookup(unit, None, None, None)
+                )
+        else:
+            cleaned = word.replace(",", "")
+            if is_digit(cleaned):
+                spelled = (ordinal_words(int(cleaned)) if suffix in ORDINALS
+                           else cardinal_words(int(cleaned)))
+            elif "." not in cleaned:
+                raise NumberError(f"cannot spell {word!r} as a number")
+            elif cleaned[0] == ".":
+                spelled = "point " + " ".join(_ONES[int(n)] for n in cleaned[1:])
+            else:
+                spelled = decimal_words(cleaned)
+            extend_num(spelled, escape=True)
+
+        if not result:
+            return None, None
+        joined = " ".join(p for p, _ in result if p)
+        ratings = [r for _, r in result if r is not None]
+        rating = min(ratings) if ratings else None
+        if suffix in ("s", "'s"):
+            return self._s(joined), rating
+        if suffix in ("ed", "'d"):
+            return self._ed(joined), rating
+        if suffix == "ing":
+            return self._ing(joined), rating
+        return joined, rating
+
+    def append_currency(self, ps: str | None, currency: str | None) -> str | None:
+        """Lexicon.append_currency."""
+        if not currency:
+            return ps
+        pair = CURRENCIES.get(currency)
+        if pair is None:
+            return ps
+        unit = self.stem_s(pair[0] + "s", None, None, None)[0]
+        return f"{ps} {unit}" if unit else ps
+
+    @staticmethod
+    def numeric_if_needed(char: str) -> str:
+        """Lexicon.numeric_if_needed."""
+        if not char.isdigit():
+            return char
+        value = unicodedata.numeric(char)
+        return str(int(value)) if value == int(value) else char
+
+    def __call__(self, token: Token, ctx: TokenContext) -> tuple[str | None, int | None]:
+        """Lexicon.__call__."""
+        word = (token.text if token.alias is None else token.alias)
+        word = word.replace(chr(8216), "'").replace(chr(8217), "'")
+        word = unicodedata.normalize("NFKC", word)
+        word = "".join(Lexicon.numeric_if_needed(c) for c in word)
+        stress = None if word == word.lower() else Lexicon.cap_stresses[int(word == word.upper())]
+        ps, rating = self.get_word(word, token.tag, stress, ctx)
+        if ps is not None:
+            return apply_stress(self.append_currency(ps, token.currency), token.stress), rating
+        if Lexicon.is_number(word, token.is_head):
+            ps, rating = self.get_number(word, token.currency, token.is_head, token.num_flags)
+            return apply_stress(ps, token.stress), rating
+        # the reference lexicon distinguishes "outside the lexicon alphabet" from "inside it but
+        # unknown" here and returns the same thing for both; the caller's next
+        # step is the fallback either way.
+        return None, None
+
+
+def _load_dictionary(path: Path) -> dict[str, Any]:
+    if not path.is_file():
+        raise FrontendError(
+            "lexicon",
+            f"dictionary not found at {path}; the bundled assets appear incomplete",
+        )
+    try:
+        entries = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        raise FrontendError("lexicon", f"could not read {path}: {exc}") from exc
+    if not isinstance(entries, dict) or not entries:
+        raise FrontendError("lexicon", f"{path} is not a non-empty JSON object")
+    return entries
+
+
+def _check_vocab(word: str, value: Any) -> None:
+    if value is None:
+        return
+    if not isinstance(value, str):
+        raise FrontendError("lexicon", f"entry {word!r} maps to {type(value).__name__}, not str")
+    unknown = [c for c in value if c not in US_VOCAB]
+    if unknown:
+        raise FrontendError(
+            "lexicon", f"entry {word!r} uses symbols outside the American vocab: {unknown}"
+        )
+
+
+# --------------------------------------------------------------------------
+# Tokeniser and tagger (the an external parser replacements)
+# --------------------------------------------------------------------------
+
+# Words whose part of speech is fixed enough to hard-code. Only tags that can
+# change the phonemes are worth listing: the punctuation tags, 'DT' for "a" and
+# "the", 'IN' for "in", 'PRP' for "I", 'TO', and the coarse NOUN/VERB/ADJ that
+# picks a variant for the 790 tag-keyed gold entries.
+_CLOSED_CLASS: dict[str, str] = {
+    "a": "DT", "an": "DT", "the": "DT", "this": "DT", "that": "IN", "these": "DT",
+    "those": "DT", "every": "DT", "each": "DT", "another": "DT", "any": "DT",
+    "some": "DT", "no": "DT", "both": "DT", "either": "DT", "neither": "DT",
+    "all": "PDT", "such": "JJ",
+    "to": "TO",
+    "of": "IN", "in": "IN", "on": "IN", "at": "IN", "by": "IN", "for": "IN",
+    "with": "IN", "from": "IN", "into": "IN", "about": "IN", "as": "IN",
+    "than": "IN", "if": "IN", "while": "IN", "though": "IN", "although": "IN",
+    "because": "IN", "since": "IN", "until": "IN", "unless": "IN", "upon": "IN",
+    "over": "IN", "under": "IN", "between": "IN", "among": "IN", "through": "IN",
+    "during": "IN", "without": "IN", "within": "IN", "against": "IN",
+    "toward": "IN", "towards": "IN", "before": "IN", "after": "IN", "behind": "IN",
+    "beyond": "IN", "near": "IN", "per": "IN", "via": "IN", "despite": "IN",
+    "above": "IN", "below": "IN", "across": "IN", "along": "IN", "around": "IN",
+    "beside": "IN", "besides": "IN", "beneath": "IN", "throughout": "IN",
+    "and": "CC", "or": "CC", "but": "CC", "nor": "CC", "yet": "CC", "so": "RB",
+    "i": "PRP", "you": "PRP", "he": "PRP", "she": "PRP", "it": "PRP", "we": "PRP",
+    "they": "PRP", "me": "PRP", "him": "PRP", "us": "PRP", "them": "PRP",
+    "myself": "PRP", "yourself": "PRP", "himself": "PRP", "herself": "PRP",
+    "itself": "PRP", "ourselves": "PRP", "themselves": "PRP",
+    "my": "PRP$", "your": "PRP$", "his": "PRP$", "its": "PRP$", "our": "PRP$",
+    "their": "PRP$", "her": "PRP$",
+    "can": "MD", "could": "MD", "will": "MD", "would": "MD", "shall": "MD",
+    "should": "MD", "may": "MD", "might": "MD", "must": "MD",
+    "am": "VBP", "are": "VBP", "is": "VBZ", "was": "VBD", "were": "VBD",
+    "be": "VB", "been": "VBN", "being": "VBG",
+    "have": "VBP", "has": "VBZ", "had": "VBD", "having": "VBG",
+    "do": "VBP", "does": "VBZ", "did": "VBD", "done": "VBN", "doing": "VBG",
+    "not": "RB", "never": "RB", "very": "RB", "too": "RB", "also": "RB",
+    "just": "RB", "only": "RB", "then": "RB", "now": "RB", "again": "RB",
+    "still": "RB", "quite": "RB", "rather": "RB", "almost": "RB", "always": "RB",
+    "often": "RB", "here": "RB", "well": "RB", "even": "RB", "much": "RB",
+    "more": "RBR", "most": "RBS", "less": "RBR", "least": "RBS",
+    "there": "EX", "when": "WRB", "where": "WRB", "why": "WRB", "how": "WRB",
+    "who": "WP", "whom": "WP", "what": "WP", "whose": "WP$", "which": "WDT",
+}
+
+# Punctuation character -> Penn tag. the reference lexicon reads the tag, not the character:
+# ';' has to arrive as ':' and '!' as '.' or the phoneme lookup misses.
+_PUNCT_TAG_BY_CHAR: dict[str, str] = {
+    ",": ",", ".": ".", "!": ".", "?": ".", ";": ":", ":": ":",
+    # A bare ASCII hyphen is HYPH, not ':': an external parser calls it that even when it is
+    # standing in for a dash, and HYPH is outside PUNCT_TAGS, so the reference lexicon voices
+    # nothing for it. Real en/em dashes do get ':' and become the "—" symbol.
+    "-": "HYPH", "–": ":", "—": ":", "…": ":",
+    "(": "-LRB-", "[": "-LRB-", "{": "-LRB-",
+    ")": "-RRB-", "]": "-RRB-", "}": "-RRB-",
+    "$": "$", "£": "$", "€": "$", "#": "#",
+    "“": "``", "‘": "``", "”": "''", "’": "''",
+}
+
+_PREFIX_CHARS = "\"`([{“‘«¿¡$£€#*…"
+_SUFFIX_CHARS = ".,;:!?\")]}”»…%"
+
+# Abbreviations whose trailing period belongs to the word, hand-written here
+# rather than taken from an external parser's exception table. Only the ones the gold
+# dictionary can actually pronounce, plus the common titles and Latin
+# abbreviations, are listed; anything else keeps the period as its own token,
+# which is also what the reference lexicon does when an external parser does not recognise the form.
+_ABBREVIATIONS = frozenset([
+    "Mr.", "Mrs.", "Ms.", "Dr.", "Prof.", "St.", "Jr.", "Sr.", "Esq.", "Rev.",
+    "Gen.", "Gov.", "Sen.", "Rep.", "Capt.", "Lt.", "Col.", "Sgt.", "Adm.",
+    "Mt.", "Ft.", "Co.", "Corp.", "Inc.", "Ltd.", "Bros.",
+    "Jan.", "Feb.", "Mar.", "Apr.", "Jun.", "Jul.", "Aug.", "Sep.", "Sept.",
+    "Oct.", "Nov.", "Dec.",
+    "etc.", "vs.", "e.g.", "i.e.", "a.m.", "p.m.",
+])
+
+_QUOTE_CHARS = "\"“”"
+
+# an external parser splits a double hyphen that sits between two word characters into its
+# own token ("saw--and" -> "saw", "--", "and"); the reference lexicon then reads the ':' tag
+# and voices nothing for it. Without this the whole run reaches the fallback as
+# one unpronounceable string.
+_DOUBLE_HYPHEN_RE = re.compile(r"(?<=\w)(-{2,})(?=\w)")
+
+
+def _punct_tag(text: str, position: str, quote_open: bool) -> str | None:
+    """Penn tag for a punctuation-only token, or None if it is not punctuation."""
+    if any(c.isalnum() for c in text):
+        return None
+    if text in SYMBOLS:
+        # "%", "&", "+", "@" are words, not punctuation: the reference lexicon's
+        # get_special_case spells them out. Tagging them here would put them in
+        # PUNCT_TAGS, where they phonemize to nothing at all.
+        return "NN"
+    if text and set(text) <= set(_QUOTE_CHARS):
+        if text in ("“", "”"):
+            return "``" if text == "“" else "''"
+        if position == "prefix":
+            return "``"
+        if position == "suffix":
+            return "''"
+        return "``" if quote_open else "''"
+    if set(text) == {"'"}:
+        return "''"
+    tags = {_PUNCT_TAG_BY_CHAR.get(c) for c in text}
+    if len(tags) == 1:
+        only = tags.pop()
+        if only is not None:
+            return only
+    return "NFP"
+
+
+def _tag(text: str, position: str, sentence_start: bool, quote_open: bool) -> str:
+    """A Penn tag for one token; the stand-in for an external parser's statistical tagger.
+
+    See the module docstring for what this costs. It is deliberately blunt: a
+    wrong tag on an ordinary content word changes nothing, because the lexicon
+    only consults the tag for punctuation, a dozen function words, and the gold
+    entries that carry per-tag variants.
+    """
+    punct = _punct_tag(text, position, quote_open)
+    if punct is not None:
+        return punct
+    if Lexicon.is_number(text, True):
+        return "CD"
+    if text == "I":
+        return "PRP"
+    lowered = text.lower()
+    closed = _CLOSED_CLASS.get(lowered)
+    if closed is not None:
+        return closed
+    if text[:1].isupper() and not sentence_start:
+        return "NNP"
+    return "NN"
+
+
+def _split_chunk(chunk: str) -> list[tuple[str, str]]:
+    """One whitespace-delimited chunk -> [(token text, position)] as an external parser splits it.
+
+    Position is "prefix", "core" or "suffix" and exists only so a straight
+    double quote can be called opening or closing by where it sits: a quote
+    peeled off the front of a chunk opens, one peeled off the back closes. That
+    beats alternating from the start of the string, which gets the direction
+    wrong for every sentence that begins inside a quotation.
+
+    Prefix and suffix punctuation is peeled one character at a time. Apostrophes
+    are never split: the reference lexicon's own sub-tokeniser keeps "don't" and "boys'" whole
+    and `get_word` has the rules for both, whereas a split apostrophe would be
+    tagged as a closing quote and voiced.
+    """
+    if not chunk:
+        return []
+    prefixes: list[str] = []
+    suffixes: list[str] = []
+    core = chunk
+    changed = True
+    while changed and len(core) > 1:
+        changed = False
+        if core[0] in _PREFIX_CHARS:
+            prefixes.append(core[0])
+            core = core[1:]
+            changed = True
+            continue
+        if core[-1] in _SUFFIX_CHARS and not _keeps_final_period(core):
+            suffixes.insert(0, core[-1])
+            core = core[:-1]
+            changed = True
+    cores = [part for part in _DOUBLE_HYPHEN_RE.split(core) if part] if core else []
+    return [*((p, "prefix") for p in prefixes),
+            *((c, "core") for c in cores),
+            *((x, "suffix") for x in suffixes)]
+
+
+def _keeps_final_period(word: str) -> bool:
+    """True when a trailing '.' is part of the token, not sentence punctuation."""
+    if not word.endswith("."):
+        return False
+    if word in _ABBREVIATIONS or word.lower() in _ABBREVIATIONS:
+        return True
+    # Dotted initialisms ("U.S.", "a.m.") -- the same shape the reference lexicon's
+    # get_special_case spells out letter by letter.
+    stripped = word.strip(".")
+    return ("." in stripped and word.replace(".", "").isalpha()
+            and len(max(word.split("."), key=len)) < 3)
+
+
+def tokenize(text: str) -> list[Token]:
+    """Text -> tagged tokens (rule tokeniser + closed-class lookup)."""
+    tokens: list[Token] = []
+    quote_open = True
+    sentence_start = True
+    for chunk in text.split():
+        pieces = _split_chunk(chunk)
+        for index, (piece, position) in enumerate(pieces):
+            tag = _tag(piece, position, sentence_start, quote_open)
+            if tag in ("``", "''"):
+                quote_open = tag == "''"
+            sentence_start = tag == "." or (sentence_start and tag in ("``", "-LRB-"))
+            tokens.append(Token(text=piece, tag=tag,
+                                whitespace=" " if index == len(pieces) - 1 else ""))
+    if tokens:
+        tokens[-1].whitespace = ""
+    _retag_verbs(tokens)
+    _retag_that(tokens)
+    return tokens
+
+
+def _retag_that(tokens: list[Token]) -> None:
+    """"that" is the one homograph a single lookahead resolves.
+
+    us_gold keys it as {'DEFAULT': 'ðæt', 'DT': 'ðˈæt'}, so only the
+    determiner reading is stressed. Demonstrative "that" is followed by a noun
+    or an adjective ("that cup", "that lively air"); the complementiser and
+    relative readings are followed by a pronoun, a determiner or a verb. On the
+    measured set this rule is right 11 times and wrong twice.
+    """
+    for i, token in enumerate(tokens):
+        if token.text.lower() != "that" or token.tag != "IN":
+            continue
+        following = tokens[i + 1].tag if i + 1 < len(tokens) else None
+        if following is not None and (following.startswith("NN") or following.startswith("JJ")):
+            token.tag = "DT"
+
+
+# Auxiliaries after which an open-class word is a past participle rather than a
+# bare verb; "read" is keyed on VBN and VBD separately, so VB alone is no use.
+_PERFECT_AUXILIARIES = frozenset(["have", "has", "had", "having",
+                                  "is", "are", "was", "were", "be", "been", "being"])
+
+
+def _retag_verbs(tokens: list[Token]) -> None:
+    """Promote a following open-class word to a verb after "to" or an auxiliary.
+
+    The 790 tag-keyed gold entries include a few dozen noun/verb pairs whose
+    vowel changes ("live", "tear", "use", "close"), and without an external parser the only
+    signal available is the word in front. "to X" and "will X" are verbs;
+    "had X" and "was X" are past participles. Both are safe enough to apply
+    unconditionally -- an open-class word in those slots is a verb in ordinary
+    English -- and neither fires on a word the closed-class table already tagged.
+    """
+    previous_tag = None
+    previous_text = ""
+    for token in tokens:
+        if token.tag in ("NN", "JJ"):
+            if previous_tag in ("TO", "MD"):
+                token.tag = "VB"
+            elif previous_text in _PERFECT_AUXILIARIES:
+                token.tag = "VBN"
+        if token.tag not in ("RB", "RBR", "RBS"):
+            previous_tag = token.tag
+            previous_text = token.text.lower()
+
+
+# --------------------------------------------------------------------------
+# G2P
+# --------------------------------------------------------------------------
+
+
+class EnglishG2P:
+    """G2P, with the an external parser front and the espeak fallback replaced."""
+
+    def __init__(self, fallback: Callable[[Token], tuple[str | None, int | None]] | None = None,
+                 unk: str = "") -> None:
+        self.lexicon = Lexicon()
+        self.unk = unk
+        self.fallback = fallback if fallback is not None else _NeuralFallback()
+
+    @staticmethod
+    def fold_left(tokens: list[Token]) -> list[Token]:
+        """G2P.fold_left."""
+        result: list[Token] = []
+        for token in tokens:
+            if result and not token.is_head:
+                token = merge_tokens([result.pop(), token], unk="")
+            result.append(token)
+        return result
+
+    @staticmethod
+    def retokenize(tokens: list[Token]) -> list[Token | list[Token]]:
+        """G2P.retokenize."""
+        words: list[Token | list[Token]] = []
+        currency: str | None = None
+        for i, token in enumerate(tokens):
+            if token.alias is None and token.phonemes is None:
+                pieces = subtokenize(token.text)
+                if not pieces:
+                    pieces = [token.text]
+                tks = [replace(token, text=piece, whitespace="", is_head=True,
+                               num_flags=token.num_flags, stress=token.stress,
+                               prespace=False, phonemes=None, alias=None, currency=None,
+                               rating=None)
+                       for piece in pieces]
+            else:
+                tks = [token]
+            tks[-1].whitespace = token.whitespace
+            for j, tk in enumerate(tks):
+                if tk.alias is not None or tk.phonemes is not None:
+                    pass
+                elif tk.tag == "$" and tk.text in CURRENCIES:
+                    currency = tk.text
+                    tk.phonemes = ""
+                    tk.rating = 4
+                elif tk.tag == ":" and tk.text in ("-", "–"):
+                    tk.phonemes = "—"
+                    tk.rating = 3
+                elif (tk.tag in PUNCT_TAGS
+                      and not all(97 <= ord(c.lower()) <= 122 for c in tk.text)):
+                    tk.phonemes = PUNCT_TAG_PHONEMES.get(
+                        tk.tag, "".join(c for c in tk.text if c in PUNCTS)
+                    )
+                    tk.rating = 4
+                elif currency is not None:
+                    if tk.tag != "CD":
+                        currency = None
+                    elif (j + 1 == len(tks)
+                          and (i + 1 == len(tokens) or tokens[i + 1].tag != "CD")):
+                        tk.currency = currency
+                elif (0 < j < len(tks) - 1 and tk.text == "2"
+                      and (tks[j - 1].text[-1] + tks[j + 1].text[0]).isalpha()):
+                    tk.alias = "to"
+                if tk.alias is not None or tk.phonemes is not None:
+                    words.append(tk)
+                elif words and isinstance(words[-1], list) and not words[-1][-1].whitespace:
+                    tk.is_head = False
+                    words[-1].append(tk)
+                else:
+                    words.append(tk if tk.whitespace else [tk])
+        return [w[0] if isinstance(w, list) and len(w) == 1 else w for w in words]
+
+    @staticmethod
+    def token_context(ctx: TokenContext, ps: str | None, token: Token) -> TokenContext:
+        """G2P.token_context."""
+        vowel = ctx.future_vowel
+        if ps:
+            vowel = next(
+                (None if c in NON_QUOTE_PUNCTS else (c in VOWELS)
+                 for c in ps
+                 if any(c in group for group in (VOWELS, CONSONANTS, NON_QUOTE_PUNCTS))),
+                vowel,
+            )
+        future_to = token.text in ("to", "To") or (token.text == "TO"
+                                                   and token.tag in ("TO", "IN"))
+        return TokenContext(future_vowel=vowel, future_to=future_to)
+
+    @staticmethod
+    def resolve_tokens(tokens: list[Token]) -> None:
+        """G2P.resolve_tokens."""
+        text = "".join(tk.text + tk.whitespace for tk in tokens[:-1]) + tokens[-1].text
+        prespace = (" " in text or "/" in text
+                    or len({0 if c.isalpha() else (1 if is_digit(c) else 2)
+                            for c in text if c not in SUBTOKEN_JUNKS}) > 1)
+        for i, tk in enumerate(tokens):
+            if tk.phonemes is None:
+                if i == len(tokens) - 1 and tk.text in NON_QUOTE_PUNCTS:
+                    tk.phonemes = tk.text
+                    tk.rating = 3
+                elif all(c in SUBTOKEN_JUNKS for c in tk.text):
+                    tk.phonemes = ""
+                    tk.rating = 3
+            elif i > 0:
+                tk.prespace = prespace
+        if prespace:
+            return
+        indices = [(PRIMARY_STRESS in tk.phonemes, stress_weight(tk.phonemes), i)
+                   for i, tk in enumerate(tokens) if tk.phonemes]
+        if len(indices) == 2 and len(tokens[indices[0][2]].text) == 1:
+            i = indices[1][2]
+            tokens[i].phonemes = apply_stress(tokens[i].phonemes, -0.5)
+            return
+        if len(indices) < 2 or sum(b for b, _, _ in indices) <= (len(indices) + 1) // 2:
+            return
+        for _, _, i in sorted(indices)[: len(indices) // 2]:
+            tokens[i].phonemes = apply_stress(tokens[i].phonemes, -0.5)
+
+    def __call__(self, text: str) -> tuple[str, list[Token]]:
+        """G2P.__call__ (preprocess reduced to a left strip)."""
+        tokens: list[Token | list[Token]] = EnglishG2P.retokenize(
+            EnglishG2P.fold_left(tokenize(text.lstrip()))
+        )
+        ctx = TokenContext()
+        for _i, word in reversed(list(enumerate(tokens))):
+            if not isinstance(word, list):
+                if word.phonemes is None:
+                    word.phonemes, word.rating = self.lexicon(word, ctx)
+                if word.phonemes is None and self.fallback is not None:
+                    word.phonemes, word.rating = self.fallback(word)
+                ctx = EnglishG2P.token_context(ctx, word.phonemes, word)
+                continue
+            left, right = 0, len(word)
+            should_fallback = False
+            while left < right:
+                if any(tk.alias is not None or tk.phonemes is not None
+                       for tk in word[left:right]):
+                    merged = None
+                else:
+                    merged = merge_tokens(word[left:right])
+                ps, rating = (None, None) if merged is None else self.lexicon(merged, ctx)
+                # `ps` is None whenever `merged` is, but only the reader knows
+                # that; naming both keeps the invariant checkable.
+                if merged is not None and ps is not None:
+                    word[left].phonemes = ps
+                    word[left].rating = rating
+                    for other in word[left + 1:right]:
+                        other.phonemes = ""
+                        other.rating = rating
+                    ctx = EnglishG2P.token_context(ctx, ps, merged)
+                    right = left
+                    left = 0
+                elif left + 1 < right:
+                    left += 1
+                else:
+                    right -= 1
+                    tk = word[right]
+                    if tk.phonemes is None:
+                        if all(c in SUBTOKEN_JUNKS for c in tk.text):
+                            tk.phonemes = ""
+                            tk.rating = 3
+                        elif self.fallback is not None:
+                            should_fallback = True
+                            break
+                    left = 0
+            if should_fallback:
+                merged = merge_tokens(word)
+                word[0].phonemes, word[0].rating = self.fallback(merged)
+                for other in word[1:]:
+                    other.phonemes = ""
+                    other.rating = word[0].rating
+            else:
+                EnglishG2P.resolve_tokens(word)
+        flat = [merge_tokens(tk, unk=self.unk) if isinstance(tk, list) else tk for tk in tokens]
+        # the reference lexicon applies this whenever version != '2.0', which is the text pipeline's setting.
+        for tk in flat:
+            if tk.phonemes:
+                tk.phonemes = tk.phonemes.replace("ɾ", "T").replace("ʔ", "t")
+        result = "".join((self.unk if tk.phonemes is None else tk.phonemes) + tk.whitespace
+                         for tk in flat)
+        return result, flat
+
+
+# A word-like run for the fallback: letters, plus the hyphens, apostrophes and
+# periods that sit between letters. The model's grapheme vocabulary contains
+# "-", "'" and ".", because the reference lexicon's dictionary keys do, so hyphenated names
+# stay in-domain instead of being chopped into pieces it never saw.
+_FALLBACK_PIECE_RE = re.compile(
+    r"[^\W\d_]+(?:['’\-.][^\W\d_]+)*|\s+|.", re.DOTALL
+)
+
+
+def _fold_to_model_alphabet(word: str) -> str:
+    """Drop the diacritics the model has no grapheme token for.
+
+    It was trained on the reference lexicon's dictionary keys, whose alphabet is ASCII letters
+    plus "'", "-" and "."; an accented letter would become <unk> and take the
+    surrounding phonemes down with it. NFD-decomposing and dropping the
+    combining marks turns "café" into "cafe", which the model can read.
+    """
+    decomposed = unicodedata.normalize("NFD", word.replace(chr(8217), "'"))
+    stripped = "".join(c for c in decomposed if not unicodedata.combining(c))
+    return unicodedata.normalize("NFC", stripped).strip("-.'")
+
+
+def _split_for_model(word: str, max_positions: int) -> list[str]:
+    """Cut a word that will not fit the model's 64-position table.
+
+    Ordinary English words never reach this; runs of letters this long are URLs
+    with the separators already stripped, or someone leaning on a key. Cutting
+    is better than raising, because raising loses the whole utterance over one
+    pathological token.
+    """
+    limit = max_positions - 2  # the model's own bos and eos
+    if len(word) <= limit:
+        return [word]
+    return [word[i:i + limit] for i in range(0, len(word), limit)]
+
+
+class _NeuralFallback:
+    """The OOV path: the bundled neural fallback for out-of-vocabulary words.
+
+    the reference lexicon hands the fallback whatever the back-off loop could not resolve,
+    which is not always a single clean word: a token like "forgave;--that" gets
+    here whole because an external parser never split it and no prefix of it is in the
+    dictionary. espeak phonemizes the word runs and keeps the punctuation. This
+    does the same -- word runs through the model, characters that are in PUNCTS
+    passed through, everything else dropped -- rather than handing the model a
+    string full of characters it has no token for.
+    """
+
+    def __init__(self, model: OOVPhonemizer | None = None) -> None:
+        self._model = model
+
+    def __call__(self, token: Token) -> tuple[str | None, int | None]:
+        text = token.text.strip()
+        if not text:
+            return "", 2
+        if self._model is None:
+            self._model = shared_phonemizer()
+        out: list[str] = []
+        for piece in _FALLBACK_PIECE_RE.findall(text):
+            if piece.isspace():
+                if out and not out[-1].endswith(" "):
+                    out.append(" ")
+                continue
+            if piece[0].isalpha():
+                cleaned = _fold_to_model_alphabet(piece)
+                if not cleaned:
+                    continue
+                for part in _split_for_model(cleaned, self._model.max_positions):
+                    try:
+                        phonemes = self._model(part)
+                    except OOVModelError as exc:
+                        raise FrontendError(
+                            "oov", f"the fallback model could not phonemize {part!r}: {exc}"
+                        ) from exc
+                    if phonemes:
+                        out.append(phonemes)
+            elif piece in PUNCTS:
+                out.append(piece)
+        joined = "".join(out).strip()
+        return joined, 2
+
+
+# --------------------------------------------------------------------------
+# Chunking and the public entry point
+# --------------------------------------------------------------------------
+
+
+def _tokens_to_ps(tokens: list[Token]) -> str:
+    """tokens_to_ps: phoneme string -> the 62-symbol token ids."""
+    return "".join((tk.phonemes or "") + (" " if tk.whitespace else "")
+                   for tk in tokens).strip()
+
+
+def _waterfall_last(tokens: list[Token], next_count: int) -> int:
+    """waterfall_last: the word-level fallback chain."""
+    for group in WATERFALL:
+        z = next((i for i, t in reversed(list(enumerate(tokens))) if t.phonemes in set(group)),
+                 None)
+        if z is None:
+            continue
+        z += 1
+        if z < len(tokens) and tokens[z].phonemes in WATERFALL_BUMPS:
+            z += 1
+        if next_count - len(_tokens_to_ps(tokens[:z])) <= MAX_PS_CHARS:
+            return z
+    return len(tokens)
+
+
+def en_chunks(tokens: list[Token]) -> list[str]:
+    """en_tokenize, reduced to the phoneme strings.
+
+    The chunk boundaries matter beyond length: each chunk is wrapped in its own
+    <bos>/<eos> when the ids are built, which is how the training packs were
+    laid out.
+    """
+    chunks: list[str] = []
+    held: list[Token] = []
+    pcount = 0
+    for token in tokens:
+        if token.phonemes is None:
+            token.phonemes = ""
+        next_ps = token.phonemes + (" " if token.whitespace else "")
+        next_pcount = pcount + len(next_ps.rstrip())
+        if next_pcount > MAX_PS_CHARS:
+            z = _waterfall_last(held, next_pcount)
+            ps = _tokens_to_ps(held[:z])
+            if ps:
+                chunks.append(ps)
+            held = held[z:]
+            pcount = len(_tokens_to_ps(held))
+            if not held:
+                next_ps = next_ps.lstrip()
+        held.append(token)
+        pcount += len(next_ps)
+    if held:
+        ps = _tokens_to_ps(held)
+        if ps:
+            chunks.append(ps)
+    return chunks
+
+
+_SHARED_G2P: EnglishG2P | None = None
+
+
+def shared_g2p() -> EnglishG2P:
+    """One process-wide G2P.
+
+    Building it reads 6.1 MB of JSON into 365,368 dict entries (the reference lexicon's
+    `grow_dictionary` adds the capitalised and lower-cased variants), which
+    takes about 0.2 s and 68 MB of resident memory. Worth doing once.
+    """
+    global _SHARED_G2P
+    if _SHARED_G2P is None:
+        _SHARED_G2P = EnglishG2P()
+    return _SHARED_G2P
+
+
+def phonemize(text: str, *, vocabulary: dict[str, int] | None = None,
+              max_tokens: int = DEFAULT_MAX_TOKENS,
+              g2p: EnglishG2P | None = None) -> tuple[list[int], str]:
+    """Text -> (phoneme ids, dropped symbols).
+
+    American English: the dictionaries bundled in g2p_data/ are US gold/silver.
+    """
+    if not isinstance(text, str) or not text.strip():
+        raise FrontendError("empty", "text must be a non-empty string")
+    engine = g2p if g2p is not None else shared_g2p()
+    _result, tokens = engine(text)
+    chunks = en_chunks(tokens)
+    if not chunks:
+        raise FrontendError("empty", f"phonemization produced no symbols for text: {text!r}")
+    ids: list[int] = []
+    dropped: list[str] = []
+    for chunk in chunks:
+        if len(chunk) > MAX_PS_CHARS:
+            chunk = chunk[:MAX_PS_CHARS]
+        # The per-chunk cap is disabled (a chunk can never exceed its own length
+        # plus BOS/EOS) so that the real limit is checked once, on the whole
+        # sequence, and reports the number the caller cares about.
+        chunk_ids, chunk_dropped = phonemes_to_token_ids(
+            chunk, vocabulary, max_tokens=len(chunk) + 2
+        )
+        ids.extend(chunk_ids)
+        dropped.append(chunk_dropped)
+    if len(ids) > max_tokens:
+        raise FrontendError(
+            "too_long",
+            f"phoneme sequence has {len(ids)} tokens including BOS/EOS; maximum is {max_tokens}",
+        )
+    return ids, "".join(dropped)
+
+
+def phonemize_to_string(text: str, *, g2p: EnglishG2P | None = None) -> str:
+    """The phoneme string alone, for comparing against the reference lexicon without the ids."""
+    if not isinstance(text, str) or not text.strip():
+        raise FrontendError("empty", "text must be a non-empty string")
+    engine = g2p if g2p is not None else shared_g2p()
+    return "".join(en_chunks(engine(text)[1]))

microtts/g2p/g2p_data/LICENSE.apache-2.0.txt

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

microtts/g2p/g2p_data/NOTICE.md

@@ -0,0 +1,16 @@
+# Bundled data — `microtts/g2p/g2p_data/`
+
+The grapheme-to-phoneme front end runs on three data files that are
+redistributed here under the Apache License 2.0 (full text in
+`LICENSE.apache-2.0.txt`):
+
+| file | what it is |
+|---|---|
+| `us_gold.json` | US English pronunciation dictionary (gold subset) |
+| `us_silver.json` | US English pronunciation dictionary (silver subset) |
+| `oov_bart_en_us.npz` | neural fallback model for out-of-vocabulary words (weights only) |
+
+`microtts/g2p/oov.py` is a numpy-only transcription of the fallback model's
+forward pass; `microtts/g2p/english.py` is the dictionary-first front end.
+
+No GPL code or data is included.

microtts/g2p/g2p_data/oov_bart_en_us.npz

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:f14370fca67996500724d2ecfb73c5ef170ff3bbc5814d613943f75730270ff2
+size 2806853

microtts/g2p/oov.py

@@ -0,0 +1,244 @@
+"""Numpy-only grapheme -> phoneme model for words the dictionary does not have.
+
+The checkpoint is the bundled fallback model, a
+751,551-parameter transformer with one encoder layer, one decoder layer, one attention
+head and d_model 128, trained on the reference lexicon's own us_gold/us_silver dictionaries.
+It was not distilled from espeak-ng, which is the whole point: it is the OOV
+path for a front end that must not carry a GPL dependency.
+
+The published safetensors were converted once to `g2p_data/oov_bart_en_us.npz`;
+this module is the forward pass, transcribed
+from transformers' `BartModel` so it can run under numpy alone:
+
+  * post-norm blocks (residual add, then LayerNorm), which is transformer, not the
+    pre-norm arrangement most later decoders use;
+  * learned positional embeddings with the offset of 2 that transformer reserves for
+    pad and bos, hence the 66-row table for 64 positions;
+  * `scale_embedding=false`, so token embeddings are used unscaled;
+  * exact erf gelu, not the tanh approximation;
+  * greedy decoding from `decoder_start_token_id`, which is what the upstream
+    reference script gets from its generation config (no beams, no sampling).
+
+Decoding is per word and words are short, so there is no KV cache: the decoder
+is re-run over the whole prefix each step. A cache would save microseconds on
+sequences that are at most a few dozen tokens and is not worth the surface area.
+"""
+
+from __future__ import annotations
+
+import json
+import math
+from pathlib import Path
+
+import numpy as np
+
+DATA_DIR = Path(__file__).resolve().parent / "g2p_data"
+MODEL_PATH = DATA_DIR / "oov_bart_en_us.npz"
+
+# The tokenizer reserves 0..3 for <pad>/<s>/</s>/<unk> and then indexes the
+# character lists; the shipped config records both lists already padded with
+# four underscores so the character at index i is simply chars[i].
+SPECIAL_TOKEN_COUNT = 4
+UNK_ID = 3
+
+
+class OOVModelError(RuntimeError):
+    """Raised when the fallback model is unusable; never swallowed by callers."""
+
+
+def _layer_norm(x: np.ndarray, weight: np.ndarray, bias: np.ndarray, eps: float) -> np.ndarray:
+    mean = x.mean(axis=-1, keepdims=True)
+    var = x.var(axis=-1, keepdims=True)
+    return (x - mean) / np.sqrt(var + eps) * weight + bias
+
+
+def _erf(x: np.ndarray) -> np.ndarray:
+    """Abramowitz-Stegun 7.1.26 erf, max abs error 1.5e-7.
+
+    transformers maps the "gelu" activation to the erf form, not the tanh
+    approximation. numpy has no erf and scipy is not a dependency of this
+    package, so the approximation is inlined. 1.5e-7 is far below the margin between competing
+    characters in a 63-way argmax; an output-parity check compares this port's
+    greedy output against the transformers implementation on the dictionary and
+    finds no disagreement.
+    """
+    sign = np.sign(x)
+    ax = np.abs(x)
+    t = 1.0 / (1.0 + 0.3275911 * ax)
+    poly = t * (0.254829592 + t * (-0.284496736 + t * (1.421413741
+                + t * (-1.453152027 + t * 1.061405429))))
+    return sign * (1.0 - poly * np.exp(-ax * ax))
+
+
+def _gelu_exact(x: np.ndarray) -> np.ndarray:
+    return 0.5 * x * (1.0 + _erf(x / math.sqrt(2.0)))
+
+
+def _softmax(x: np.ndarray) -> np.ndarray:
+    shifted = x - x.max(axis=-1, keepdims=True)
+    exp = np.exp(shifted)
+    return exp / exp.sum(axis=-1, keepdims=True)
+
+
+class _Attention:
+    """Single-head BartAttention. num_heads is 1 in this checkpoint, asserted
+    by the asset builder, so the head reshape collapses to a plain matmul."""
+
+    def __init__(self, weights: dict[str, np.ndarray], prefix: str, scaling: float) -> None:
+        self.q_w = weights[f"{prefix}.q_proj.weight"].T
+        self.q_b = weights[f"{prefix}.q_proj.bias"]
+        self.k_w = weights[f"{prefix}.k_proj.weight"].T
+        self.k_b = weights[f"{prefix}.k_proj.bias"]
+        self.v_w = weights[f"{prefix}.v_proj.weight"].T
+        self.v_b = weights[f"{prefix}.v_proj.bias"]
+        self.o_w = weights[f"{prefix}.out_proj.weight"].T
+        self.o_b = weights[f"{prefix}.out_proj.bias"]
+        self.scaling = scaling
+
+    def __call__(self, query: np.ndarray, memory: np.ndarray,
+                 causal: bool = False) -> np.ndarray:
+        q = (query @ self.q_w + self.q_b) * self.scaling
+        k = memory @ self.k_w + self.k_b
+        v = memory @ self.v_w + self.v_b
+        scores = q @ k.T
+        if causal:
+            mask = np.triu(np.ones((scores.shape[0], scores.shape[1]), dtype=bool), k=1)
+            scores = np.where(mask, np.float32(-np.inf), scores)
+        return _softmax(scores) @ v @ self.o_w + self.o_b
+
+
+class _Layer:
+    """One BartEncoderLayer, or one BartDecoderLayer when `cross` is present."""
+
+    def __init__(self, weights: dict[str, np.ndarray], prefix: str,
+                 scaling: float, eps: float, cross: bool) -> None:
+        self.eps = eps
+        self.self_attn = _Attention(weights, f"{prefix}.self_attn", scaling)
+        self.self_ln = (weights[f"{prefix}.self_attn_layer_norm.weight"],
+                        weights[f"{prefix}.self_attn_layer_norm.bias"])
+        if cross:
+            self.cross_attn = _Attention(weights, f"{prefix}.encoder_attn", scaling)
+            self.cross_ln = (weights[f"{prefix}.encoder_attn_layer_norm.weight"],
+                             weights[f"{prefix}.encoder_attn_layer_norm.bias"])
+        else:
+            self.cross_attn = None
+            self.cross_ln = None
+        self.fc1_w = weights[f"{prefix}.fc1.weight"].T
+        self.fc1_b = weights[f"{prefix}.fc1.bias"]
+        self.fc2_w = weights[f"{prefix}.fc2.weight"].T
+        self.fc2_b = weights[f"{prefix}.fc2.bias"]
+        self.final_ln = (weights[f"{prefix}.final_layer_norm.weight"],
+                         weights[f"{prefix}.final_layer_norm.bias"])
+
+    def __call__(self, hidden: np.ndarray, memory: np.ndarray | None,
+                 causal: bool) -> np.ndarray:
+        hidden = _layer_norm(hidden + self.self_attn(hidden, hidden, causal=causal),
+                             *self.self_ln, self.eps)
+        if self.cross_attn is not None:
+            if memory is None:
+                raise OOVModelError("decoder layer reached with no encoder memory")
+            hidden = _layer_norm(hidden + self.cross_attn(hidden, memory),
+                                 *self.cross_ln, self.eps)
+        ffn = _gelu_exact(hidden @ self.fc1_w + self.fc1_b) @ self.fc2_w + self.fc2_b
+        return _layer_norm(hidden + ffn, *self.final_ln, self.eps)
+
+
+class OOVPhonemizer:
+    """Greedy grapheme -> phoneme decoding for one word at a time."""
+
+    def __init__(self, path: Path | str = MODEL_PATH) -> None:
+        path = Path(path)
+        if not path.is_file():
+            raise OOVModelError(
+                f"fallback model not found at {path}; run "
+                "the bundled asset appears incomplete"
+            )
+        try:
+            with np.load(path, allow_pickle=False) as bundle:
+                weights = {name: np.asarray(bundle[name], dtype=np.float32)
+                           for name in bundle.files if name != "meta_json"}
+                meta_raw = str(bundle["meta_json"])
+        except (OSError, ValueError, KeyError) as exc:
+            raise OOVModelError(f"could not read {path}: {exc}") from exc
+        try:
+            meta = json.loads(meta_raw)
+        except json.JSONDecodeError as exc:
+            raise OOVModelError(f"{path}: meta_json is not valid JSON: {exc}") from exc
+
+        self.grapheme_chars: str = meta["grapheme_chars"]
+        self.phoneme_chars: str = meta["phoneme_chars"]
+        self.max_positions = int(meta["max_position_embeddings"])
+        self.bos_id = int(meta["bos_token_id"])
+        self.eos_id = int(meta["eos_token_id"])
+        self.start_id = int(meta["decoder_start_token_id"])
+        self.offset = int(meta["position_offset"])
+        eps = float(meta["layer_norm_eps"])
+        heads = int(meta["num_heads"])
+        d_model = int(meta["d_model"])
+        if heads != 1:
+            raise OOVModelError(f"this port assumes one attention head, checkpoint has {heads}")
+        scaling = (d_model // heads) ** -0.5
+
+        self.grapheme_to_id = {
+            ch: i for i, ch in enumerate(self.grapheme_chars) if i >= SPECIAL_TOKEN_COUNT
+        }
+        self.embed = weights["model.shared.weight"]
+        self.logit_bias = weights["final_logits_bias"][0]
+        self.enc_pos = weights["model.encoder.embed_positions.weight"]
+        self.dec_pos = weights["model.decoder.embed_positions.weight"]
+        self.enc_ln = (weights["model.encoder.layernorm_embedding.weight"],
+                       weights["model.encoder.layernorm_embedding.bias"])
+        self.dec_ln = (weights["model.decoder.layernorm_embedding.weight"],
+                       weights["model.decoder.layernorm_embedding.bias"])
+        self.encoder = _Layer(weights, "model.encoder.layers.0", scaling, eps, cross=False)
+        self.decoder = _Layer(weights, "model.decoder.layers.0", scaling, eps, cross=True)
+        self.eps = eps
+
+    def encode_word(self, word: str) -> list[int]:
+        """Character ids with bos/eos, unknown characters mapped to <unk>."""
+        return [self.bos_id, *(self.grapheme_to_id.get(c, UNK_ID) for c in word), self.eos_id]
+
+    def __call__(self, word: str) -> str:
+        """Phonemes for `word`, or '' if the model emits nothing usable."""
+        if not word:
+            raise OOVModelError("cannot phonemize an empty word")
+        ids = self.encode_word(word)
+        if len(ids) > self.max_positions:
+            raise OOVModelError(
+                f"word {word!r} needs {len(ids)} positions; the model has {self.max_positions}"
+            )
+        memory = self._encode(np.asarray(ids, dtype=np.int64))
+
+        out: list[int] = [self.start_id]
+        for _ in range(self.max_positions - 1):
+            logits = self._decode_step(np.asarray(out, dtype=np.int64), memory)
+            nxt = int(np.argmax(logits))
+            if nxt == self.eos_id:
+                break
+            out.append(nxt)
+        return "".join(
+            self.phoneme_chars[i] for i in out[1:]
+            if SPECIAL_TOKEN_COUNT <= i < len(self.phoneme_chars)
+        )
+
+    def _encode(self, ids: np.ndarray) -> np.ndarray:
+        hidden = self.embed[ids] + self.enc_pos[self.offset : self.offset + len(ids)]
+        hidden = _layer_norm(hidden, *self.enc_ln, self.eps)
+        return self.encoder(hidden, None, causal=False)
+
+    def _decode_step(self, ids: np.ndarray, memory: np.ndarray) -> np.ndarray:
+        hidden = self.embed[ids] + self.dec_pos[self.offset : self.offset + len(ids)]
+        hidden = _layer_norm(hidden, *self.dec_ln, self.eps)
+        hidden = self.decoder(hidden, memory, causal=True)
+        return hidden[-1] @ self.embed.T + self.logit_bias
+
+
+_SHARED: OOVPhonemizer | None = None
+
+
+def shared_phonemizer() -> OOVPhonemizer:
+    """One process-wide instance; loading the npz costs ~3 MB and a few ms."""
+    global _SHARED
+    if _SHARED is None:
+        _SHARED = OOVPhonemizer()
+    return _SHARED

microtts/models.py

@@ -0,0 +1,225 @@
+"""Vocetta2 student networks: three small models over a mel-100 interface.
+
+  duration:  phoneme ids -> per-phoneme frame counts
+  acoustic:  ids + durations -> mel spectrogram [100, T]
+  decoder:   mel + noise [4, T] -> complex spectrum [513, T] -> iSTFT -> audio
+
+Residual Conv1d blocks, ConvNeXt1D decoder, LayerNorm eps=1e-6, an
+exp-magnitude head with bin 0 and the Nyquist bin zeroed, Hann-windowed
+overlap-add iSTFT and a DC-blocking filter.
+"""
+import math
+
+import numpy as np
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+
+
+# ---------------------------------------------------------------------------
+# Duration student
+# ---------------------------------------------------------------------------
+class DurationStudent(nn.Module):
+    def __init__(self, vocab=62, hidden=20, depth=3, kernel=5,
+                 max_tokens=207, max_duration=80):
+        super().__init__()
+        self.hidden = hidden
+        self.kernel = kernel
+        self.max_tokens = max_tokens
+        self.max_duration = max_duration
+        self.embed = nn.Embedding(vocab, hidden)
+        self.proj = nn.Conv1d(hidden + 3, hidden, 1)
+        self.blocks = nn.ModuleList()
+        self.scales = nn.ParameterList()
+        for _ in range(depth):
+            self.blocks.append(nn.ModuleList([
+                nn.Conv1d(hidden, hidden, kernel, padding=kernel // 2),
+                nn.Conv1d(hidden, hidden, kernel, padding=kernel // 2),
+            ]))
+            self.scales.append(nn.Parameter(torch.tensor(0.5)))
+        self.out = nn.Conv1d(hidden, 1, 1)
+
+    def forward(self, ids, round_out=True):
+        n = ids.shape[0]
+        x = self.embed(ids).T  # [H, n]
+        positions = torch.linspace(0.0, 1.0, n, device=ids.device) if n > 1 else torch.zeros(1, device=ids.device)
+        length_hint = math.log1p(max(n, 1)) / math.log1p(float(self.max_tokens))
+        feats = torch.stack([positions,
+                             torch.full((n,), length_hint, device=ids.device),
+                             torch.ones(n, device=ids.device)])
+        x = torch.cat([x, feats], dim=0)  # [H+3, n]
+        x = self.proj(x)
+        for (c0, c1), scale in zip(self.blocks, self.scales):
+            h = F.silu(c0(x))
+            h = c1(h)
+            x = x + scale * h
+        log_d = self.out(x)[0]  # [n] log-duration (differentiable)
+        if not round_out:
+            return log_d
+        d = torch.round(torch.clamp(torch.exp(log_d), min=1.0))
+        return torch.clamp(d, 1, self.max_duration).long()
+
+
+# ---------------------------------------------------------------------------
+# Acoustic student (token-context)
+# ---------------------------------------------------------------------------
+class AcousticStudent(nn.Module):
+    def __init__(self, vocab=62, hidden=24, token_depth=3, depth=3, kernel=5, n_mels=100):
+        super().__init__()
+        self.hidden = hidden
+        self.kernel = kernel
+        self.embed = nn.Embedding(vocab, hidden)
+        self.tproj = nn.Conv1d(hidden + 2, hidden, 1)
+        self.token_blocks = nn.ModuleList()
+        self.token_scales = nn.ParameterList()
+        for _ in range(token_depth):
+            self.token_blocks.append(nn.ModuleList([
+                nn.Conv1d(hidden, hidden, kernel, padding=kernel // 2),
+                nn.Conv1d(hidden, hidden, kernel, padding=kernel // 2),
+            ]))
+            self.token_scales.append(nn.Parameter(torch.tensor(0.5)))
+        self.fproj = nn.Conv1d(hidden + 3, hidden, 1)
+        self.frame_blocks = nn.ModuleList()
+        self.frame_scales = nn.ParameterList()
+        for _ in range(depth):
+            self.frame_blocks.append(nn.ModuleList([
+                nn.Conv1d(hidden, hidden, kernel, padding=kernel // 2),
+                nn.Conv1d(hidden, hidden, kernel, padding=kernel // 2),
+            ]))
+            self.frame_scales.append(nn.Parameter(torch.tensor(0.5)))
+        self.out = nn.Conv1d(hidden, n_mels, 1)
+
+    def forward(self, ids, durations):
+        n = ids.shape[0]
+        dev = ids.device
+        x = self.embed(ids).T  # [H, n]
+        token_pos = torch.linspace(0.0, 1.0, n, device=dev) if n > 1 else torch.zeros(1, device=dev)
+        dur_f = durations.float().to(dev)
+        max_dur = max(float(dur_f.max()), 1.0)
+        duration_hint = torch.log1p(dur_f) / math.log1p(max_dur)
+        x = torch.cat([x, torch.stack([token_pos, duration_hint])], dim=0)  # [H+2, n]
+        x = self.tproj(x)
+        for (c0, c1), scale in zip(self.token_blocks, self.token_scales):
+            h = F.silu(c0(x))
+            h = c1(h)
+            x = x + scale * h
+        # repeat by durations
+        x = torch.repeat_interleave(x, durations.to(dev), dim=1)  # [H, T]
+        frames = x.shape[1]
+        frame_pos = torch.linspace(0.0, 1.0, frames, device=dev) if frames > 1 else torch.zeros(1, device=dev)
+        token_pos_f = torch.repeat_interleave(token_pos, durations.to(dev))
+        dur_pos_f = torch.cat([torch.linspace(0.0, 1.0, int(d), device=dev) if d > 1
+                               else torch.zeros(1, device=dev) for d in durations])
+        x = torch.cat([x, torch.stack([frame_pos, token_pos_f, dur_pos_f])], dim=0)  # [H+3, T]
+        x = self.fproj(x)
+        for (c0, c1), scale in zip(self.frame_blocks, self.frame_scales):
+            h = F.silu(c0(x))
+            h = c1(h)
+            x = x + scale * h
+        return self.out(x)  # [100, T]
+
+
+# ---------------------------------------------------------------------------
+# Decoder student (ConvNeXt1D -> iSTFT)
+# ---------------------------------------------------------------------------
+class ConvNeXtBlock(nn.Module):
+    def __init__(self, dim, pw_hidden, dw_kernel=7):
+        super().__init__()
+        self.dw = nn.Conv1d(dim, dim, dw_kernel, padding=dw_kernel // 2, groups=dim)
+        self.norm = nn.LayerNorm(dim, eps=1e-6)
+        self.pw0 = nn.Linear(dim, pw_hidden)
+        self.pw1 = nn.Linear(pw_hidden, dim)
+        self.gamma = nn.Parameter(torch.ones(dim))
+
+    def forward(self, x):
+        # x: [C, T]
+        h = self.dw(x)
+        h = h.transpose(0, 1)  # [T, C]
+        h = self.norm(h)
+        h = F.gelu(self.pw0(h))
+        h = self.pw1(h)
+        h = h.transpose(0, 1) * self.gamma[:, None]  # [C, T]
+        return x + h
+
+
+class DecoderStudent(nn.Module):
+    def __init__(self, n_mels=100, dim=48, blocks=3, pw_hidden=144,
+                 dw_kernel=7, embed_kernel=7, noise_ch=4,
+                 n_fft=1024, hop=256, bins=513):
+        super().__init__()
+        self.n_fft = n_fft
+        self.hop = hop
+        self.bins = bins
+        self.embed = nn.Conv1d(n_mels, dim, embed_kernel, padding=embed_kernel // 2)
+        self.noise_adapter = nn.Conv1d(noise_ch, dim, embed_kernel, padding=embed_kernel // 2)
+        self.norm = nn.LayerNorm(dim, eps=1e-6)
+        self.blocks = nn.ModuleList([ConvNeXtBlock(dim, pw_hidden, dw_kernel) for _ in range(blocks)])
+        self.fnorm = nn.LayerNorm(dim, eps=1e-6)
+        self.head = nn.Linear(dim, bins * 2)
+
+    def forward(self, mel, noise):
+        # mel: [100, T], noise: [4, T]
+        x = self.embed(mel) + self.noise_adapter(noise)  # [C, T]
+        x = self.norm(x.transpose(0, 1)).transpose(0, 1)  # LayerNorm over channels
+        for b in self.blocks:
+            x = b(x)
+        x = self.fnorm(x.transpose(0, 1)).transpose(0, 1)
+        out = self.head(x.transpose(0, 1)).transpose(0, 1)  # [2*bins, T]
+        mag, phase = out[:self.bins], out[self.bins:]
+        mag = torch.exp(mag)
+        mag = mag.clone()
+        mag[0] = 0.0
+        mag[-1] = 0.0
+        mag = torch.clamp(mag, max=1e2)
+        return mag.unsqueeze(-1) * torch.stack([torch.cos(phase), torch.sin(phase)], dim=-1)  # [bins, T, 2]
+
+    def istft(self, spec):
+        """spec: [bins, T, 2] complex -> audio via Hann-windowed overlap-add."""
+        bins, frames, _ = spec.shape
+        window = torch.hann_window(self.n_fft, periodic=True, device=spec.device).double()
+        length = (frames - 1) * self.hop + self.n_fft
+        out = torch.zeros(length, device=spec.device, dtype=torch.float64)
+        norm = torch.zeros(length, device=spec.device, dtype=torch.float64)
+        spec_c = torch.complex(spec[..., 0], spec[..., 1])  # [bins, T]
+        frames_td = torch.fft.irfft(spec_c, n=self.n_fft, dim=0)  # [n_fft, T]
+        wsq = window * window
+        for i in range(frames):
+            start = i * self.hop
+            out[start:start + self.n_fft] += frames_td[:, i] * window
+            norm[start:start + self.n_fft] += wsq
+        pad = self.n_fft // 2
+        out = out[pad:length - pad]
+        norm = norm[pad:length - pad]
+        nonzero = norm > 1e-11
+        out[nonzero] /= norm[nonzero]
+        return out.float()
+
+    def dc_block(self, wav, r=0.9973, taps=4096):
+        impulse = torch.zeros(taps, device=wav.device, dtype=torch.float64)
+        impulse[0] = 1.0
+        n = torch.arange(1, taps, device=wav.device, dtype=torch.float64)
+        impulse[1:] = (r - 1.0) * r ** (n - 1.0)
+        samples = wav.shape[0]
+        n_lin = samples + taps - 1
+        n_fft = 1 << (n_lin - 1).bit_length()
+        filtered = torch.fft.irfft(torch.fft.rfft(wav.double(), n_fft) * torch.fft.rfft(impulse, n_fft), n_fft)
+        return filtered[:samples].float()
+
+    def synthesize(self, mel, noise):
+        spec = self.forward(mel, noise)
+        return self.dc_block(self.istft(spec))
+
+
+def count_params(m):
+    return sum(p.numel() for p in m.parameters())
+
+
+if __name__ == "__main__":
+    dur = DurationStudent()
+    ac = AcousticStudent()
+    dec = DecoderStudent()
+    n_dur, n_ac, n_dec = count_params(dur), count_params(ac), count_params(dec)
+    print(f"duration: {n_dur:,}")
+    print(f"acoustic: {n_ac:,}")
+    print(f"decoder:  {n_dec:,}")
+    print(f"TOTAL:    {n_dur + n_ac + n_dec:,}")

microtts/synthesize.py

@@ -0,0 +1,134 @@
+"""The end-to-end Vocetta2 runtime: text -> waveform.
+
+    from microtts import MicroTTS
+    tts = MicroTTS.load(".")
+    wav = tts.synthesize("Hello world.")   # float32 numpy, 24 kHz
+
+Pipeline: english G2P -> duration -> acoustic -> (+ mel tilt) -> decoder.
+
+This model ships a mel-level tilt correction (`tilt.npy`, a 100-value per-band
+offset) and the runtime applies it by default, exactly as the published
+benchmark numbers were measured. For this checkpoint the shipped vector is all
+zeros: zero tilt measured best for this acoustic, so applying it changes
+nothing. The file is kept so the inference path carries the same explicit,
+inspectable convention as the smaller releases in the family, and so a tilt
+recomputed for a different acoustic has a defined home.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+import numpy as np
+import torch
+
+from .g2p import phonemize
+from .models import AcousticStudent, DecoderStudent, DurationStudent
+
+SAMPLE_RATE = 24000
+MAX_FRAMES = 2400          # ~25 s at hop 256 / 24 kHz; the training cap
+# Architecture dims. The shipped config.json overrides these at load time, so
+# one runtime serves every model in the family (500k / 1M / ...); the values
+# below are this model's shipped configuration.
+ACOUSTIC_HIDDEN = 72
+ACOUSTIC_DEPTH = 5
+ACOUSTIC_TOKEN_DEPTH = 3
+DECODER_DIM = 130
+DECODER_PW = 337
+DECODER_BLOCKS = 4
+DURATION_HIDDEN = 12
+DURATION_DEPTH = 3
+
+
+class MicroTTS:
+    """Loaded once, reused for many sentences."""
+
+    def __init__(self, duration, acoustic, decoder, tilt=None, device: str = "cpu"):
+        self.duration = duration.eval()
+        self.acoustic = acoustic.eval()
+        self.decoder = decoder.eval()
+        self.tilt = tilt                      # torch [100] or None
+        self.device = torch.device(device)
+
+    # ------------------------------------------------------------------ load
+    @classmethod
+    def load(cls, model_dir: str | os.PathLike = ".", device: str = "cpu") -> "MicroTTS":
+        """Load duration.pt / acoustic.pt / decoder.pt (and tilt.npy) from `model_dir`."""
+        d = Path(model_dir)
+        cfg = {}
+        cfg_path = d / "config.json"
+        if cfg_path.exists():
+            try:
+                cfg = json.loads(cfg_path.read_text(encoding="utf-8"))
+            except Exception:
+                cfg = {}
+        dims = cfg.get("architecture_dims", {})
+        dur = DurationStudent(hidden=dims.get("duration_hidden", DURATION_HIDDEN),
+                              depth=dims.get("duration_depth", DURATION_DEPTH))
+        ac = AcousticStudent(hidden=dims.get("acoustic_hidden", ACOUSTIC_HIDDEN),
+                             depth=dims.get("acoustic_depth", ACOUSTIC_DEPTH),
+                             token_depth=dims.get("acoustic_token_depth", ACOUSTIC_TOKEN_DEPTH))
+        dec = DecoderStudent(dim=dims.get("decoder_dim", DECODER_DIM),
+                             pw_hidden=dims.get("decoder_pw", DECODER_PW),
+                             blocks=dims.get("decoder_blocks", DECODER_BLOCKS))
+
+        dur.load_state_dict(torch.load(d / "duration.pt", map_location="cpu", weights_only=True))
+        ac.load_state_dict(torch.load(d / "acoustic.pt", map_location="cpu", weights_only=True))
+        dec.load_state_dict(torch.load(d / "decoder.pt", map_location="cpu", weights_only=True))
+
+        tilt = None
+        tilt_path = d / "tilt.npy"
+        if tilt_path.exists():
+            tilt = torch.from_numpy(np.load(tilt_path).astype(np.float32)).reshape(-1)
+
+        dev = torch.device(device)
+        return cls(dur.to(dev), ac.to(dev), dec.to(dev),
+                   tilt=None if tilt is None else tilt.to(dev), device=device)
+
+    @staticmethod
+    def total_params(model_dir: str | os.PathLike = ".") -> int:
+        n = 0
+        for f in ("duration.pt", "acoustic.pt", "decoder.pt"):
+            sd = torch.load(Path(model_dir) / f, map_location="cpu", weights_only=True)
+            n += sum(v.numel() for v in sd.values() if hasattr(v, "numel"))
+        return n
+
+    # -------------------------------------------------------------- synthesis
+    def synthesize_ids(self, ids: list[int], noise_scale: float = 0.0,
+                       use_tilt: bool = True) -> np.ndarray:
+        """Phoneme ids -> waveform. noise_scale=0.0 is the recommended default;
+        use_tilt applies the shipped per-band mel correction (recommended)."""
+        t = torch.tensor(ids, device=self.device)
+        with torch.no_grad():
+            log_d = self.duration(t, round_out=False)
+            durs = torch.exp(log_d).round().clamp_min(1).long()
+            mel = self.acoustic(t, durs)
+            T = int(min(durs.sum().item(), MAX_FRAMES))
+            mel = mel[:, :T]
+            if use_tilt and self.tilt is not None:
+                mel = mel + self.tilt.unsqueeze(1)
+            if noise_scale == 0.0:
+                noise = torch.zeros(4, mel.shape[1], device=self.device)
+            else:
+                noise = torch.randn(4, mel.shape[1], device=self.device) * noise_scale
+            wav = self.decoder.synthesize(mel, noise)
+        return wav.cpu().numpy().reshape(-1).astype(np.float32)
+
+    def synthesize(self, text: str, noise_scale: float = 0.0,
+                   use_tilt: bool = True) -> np.ndarray:
+        """Text -> waveform. Loudness is unnormalized; see normalize() below."""
+        ids, _dropped = phonemize(text)
+        return self.synthesize_ids(ids, noise_scale=noise_scale, use_tilt=use_tilt)
+
+    # ---------------------------------------------------------------- helpers
+    @staticmethod
+    def normalize(wav: np.ndarray, rms: float = 0.05) -> np.ndarray:
+        """RMS-normalize to `rms` (0.05 is about -26 dBFS, a comfortable speech level)."""
+        return (wav / (np.sqrt(np.mean(wav ** 2)) + 1e-9) * rms).astype(np.float32)
+
+    @staticmethod
+    def save(path: str | os.PathLike, wav: np.ndarray) -> None:
+        import soundfile as sf
+        sf.write(str(path), MicroTTS.normalize(wav), SAMPLE_RATE)

model.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:efafc7bb114d44a33f89ac8955c201d3c6993069fe4694decf69e3f93c6a1eed
+size 4136872

requirements.txt

@@ -0,0 +1,3 @@
+numpy>=1.24
+torch>=2.0
+soundfile>=0.12

samples/sample_0.wav

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:8644685babb8fcb22fcc1b8c9700094920e9ac477b7ff310cd1f9faf469a6339
+size 176684

samples/sample_1.wav

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:923324b2a990991f18d773a6e9cbf7c33be9001e716d521e14bdc8fa385a894d
+size 111148

samples/sample_2.wav

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:bd4b6033651edd06ce93c25be67dc80bbaf9777677659a147d66cb2c6deafa6b
+size 174636

samples/sample_3.wav

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:9f17e362981e1053d01c6bb145daee8492b8f5e1449eb98e95c8794bfdbfa0a3
+size 168492

samples/sample_4.wav

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:b2f3fa987968f5ad7609052d31656d45524210b578716a19db2d5a1ad88868a3
+size 146476

samples/sample_5.wav

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:e66cb319ee441680c450b36549f7d30301ba069444cd8d2068032ac1a13474b9
+size 178220

samples/sample_6.wav

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:1c7d20317613c797f34e40f66de64f47cfe12f3068d111f2bbcec0d66578a9c8
+size 122412

samples/sample_7.wav

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:36583c66d4e7ee88e9d4f30c5a99b3780588bd2aa8308e54aae0e9e09484b936
+size 206892

tilt.npy

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:4e6e224a262c9b6cf055a59b8f994b1c02654003d0b5025843538efe6e2c5275
+size 528

train/README.md

@@ -0,0 +1,130 @@
+# Training scripts
+
+Eight scripts. Together they reproduce the recipe behind the shipped
+checkpoint, starting from a text corpus and a teacher TTS of your own.
+
+```
+build_pack.py            text corpus -> training pack (.npz per line)
+build_deploy_pack.py     teacher pack -> deployment pack (acoustic mels + vocoder renders)
+train_duration.py        ids -> frame counts (base run and pacing fine-tunes)
+train_acoustic.py        ids + durations -> mel
+init_decoder.py          slice a pretrained vocoder's decoder -> decoder_init.pt
+train_decoder.py         deployment-distribution decoder training and continuations
+compute_tilt.py          per-band mel correction between acoustic mel and teacher mel
+average_checkpoints.py   checkpoint averaging (the final lever; see below)
+```
+
+There is no joint stage here. Co-training the acoustic and decoder together
+was measured to make things worse on this family (twice, with two different
+loss stacks), so the recipe freezes the acoustic after its own training and
+trains the decoder only.
+
+## The configuration behind the released weights
+
+Teacher: one fixed-voice neural TTS (bring your own; the scripts are
+teacher-agnostic and mark where it plugs in). Corpus: about 42,000 varied
+sentences. Pack: 100-band mel, n_fft 1024, hop 256, 24 kHz.
+
+| stage | command core | steps | batch | lr | wall clock (approx., RTX 3090-class) |
+|---|---|---|---|---|---|
+| pack | `build_pack.py --textset corpus.jsonl --out packs/train` | ~42k rows | - | - | ~1 h |
+| duration base | `train_duration.py --hidden 12 --depth 3 --const-lr` | 4,000 | 32 | 2e-3 | ~6 min |
+| duration pacing 1 | `train_duration.py --init dur/final.pt --const-lr` | 8,000 | 16 | 5e-4 | ~11 min |
+| duration pacing 2 | `train_duration.py --init dur_ft12/final.pt --const-lr` | 12,000 | 16 | 2e-4 | ~17 min |
+| acoustic base | `train_acoustic.py --hidden 72 --depth 5 --token-depth 3 --const-lr` | 50,000 | 8 | 2e-3 | ~2.5 h |
+| acoustic polish | `train_acoustic.py --init 50k/final.pt` | 12,000 | 8 | 2e-4 | ~40 min |
+| acoustic polish 2 | `train_acoustic.py --init snap6k.pt` | 6,000 | 8 | 1e-4 | ~20 min |
+| acoustic bite | `train_acoustic.py --init ft2/final.pt --sc-weight 0.15` | 6,000 | 8 | 1e-4 | ~20 min |
+| acoustic twins | `train_acoustic.py --init bs015/final.pt` (x3, lr 1e-4 / 8e-5 / 1e-4) | 6k/6k/9k | 8 | see left | ~1 h |
+| deploy pack | `build_deploy_pack.py --pack packs/train --acoustic ... --duration ...` | ~20k rows | - | - | ~30 min |
+| decoder init | `init_decoder.py --dim 130 --pw 337 --blocks 4 --vocoder-ckpt <path>` | - | - | - | seconds |
+| decoder | `train_decoder.py --mix-prob 0.0 --const-lr --noise-zeros` | 115,000 | 4 | 2e-4 | ~6 h |
+| continuations | `train_decoder.py --init <prev>/last.pt --resume-step <n>` | 12k each | 4 | 2e-4 | ~40 min each |
+| soup | `average_checkpoints.py ...` | - | - | - | seconds |
+
+All stages are resumable: the trainers write `last.pt` plus `last_step.txt`
+every 500 to 1000 steps, and `--resume-step` restores the schedule position.
+
+Total shipped parameters: **1,031,754** (duration 5,344 + acoustic 438,516 +
+decoder 587,894).
+
+## What the released weights actually are
+
+The shipped checkpoints are not single training runs. They are averages, and
+the averaging is the part that produced the final quality:
+
+```
+decoder  fs1 = avg(e5, ss2)
+           e5  = avg(avgp1, w3e, w3d, w2ctl)
+           ss2 = avg(e2, e5)
+           e2  = avg(avgp1, w3e, w3d)
+           avgp1 = avg(champion_576k, w2ctl)
+
+           champion_576k = the best single decoder checkpoint
+           w2ctl = +12k steps on a 20k-row deployment pack
+           w3e   = +12k steps, crop length 256 frames, full pack
+           w3d   = +12k steps, crop length 128 frames, full pack
+
+acoustic G4 = weighted average of (bs015, ft2, t1, t2, t3) with weights
+              (2, 2, 1, 1, 1); bs015 is the gate-4.239 base, ft2 the
+              4.216 polish, t1..t3 three divergent fine-tune twins
+
+duration = the third stage of the pacing chain (pacing 2 above)
+```
+
+The practice, in plain terms: continue one good run in several short
+same-recipe stretches with one setting varied (crop length, pack subset), then
+average the results, then average the averages. Every member stays in the same
+basin, which is what makes the average better than any member. The script
+refuses to mix incompatible key sets and supports the weighted form used for
+the acoustic.
+
+Two measured rules from this line:
+- Averaging paid on every attempt. All of the night's gains (3.9462 to 4.0384,
+  +0.09) came from averaging; the only trained artifacts were six short
+  acoustic twins (about 10 minutes each). Training past the point of the soup
+  regressed on every attempt.
+- Two to six members is the working range. Larger blends diluted (a six-way
+  decoder blend and nine-way acoustic blends both lost to smaller ones).
+
+## Stage notes
+
+**Constant learning rates.** Every stage above runs with a constant lr. An
+exponential decay measurably starves models this small: the loss looks healthy
+while the output stays muddy. The duration fine-tunes and decoder runs used
+`--const-lr`; keep it.
+
+**Acoustic learning rate.** 2e-3 for the base run is the working value, and it
+matters more than anything else in this stage. The polish and bite stages use
+much lower rates (2e-4, 1e-4) for short stretches, and that is where the
+acoustic gate climbed from 4.083 to 4.239. The delta-L1 term (0.10) is the
+anti-smoothing supervision; the hinge PatchGAN critic (weight 0.1 starting
+early) sharpens further.
+
+**Acoustic depth is load-bearing.** Depth 5 is the value the family's
+reference recipe used; earlier work on this line had inherited depth 3, and
+switching to depth 5 at matched width was worth about +0.42 gate SCOREQ. Depth
+7 lost, and token-depth 5 lost. Sweep depth before spending budget elsewhere.
+
+**The decoder trains on the deployment distribution.** The deployment pack
+stores the acoustic student's own mels as inputs and full vocoder renders of
+those exact mels as targets. The decoder's objective becomes "reproduce the
+vocoder's output on the mels you will receive at inference", and the usual
+acoustic-to-decoder distribution gap does not exist to begin with. Pass
+`--noise-zeros` to match the inference convention.
+
+**Duration pacing is a quiet lever.** Two short fine-tunes of the duration
+student (8k then 12k steps at falling lr) improved the full system by about
++0.03 SCOREQ with nothing else changed. Rebuild the deployment pack after
+swapping the duration model, since the pack embeds its pacing.
+
+**The tilt file ships as zeros.** `compute_tilt.py` measures a per-band
+offset between the acoustic's mel and the teacher's mel. For this acoustic
+zero tilt measured best, so the shipped vector is all zeros and the runtime
+applies it as a no-op; the tool is included for retrained acoustics, where
+the answer can differ (it was worth +0.036 on the 500K sibling).
+
+**Do not tune against one metric.** A decoder tuned only against SCOREQ once
+learned to emit muffled, unintelligible audio that scored well on SCOREQ with
+a word error rate of 1.0. Every candidate in this line was checked with WER,
+DNSMOS, and listening.

train/average_checkpoints.py

@@ -0,0 +1,74 @@
+"""Average checkpoints into a soup (the lever that carried this release).
+
+Same-basin checkpoints from the same recipe, saved at different points of
+short continuation runs, average into a better model than any member: on this
+line the final soups scored +0.09 SCOREQ above their best single member, for
+zero training.
+
+    # uniform average
+    python average_checkpoints.py --out decoder_soup.pt a.pt b.pt c.pt d.pt
+
+    # weighted average (the acoustic blend used weights 2,2,1,1,1)
+    python average_checkpoints.py --out acoustic_G4.pt \
+        --weights 2,2,1,1,1 bs015.pt ft2.pt t1.pt t2.pt t3.pt
+
+Rules (measured on this line):
+  - Only average checkpoints with IDENTICAL key sets; the script refuses to mix
+    different architectures.
+  - Float tensors are averaged; non-float tensors are copied from the first
+    member.
+  - Members must share a basin (same recipe, diverged only by training noise
+    and step count). Mixing distant runs loses.
+  - 2 to 6 members is the proven range; more members dilute. The shipped
+    decoder is the average of its two best soups, which itself beat larger
+    blends, and the shipped acoustic is a pair-heavy blend of five
+    checkpoints.
+  - Averaging can be applied to soups again (nested), e.g. the shipped decoder
+    is avg(e5, ss2) where e5 and ss2 are themselves averages.
+"""
+import argparse
+
+import torch
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--out", required=True)
+    ap.add_argument("--weights", default=None,
+                    help="comma-separated per-input weights (default: uniform)")
+    ap.add_argument("inputs", nargs="+", help="checkpoint files to average")
+    args = ap.parse_args()
+
+    weights = None
+    if args.weights:
+        weights = [float(x) for x in args.weights.split(",")]
+        if len(weights) != len(args.inputs):
+            raise SystemExit(f"{len(weights)} weights for {len(args.inputs)} inputs")
+    else:
+        weights = [1.0] * len(args.inputs)
+    tot = sum(weights)
+
+    sds = [torch.load(p, map_location="cpu", weights_only=False) for p in args.inputs]
+    ks0 = set(sds[0].keys())
+    for p, sd in zip(args.inputs[1:], sds[1:]):
+        if set(sd.keys()) != ks0:
+            raise SystemExit(f"key mismatch: {p} does not match {args.inputs[0]}")
+
+    out = {}
+    for k in sds[0].keys():
+        ref = sds[0][k]
+        if torch.is_tensor(ref) and ref.is_floating_point():
+            acc = None
+            for w, sd in zip(weights, sds):
+                v = sd[k].float() * (w / tot)
+                acc = v if acc is None else acc + v
+            out[k] = acc
+        else:
+            out[k] = ref
+    torch.save(out, args.out)
+    n = sum(v.numel() for v in out.values() if torch.is_tensor(v))
+    print(f"averaged {len(sds)} checkpoints -> {args.out} ({n:,} parameters)")
+
+
+if __name__ == "__main__":
+    main()

train/build_deploy_pack.py

@@ -0,0 +1,112 @@
+"""Build the deployment pack: the decoder's training distribution.
+
+For every row of the teacher pack this produces a new row where:
+
+    mel   := acoustic_student(ids, durations)      (the exact inference input)
+    audio := full vocoder render of THAT mel       (the training target)
+    ids / durations := unchanged
+
+The decoder trained on this pack learns "reproduce the vocoder's output on the
+mels you will actually receive at inference", so the usual acoustic->decoder
+distribution gap does not exist to begin with. This is the single most
+important departure from the classic teacher-mel recipe, and it is what the
+released decoder was trained on.
+
+    python build_deploy_pack.py --pack packs/train \
+        --acoustic acoustic.pt --duration duration.pt --out packs/deploy
+
+Requires `vocos` (pip install vocos) for the renders. Uses CUDA when
+available; CPU works but is slower. The acoustic's sizes (width, depth) are
+detected from its state dict, so the script works for any model in the family.
+"""
+import argparse
+import glob
+import os
+import re
+import sys
+import time
+from pathlib import Path
+
+import numpy as np
+import torch
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+from microtts.models import AcousticStudent, DurationStudent
+
+
+def _detect_ac_dims(sd):
+    """(hidden, depth, token_depth) from an acoustic state dict."""
+    hidden = int(sd["embed.weight"].shape[1])
+    idx = [int(m.group(1)) for k in sd for m in [re.match(r"frame_blocks\.(\d+)\.", k)] if m]
+    depth = (max(idx) + 1) if idx else 3
+    tidx = [int(m.group(1)) for k in sd for m in [re.match(r"token_blocks\.(\d+)\.", k)] if m]
+    token_depth = (max(tidx) + 1) if tidx else 3
+    return hidden, depth, token_depth
+
+
+def _detect_dur_dims(sd):
+    """(hidden, depth) from a duration state dict."""
+    hidden = int(sd["embed.weight"].shape[1])
+    idx = [int(m.group(1)) for k in sd for m in [re.match(r"blocks\.(\d+)\.", k)] if m]
+    depth = (max(idx) + 1) if idx else 3
+    return hidden, depth
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--pack", default="packs/train")
+    ap.add_argument("--acoustic", required=True)
+    ap.add_argument("--duration", required=True)
+    ap.add_argument("--out", default="packs/deploy")
+    ap.add_argument("--device", default="cuda")
+    args = ap.parse_args()
+
+    device = torch.device(args.device if torch.cuda.is_available() else "cpu")
+    os.makedirs(args.out, exist_ok=True)
+
+    dur_sd = torch.load(args.duration, map_location="cpu", weights_only=False)
+    dur_h, dur_d = _detect_dur_dims(dur_sd)
+    dur = DurationStudent(hidden=dur_h, depth=dur_d).to(device)
+    dur.load_state_dict(dur_sd)
+    dur.eval()
+
+    ac_sd = torch.load(args.acoustic, map_location="cpu", weights_only=False)
+    ac_h, ac_d, ac_td = _detect_ac_dims(ac_sd)
+    ac = AcousticStudent(hidden=ac_h, depth=ac_d, token_depth=ac_td).to(device)
+    ac.load_state_dict(ac_sd)
+    ac.eval()
+    print(f"acoustic: hidden {ac_h}, depth {ac_d}, token_depth {ac_td} | duration: hidden {dur_h}, depth {dur_d}", flush=True)
+
+    from vocos import Vocos
+    vocos = Vocos.from_pretrained("charactr/vocos-mel-24khz").to(device).eval()
+    print("models loaded", flush=True)
+
+    files = sorted(glob.glob(os.path.join(args.pack, "*.npz")))
+    print(f"rows: {len(files)}", flush=True)
+    t0 = time.time()
+    done = 0
+    for i, f in enumerate(files):
+        out = os.path.join(args.out, os.path.basename(f))
+        if os.path.exists(out):
+            done += 1
+            continue
+        d = np.load(f)
+        ids = torch.from_numpy(d["phone_ids"].astype(np.int64)).long().to(device)
+        with torch.no_grad():
+            fr = torch.round(dur(ids)).long().clamp_min(1)
+            mel = ac(ids, fr)                      # [100, T] exact inference mel
+            aud = vocos.decode(mel.unsqueeze(0)).squeeze(0)
+        np.savez(out,
+                 phone_ids=d["phone_ids"].astype(np.int16),
+                 durations=fr.cpu().numpy().astype(np.int16),
+                 mel=mel.cpu().numpy().astype(np.float32),
+                 audio=aud.cpu().numpy().astype(np.float32))
+        done += 1
+        if done % 500 == 0:
+            print(f"  {done} done, {time.time()-t0:.0f}s", flush=True)
+
+    print(f"DEPLOY PACK DONE: {done} rows in {time.time()-t0:.0f}s", flush=True)
+
+
+if __name__ == "__main__":
+    main()

train/build_pack.py

@@ -0,0 +1,119 @@
+"""Build the training pack: render teacher audio for a text corpus.
+
+For every line of text this produces one .npz row holding everything the
+students need:
+
+    text -> teacher G2P -> phoneme string
+         -> teacher TTS -> audio (24 kHz) + per-phoneme durations
+         -> mel spectrogram (100 bands, n_fft 1024, hop 256) from that audio
+
+The teacher stack is a larger neural teacher TTS with a dictionary-first G2P,
+plus a 100-band log-mel extractor. The two classes are imported at the top of
+main() under placeholder names; point them at the teacher you have and the
+rest of the file works unchanged. Any teacher works as long as it reports
+phonemes, audio at 24 kHz, and per-phoneme durations.
+
+One subtlety matters: the released teacher reports durations at 40 Hz (600
+samples per unit at 24 kHz), while this pipeline's mel hop is 256 samples, so
+durations are converted with `dur_mel = round(pred_dur * 600 / 256)`.
+
+Run with the interpreter that has the teacher TTS and a mel extractor
+installed.
+
+    python build_pack.py --textset corpus.jsonl --out packs/train
+
+`--textset` is a JSONL file with one {"text": "..."} object per line.
+
+Note: the decoder stage of this release trains on a *deployment pack*, not on
+this teacher pack directly. See `build_deploy_pack.py` for how the teacher pack
+is converted (acoustic mels + vocoder renders of those mels) once the acoustic
+student exists.
+"""
+import argparse
+import json
+import os
+import sys
+import time
+from pathlib import Path
+
+import numpy as np
+import torch
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+from microtts.frontend import DEFAULT_VOCABULARY, phonemes_to_token_ids  # noqa: E402
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--textset", default="corpus.jsonl",
+                    help="JSONL with one {'text': ...} object per line")
+    ap.add_argument("--out", default="packs/train")
+    ap.add_argument("--max-rows", type=int, default=42000)
+    ap.add_argument("--max-sec", type=float, default=10.0)
+    ap.add_argument("--voice", default=None, help="teacher voice id")
+    ap.add_argument("--start", type=int, default=0)
+    args = ap.parse_args()
+
+    from teacher_runtime import TeacherPipeline  # your teacher TTS package
+    from your_mel_extractor import MelSpectrogramFeatures  # any 100-band log-mel extractor
+
+    pipeline = TeacherPipeline(device="cuda" if torch.cuda.is_available() else "cpu")
+    mel_ext = MelSpectrogramFeatures(sample_rate=24000, n_fft=1024, hop_length=256, n_mels=100, padding="center")
+
+    out_dir = Path(args.out)
+    out_dir.mkdir(parents=True, exist_ok=True)
+    rows = []
+    for line in open(args.textset, encoding="utf-8"):
+        line = line.strip()
+        if not line:
+            continue
+        obj = json.loads(line)
+        if "text" in obj:
+            rows.append((obj.get("id", f"row{len(rows)}"), obj["text"]))
+
+    rows = rows[args.start:args.start + args.max_rows]
+    print(f"rendering {len(rows)} rows to {out_dir}", flush=True)
+    t0 = time.time()
+    done = 0
+    for uid, text in rows:
+        try:
+            # 1. phonemes via the teacher's dictionary-first G2P
+            phonemes = None
+            for res in pipeline(text, voice=args.voice, speed=1.0):
+                phonemes = res.phonemes
+                audio = res.output.audio  # (L,) 24kHz
+                pred_dur = res.output.pred_dur  # (n_phonemes,) frames
+                break
+            if phonemes is None or pred_dur is None:
+                continue
+            # 2. tokenize to 62-symbol ids (BOS/EOS included)
+            ids, dropped = phonemes_to_token_ids(phonemes, DEFAULT_VOCABULARY)
+            if len(ids) > 207:
+                continue
+            # 3. mel-100 from teacher audio
+            audio_t = audio.unsqueeze(0) if audio.ndim == 1 else audio
+            mel = mel_ext(audio_t).squeeze(0)
+            # 4. IMPORTANT: teacher durations are at 40 Hz (600 samples/unit);
+            #    this pipeline's hop is 256 samples, so convert to mel-frame
+            #    units: dur_mel = round(pred_dur * 600 / 256)
+            dur_mel = np.round(pred_dur.numpy().astype(np.float64) * 600.0 / 256.0)
+            dur_mel = np.clip(dur_mel, 1, 80).astype(np.int16)
+            np.savez(
+                out_dir / f"{uid}.npz",
+                phone_ids=np.asarray(ids, dtype=np.int16),
+                durations=dur_mel,
+                mel=mel.numpy().astype(np.float32),
+                audio=audio.numpy().astype(np.float32),
+            )
+            done += 1
+        except Exception as e:
+            print(f"  skip {uid}: {type(e).__name__}: {e}", flush=True)
+        if done % 100 == 0 and done > 0:
+            el = time.time() - t0
+            print(f"  {done} done, {el:.0f}s ({done/el:.2f}/s)", flush=True)
+
+    print(f"DONE: {done} rows in {time.time()-t0:.0f}s", flush=True)
+
+
+if __name__ == "__main__":
+    main()

train/compute_tilt.py

@@ -0,0 +1,91 @@
+"""Compute the per-band mel tilt correction applied at inference.
+
+tilt[b] = mean over pack rows of (teacher_mel[b] - acoustic_mel[b])
+
+The shipped `tilt.npy` is a 100-value float32 vector; `microtts/synthesize.py`
+adds it to the acoustic's mel before decoding when present. For this model the
+shipped vector is all zeros: zero tilt measured best for this acoustic (a
+nonzero tilt computed for a different acoustic actively hurt, and the sweep
+0.0 / 0.75 / 1.0 / 1.25 / 1.5 was monotonic in the wrong direction). The tool
+is included so the correction can be recomputed for a retrained acoustic; the
+0.036 SCOREQ gain it gave the 500k line did not transfer here.
+
+    python compute_tilt.py --pack packs/train \
+        --acoustic acoustic.pt --duration duration.pt --out tilt.npy
+
+Recompute whenever the acoustic changes; whether tilt helps is acoustic
+specific. Acoustic sizes (width, depth) are detected from the state dicts.
+"""
+import argparse
+import glob
+import os
+import re
+import sys
+from pathlib import Path
+
+import numpy as np
+import torch
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+from microtts.models import AcousticStudent, DurationStudent
+
+
+def _detect_ac_dims(sd):
+    hidden = int(sd["embed.weight"].shape[1])
+    idx = [int(m.group(1)) for k in sd for m in [re.match(r"frame_blocks\.(\d+)\.", k)] if m]
+    depth = (max(idx) + 1) if idx else 3
+    tidx = [int(m.group(1)) for k in sd for m in [re.match(r"token_blocks\.(\d+)\.", k)] if m]
+    token_depth = (max(tidx) + 1) if tidx else 3
+    return hidden, depth, token_depth
+
+
+def _detect_dur_dims(sd):
+    hidden = int(sd["embed.weight"].shape[1])
+    idx = [int(m.group(1)) for k in sd for m in [re.match(r"blocks\.(\d+)\.", k)] if m]
+    depth = (max(idx) + 1) if idx else 3
+    return hidden, depth
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--pack", default="packs/train")
+    ap.add_argument("--acoustic", default="acoustic.pt")
+    ap.add_argument("--duration", default="duration.pt")
+    ap.add_argument("--rows", type=int, default=120)
+    ap.add_argument("--out", default="tilt.npy")
+    ap.add_argument("--device", default="cpu")
+    args = ap.parse_args()
+
+    device = torch.device(args.device if torch.cuda.is_available() else "cpu")
+    dur_sd = torch.load(args.duration, map_location="cpu", weights_only=False)
+    dur = DurationStudent(hidden=_detect_dur_dims(dur_sd)[0], depth=_detect_dur_dims(dur_sd)[1]).to(device)
+    dur.load_state_dict(dur_sd)
+    dur.eval()
+    ac_sd = torch.load(args.acoustic, map_location="cpu", weights_only=False)
+    ac_h, ac_d, ac_td = _detect_ac_dims(ac_sd)
+    ac = AcousticStudent(hidden=ac_h, depth=ac_d, token_depth=ac_td).to(device)
+    ac.load_state_dict(ac_sd)
+    ac.eval()
+
+    files = sorted(glob.glob(os.path.join(args.pack, "*.npz")))[:args.rows]
+    acc = np.zeros(100)
+    n = 0
+    for f in files:
+        d = np.load(f)
+        ids = torch.from_numpy(d["phone_ids"].astype(np.int64)).to(device)
+        with torch.no_grad():
+            fr = torch.round(dur(ids)).long().clamp_min(1)
+            mel_s = ac(ids, fr).cpu().numpy()
+        mel_t = d["mel"]
+        Ts = min(mel_t.shape[1], mel_s.shape[1])
+        if Ts < 4:
+            continue
+        acc += (mel_t[:, :Ts] - mel_s[:, :Ts]).mean(1)
+        n += 1
+    tilt = (acc / max(n, 1)).astype(np.float32)
+    np.save(args.out, tilt)
+    print(f"tilt from {n} rows -> {args.out} (mean {tilt.mean():.3f}, std {tilt.std():.3f})")
+
+
+if __name__ == "__main__":
+    main()

train/init_decoder.py

@@ -0,0 +1,75 @@
+"""Initialize the decoder student by channel-slicing a frozen pretrained vocoder.
+
+Training a decoder this small from scratch does not converge to intelligible
+audio; slicing the top-left corner of a pretrained neural vocoder's decoder
+weights does. Pass any ConvNeXt-style vocoder state dict with --vocoder-ckpt;
+this takes the first `--dim` channels, the first `--pw` hidden units and the
+first `--blocks` blocks (dim 130 / pw 337 / blocks 4 for the shipped model).
+
+The sliced checkpoint still needs decoder training (train_decoder.py) before
+it is usable: a fresh slice renders noise, and only fine-tuning brings it back.
+
+    python init_decoder.py --dim 130 --pw 337 --blocks 4 \
+        --vocoder-ckpt <vocos-mel-24khz state dict> --out decoder_init.pt
+"""
+import sys
+from pathlib import Path
+
+import torch
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+from microtts.models import DecoderStudent
+
+
+def main():
+    import argparse
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--dim", type=int, default=130)
+    ap.add_argument("--pw", type=int, default=337)
+    ap.add_argument("--blocks", type=int, default=4)
+    ap.add_argument("--vocoder-ckpt", default=None,
+                    help="state dict / checkpoint of a ConvNeXt-style neural vocoder")
+    ap.add_argument("--out", default="decoder_init.pt")
+    args = ap.parse_args()
+
+    if args.vocoder_ckpt:
+        obj = torch.load(args.vocoder_ckpt, map_location="cpu", weights_only=False)
+        sd = obj.state_dict() if hasattr(obj, "state_dict") else obj
+    else:
+        raise ImportError("pass --vocoder-ckpt pointing at a ConvNeXt-style vocoder state dict")
+
+    student = DecoderStudent(dim=args.dim, pw_hidden=args.pw, blocks=args.blocks)
+    ssd = student.state_dict()
+
+    # embedding conv: [512, 100, 7] -> [dim, 100, 7]
+    ssd["embed.weight"] = sd["backbone.embed.weight"][:args.dim].contiguous()
+    ssd["embed.bias"] = sd["backbone.embed.bias"][:args.dim].contiguous()
+    ssd["norm.weight"] = sd["backbone.norm.weight"][:args.dim].contiguous()
+    ssd["norm.bias"] = sd["backbone.norm.bias"][:args.dim].contiguous()
+    for i in range(args.blocks):
+        src = f"backbone.convnext.{i}"
+        dst = f"blocks.{i}"
+        ssd[f"{dst}.dw.weight"] = sd[f"{src}.dwconv.weight"][:args.dim].contiguous()
+        ssd[f"{dst}.dw.bias"] = sd[f"{src}.dwconv.bias"][:args.dim].contiguous()
+        ssd[f"{dst}.norm.weight"] = sd[f"{src}.norm.weight"][:args.dim].contiguous()
+        ssd[f"{dst}.norm.bias"] = sd[f"{src}.norm.bias"][:args.dim].contiguous()
+        # pointwise slices: pw0 [pw, dim], pw1 [dim, pw]
+        ssd[f"{dst}.pw0.weight"] = sd[f"{src}.pwconv1.weight"][:args.pw, :args.dim].contiguous()
+        ssd[f"{dst}.pw0.bias"] = sd[f"{src}.pwconv1.bias"][:args.pw].contiguous()
+        ssd[f"{dst}.pw1.weight"] = sd[f"{src}.pwconv2.weight"][:args.dim, :args.pw].contiguous()
+        ssd[f"{dst}.pw1.bias"] = sd[f"{src}.pwconv2.bias"][:args.dim].contiguous()
+        ssd[f"{dst}.gamma"] = sd[f"{src}.gamma"][:args.dim].contiguous()
+    # final norm + head
+    ssd["fnorm.weight"] = sd["backbone.final_layer_norm.weight"][:args.dim].contiguous()
+    ssd["fnorm.bias"] = sd["backbone.final_layer_norm.bias"][:args.dim].contiguous()
+    ssd["head.weight"] = sd["head.out.weight"][:, :args.dim].contiguous()
+    ssd["head.bias"] = sd["head.out.bias"].contiguous()
+
+    student.load_state_dict(ssd)
+    torch.save(student.state_dict(), args.out)
+    n = sum(p.numel() for p in student.parameters())
+    print(f"saved {args.out} | student params: {n:,}")
+
+
+if __name__ == "__main__":
+    main()

train/train_acoustic.py

@@ -0,0 +1,215 @@
+"""Train the acoustic student: ids + durations -> mel-100.
+
+Targets are the teacher mels from the pack. Loss: L1 + spectral convergence,
+plus norm/delta/channel-statistics terms and a hinge PatchGAN adversarial term
+that fights the over-smoothing a pure L1 regressor produces.
+
+Learning rate matters more than anything else here: 2e-3 is the working value
+for the base run. A model trained a few times lower simply underfits, and the
+symptom is a mel that is too smooth in time (frame-to-frame delta well below
+the teacher's) which garbles the output even when the L1 looks fine. The
+polish stages after the base run use lower rates (1e-4) for short stretches;
+see train/README.md for the exact chain that produced the shipped weights.
+
+    python train_acoustic.py --pack packs/train --hidden 72 --depth 5 \
+        --token-depth 3 --batch 8 --steps 50000
+"""
+import argparse
+import glob
+import os
+import time
+
+import numpy as np
+import torch
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+import torch.nn as nn
+import torch.nn.functional as F
+
+from microtts.models import AcousticStudent
+
+
+class MelDisc(nn.Module):
+    """PatchGAN 1D critic over time. Training-only, never shipped.
+
+    Hinge loss, dense patch scores over the time axis.
+    """
+    def __init__(self, channels=100, hidden=64, layers=3, kernel_size=5):
+        super().__init__()
+        padding = kernel_size // 2
+        widths = [channels] + [hidden] * layers
+        net: list[nn.Module] = []
+        for i in range(layers):
+            net.append(nn.Conv1d(widths[i], widths[i + 1], kernel_size, padding=padding))
+            net.append(nn.LeakyReLU(0.2))
+        net.append(nn.Conv1d(widths[layers], 1, kernel_size, padding=padding))
+        self.net = nn.Sequential(*net)
+
+    def forward(self, latent):
+        # [B, C, T] -> [B, 1, T'] -> [B, T']
+        return self.net(latent).squeeze(1)
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--pack", default="packs/train")
+    ap.add_argument("--steps", type=int, default=50000)
+    ap.add_argument("--batch", type=int, default=8)
+    ap.add_argument("--lr", type=float, default=2e-3)
+    ap.add_argument("--const-lr", action="store_true",
+                    help="constant lr (the released recipe; no scheduler)")
+    ap.add_argument("--norm-l1-weight", type=float, default=0.25)
+    ap.add_argument("--delta-l1-weight", type=float, default=0.10,
+                    help="temporal slope L1, the anti-over-smoothing term")
+    ap.add_argument("--channel-stat-weight", type=float, default=0.05)
+    ap.add_argument("--sc-weight", type=float, default=0.5,
+                    help="spectral-convergence weight (the sc-bite stage used 0.15)")
+    ap.add_argument("--adv-weight", type=float, default=0.1)
+    ap.add_argument("--adv-start-step", type=int, default=500)
+    ap.add_argument("--disc-lr-ratio", type=float, default=0.25,
+                    help="discriminator lr as a fraction of the model lr")
+    ap.add_argument("--betas", type=str, default="0.8,0.99")
+    ap.add_argument("--init", default=None,
+                    help="checkpoint to fine-tune from (polish and bite stages)")
+    ap.add_argument("--resume-step", type=int, default=0)
+    ap.add_argument("--device", default="cuda")
+    ap.add_argument("--tag", default="ac")
+    ap.add_argument("--hidden", type=int, default=72)
+    ap.add_argument("--token-depth", type=int, default=3)
+    ap.add_argument("--depth", type=int, default=5)
+    args = ap.parse_args()
+
+    device = torch.device(args.device if torch.cuda.is_available() else "cpu")
+    files = sorted(glob.glob(os.path.join(args.pack, "*.npz")))
+    print(f"pack: {len(files)} rows, device {device}")
+    model = AcousticStudent(hidden=args.hidden, token_depth=args.token_depth,
+                            depth=args.depth).to(device)
+    if args.init:
+        model.load_state_dict(torch.load(args.init, map_location=device, weights_only=False))
+        print(f"acoustic fine-tune init: {args.init}")
+    disc = MelDisc().to(device)
+    n = sum(p.numel() for p in model.parameters())
+    print(f"acoustic params: {n:,}")
+    betas = tuple(float(x) for x in args.betas.split(","))
+    opt = torch.optim.AdamW(model.parameters(), lr=args.lr, betas=betas)
+    opt_d = torch.optim.AdamW(disc.parameters(), lr=args.lr * args.disc_lr_ratio, betas=betas)
+    sched = None if args.const_lr else torch.optim.lr_scheduler.ExponentialLR(opt, gamma=0.9998)
+    sched_d = None if args.const_lr else torch.optim.lr_scheduler.ExponentialLR(opt_d, gamma=0.9998)
+    if sched is not None and args.resume_step > 0:
+        for _ in range(args.resume_step):
+            sched.step()
+            sched_d.step()
+
+    RUN = os.path.join("runs", args.tag)
+    os.makedirs(RUN, exist_ok=True)
+    t0 = time.time()
+    for step in range(args.resume_step + 1, args.steps + 1):
+        idx = np.random.choice(len(files), min(args.batch, len(files)), replace=False)
+        ids_list, dur_list, mel_list = [], [], []
+        for i in idx:
+            d = np.load(files[i])
+            ids_list.append(torch.from_numpy(d["phone_ids"].astype(np.int64)))
+            dur_list.append(torch.from_numpy(d["durations"].astype(np.int64)))
+            mel_list.append(torch.from_numpy(d["mel"]).float())
+        T = max(x.shape[0] for x in ids_list)
+        ids = torch.zeros(len(ids_list), T, dtype=torch.long)
+        for b, x in enumerate(ids_list):
+            ids[b, :x.shape[0]] = x
+        ids = ids.to(device)
+
+        opt.zero_grad()
+        opt_d.zero_grad()
+        total = 0.0
+        cnt = 0
+        adv_g_total = 0.0
+        use_adv = step >= args.adv_start_step
+        if use_adv:
+            for prm in disc.parameters():
+                prm.requires_grad_(False)  # generator path: no disc grads
+        for b in range(len(ids_list)):
+            n_tok = int((ids[b] > 0).sum())
+            if n_tok < 2:
+                continue
+            xb = ids[b, :n_tok]
+            db = dur_list[b][:n_tok]
+            mel_t = mel_list[b].to(device)  # [100, T]
+            Tf = mel_t.shape[1]
+            while db.sum() > Tf:
+                db = db.clone()
+                db[db.argmax()] -= 1
+            db = db.clamp_min(1)
+            mel_pred = model(xb, db)
+            Tp = min(mel_pred.shape[1], Tf)
+            p, t = mel_pred[:, :Tp], mel_t[:, :Tp]
+            l1 = F.l1_loss(p, t)
+            sc = (p - t).norm(dim=0) / (t.norm(dim=0) + 1e-6)
+            # anti-smoothing supervision
+            l_norm = torch.abs((p - p.mean(dim=1, keepdim=True)) / (p.std(dim=1, keepdim=True).clamp_min(1e-4))
+                               - (t - t.mean(dim=1, keepdim=True)) / (t.std(dim=1, keepdim=True).clamp_min(1e-4))).mean()
+            if Tp > 1:
+                l_delta = ((p[:, 1:] - p[:, :-1]) - (t[:, 1:] - t[:, :-1])).abs().mean()
+            else:
+                l_delta = torch.zeros((), device=device)
+            l_cstat = (torch.abs(p.mean(dim=1) - t.mean(dim=1))
+                       + torch.abs(p.std(dim=1) - t.std(dim=1))).mean()
+            total = total + l1 + args.sc_weight * sc.mean() \
+                + args.norm_l1_weight * l_norm \
+                + args.delta_l1_weight * l_delta \
+                + args.channel_stat_weight * l_cstat
+            if use_adv:
+                adv_g_total = adv_g_total - disc(p.unsqueeze(0)).mean()
+            cnt += 1
+        if cnt == 0:
+            continue
+        loss = total / cnt
+        if use_adv:
+            loss = loss + args.adv_weight * (adv_g_total / cnt)
+        loss.backward()
+        torch.nn.utils.clip_grad_norm_(model.parameters(), 1.0)
+        opt.step()
+        if use_adv:
+            for prm in disc.parameters():
+                prm.requires_grad_(True)
+            # update discriminator on detached inputs (dense patch hinge)
+            opt_d.zero_grad()
+            dl = 0.0
+            for b in range(len(ids_list)):
+                n_tok = int((ids[b] > 0).sum())
+                if n_tok < 2:
+                    continue
+                xb = ids[b, :n_tok]
+                db = dur_list[b][:n_tok]
+                mel_t = mel_list[b].to(device)
+                Tf = mel_t.shape[1]
+                while db.sum() > Tf:
+                    db = db.clone()
+                    db[db.argmax()] -= 1
+                db = db.clamp_min(1)
+                with torch.no_grad():
+                    mp = model(xb, db)
+                p = mp[:, :min(mp.shape[1], Tf)]
+                t = mel_t[:, :min(mp.shape[1], Tf)]
+                dl = dl + (F.relu(1.0 - disc(t.unsqueeze(0))).mean()
+                           + F.relu(1.0 + disc(p.unsqueeze(0))).mean())
+            (dl / max(cnt, 1)).backward()
+            opt_d.step()
+            if sched_d is not None:
+                sched_d.step()
+        if sched is not None:
+            sched.step()
+
+        if step % 100 == 0 or step == 1:
+            dt = time.time() - t0
+            print(f"step {step}/{args.steps} | mel {loss.item():.4f} | {step/dt:.1f} sps", flush=True)
+        if step % 1000 == 0:
+            torch.save(model.state_dict(), os.path.join(RUN, "last.pt"))
+
+    torch.save(model.state_dict(), os.path.join(RUN, "final.pt"))
+    print("ACOUSTIC DONE")
+
+
+if __name__ == "__main__":
+    main()

train/train_decoder.py

@@ -0,0 +1,501 @@
+"""Train the decoder student on the deployment distribution.
+
+The pack holds, per row: the acoustic student's mels (the exact inference
+input), the teacher's phoneme ids/durations, and, as audio targets, full
+vocoder renders of those exact mels. The objective is therefore "reproduce the
+vocoder's output on the mels you will actually receive", and there is no
+acoustic->decoder distribution gap to fix later.
+
+This is the full supervision stack used for the released weights:
+
+  waveform L1                       (wav-weight 1.0 for this model)
+  multi-resolution spectral loss
+  sig-temporal (cosine-gram)        (0.4)  temporal texture
+  feature-hint (channel moments)    (0.1)  distillation from the vocoder
+  quiet-ceiling                     (0.010) stops quiet-frame hiss
+  high-band-excess                  (0.1)  penalizes HF overshoot
+  MRD adversarial + feature match   (0.075 / 0.75 from step 1500)
+
+Requires `vocos` (pip install vocos) for the feature hooks; the pack itself
+needs no vocoder at train time.
+
+Stages used for the release (see train/README.md for wall-clock):
+    recovery  --mix-prob 0.0 --const-lr --noise-zeros
+    ... then short continuation arms and an averaging pass over the arms
+        (the released weights are a weight average of five same-recipe runs;
+         averaging paid +0.09 SCOREQ on this line, see the README).
+"""
+import argparse
+import glob
+import os
+import time
+
+import numpy as np
+import torch
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+import torch.nn as nn
+import torch.nn.functional as F
+
+from microtts.models import DecoderStudent
+
+
+# --------------------------------------------------------------------------
+# Teacher feature hooks (vocoder internals, for the hint + sig-temporal terms)
+# --------------------------------------------------------------------------
+class TeacherFeats:
+    """Capture the vocoder's internal activations at chosen stages."""
+
+    def __init__(self, vocos):
+        self.feats = {}
+        self.handles = []
+        b = vocos.backbone
+        self.handles.append(b.embed.register_forward_hook(self._h("embed")))
+        self.handles.append(b.convnext[3].register_forward_hook(self._h("cn3")))
+        self.handles.append(b.final_layer_norm.register_forward_hook(self._h("final")))
+
+    def _h(self, key):
+        def fn(mod, inp, out):
+            self.feats[key] = out
+        return fn
+
+    def clear(self):
+        self.feats = {}
+
+
+def standardized_time_series(v):
+    mean = v.mean(dim=1, keepdim=True)
+    std = v.std(dim=1, keepdim=True).clamp_min(1e-4)
+    return (v - mean) / std
+
+
+def temporal_cosine_gram(value):
+    """Per-timestep channel-vector self-similarity [B,T,T]."""
+    if value.ndim != 3:
+        raise RuntimeError(f"expected [B, C, T], got {value.shape}")
+    series = value.transpose(1, 2)
+    series = series - series.mean(dim=-1, keepdim=True)
+    series = F.normalize(series, dim=-1, eps=1e-6)
+    return torch.matmul(series, series.transpose(1, 2))
+
+
+def signature_temporal_loss(student_feats, teacher_feats, keys=("embed", "cn3")):
+    losses = []
+    for key in keys:
+        s = student_feats.get(key)
+        t = teacher_feats.get(key)
+        if s is None or t is None:
+            continue
+        if s.ndim == 3:
+            s = s[0]
+        if t.ndim == 3:
+            t = t[0]
+        T = min(s.shape[-1], t.shape[-1])
+        if T < 4:
+            continue
+        s = s[:, :T].unsqueeze(0).float()
+        t = t[:, :T].unsqueeze(0).float()
+        losses.append(F.l1_loss(temporal_cosine_gram(s), temporal_cosine_gram(t)))
+    if not losses:
+        return torch.zeros((), device=next(iter(student_feats.values())).device)
+    return sum(losses) / len(losses)
+
+
+def channel_moment_hint_loss(student_feats, teacher_feats):
+    """Standardized channel-mean + log-RMS envelopes."""
+    losses = []
+    for key in ("embed", "cn3"):
+        s = student_feats.get(key)
+        t = teacher_feats.get(key)
+        if s is None or t is None:
+            continue
+        if s.ndim == 3:
+            s = s[0]
+        if t.ndim == 3:
+            t = t[0]
+        if s.shape[-1] != t.shape[-1]:
+            T = min(s.shape[-1], t.shape[-1])
+            s, t = s[:, :T], t[:, :T]
+        s_mean = standardized_time_series(s.mean(dim=0, keepdim=True))
+        t_mean = standardized_time_series(t.mean(dim=0, keepdim=True))
+        s_rms = standardized_time_series(torch.log1p(torch.sqrt(s.square().mean(dim=0, keepdim=True) + 1e-6)))
+        t_rms = standardized_time_series(torch.log1p(torch.sqrt(t.square().mean(dim=0, keepdim=True) + 1e-6)))
+        losses.append(F.l1_loss(s_mean, t_mean))
+        losses.append(F.l1_loss(s_rms, t_rms))
+    if not losses:
+        return torch.zeros((), device=next(iter(student_feats.values())).device)
+    return sum(losses) / len(losses)
+
+
+# --------------------------------------------------------------------------
+# Spectral-resolution discriminator (UnivNet-style MRD)
+# --------------------------------------------------------------------------
+class SpectralResolutionDiscriminator(nn.Module):
+    def __init__(self, n_fft, hop_length, win_length, channels=(32, 32, 32, 32)):
+        super().__init__()
+        self.n_fft, self.hop_length, self.win_length = n_fft, hop_length, win_length
+        ks, st, pd = (3, 9), (1, 2), (1, 4)
+        layers = []
+        in_ch = 1
+        for out_ch in channels:
+            layers.append(nn.Conv2d(in_ch, out_ch, kernel_size=ks, stride=st, padding=pd))
+            in_ch = out_ch
+        self.layers = nn.ModuleList(layers)
+        self.post = nn.Conv2d(in_ch, 1, kernel_size=ks, padding=pd)
+
+    def spec(self, x):  # x: [1, T]
+        if x.shape[-1] < self.n_fft:
+            return None
+        w = torch.hann_window(self.n_fft, device=x.device, dtype=x.dtype)
+        s = torch.stft(x[0], self.n_fft, self.hop_length, win_length=self.win_length,
+                       window=w, return_complex=True)
+        return torch.log1p(s.abs()).unsqueeze(0).unsqueeze(0)  # [1,1,F,T]
+
+    def forward(self, x):
+        h = self.spec(x)
+        if h is None:
+            return None, None
+        feats = []
+        for layer in self.layers:
+            h = F.leaky_relu(layer(h), 0.1)
+            feats.append(h)
+        score = self.post(h)
+        feats.append(score)
+        return score, feats
+
+
+class MRD(nn.Module):
+    def __init__(self, configs=((512, 128, 512), (1024, 256, 1024), (2048, 512, 2048))):
+        super().__init__()
+        self.discs = nn.ModuleList([SpectralResolutionDiscriminator(*c) for c in configs])
+
+    def forward(self, x):
+        scores, feats = [], []
+        for d in self.discs:
+            s, f = d(x)
+            if s is None:
+                continue
+            scores.append(s)
+            feats.append(f)
+        return scores, feats
+
+
+def generator_lsgan_loss(fake_scores):
+    if not fake_scores:
+        return torch.zeros(())
+    total = sum((s - 1.0).square().mean() for s in fake_scores)
+    return total / len(fake_scores)
+
+
+def discriminator_lsgan_loss(real_scores, fake_scores):
+    if not real_scores:
+        return torch.zeros(())
+    total = sum((r - 1.0).square().mean() + f.square().mean()
+                for r, f in zip(real_scores, fake_scores))
+    return total / len(real_scores)
+
+
+def feature_matching_loss(real_feats, fake_feats):
+    losses = []
+    for rf, ff in zip(real_feats, fake_feats):
+        for a, b in zip(rf, ff):
+            losses.append(F.l1_loss(b, a.detach()))
+    if not losses:
+        return torch.zeros(())
+    return sum(losses) / len(losses)
+
+
+# --------------------------------------------------------------------------
+# Spectral losses
+# --------------------------------------------------------------------------
+def stft_loss(y, yh, device):
+    loss = 0.0
+    n = min(y.shape[-1], yh.shape[-1])
+    for n_fft, hop in [(512, 128), (1024, 256), (2048, 512)]:
+        if n < n_fft:
+            continue  # skip FFTs larger than the input
+        Y = torch.stft(y[..., :n], n_fft, hop, window=torch.hann_window(n_fft, device=device),
+                       return_complex=True, center=False)
+        Yh = torch.stft(yh[..., :n], n_fft, hop, window=torch.hann_window(n_fft, device=device),
+                        return_complex=True, center=False)
+        T = min(Y.shape[-1], Yh.shape[-1])
+        mag, mag_r = Y[..., :T].abs(), Yh[..., :T].abs()
+        sc = (mag - mag_r).norm(dim=-2) / (mag.norm(dim=-2) + mag_r.norm(dim=-2) + 1e-6)
+        lm = (mag.clamp_min(1e-6).log10() - mag_r.clamp_min(1e-6).log10()).abs().mean()
+        loss = loss + sc.mean() + lm
+    return loss / 3.0
+
+
+def high_band_excess_loss(prediction, target, sample_rate=24000, high_band_hz=6000.0, margin_db=1.0):
+    """Penalize HF energy ratio above the target's ratio times a margin."""
+    n_fft, hop = 1024, 256
+    window = torch.hann_window(n_fft, device=prediction.device, dtype=prediction.dtype)
+    ps = torch.stft(prediction[0], n_fft, hop, win_length=n_fft, window=window, return_complex=True)
+    ts = torch.stft(target[0], n_fft, hop, win_length=n_fft, window=window, return_complex=True)
+    nyq = sample_rate / 2.0
+    freqs = torch.linspace(0.0, nyq, n_fft // 2 + 1, device=prediction.device, dtype=prediction.dtype)
+    mask = (freqs >= high_band_hz).to(dtype=prediction.dtype).unsqueeze(-1)
+    p_pow = ps.abs().square()
+    t_pow = ts.abs().square()
+    pr = torch.sum(p_pow * mask) / torch.sum(p_pow).clamp_min(1e-10)
+    tr = torch.sum(t_pow * mask) / torch.sum(t_pow).clamp_min(1e-10)
+    margin_ratio = 10.0 ** (margin_db / 10.0)
+    excess = torch.log(pr.clamp_min(1e-10)) - torch.log((tr * margin_ratio).clamp_min(1e-10))
+    return F.relu(excess).square()
+
+
+def framed_rms(x, frame_size=1024, frame_hop=256):
+    if x.ndim == 2:
+        x = x[0]
+    if x.ndim == 1:
+        x = x.unsqueeze(0)
+    if x.shape[-1] < frame_size:
+        return x.square().mean(dim=-1).sqrt().unsqueeze(-1)
+    frames = x.unfold(-1, frame_size, frame_hop)
+    return frames.square().mean(dim=-1).sqrt().mean(dim=0, keepdim=True)
+
+
+def quiet_ceiling_loss(prediction, target, quantile=0.25, frame_size=1024, frame_hop=256, margin_db=0.5):
+    """Penalize predictions louder than the target on the target's quiet frames."""
+    tr = framed_rms(target, frame_size, frame_hop)
+    pr = framed_rms(prediction, frame_size, frame_hop)
+    T = min(tr.shape[-1], pr.shape[-1])
+    tr, pr = tr[..., :T], pr[..., :T]
+    thr = torch.quantile(tr.flatten(), quantile)
+    mask = (torch.log1p(tr) <= thr).to(prediction.dtype)
+    db = 20.0 / np.log(10.0)
+    excess_db = db * (torch.log(pr + 1e-8) - torch.log(tr + 1e-8)) - margin_db
+    return torch.sum(F.relu(excess_db) * mask) / mask.sum().clamp_min(1.0) / 20.0
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--pack", default="packs/deploy")
+    ap.add_argument("--steps", type=int, default=20000)
+    ap.add_argument("--batch", type=int, default=4)
+    ap.add_argument("--lr", type=float, default=2e-4)
+    ap.add_argument("--device", default="cuda")
+    ap.add_argument("--tag", default="dec")
+    ap.add_argument("--mix-prob", type=float, default=0.0,
+                    help="fraction of items that use live acoustic mels instead "
+                         "of the pack's (the deployment pack needs 0.0)")
+    ap.add_argument("--init", required=True,
+                    help="teacher-initialized decoder checkpoint (init_decoder.py) or a "
+                         "previous decoder checkpoint for continuation runs")
+    ap.add_argument("--resume-step", type=int, default=0,
+                    help="step number the init checkpoint was saved at (continuation runs)")
+    ap.add_argument("--dec-dim", type=int, default=130)
+    ap.add_argument("--dec-pw", type=int, default=337)
+    ap.add_argument("--dec-blocks", type=int, default=4)
+    ap.add_argument("--ac-hidden", type=int, default=72)
+    ap.add_argument("--ac-depth", type=int, default=5)
+    ap.add_argument("--ac-ckpt", default="acoustic.pt")
+    ap.add_argument("--dur-hidden", type=int, default=12)
+    ap.add_argument("--dur-ckpt", default="duration.pt")
+    # loss weights (the released recipe)
+    ap.add_argument("--feature-hint-weight", type=float, default=0.1)
+    ap.add_argument("--quiet-ceiling-weight", type=float, default=0.010)
+    ap.add_argument("--high-band-excess-weight", type=float, default=0.1)
+    ap.add_argument("--adv-weight", type=float, default=0.075)
+    ap.add_argument("--adv-feature-weight", type=float, default=0.75)
+    ap.add_argument("--adv-lr", type=float, default=2e-4)
+    ap.add_argument("--adv-start-step", type=int, default=1500)
+    ap.add_argument("--const-lr", action="store_true",
+                    help="constant lr (the released recipe)")
+    ap.add_argument("--betas", type=str, default="0.8,0.99")
+    ap.add_argument("--wav-weight", type=float, default=1.0)
+    ap.add_argument("--sig-temporal-weight", type=float, default=0.4)
+    ap.add_argument("--loud-weight", type=float, default=0.0)
+    ap.add_argument("--seg", type=int, default=64,
+                    help="training crop length in mel frames")
+    ap.add_argument("--noise-zeros", action="store_true",
+                    help="zeros instead of randn for the decoder noise input "
+                         "(matches inference; the released recipe)")
+    args = ap.parse_args()
+
+    device = torch.device(args.device if torch.cuda.is_available() else "cpu")
+    files = sorted(glob.glob(os.path.join(args.pack, "*.npz")))
+    print(f"pack: {len(files)} rows, device {device}", flush=True)
+
+    from microtts.models import AcousticStudent, DurationStudent
+
+    ac = AcousticStudent(hidden=args.ac_hidden, depth=args.ac_depth).to(device)
+    ac.load_state_dict(torch.load(args.ac_ckpt, map_location=device, weights_only=False))
+    ac.eval()
+    dur = DurationStudent(hidden=args.dur_hidden).to(device)
+    dur.load_state_dict(torch.load(args.dur_ckpt, map_location=device, weights_only=False))
+    dur.eval()
+
+    model = DecoderStudent(dim=args.dec_dim, pw_hidden=args.dec_pw, blocks=args.dec_blocks).to(device)
+    model.load_state_dict(torch.load(args.init, map_location=device, weights_only=False))
+    n = sum(p.numel() for p in model.parameters())
+    print(f"decoder params: {n:,} (init {args.init})", flush=True)
+
+    from vocos import Vocos
+    teacher = Vocos.from_pretrained("charactr/vocos-mel-24khz").to(device).eval()
+    for p in teacher.parameters():
+        p.requires_grad_(False)
+    tf = TeacherFeats(teacher)
+    print("vocoder loaded with hooks", flush=True)
+
+    mrd = MRD().to(device)
+    betas = tuple(float(x) for x in args.betas.split(","))
+    opt = torch.optim.AdamW(model.parameters(), lr=args.lr, betas=betas)
+    opt_d = torch.optim.AdamW(mrd.parameters(), lr=args.adv_lr, betas=betas)
+    sched = None if args.const_lr else torch.optim.lr_scheduler.ExponentialLR(opt, gamma=0.9998)
+    if sched is not None and args.resume_step > 0:
+        for _ in range(args.resume_step):
+            sched.step()
+
+    RUN = os.path.join("runs", args.tag)
+    os.makedirs(RUN, exist_ok=True)
+    t0 = time.time()
+    for step in range(args.resume_step + 1, args.steps + 1):
+        idx = np.random.choice(len(files), min(args.batch, len(files)), replace=False)
+        cnt = 0
+        content_total = None
+        opt.zero_grad()
+        gan_pair = None
+        for ii, i in enumerate(idx):
+            d = np.load(files[i])
+            mel_t = torch.from_numpy(d["mel"]).to(device)
+            audio = torch.from_numpy(d["audio"]).to(device)
+            T = mel_t.shape[1]
+            seg = args.seg
+            s = 0
+            if T > seg:
+                s = np.random.randint(0, T - seg)
+            if np.random.rand() < args.mix_prob:
+                # live student mel (used only for non-deployment packs)
+                ids = torch.from_numpy(d["phone_ids"]).long().to(device)
+                with torch.no_grad():
+                    dd = dur(ids)
+                    mel_s = ac(ids, dd)
+                seg_s = min(seg, mel_s.shape[1])
+                if seg_s < 16:
+                    continue
+                s_s = np.random.randint(0, max(1, mel_s.shape[1] - seg_s + 1))
+                mel = mel_s[:, s_s:s_s + seg_s]
+                a0, a1 = s_s * 256, (s_s + seg_s) * 256
+                if a1 > audio.shape[0]:
+                    a1 = audio.shape[0]
+                if a1 - a0 < 1024:
+                    continue
+                audio = audio[a0:a1]
+            else:
+                mel = mel_t[:, s:s + seg] if T > seg else mel_t
+                audio = audio[s * 256:(s + mel.shape[1]) * 256]
+            noise = torch.zeros(4, mel.shape[1], device=device) if args.noise_zeros \
+                else torch.randn(4, mel.shape[1], device=device)
+            wav = model.synthesize(mel, noise)
+            n_w = min(wav.shape[-1], audio.shape[-1])
+            wav_c, aud_c = wav[:n_w].unsqueeze(0), audio[:n_w].unsqueeze(0)
+            if gan_pair is None:
+                gan_pair = (wav_c, aud_c)
+
+            l_wav = F.l1_loss(wav[:n_w], audio[:n_w])
+            l_stft = stft_loss(wav_c, aud_c, device)
+            rms_p = wav[:n_w].square().mean().clamp_min(1e-8).sqrt()
+            rms_t = audio[:n_w].square().mean().clamp_min(1e-8).sqrt()
+            l_loud = F.l1_loss(rms_p, rms_t)
+
+            # feature-hint + signature-temporal: first item of the step only
+            l_hint = torch.zeros((), device=device)
+            l_sigt = torch.zeros((), device=device)
+            need_feats = (args.feature_hint_weight > 0 or args.sig_temporal_weight > 0) and ii == 0
+            if need_feats:
+                with torch.no_grad():
+                    tf.clear()
+                    teacher.decode(mel.unsqueeze(0))
+                    t_feats = {k: v.detach() for k, v in tf.feats.items()}
+                s_feats = {}
+                x = model.embed(mel) + model.noise_adapter(noise)
+                s_feats["embed"] = x
+                x2 = model.norm(x.transpose(0, 1)).transpose(0, 1)
+                cn_idx = min(3, len(model.blocks) - 1)
+                for bi, b in enumerate(model.blocks):
+                    x2 = b(x2)
+                    if bi == cn_idx:
+                        s_feats["cn3"] = x2
+                t_embed = t_feats.get("embed")
+                if t_embed is not None:
+                    t_embed = t_embed[0]
+                    Tt = min(t_embed.shape[-1], s_feats["embed"].shape[-1])
+                    t_feats["embed"] = t_embed[:, :Tt].unsqueeze(0)
+                    s_feats["embed"] = s_feats["embed"][:, :Tt].unsqueeze(0)
+                t_cn3 = t_feats.get("cn3")
+                if t_cn3 is not None:
+                    t_cn3 = t_cn3[0]
+                    Tt = min(t_cn3.shape[-1], s_feats["cn3"].shape[-1])
+                    t_feats["cn3"] = t_cn3[:, :Tt].unsqueeze(0)
+                    s_feats["cn3"] = s_feats["cn3"][:, :Tt].unsqueeze(0)
+                l_hint = channel_moment_hint_loss(s_feats, t_feats)
+                if args.sig_temporal_weight > 0:
+                    l_sigt = signature_temporal_loss(s_feats, t_feats)
+
+            l_hf = high_band_excess_loss(wav_c, aud_c, 24000, 6000.0, 1.0) \
+                if args.high_band_excess_weight > 0 else torch.zeros((), device=device)
+            l_quiet = quiet_ceiling_loss(wav_c[0], aud_c[0], 0.25, 1024, 256, 0.5) \
+                if args.quiet_ceiling_weight > 0 else torch.zeros((), device=device)
+
+            item = (args.wav_weight * l_wav + 1.0 * l_stft + args.loud_weight * l_loud
+                    + args.feature_hint_weight * l_hint
+                    + args.sig_temporal_weight * l_sigt
+                    + args.high_band_excess_weight * l_hf
+                    + args.quiet_ceiling_weight * l_quiet) / max(args.batch, 1)
+            content_total = item if content_total is None else content_total + item
+            cnt += 1
+
+        if cnt == 0 or content_total is None:
+            continue
+
+        content_total.backward(retain_graph=True)
+        l_adv = torch.zeros((), device=device)
+        l_adv_feat = torch.zeros((), device=device)
+        if step >= args.adv_start_step and gan_pair is not None:
+            wav_g, aud_g = gan_pair
+            nw = min(wav_g.shape[-1], aud_g.shape[-1])
+            wav_g, aud_g = wav_g[..., :nw], aud_g[..., :nw]
+            opt_d.zero_grad()
+            real_scores, _ = mrd(aud_g)
+            fake_scores, _ = mrd(wav_g.detach())
+            d_loss = discriminator_lsgan_loss(real_scores, fake_scores)
+            d_loss.backward()
+            torch.nn.utils.clip_grad_norm_(mrd.parameters(), 5.0)
+            opt_d.step()
+            for p in mrd.parameters():
+                p.requires_grad_(False)
+            fake_scores_g, fake_feats_g = mrd(wav_g)
+            _, real_feats_g = mrd(aud_g)
+            l_adv = generator_lsgan_loss(fake_scores_g)
+            l_adv_feat = feature_matching_loss(real_feats_g, fake_feats_g)
+            for p in mrd.parameters():
+                p.requires_grad_(True)
+            gan_loss = (args.adv_weight * l_adv + args.adv_feature_weight * l_adv_feat) / max(args.batch, 1)
+            gan_loss.backward()
+
+        torch.nn.utils.clip_grad_norm_(model.parameters(), 5.0)
+        opt.step()
+        if sched is not None:
+            sched.step()
+
+        if step % 100 == 0 or step == 1:
+            dt = time.time() - t0
+            print(f"step {step}/{args.steps} | wav {l_wav.item():.4f} stft {l_stft.item():.3f} "
+                  f"hint {l_hint.item():.4f} sigt {l_sigt.item():.4f} hf {l_hf.item():.4f} "
+                  f"quiet {l_quiet.item():.5f} adv {l_adv.item():.3f} fm {l_adv_feat.item():.3f} "
+                  f"| {step/dt:.1f} sps", flush=True)
+        if step % 500 == 0:
+            torch.save(model.state_dict(), os.path.join(RUN, "last.pt"))
+            with open(os.path.join(RUN, "last_step.txt"), "w") as f:
+                f.write(str(step))
+
+    torch.save(model.state_dict(), os.path.join(RUN, "final.pt"))
+    print("DECODER DONE")
+
+
+if __name__ == "__main__":
+    main()

train/train_duration.py

@@ -0,0 +1,126 @@
+"""Train the duration student: phoneme ids -> per-phoneme frame counts.
+
+Targets come from the teacher pack (the teacher's durations, converted to
+mel-frame units at build time). Loss: smooth-L1 on log-duration plus a
+total-length term (weight 0.35).
+
+The shipped checkpoint is the third stage of a small chain: a base run
+followed by two pacing fine-tunes at lower learning rates (see train/README.md
+for the exact commands). Pacing is a real quality lever on the full system:
+the end-to-end evaluation improved when the student's total-length error
+dropped, even though nothing else changed.
+
+    python train_duration.py --pack packs/train --hidden 12 --depth 3 --steps 4000
+"""
+import argparse
+import glob
+import os
+import time
+
+import numpy as np
+import torch
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+import torch.nn.functional as F
+
+from microtts.models import DurationStudent
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--pack", default="packs/train")
+    ap.add_argument("--steps", type=int, default=4000)
+    ap.add_argument("--batch", type=int, default=32)
+    ap.add_argument("--lr", type=float, default=2e-3)
+    ap.add_argument("--total-weight", type=float, default=0.35)
+    ap.add_argument("--const-lr", action="store_true",
+                    help="constant lr (the released pacing fine-tunes used this)")
+    ap.add_argument("--init", default=None,
+                    help="checkpoint to continue from (pacing fine-tune stages)")
+    ap.add_argument("--resume-step", type=int, default=0)
+    ap.add_argument("--device", default="cuda")
+    ap.add_argument("--tag", default="dur")
+    ap.add_argument("--hidden", type=int, default=12)
+    ap.add_argument("--depth", type=int, default=3)
+    ap.add_argument("--seed", type=int, default=0)
+    args = ap.parse_args()
+
+    torch.manual_seed(args.seed)
+    import random
+    random.seed(args.seed)
+
+    device = torch.device(args.device if torch.cuda.is_available() else "cpu")
+    files = sorted(glob.glob(os.path.join(args.pack, "*.npz")))
+    print(f"pack: {len(files)} rows, device {device}")
+    model = DurationStudent(hidden=args.hidden, depth=args.depth).to(device)
+    if args.init:
+        model.load_state_dict(torch.load(args.init, map_location=device, weights_only=False))
+        print(f"duration resume init: {args.init}")
+    n = sum(p.numel() for p in model.parameters())
+    print(f"duration params: {n:,}")
+    opt = torch.optim.AdamW(model.parameters(), lr=args.lr, betas=(0.8, 0.99))
+    sched = None if args.const_lr else torch.optim.lr_scheduler.ExponentialLR(opt, gamma=0.9995)
+    if sched is not None and args.resume_step > 0:
+        for _ in range(args.resume_step):
+            sched.step()
+
+    RUN = os.path.join("runs", args.tag)
+    os.makedirs(RUN, exist_ok=True)
+    t0 = time.time()
+    for step in range(args.resume_step + 1, args.steps + 1):
+        idx = np.random.choice(len(files), min(args.batch, len(files)), replace=False)
+        ids_list, dur_list = [], []
+        for i in idx:
+            d = np.load(files[i])
+            ids_list.append(torch.from_numpy(d["phone_ids"]))
+            dur_list.append(torch.from_numpy(d["durations"]))
+        # pad to max len in batch
+        T = max(x.shape[0] for x in ids_list)
+        ids = torch.zeros(args.batch, T, dtype=torch.long)
+        durs = torch.zeros(args.batch, T)
+        for b, (x, y) in enumerate(zip(ids_list, dur_list)):
+            ids[b, :x.shape[0]] = x
+            durs[b, :y.shape[0]] = y.float()
+        ids, durs = ids.to(device), durs.to(device)
+
+        opt.zero_grad()
+        # per-row forward (model takes 1D ids):
+        # smooth_l1(log pred, log target, beta=0.25) + 0.35 * log-total-frames MSE
+        losses = []
+        for b in range(args.batch):
+            n_tok = int((ids[b] > 0).sum())
+            if n_tok < 2:
+                continue
+            xb = ids[b, :n_tok]
+            log_pred = model(xb, round_out=False).float()
+            log_tgt = torch.log(durs[b, :n_tok].clamp_min(1))
+            token_loss = F.smooth_l1_loss(log_pred, log_tgt, beta=0.25)
+            total_loss = (torch.log(torch.exp(log_pred).clamp_min(1).sum().clamp_min(1))
+                          - torch.log(durs[b, :n_tok].clamp_min(1).sum().clamp_min(1))) ** 2
+            losses.append(token_loss + args.total_weight * total_loss)
+        if not losses:
+            continue
+        loss = sum(losses) / len(losses)
+        loss.backward()
+        torch.nn.utils.clip_grad_norm_(model.parameters(), 1.0)
+        opt.step()
+        if sched is not None:
+            sched.step()
+
+        if step % 200 == 0 or step == 1:
+            dt = time.time() - t0
+            print(f"step {step}/{args.steps} | dur {loss.item():.4f} | {step/dt:.1f} sps", flush=True)
+        if step % 500 == 0:
+            torch.save(model.state_dict(), os.path.join(RUN, "last.pt"))
+            with open(os.path.join(RUN, "last_step.txt"), "w") as f:
+                f.write(str(step))
+
+    torch.save(model.state_dict(), os.path.join(RUN, "final.pt"))
+    print("DURATION DONE")
+
+
+if __name__ == "__main__":
+    main()