Upload README.md with huggingface_hub

README.md

@@ -27,6 +27,9 @@ vocode   d, t_en, aln (1, N, F) fp32, ref_s
 - **Source**: [hexgrad/Kokoro-82M](https://huggingface.co/hexgrad/Kokoro-82M) — 81.8M parameters
 - **License**: apache-2.0
 - **Voices**: 54, shipped separately as `voices/*.pt` in the source repo
+- **Languages**: the graph is language-blind — it takes phoneme ids. **Verified here in
+  English and Japanese**; the voice pack also carries Spanish, French, Hindi, Italian,
+  Portuguese and Chinese voices, which are not verified on this card.
 
 Both axes — phonemes and frames — are **dynamic**, and both are **exact**. Nothing is
 padded, nothing is stretched, and there is no ladder of fixed-size methods. That took
@@ -46,6 +49,11 @@ ids = [vocab[c] for c in ps if c in vocab]          # config.json's 178-entry vo
 input_ids = torch.LongTensor([[0, *ids, 0]])        # wrapped in the boundary token
 ```
 
+For Japanese it is `misaki.ja.JAG2P()` and a `j*` voice, and nothing else changes — the
+ids go into the same graph. Install `misaki[ja]` **with `unidic-lite`**: `unidic`'s
+dictionary is a separate 250 MB download, and fugashi prefers `unidic` when both are
+present, which leaves you with an empty dicdir and an error about `mecabrc`.
+
 **2. Pick the style row by phoneme count.** The voice pack is 510 rows and the row is
 `pack[len(ps) - 1]` — indexed by the length of the phoneme **string**, which is what
 upstream's own pipeline does, and not by the number of ids, which is smaller whenever
@@ -130,11 +138,13 @@ minutes.
 
 ## Verification
 
-Five English sentences through `misaki`, each one synthesised by the `.pte` and by the
-unmodified upstream model in eager. Three gates, because no single one works here:
+Ten sentences through `misaki` — five English on `af_heart`, five Japanese on
+`jf_alpha` — each one synthesised by the `.pte` and by the unmodified upstream model in
+eager. Three gates, because no single one works here:
 
 **Durations must match exactly** — they are integers, they decide the rhythm, and they
-come out of the half of the model that has no noise in it. **5 of 5 exact.**
+come out of the half of the model that has no noise in it. **10 of 10 exact, both
+languages.**
 
 **Waveform correlation is not usable.** The vocoder's excitation carries Gaussian noise
 and a random initial phase, so the eager model does not reproduce itself: two runs of
@@ -146,14 +156,31 @@ second is the first:
 
 | | log-mel vs eager | eager's own floor | ratio |
 |---|---|---|---|
-| worst of five | 0.0427 | 0.0412 | **1.04x** |
-| best of five | 0.0442 | 0.0449 | 0.98x |
+| worst of ten | 0.0474 | 0.0455 | **1.04x** |
+| best of ten | 0.0393 | 0.0408 | 0.96x |
 
 Below and above 1.0 across the five, which is what "indistinguishable from running it
-again" looks like. For scale, one extra frame of padding shows up at 4.4x.
+again" looks like — and it moves a few percent between runs, because the noise source
+is in both arms. For scale, one extra frame of padding shows up at 4.4x, and the fp16
+build below at **73x**.
+
+**Transcripts**, through Qwen3-ASR, scored against **eager's own transcript** rather
+than against the sentence — what is under test is the conversion, and a recogniser
+choosing a different kanji is not the file's doing. **CER 0.0000 on nine of ten.**
+
+The tenth is worth writing down, because it is the recogniser and not the model:
+
+```
+この電車は東京駅に止まりますか   (does this train stop at Tokyo Station)
+eager  ...東京駅に泊まりますか    (stay overnight)      CER 0.067
+pte    ...東京駅に停まりますか    (stop)
+```
 
-**Transcripts**, through Qwen3-ASR: **CER 0.0000** on all five. Synthetic speech read
-by a recogniser is a control, not a benchmark — it says the file still says the words.
+Same reading, different kanji — and **eager disagrees with itself here**: four runs of
+the identical input gave 泊 once and 停 three times, and the `.pte` did the same. The
+vocoder's noise is enough to tip a near-tie in the recogniser. Durations are identical
+and log-mel is 1.02x the floor on this clip, so the two files are as close as eager is
+to itself. **An ASR-only gate would have recorded this as a defect.**
 
 ## Speed
 
@@ -162,9 +189,9 @@ by a recogniser is a control, not a benchmark — it says the file still says th
 | | ms |
 |---|---|
 | `predict` | 56.6 |
-| `vocode` | 443.7 |
-| **total** | **500.3** — 6.5x faster than real time |
-| the same utterance in eager PyTorch | 227.5 |
+| `vocode` | 441.4 |
+| **total** | **498.0** — 6.5x faster than real time |
+| the same utterance in eager PyTorch | 225.5 |
 
 Measured on a machine that was busy, so read these as a floor rather than a number to
 quote. Eager is faster here and that is expected: it reaches Accelerate's LSTM and
@@ -173,11 +200,31 @@ convolution kernels, while about half the graph runs on portable kernels
 
 ## What is not in this file
 
-**No fp16 or int8 build.** The int8 decision is measured, not assumed: dynamic int8
-quantises `nn.Linear` only, and Kokoro is **66.9% Conv1d** with just **15.9%** of its
-weights in Linear layers, so it would touch a sixth of the file. Static int8 would
-reach the convolutions, but a vocoder's quality under quantisation has to be measured
-per task rather than declared, and that has not been done here.
+**fp16 was built and withdrawn.** It fails three ways at once, and the first one is not
+about ExecuTorch at all:
+
+| | fp32 (this file) | fp16 (withdrawn) |
+|---|---|---|
+| size | 325.4 MB | 278.7 MB — a 14% saving, not the 50% the weights imply |
+| worst log-mel / noise floor | **0.99x** | **73x** |
+| worst CER | **0.0000** | **1.0000** — nothing intelligible |
+| 3.25 s of audio | **498 ms** | 2104 ms |
+
+**Halving this model breaks it in eager PyTorch, before any export.** At 96 phonemes the
+vocoder returns `nan`; at 24 it survives but sits at 2.8x the noise floor. Keeping the
+73 data-statistic norm layers in fp32 — the usual fix for `InstanceNorm` overflow — does
+not save it, so the overflow is not only in the norms. One duration in 96 also flips,
+which is a rounding tie rather than a numerical failure.
+
+The size is the least of it but worth knowing: the weights **do** halve to 163.4 MB, and
+the file is still 278.7 MB, because the XNNPACK delegate carries its own copy of the
+weights it takes.
+
+**No int8 build.** Measured, not assumed: dynamic int8 quantises `nn.Linear` only, and
+Kokoro is **66.9% Conv1d** with just **15.9%** of its weights in Linear layers, so it
+would touch a sixth of the file. Static int8 would reach the convolutions, but a
+vocoder's quality under quantisation has to be measured per task rather than declared,
+and that has not been done here.
 
 **The vocoder is partitioned without XNNPACK's `PermuteConfig`.** A permute inside the
 decoder feeds two consumers outside its partition, and the delegate's output list then