test(01-06): add failing tests for the vowel table and banker's frame quantisation

- 13-entry VOWEL_TO_VISEME including the uppercase devoiced A I U E O
- to_frame() proven round-half-to-even against 8 exact-half vectors

tests/test_visemes.py

@@ -0,0 +1,101 @@
+"""AVTR-02 and VOIC-03: the viseme timeline builder.
+
+This is the densest test file in Phase 1 because ``visemes.py`` is the one function whose
+failure modes are all silent. A wrong rounding mode, a lowercase-only vowel table or a
+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
+``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.
+"""
+
+from __future__ import annotations
+
+import math
+
+import pytest
+
+from japanese_avatar.voice.visemes import (
+    DEVOICED,
+    FRAMERATE,
+    VOWEL_TO_VISEME,
+    to_frame,
+    viseme_for,
+)
+
+# frames -> to_frame(frames / FRAMERATE). Round-half-up would give the third column.
+# Verified to round-trip exactly through f / 93.75 * 93.75 on CPython.
+BANKERS_VECTORS = [
+    (0.5, 0, 1),
+    (1.5, 2, 2),
+    (2.5, 2, 3),
+    (4.5, 4, 5),
+    (5.5, 6, 6),
+    (10.5, 10, 11),
+    (20.5, 20, 21),
+    (100.5, 100, 101),
+]
+
+
+def test_vowel_mapping():
+    """AVTR-02: every VOICEVOX vowel symbol, including the devoiced uppercase ones."""
+    assert VOWEL_TO_VISEME["a"] == "aa"
+    assert VOWEL_TO_VISEME["i"] == "ih"
+    assert VOWEL_TO_VISEME["u"] == "ou"
+    assert VOWEL_TO_VISEME["e"] == "ee"
+    assert VOWEL_TO_VISEME["o"] == "oh"
+
+    # Japanese devoices /i/ and /u/ between voiceless consonants constantly - です is
+    # "d e s U", した is "sh I t a". VOICEVOX emits those as UPPERCASE. A lowercase-only
+    # 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 VOWEL_TO_VISEME["N"] == "closed"  # ん
+    assert VOWEL_TO_VISEME["cl"] == "closed"  # っ
+    assert VOWEL_TO_VISEME["pau"] == "closed"  # silence
+
+    # Exactly 13: an extra key is an invented symbol, a missing key is a frozen mouth.
+    assert len(VOWEL_TO_VISEME) == 13, sorted(VOWEL_TO_VISEME)
+
+    # Devoiced vowels still open the mouth, just less.
+    assert viseme_for("u") == ("ou", 1.0)
+    assert viseme_for("U") == ("ou", 0.5)
+    assert viseme_for("I") == ("ih", 0.5)
+    assert viseme_for("N") == ("closed", 0.0)
+    assert viseme_for("pau") == ("closed", 0.0)
+
+    # A new VOICEVOX symbol must fail loudly rather than animate wrongly.
+    with pytest.raises(KeyError):
+        viseme_for("x")
+    with pytest.raises(KeyError):
+        VOWEL_TO_VISEME["q"]
+
+
+@pytest.mark.parametrize(("frames", "expected", "half_up"), BANKERS_VECTORS)
+def test_frame_quantisation_bankers(frames, expected, half_up):
+    """AVTR-02: round-half-to-even, matching np.round inside VOICEVOX itself.
+
+    The VOICEVOX source carries the warning 「NOTE: `round` は偶数丸め。移植時に取扱い注意。」
+    Python's built-in round() is banker's, so a Python port matches for free; JavaScript's
+    Math.round() is round-half-up and would disagree on every exact-half boundary. That is an
+    independent, concrete reason this arithmetic lives in Python.
+    """
+    assert FRAMERATE == 93.75
+    assert FRAMERATE == 24000 / 256
+
+    seconds = frames / FRAMERATE
+    # Fail loudly if a future Python stops round-tripping, rather than passing by luck.
+    assert seconds * FRAMERATE == frames, (frames, seconds * FRAMERATE)
+
+    assert to_frame(seconds) == expected
+
+    # Provably NOT round-half-up: on the exact-half boundaries the two modes disagree.
+    if expected != half_up:
+        assert to_frame(seconds) != math.floor(seconds * FRAMERATE + 0.5)
+        assert math.floor(seconds * FRAMERATE + 0.5) == half_up