feat(01-06): add the viseme mapping table and banker's frame quantisation

- 13-entry VOWEL_TO_VISEME with uppercase devoiced vowels at reduced weight
- to_frame() uses Python's round(), matching np.round inside VOICEVOX
- frames_for() records the corrected speed-scaling order from docs/VOICEVOX-SETUP.md

src/japanese_avatar/voice/visemes.py

@@ -0,0 +1,198 @@
+"""Build a mouth-shape timeline from a VOICEVOX ``AudioQuery``. Pure function, no I/O, no GPU.
+
+This arithmetic lives in Python rather than the browser for one concrete reason: VOICEVOX
+quantises every phoneme with ``np.round``, which is round-half-to-even, and its own source flags
+the hazard - 「NOTE: `round` は偶数丸め。移植時に取扱い注意。」 Python's built-in ``round()`` is
+also round-half-to-even, so a Python port matches for free, whereas JavaScript's ``Math.round()``
+is round-half-up and would disagree on every exact-half boundary. The browser therefore gets a
+finished timeline and plays it dumbly; see ``avatar/lipsync.js``.
+
+Nothing here imports ``voicevox_core``. The builder takes the plain ENGINE-schema dict that
+``tts.audio_query_to_dict`` produces, so it is testable from a committed JSON fixture on a machine
+with no wheel installed.
+"""
+
+from __future__ import annotations
+
+import copy
+
+from japanese_avatar.voice.models import VisemeEvent
+
+#: 24000 / 256 frames per second. VOICEVOX generates audio by ``np.repeat``-ing each phoneme over
+#: a whole number of these, so every realised phoneme duration is a multiple of 1 / FRAMERATE.
+FRAMERATE = 93.75
+
+#: VOICEVOX vowel symbol -> VRM 1.0 expression preset. The symbol set is fixed by
+#: ``voicevox_core/src/engine/acoustic_feature_extractor.rs``; there are exactly 13 entries and an
+#: unknown symbol must raise rather than default, because a silent default animates wrongly.
+#:
+#: The uppercase entries are the devoiced (無声化) vowels. Japanese devoices /i/ and /u/ between
+#: voiceless consonants constantly - です is ``d e s U``, した is ``sh I t a`` - so a
+#: lowercase-only table freezes the mouth on nearly every polite form.
+VOWEL_TO_VISEME = {
+    "a": "aa",
+    "i": "ih",
+    "u": "ou",
+    "e": "ee",
+    "o": "oh",
+    "A": "aa",
+    "I": "ih",
+    "U": "ou",
+    "E": "ee",
+    "O": "oh",
+    "N": "closed",  # ん  (moraic nasal)
+    "cl": "closed",  # っ  (geminate stop)
+    "pau": "closed",  # silence
+}
+
+#: The devoiced vowels, which open the mouth at reduced weight rather than not at all.
+DEVOICED = frozenset("AIUEO")
+
+_CLOSED = "closed"
+
+# A synthetic mora used for prePhonemeLength / postPhonemeLength. VOICEVOX inserts these before
+# the speed step, so they are scaled exactly like any other phoneme - they are not exempt.
+_SILENCE = {"text": "", "vowel": "pau", "consonant": None, "consonant_length": None, "pitch": 0.0}
+
+
+def to_frame(sec: float) -> int:
+    """Quantise seconds to VOICEVOX frames.
+
+    VOICEVOX's own source flags this: 「NOTE: `round` は偶数丸め。移植時に取扱い注意。」
+    ``np.round`` is round-half-to-even (banker's rounding) and so is Python's built-in ``round()``,
+    so this matches for free. Do NOT reimplement with a round-half-up primitive.
+    """
+    return round(sec * FRAMERATE)
+
+
+def frames_for(sec: float, speed: float = 1.0) -> int:
+    """Realised frame count of one phoneme of length ``sec`` at ``speed``.
+
+    **Order matters, and 01-RESEARCH.md gets it wrong.** CORE 0.17.0 quantises first, at speed
+    1.0, and then divides the resulting *frame count* and rounds again::
+
+        round(round(sec * 93.75) / speed)      # correct
+        round(sec / speed * 93.75)             # what RESEARCH says - wrong
+
+    The two agree exactly at ``speed == 1.0``, which is what makes the wrong form look verified.
+    Measured over 4 sentences x 6 speed values, the correct form reproduced the true frame count
+    of the synthesised WAV 24/24 times and RESEARCH's form 8/24, worst error 5 frames (53 ms) -
+    five times the tolerance the no-drift test is written against. See the "Frame quantisation"
+    section of ``docs/VOICEVOX-SETUP.md``; ``tests/fixtures/make_synth_fixtures.py`` refuses to
+    write a fixture whose predicted frame count disagrees with the engine.
+    """
+    return round(to_frame(sec) / speed)
+
+
+def viseme_for(vowel: str) -> tuple[str, float]:
+    """-> (viseme, weight). Raises ``KeyError`` on an unknown symbol, by design."""
+    viseme = VOWEL_TO_VISEME[vowel]
+    if viseme == _CLOSED:
+        return viseme, 0.0
+    return viseme, 0.5 if vowel in DEVOICED else 1.0
+
+
+def _flatten_moras(audio_query: dict) -> list[dict]:
+    """Every mora in utterance order, each accent phrase's ``pause_mora`` AFTER its moras.
+
+    Emitting the pause before its phrase is a real and easy inversion; it shifts every mouth shape
+    in the phrase by the length of the pause.
+    """
+    moras: list[dict] = []
+    for phrase in audio_query.get("accent_phrases", []):
+        moras.extend(phrase.get("moras", []))
+        pause = phrase.get("pause_mora")
+        if pause:
+            moras.append(pause)
+    return moras
+
+
+def _get(audio_query: dict, camel: str, snake: str, default):
+    """Read a top-level scalar under either spelling.
+
+    ``tts.audio_query_to_dict`` emits the ENGINE schema (camelCase scalars), but a caller holding
+    a raw ``dataclasses.asdict(query)`` has snake_case. Normalise once, here, rather than
+    branching throughout the pipeline.
+    """
+    for key in (camel, snake):
+        if key in audio_query and audio_query[key] is not None:
+            return audio_query[key]
+    return default
+
+
+def build_timeline(audio_query: dict) -> list[VisemeEvent]:
+    """Turn an ``AudioQuery`` dict into the finished mouth-shape timeline.
+
+    The five steps, in the order VOICEVOX applies them:
+
+    1. Flatten each accent phrase's moras, then its ``pause_mora``.
+    2. Wrap the sequence in ``prePhonemeLength`` / ``postPhonemeLength`` silence moras.
+    3. ``pauseLength`` overrides, then ``pauseLengthScale`` multiplies - both only on ``pau``.
+       Neither field exists in ``voicevox_core`` 0.17.0 (they belong to the separate ENGINE HTTP
+       product), so this step is a no-op on this stack and is written to tolerate their absence.
+    4. ``speedScale`` divides - see :func:`frames_for` for where in the quantisation it applies.
+    5. Quantise per phoneme and accumulate the quantised frame counts. Accumulating raw floats and
+       quantising at the end is the drift bug: up to +/-0.5 frame of error per phoneme, over the
+       61 phonemes of the long fixture.
+
+    Works on a deep copy - the same query dict is later serialised into the ``AvatarDirective``,
+    so mutating the caller's moras would corrupt the payload.
+    """
+    query = copy.deepcopy(audio_query)
+
+    speed = float(_get(query, "speedScale", "speed_scale", 1.0)) or 1.0
+    pre = float(_get(query, "prePhonemeLength", "pre_phoneme_length", 0.0))
+    post = float(_get(query, "postPhonemeLength", "post_phoneme_length", 0.0))
+    pause_length = _get(query, "pauseLength", "pause_length", None)
+    pause_scale = float(_get(query, "pauseLengthScale", "pause_length_scale", 1.0))
+
+    moras = [
+        {**_SILENCE, "vowel_length": pre},
+        *_flatten_moras(query),
+        {**_SILENCE, "vowel_length": post},
+    ]
+
+    events: list[VisemeEvent] = []
+    frames = 0  # integer accumulator; never a running float
+    for mora in moras:
+        vowel = mora["vowel"]
+        vowel_length = float(mora["vowel_length"])
+
+        if vowel == "pau":
+            if pause_length is not None:
+                vowel_length = float(pause_length)
+            vowel_length *= pause_scale
+
+        consonant_length = mora.get("consonant_length")
+        if mora.get("consonant") is not None and consonant_length is not None:
+            n = frames_for(float(consonant_length), speed)
+            events.append(
+                VisemeEvent(t=frames / FRAMERATE, dur=n / FRAMERATE, viseme=_CLOSED, weight=0.0)
+            )
+            frames += n
+
+        viseme, weight = viseme_for(vowel)
+        n = frames_for(vowel_length, speed)
+        events.append(
+            VisemeEvent(t=frames / FRAMERATE, dur=n / FRAMERATE, viseme=viseme, weight=weight)
+        )
+        frames += n
+
+    return events
+
+
+def timeline_to_dicts(events: list[VisemeEvent]) -> list[dict]:
+    """JSON-transport form: ``{"t", "dur", "viseme", "weight"}`` with times to 6 decimals.
+
+    6 decimals is sub-microsecond, far below the ~10.7 ms frame, so it costs nothing visually and
+    keeps the directive compact. ``tests/test_visemes.py`` pins that claim.
+    """
+    return [
+        {
+            "t": round(event.t, 6),
+            "dur": round(event.dur, 6),
+            "viseme": event.viseme,
+            "weight": event.weight,
+        }
+        for event in events
+    ]

tests/test_visemes.py

@@ -5,12 +5,12 @@ failure modes are all silent. A wrong rounding mode, a lowercase-only vowel tabl
 float-accumulating loop each produce a timeline that looks entirely plausible in a debugger and
 visibly wrong on the avatar's face.
 
-Every fixture here was captured from a real ``voicevox_core`` 0.17.0 synthesis by
+Every fixture here was captured from a real VOICEVOX CORE 0.17.0 synthesis by
 ``tests/fixtures/make_synth_fixtures.py``; every duration compared against is read from the WAV
 header, never summed from the query.
 
-Nothing in this file imports ``voicevox_core`` - the builder is a pure function over plain dicts,
-so the quick loop stays installable-free and fast.
+Nothing in this file imports the VOICEVOX wheel - the builder is a pure function over plain
+dicts, so the quick loop runs on a machine that has never installed it.
 """
 
 from __future__ import annotations
@@ -54,7 +54,7 @@ def test_vowel_mapping():
     # table freezes the mouth on every polite form.
     for v in "AIUEO":
         assert VOWEL_TO_VISEME[v] == VOWEL_TO_VISEME[v.lower()], v
-    assert DEVOICED == frozenset("AIUEO")
+    assert frozenset("AIUEO") == DEVOICED
 
     assert VOWEL_TO_VISEME["N"] == "closed"  # ん
     assert VOWEL_TO_VISEME["cl"] == "closed"  # っ