Replace the preview kit with calibrated modal synthesis

README.md

@@ -29,11 +29,11 @@ The Space uses Gradio Server mode with a fully custom, responsive interface.
 Upload a song, pick a difficulty, and get a full-song mel/plan preview, a
 full TJA chart image, a `.tja` playable in TJAPlayer3 / OpenTaiko, and a
 synchronized WAV mix that lets you hear the generated chart performed over
-the source music immediately. The original, arcade-tuned kit is built from
-hash-pinned CC0 head and rim recordings from the
-[Chinese Bass Drum Dagu Oneshots](https://freesound.org/people/sazanami12/packs/45781/)
-pack. SoftChart transforms those recordings offline and does not contain audio
-taken from a commercial game.
+the source music immediately. Its Don, Big Don, and Katsu voices are original
+modal-resonator syntheses built from seeded excitation noise, decaying drum
+modes, pitch sweeps, and band-limited stick transients. Reference recordings
+are used only for offline envelope and level calibration; they are not copied,
+mixed, embedded, or required by the Space.
 
 The generation API streams the real processing stages to the interface:
 audio analysis, beat-grid fitting, song-level planning, note generation,

scripts/build_taiko_bank.py

@@ -1,285 +0,0 @@
-# /// script
-# requires-python = ">=3.11"
-# dependencies = ["numpy<2.1", "scipy", "soundfile"]
-# ///
-"""Build SoftChart's redistributable arcade Taiko one-shot bank.
-
-The input directory must contain the pinned CC0 Freesound HQ OGG previews
-listed in ``SOURCES``.  This script is intentionally networkless: it verifies
-every source hash, renders deterministic mono PCM16 assets, and writes a
-provenance manifest.  Commercial-game reference audio is never an input.
-"""
-
-from __future__ import annotations
-
-import argparse
-import hashlib
-import json
-import math
-import wave
-from dataclasses import dataclass
-from fractions import Fraction
-from pathlib import Path
-
-import numpy as np
-import soundfile as sf
-from scipy.signal import butter, resample_poly, sosfilt
-
-
-SAMPLE_RATE = 44_100
-PACK_URL = "https://freesound.org/people/sazanami12/packs/45781/"
-CC0_URL = "https://creativecommons.org/publicdomain/zero/1.0/"
-
-
-@dataclass(frozen=True)
-class SourceSpec:
-    sound_id: int
-    label: str
-    sha256: str
-    preview_url: str
-
-
-SOURCES = {
-    856550: SourceSpec(856550, "center-soft", "78ed9dea56102480811e90a9653c08fe20a0eca5793c9c936f1c2592042b9a46", "https://cdn.freesound.org/previews/856/856550_17110092-hq.ogg"),
-    856552: SourceSpec(856552, "edge-soft", "85600ed1ddfab1c56fe07268f5fd68073706da8cd9a2f0cf7f16bde30bb8bb3e", "https://cdn.freesound.org/previews/856/856552_17110092-hq.ogg"),
-    856557: SourceSpec(856557, "rim-right", "6c24ee738d5995121fa85a432223a2afadb585f2a67b253747e2db0b3796bca0", "https://cdn.freesound.org/previews/856/856557_17110092-hq.ogg"),
-    856558: SourceSpec(856558, "rim-left", "5ac219e4254f27c4a3b5b581f5c67e7c72fe91fa3d0fb2e03d021793febc1872", "https://cdn.freesound.org/previews/856/856558_17110092-hq.ogg"),
-    856559: SourceSpec(856559, "rim-both-loud", "840a559e5d979e483cec2afb64e4f71a27d31c753c1bb138395303c5bd0d8253", "https://cdn.freesound.org/previews/856/856559_17110092-hq.ogg"),
-}
-
-
-def _sha256(path: Path) -> str:
-    digest = hashlib.sha256()
-    with path.open("rb") as handle:
-        for block in iter(lambda: handle.read(1 << 20), b""):
-            digest.update(block)
-    return digest.hexdigest()
-
-
-def _load_source(source_dir: Path, sound_id: int) -> np.ndarray:
-    spec = SOURCES[sound_id]
-    path = source_dir / f"{sound_id}.ogg"
-    if not path.is_file():
-        raise FileNotFoundError(f"missing pinned CC0 source: {path}")
-    actual_hash = _sha256(path)
-    if actual_hash != spec.sha256:
-        raise ValueError(
-            f"source hash mismatch for {path.name}: {actual_hash} != {spec.sha256}"
-        )
-    audio, sample_rate = sf.read(path, dtype="float64", always_2d=True)
-    if sample_rate != SAMPLE_RATE or audio.shape[1] != 2:
-        raise ValueError(f"{path.name} must decode as 44.1 kHz stereo")
-    mono = np.mean(audio, axis=1)
-    peak = float(np.max(np.abs(mono)))
-    onset_candidates = np.flatnonzero(np.abs(mono) >= peak * 10.0 ** (-30.0 / 20.0))
-    if len(onset_candidates) == 0:
-        raise ValueError(f"{path.name} has no measurable onset")
-    start = max(0, int(onset_candidates[0]) - int(round(0.001 * SAMPLE_RATE)))
-    mono = mono[start:].copy()
-    mono -= float(np.mean(mono[: min(100, len(mono))]))
-    return mono
-
-
-def _highpass(signal: np.ndarray, cutoff_hz: float) -> np.ndarray:
-    sos = butter(3, cutoff_hz, btype="highpass", fs=SAMPLE_RATE, output="sos")
-    return sosfilt(sos, signal)
-
-
-def _pitch(signal: np.ndarray, factor: float) -> np.ndarray:
-    ratio = Fraction(1.0 / factor).limit_denominator(1_000)
-    return resample_poly(signal, ratio.numerator, ratio.denominator)
-
-
-def _fit(signal: np.ndarray, frames: int) -> np.ndarray:
-    if len(signal) < frames:
-        return np.pad(signal, (0, frames - len(signal)))
-    return signal[:frames].copy()
-
-
-def _normalize(signal: np.ndarray, peak: float = 1.0) -> np.ndarray:
-    measured = float(np.max(np.abs(signal)))
-    if measured <= 1e-12:
-        raise ValueError("cannot normalize a silent sample")
-    return signal * (peak / measured)
-
-
-def _smooth_ramp(frames: int, seconds: float) -> np.ndarray:
-    position = np.arange(frames, dtype=np.float64) / SAMPLE_RATE
-    unit = np.clip(position / seconds, 0.0, 1.0)
-    return 0.06 + 0.94 * (unit * unit * (3.0 - 2.0 * unit))
-
-
-def _tail_fade(signal: np.ndarray, start_seconds: float, end_seconds: float) -> np.ndarray:
-    start = int(round(start_seconds * SAMPLE_RATE))
-    end = min(len(signal), int(round(end_seconds * SAMPLE_RATE)))
-    if not 0 <= start < end <= len(signal):
-        raise ValueError("invalid tail fade")
-    envelope = np.ones(len(signal), dtype=np.float64)
-    envelope[start:end] = 0.5 + 0.5 * np.cos(np.linspace(0.0, np.pi, end - start))
-    envelope[end:] = 0.0
-    return signal * envelope
-
-
-def _transient(source: dict[int, np.ndarray]) -> np.ndarray:
-    rim = _highpass(_pitch(source[856559], 2.15), 450.0)
-    search = rim[: int(round(0.100 * SAMPLE_RATE))]
-    peak = int(np.argmax(np.abs(search)))
-    start = max(0, peak - int(round(0.002 * SAMPLE_RATE)))
-    return _normalize(_fit(rim[start:], int(round(0.040 * SAMPLE_RATE))))
-
-
-def _don_body(source: dict[int, np.ndarray], sound_id: int, frames: int,
-              ramp_seconds: float) -> np.ndarray:
-    body = _fit(_normalize(_highpass(source[sound_id], 35.0)), frames)
-    return body * _smooth_ramp(frames, ramp_seconds)
-
-
-def _make_don(source: dict[int, np.ndarray], sound_id: int,
-              fade_start: float, fade_end: float) -> np.ndarray:
-    frames = int(round(0.830 * SAMPLE_RATE))
-    body = _don_body(source, sound_id, frames, 0.060)
-    hit = body + 0.15 * _fit(_transient(source), frames)
-    hit = np.tanh(_tail_fade(hit, fade_start, fade_end))
-    return _normalize(hit, 0.90)
-
-
-def _make_big_don(source: dict[int, np.ndarray]) -> np.ndarray:
-    frames = int(round(0.895 * SAMPLE_RATE))
-    center = _don_body(source, 856550, frames, 0.020)
-    hit = center + 0.60 * _fit(_transient(source), frames)
-    hit = np.tanh(_tail_fade(hit, 0.380, 0.800))
-    return _normalize(hit, 0.94)
-
-
-def _make_ka(source: dict[int, np.ndarray], primary_id: int,
-             secondary_id: int, secondary_gain: float) -> np.ndarray:
-    frames = int(round(0.407 * SAMPLE_RATE))
-    primary_raw = _pitch(source[primary_id], 2.15)
-    primary = _normalize(_highpass(primary_raw, 450.0))
-    secondary = _normalize(_highpass(_pitch(source[secondary_id], 0.85), 450.0))
-    hit = _fit(primary, frames) + secondary_gain * _fit(secondary, frames)
-    bright = _normalize(_highpass(_pitch(source[primary_id], 4.30), 1_800.0))
-    search = bright[: int(round(0.050 * SAMPLE_RATE))]
-    bright_peak = int(np.argmax(np.abs(search)))
-    bright_start = max(0, bright_peak - int(round(0.001 * SAMPLE_RATE)))
-    bright = _fit(bright[bright_start:], int(round(0.015 * SAMPLE_RATE)))
-    hit += 0.90 * _fit(bright, frames)
-    hit = _tail_fade(hit, 0.230, 0.407)
-    return _normalize(hit, 0.94)
-
-
-def _short_hit(signal: np.ndarray, duration: float, fade_start: float,
-               peak: float) -> np.ndarray:
-    frames = int(round(duration * SAMPLE_RATE))
-    hit = _fit(signal, frames)
-    hit = _tail_fade(hit, fade_start, duration)
-    return _normalize(hit, peak)
-
-
-def _build_assets(source: dict[int, np.ndarray]) -> dict[str, tuple[str, int, np.ndarray, list[int]]]:
-    don_1 = _make_don(source, 856552, 0.280, 0.710)
-    don_2 = _make_don(source, 856550, 0.220, 0.600)
-    don_big = _make_big_don(source)
-    ka_1 = _make_ka(source, 856559, 856557, 0.20)
-    ka_2 = _make_ka(source, 856557, 856558, 0.15)
-    ka_big = _normalize(0.70 * ka_1 + 0.70 * ka_2, 0.96)
-    roll_1 = _short_hit(don_1, 0.150, 0.065, 0.56)
-    roll_2 = _short_hit(don_2, 0.150, 0.065, 0.56)
-    roll_big_1 = _short_hit(don_big, 0.175, 0.080, 0.66)
-    roll_big_2 = _short_hit(0.72 * don_big + 0.28 * _fit(don_1, len(don_big)), 0.175, 0.080, 0.66)
-    balloon_1 = _short_hit(don_1, 0.135, 0.055, 0.54)
-    balloon_2 = _short_hit(don_2, 0.135, 0.055, 0.54)
-    return {
-        "don-01.wav": ("don", 1, don_1, [856552, 856559]),
-        "don-02.wav": ("don", 2, don_2, [856550, 856559]),
-        "don-big.wav": ("don_big", 1, don_big, [856550, 856559]),
-        "ka-01.wav": ("ka", 1, ka_1, [856559, 856557]),
-        "ka-02.wav": ("ka", 2, ka_2, [856557, 856558]),
-        "ka-big.wav": ("ka_big", 1, ka_big, [856559, 856557, 856558]),
-        "roll-01.wav": ("roll", 1, roll_1, [856552, 856559]),
-        "roll-02.wav": ("roll", 2, roll_2, [856550, 856559]),
-        "roll-big-01.wav": ("roll_big", 1, roll_big_1, [856550, 856559]),
-        "roll-big-02.wav": ("roll_big", 2, roll_big_2, [856550, 856552, 856559]),
-        "balloon-01.wav": ("balloon", 1, balloon_1, [856552, 856559]),
-        "balloon-02.wav": ("balloon", 2, balloon_2, [856550, 856559]),
-    }
-
-
-def _profile(signal: np.ndarray) -> dict[str, float]:
-    energy = signal * signal
-    cumulative = np.cumsum(energy)
-    spectrum = np.abs(np.fft.rfft(signal * np.hanning(len(signal)))) ** 2
-    frequency = np.fft.rfftfreq(len(signal), 1.0 / SAMPLE_RATE)
-    spectrum /= max(float(np.sum(spectrum)), 1e-15)
-    attack = signal[: int(round(0.010 * SAMPLE_RATE))]
-    attack_spectrum = np.abs(np.fft.rfft(attack * np.hanning(len(attack)))) ** 2
-    attack_frequency = np.fft.rfftfreq(len(attack), 1.0 / SAMPLE_RATE)
-    attack_spectrum /= max(float(np.sum(attack_spectrum)), 1e-15)
-    return {
-        "centroid_hz": round(float(frequency @ spectrum), 3),
-        "attack_centroid_hz": round(float(attack_frequency @ attack_spectrum), 3),
-        "t90_seconds": round(float(np.searchsorted(cumulative, 0.90 * cumulative[-1]) / SAMPLE_RATE), 6),
-        "t99_seconds": round(float(np.searchsorted(cumulative, 0.99 * cumulative[-1]) / SAMPLE_RATE), 6),
-        "crest_db": round(float(20.0 * math.log10(np.max(np.abs(signal)) / np.sqrt(np.mean(energy)))), 3),
-    }
-
-
-def _write_pcm16(path: Path, signal: np.ndarray) -> tuple[str, str, int]:
-    pcm = np.rint(np.clip(signal, -1.0, 1.0) * 32767.0).astype("<i2")
-    with wave.open(str(path), "wb") as output:
-        output.setnchannels(1)
-        output.setsampwidth(2)
-        output.setframerate(SAMPLE_RATE)
-        output.writeframes(pcm.tobytes())
-    return _sha256(path), hashlib.sha256(pcm.tobytes()).hexdigest(), len(pcm)
-
-
-def build(source_dir: Path, output_dir: Path) -> None:
-    source = {sound_id: _load_source(source_dir, sound_id) for sound_id in SOURCES}
-    output_dir.mkdir(parents=True, exist_ok=True)
-    files = []
-    for filename, (kind, round_robin, signal, source_ids) in _build_assets(source).items():
-        file_hash, pcm_hash, frames = _write_pcm16(output_dir / filename, signal)
-        peak = float(np.max(np.abs(signal)))
-        anchor = int(np.flatnonzero(np.abs(signal) >= peak * 10.0 ** (-30.0 / 20.0))[0])
-        files.append({
-            "filename": filename,
-            "kind": kind,
-            "round_robin": round_robin,
-            "sha256": file_hash,
-            "pcm_sha256": pcm_hash,
-            "sample_rate": SAMPLE_RATE,
-            "channels": 1,
-            "frames": frames,
-            "anchor_frame": anchor,
-            "source_sound_ids": source_ids,
-            "profile": _profile(signal),
-        })
-    manifest = {
-        "schema_version": 1,
-        "kit_id": "softchart-arcade-taiko-cc0",
-        "license": "CC0-1.0",
-        "license_url": CC0_URL,
-        "source_pack_url": PACK_URL,
-        "source_creator": "sazanami12",
-        "source_instrument": "Chinese Huapengu / Dagu recorded in Taipei, Taiwan",
-        "source_encoding": "public Freesound HQ OGG preview of the CC0 original WAV",
-        "sources": [spec.__dict__ for spec in SOURCES.values()],
-        "files": sorted(files, key=lambda item: item["filename"]),
-    }
-    (output_dir / "manifest.json").write_text(
-        json.dumps(manifest, indent=2, ensure_ascii=False) + "\n",
-        encoding="utf-8",
-    )
-
-
-def main() -> None:
-    parser = argparse.ArgumentParser()
-    parser.add_argument("--source-dir", type=Path, required=True)
-    parser.add_argument("--output-dir", type=Path, required=True)
-    args = parser.parse_args()
-    build(args.source_dir, args.output_dir)
-
-
-if __name__ == "__main__":
-    main()

scripts/build_taiko_synth.py

@@ -0,0 +1,437 @@
+# /// script
+# requires-python = ">=3.11"
+# dependencies = ["numpy<2.1", "scipy"]
+# ///
+"""Build SoftChart's three-voice modal-resonator Taiko preview bank.
+
+The supplied reference WAVs are used offline for RMS-envelope and level
+calibration only.  Reference samples, paths, hashes, and envelope arrays are
+never written to the output.  Every output sample is generated from a seeded
+noise/impulse excitation, modal resonators, and a decaying pitch sweep.
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import math
+import wave
+from dataclasses import dataclass
+from pathlib import Path
+
+import numpy as np
+from scipy.signal import butter, sosfilt
+
+
+SAMPLE_RATE = 48_000
+RANDOM_SEED = 20_260_713
+BUILD_ORDER = ("Big Don", "Don", "Katsu")
+EXPECTED_FRAMES = {"Big Don": 42_946, "Don": 39_836, "Katsu": 19_537}
+SYNTH_FRAMES = EXPECTED_FRAMES
+OUTPUT_NAMES = {
+    "Big Don": ("don-big.wav", "don_big"),
+    "Don": ("don.wav", "don"),
+    "Katsu": ("katsu.wav", "katsu"),
+}
+
+
+@dataclass(frozen=True)
+class ReferencePaths:
+    big_don: Path
+    don: Path
+    katsu: Path
+
+    def by_role(self) -> dict[str, Path]:
+        return {"Big Don": self.big_don, "Don": self.don, "Katsu": self.katsu}
+
+
+def _sha256(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as handle:
+        for block in iter(lambda: handle.read(1 << 20), b""):
+            digest.update(block)
+    return digest.hexdigest()
+
+
+def _read_reference(path: Path, role: str) -> np.ndarray:
+    if not path.is_file():
+        raise FileNotFoundError(f"missing {role} reference WAV: {path}")
+    with wave.open(str(path), "rb") as source:
+        sample_rate = source.getframerate()
+        channels = source.getnchannels()
+        width = source.getsampwidth()
+        frames = source.getnframes()
+        payload = source.readframes(frames)
+    if sample_rate != SAMPLE_RATE or channels != 1 or width != 2:
+        raise ValueError(f"{role} reference must be mono PCM16 at 48 kHz")
+    if frames != EXPECTED_FRAMES[role]:
+        raise ValueError(
+            f"{role} reference must contain {EXPECTED_FRAMES[role]} frames, got {frames}"
+        )
+    audio = np.frombuffer(payload, dtype="<i2").astype(np.float64) / 32768.0
+    if not np.all(np.isfinite(audio)) or float(np.max(np.abs(audio))) <= 1e-9:
+        raise ValueError(f"{role} reference must contain finite, non-silent audio")
+    return audio
+
+
+def _resonator_bank(
+    excitation: np.ndarray,
+    frequencies: list[float],
+    gains: list[float],
+    t60s: list[float],
+) -> np.ndarray:
+    output = np.zeros_like(excitation)
+    for frequency, gain, t60 in zip(frequencies, gains, t60s, strict=True):
+        radius = 10.0 ** (-3.0 / (max(t60, 0.001) * SAMPLE_RATE))
+        a1 = 2.0 * radius * math.cos(2.0 * math.pi * frequency / SAMPLE_RATE)
+        a2 = -(radius * radius)
+        input_gain = (1.0 - radius) * 4.0
+        previous = second_previous = 0.0
+        mode = np.empty_like(excitation)
+        for index, sample in enumerate(excitation):
+            value = input_gain * sample + a1 * previous + a2 * second_previous
+            mode[index] = value
+            second_previous, previous = previous, value
+        output += gain * mode
+    return output
+
+
+def _soft_normalize(audio: np.ndarray, peak: float = 0.95) -> np.ndarray:
+    shaped = np.tanh(audio * 1.15)
+    maximum = float(np.max(np.abs(shaped)))
+    if not math.isfinite(maximum) or maximum <= 1e-12:
+        raise ValueError("synthesizer produced silent or non-finite audio")
+    return shaped * (peak / maximum)
+
+
+def _make_synth(role: str, rng: np.random.Generator) -> np.ndarray:
+    frame_count = SYNTH_FRAMES[role]
+    if role == "Big Don":
+        frequencies = [86, 125, 141, 176, 193, 240, 264, 291, 313, 344, 409,
+                       529, 578, 700, 788, 869, 957, 1207, 1650, 2200, 2770]
+        gains = [1.00, .92, .28, .22, .45, .38, .28, .22, .18, .12, .12,
+                 .09, .07, .07, .08, .045, .04, .035, .018, .012, .010]
+        t60s = [.72, .82, .55, .50, .46, .40, .36, .34, .31, .28, .25,
+                .22, .19, .16, .14, .12, .11, .09, .07, .055, .045]
+        cutoff, noise_decay = 6_500.0, .018
+        sweep_start, sweep_end, sweep_decay = 302.0, 82.0, .11
+        direct_amount, body_amount, sweep_amount = .13, 1.60, .23
+    elif role == "Don":
+        frequencies = [86, 125, 141, 174, 193, 240, 247, 276, 292, 313, 368,
+                       386, 408, 487, 540, 578, 647, 694, 787, 870, 962, 2165]
+        gains = [1.0, .60, .27, .15, .34, .36, .23, .18, .20, .21, .10,
+                 .15, .10, .08, .08, .07, .07, .12, .12, .05, .05, .018]
+        t60s = [.52, .48, .37, .34, .34, .31, .30, .27, .25, .24, .22,
+                .21, .20, .18, .17, .16, .14, .14, .12, .10, .09, .052]
+        cutoff, noise_decay = 7_500.0, .024
+        sweep_start, sweep_end, sweep_decay = 346.0, 86.0, .075
+        direct_amount, body_amount, sweep_amount = .17, 1.55, .16
+    elif role == "Katsu":
+        time = np.arange(frame_count) / SAMPLE_RATE
+        noise = rng.standard_normal(frame_count)
+        high = sosfilt(
+            butter(3, 300 / (SAMPLE_RATE / 2), btype="high", output="sos"), noise,
+        )
+        band = sosfilt(
+            butter(
+                4, [450 / (SAMPLE_RATE / 2), 10_000 / (SAMPLE_RATE / 2)],
+                btype="band", output="sos",
+            ),
+            noise,
+        )
+        excitation = np.zeros(frame_count)
+        excitation[0] = 4.5
+        excitation += 1.6 * band * np.exp(-time / .018)
+        frequencies = [455, 560, 641, 735, 849, 1025, 1047, 1166, 1214, 1374,
+                       2188, 2231, 2279, 2933, 2994, 3083, 3123, 3856, 4006]
+        gains = [.25, .32, .38, .30, .26, .65, .52, .34, .26, .30, .85,
+                 .72, .38, .38, .30, .40, .34, .30, .28]
+        t60s = [.23, .18, .16, .14, .13, .20, .18, .15, .14, .13, .17,
+                .16, .13, .12, .11, .12, .11, .10, .10]
+        body = _resonator_bank(excitation, frequencies, gains, t60s)
+        direct = .32 * high * np.exp(-time / .050) + .50 * band * np.exp(-time / .012)
+        click_frames = max(1, int(.0012 * SAMPLE_RATE))
+        click = np.zeros(frame_count)
+        click[:click_frames] = rng.standard_normal(click_frames) * np.hanning(click_frames)
+        synth = 1.2 * body + direct + .18 * click
+        lead = int(.018 * SAMPLE_RATE)
+        return _soft_normalize(np.concatenate([np.zeros(lead), synth])[:frame_count])
+    else:
+        raise ValueError(f"unsupported synth role: {role}")
+
+    time = np.arange(frame_count) / SAMPLE_RATE
+    noise = rng.standard_normal(frame_count)
+    low = sosfilt(
+        butter(4, cutoff / (SAMPLE_RATE / 2), btype="low", output="sos"), noise,
+    )
+    excitation = np.zeros(frame_count)
+    excitation[0] = 3.0
+    excitation += 1.2 * low * np.exp(-time / noise_decay)
+    body = _resonator_bank(excitation, frequencies, gains, t60s)
+    instantaneous_frequency = (
+        (sweep_start - sweep_end) * np.exp(-time / .025) + sweep_end
+    )
+    phase = 2.0 * math.pi * np.cumsum(instantaneous_frequency) / SAMPLE_RATE
+    sweep = np.sin(phase) * np.exp(-time / sweep_decay)
+    synth = (
+        body_amount * body
+        + sweep_amount * sweep
+        + direct_amount * low * np.exp(-time / noise_decay)
+    )
+    synth *= (
+        1.0
+        + .03 * np.sin(2.0 * math.pi * 7.7 * time)
+        + .018 * np.sin(2.0 * math.pi * 14.9 * time + .5)
+    )
+    lead = int(.018 * SAMPLE_RATE)
+    return _soft_normalize(np.concatenate([np.zeros(lead), synth])[:frame_count])
+
+
+def _attack_burst(
+    frame_count: int,
+    seed: int,
+    low_hz: float,
+    high_hz: float,
+    attack_seconds: float,
+    decay_seconds: float,
+) -> np.ndarray:
+    time = np.arange(frame_count) / SAMPLE_RATE
+    noise = np.random.default_rng(seed).standard_normal(frame_count)
+    band = sosfilt(
+        butter(
+            3,
+            [low_hz / (SAMPLE_RATE / 2), high_hz / (SAMPLE_RATE / 2)],
+            btype="band",
+            output="sos",
+        ),
+        noise,
+    )
+    envelope = (
+        (1.0 - np.exp(-time / attack_seconds))
+        * np.exp(-time / decay_seconds)
+    )
+    return band * envelope
+
+
+def _calibrate_spectrum(role: str, synth: np.ndarray) -> np.ndarray:
+    """Tune attack and modal balance while preserving the supplied method."""
+
+    lead = int(.018 * SAMPLE_RATE)
+    active_frames = len(synth) - lead
+    time = np.arange(active_frames) / SAMPLE_RATE
+    calibrated = synth.copy()
+
+    if role in {"Big Don", "Don"}:
+        seed = 9_201 if role == "Big Don" else 9_202
+        burst = _attack_burst(
+            active_frames, seed, 2_000.0, 14_000.0, .0006, .0045,
+        )
+        if role == "Big Don":
+            calibrated[lead:] += 2.05 * burst
+            calibrated[lead:] += (
+                .25 * np.sin(2.0 * math.pi * 86.0 * time) * np.exp(-time / .50)
+            )
+        else:
+            calibrated[lead:] += 2.40 * burst
+            calibrated[lead:] += (
+                .20 * np.sin(2.0 * math.pi * 125.0 * time) * np.exp(-time / .30)
+            )
+        return calibrated
+
+    if role == "Katsu":
+        low = sosfilt(
+            butter(4, 3_000.0 / (SAMPLE_RATE / 2), btype="low", output="sos"),
+            calibrated,
+        )
+        mid = sosfilt(
+            butter(
+                3,
+                [1_400.0 / (SAMPLE_RATE / 2), 2_800.0 / (SAMPLE_RATE / 2)],
+                btype="band",
+                output="sos",
+            ),
+            calibrated,
+        )
+        burst = _attack_burst(
+            active_frames, 9_203, 1_000.0, 10_000.0, .0003, .004,
+        )
+        calibrated = low
+        calibrated[lead:] += 12.0 * mid[lead:] * np.exp(-time / .060)
+        calibrated[lead:] += 10.0 * burst
+        return calibrated
+
+    raise ValueError(f"unsupported synth role: {role}")
+
+
+def _rms_envelope(audio: np.ndarray, milliseconds: float = 6.0) -> np.ndarray:
+    window = max(1, int(SAMPLE_RATE * milliseconds / 1_000.0))
+    return np.sqrt(
+        np.convolve(audio * audio, np.ones(window) / window, mode="same") + 1e-10
+    )
+
+
+def _match_reference_envelope(
+    synth: np.ndarray,
+    reference: np.ndarray,
+) -> np.ndarray:
+    frame_count = min(len(synth), len(reference))
+    if frame_count <= 0:
+        raise ValueError("synthesis and reference must both contain audio")
+    reference = reference[:frame_count]
+    matched = synth[:frame_count].copy()
+    window = max(3, int(.012 * SAMPLE_RATE))
+    kernel = np.hanning(window)
+    kernel /= np.sum(kernel)
+    for _ in range(2):
+        ratio = _rms_envelope(reference) / (_rms_envelope(matched) + 1e-7)
+        log_ratio = np.log(np.clip(ratio, .03, 30.0))
+        matched *= np.exp(np.convolve(log_ratio, kernel, mode="same"))
+    target_rms = float(np.sqrt(np.mean(reference * reference)))
+    measured_rms = float(np.sqrt(np.mean(matched * matched)))
+    if measured_rms <= 1e-12:
+        raise ValueError("envelope calibration produced silence")
+    matched *= target_rms / measured_rms
+    peak_limit = min(.98, max(.90, float(np.max(np.abs(reference)))))
+    measured_peak = float(np.max(np.abs(matched)))
+    if measured_peak > peak_limit:
+        matched *= peak_limit / measured_peak
+    if not np.all(np.isfinite(matched)):
+        raise ValueError("envelope calibration produced non-finite audio")
+    return matched
+
+
+def _anchor_frame(signal: np.ndarray) -> int:
+    peak = float(np.max(np.abs(signal)))
+    candidates = np.flatnonzero(np.abs(signal) >= peak * 10.0 ** (-30.0 / 20.0))
+    if len(candidates) == 0:
+        raise ValueError("synthesized voice has no measurable onset")
+    return int(candidates[0])
+
+
+def _profile(signal: np.ndarray, anchor: int) -> dict[str, float]:
+    active = signal[anchor:]
+    energy = active * active
+    cumulative = np.cumsum(energy)
+    spectrum = np.abs(np.fft.rfft(active * np.hanning(len(active)))) ** 2
+    frequencies = np.fft.rfftfreq(len(active), 1.0 / SAMPLE_RATE)
+    spectrum /= max(float(np.sum(spectrum)), 1e-15)
+    attack = active[:int(round(.010 * SAMPLE_RATE))]
+    attack_spectrum = np.abs(np.fft.rfft(attack * np.hanning(len(attack)))) ** 2
+    attack_frequencies = np.fft.rfftfreq(len(attack), 1.0 / SAMPLE_RATE)
+    tail = active[int(round(.120 * SAMPLE_RATE)):]
+    tail_spectrum = np.abs(np.fft.rfft(tail * np.hanning(len(tail)))) ** 2
+    tail_frequencies = np.fft.rfftfreq(len(tail), 1.0 / SAMPLE_RATE)
+    return {
+        "centroid_hz": round(float(np.sum(frequencies * spectrum)), 3),
+        "attack_centroid_hz": round(float(
+            np.sum(attack_frequencies * attack_spectrum)
+            / max(float(np.sum(attack_spectrum)), 1e-15)
+        ), 3),
+        "tail_centroid_hz": round(float(
+            np.sum(tail_frequencies * tail_spectrum)
+            / max(float(np.sum(tail_spectrum)), 1e-15)
+        ), 3),
+        "peak_seconds_after_anchor": round(
+            float(np.argmax(np.abs(active)) / SAMPLE_RATE), 6,
+        ),
+        "t90_seconds_after_anchor": round(
+            float(np.searchsorted(cumulative, .90 * cumulative[-1]) / SAMPLE_RATE), 6,
+        ),
+        "t99_seconds_after_anchor": round(
+            float(np.searchsorted(cumulative, .99 * cumulative[-1]) / SAMPLE_RATE), 6,
+        ),
+        "crest_db": round(
+            float(20.0 * math.log10(
+                np.max(np.abs(active)) / np.sqrt(np.mean(energy))
+            )),
+            3,
+        ),
+    }
+
+
+def _write_pcm16(path: Path, signal: np.ndarray) -> tuple[str, str]:
+    clipped = np.clip(signal, -1.0, 1.0)
+    pcm = np.rint(clipped * 32767.0).astype("<i2")
+    with wave.open(str(path), "wb") as output:
+        output.setnchannels(1)
+        output.setsampwidth(2)
+        output.setframerate(SAMPLE_RATE)
+        output.writeframes(pcm.tobytes())
+    return _sha256(path), hashlib.sha256(pcm.tobytes()).hexdigest()
+
+
+def build(reference_paths: ReferencePaths, output_dir: Path) -> None:
+    references = {
+        role: _read_reference(path, role)
+        for role, path in reference_paths.by_role().items()
+    }
+    output_dir.mkdir(parents=True, exist_ok=True)
+    for stale in output_dir.glob("*.wav"):
+        stale.unlink()
+
+    rng = np.random.default_rng(RANDOM_SEED)
+    files: list[dict[str, object]] = []
+    for role in BUILD_ORDER:
+        synth = _make_synth(role, rng)
+        synth = _calibrate_spectrum(role, synth)
+        synth = _match_reference_envelope(synth, references[role])
+        filename, kind = OUTPUT_NAMES[role]
+        path = output_dir / filename
+        file_hash, pcm_hash = _write_pcm16(path, synth)
+        anchor = _anchor_frame(synth)
+        files.append({
+            "filename": filename,
+            "kind": kind,
+            "sha256": file_hash,
+            "pcm_sha256": pcm_hash,
+            "sample_rate": SAMPLE_RATE,
+            "channels": 1,
+            "frames": len(synth),
+            "anchor_frame": anchor,
+            "profile": _profile(synth, anchor),
+        })
+
+    manifest = {
+        "schema_version": 2,
+        "kit_id": "softchart-modal-resonator-v1",
+        "license": "MIT",
+        "sample_rate": SAMPLE_RATE,
+        "generator": "scripts/build_taiko_synth.py",
+        "method": (
+            "seeded noise/impulse excitation, modal resonators, decaying pitch "
+            "sweep, band-limited transient calibration, and offline RMS-envelope "
+            "calibration"
+        ),
+        "random_seed": RANDOM_SEED,
+        "reference_policy": (
+            "Reference audio is used only for offline RMS-envelope and level "
+            "calibration; it is not copied, mixed, embedded, or required at runtime."
+        ),
+        "files": sorted(files, key=lambda item: str(item["filename"])),
+    }
+    (output_dir / "manifest.json").write_text(
+        json.dumps(manifest, indent=2, ensure_ascii=False) + "\n",
+        encoding="utf-8",
+    )
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--big-don-reference", type=Path, required=True)
+    parser.add_argument("--don-reference", type=Path, required=True)
+    parser.add_argument("--katsu-reference", type=Path, required=True)
+    parser.add_argument("--output-dir", type=Path, required=True)
+    args = parser.parse_args()
+    build(
+        ReferencePaths(
+            big_don=args.big_don_reference,
+            don=args.don_reference,
+            katsu=args.katsu_reference,
+        ),
+        args.output_dir,
+    )
+
+
+if __name__ == "__main__":
+    main()

softchart/assets/taiko/README.md

@@ -1,17 +0,0 @@
-# SoftChart Arcade Taiko Kit
-
-These one-shots are original SoftChart transformations of the **Chinese Bass
-Drum Dagu Oneshots** pack recorded in Taipei by `sazanami12`:
-
-- Source: https://freesound.org/people/sazanami12/packs/45781/
-- License: CC0 1.0 — https://creativecommons.org/publicdomain/zero/1.0/
-- Build recipe: `scripts/build_taiko_bank.py` in both the source repository and
-  the self-contained Space payload
-- Exact source and output hashes: `manifest.json`
-
-The source instrument is a Chinese Huapengu / Dagu, selected as a
-redistributable large East-Asian barrel-drum recording with isolated head and
-rim articulations. It is not represented as a Japanese wadaiko recording.
-
-No audio from Taiko no Tatsujin or any other commercial game is included,
-transformed, embedded, or required by the build.

softchart/assets/taiko/manifest.json

@@ -1,310 +0,0 @@
-{
-  "schema_version": 1,
-  "kit_id": "softchart-arcade-taiko-cc0",
-  "license": "CC0-1.0",
-  "license_url": "https://creativecommons.org/publicdomain/zero/1.0/",
-  "source_pack_url": "https://freesound.org/people/sazanami12/packs/45781/",
-  "source_creator": "sazanami12",
-  "source_instrument": "Chinese Huapengu / Dagu recorded in Taipei, Taiwan",
-  "source_encoding": "public Freesound HQ OGG preview of the CC0 original WAV",
-  "sources": [
-    {
-      "sound_id": 856550,
-      "label": "center-soft",
-      "sha256": "78ed9dea56102480811e90a9653c08fe20a0eca5793c9c936f1c2592042b9a46",
-      "preview_url": "https://cdn.freesound.org/previews/856/856550_17110092-hq.ogg"
-    },
-    {
-      "sound_id": 856552,
-      "label": "edge-soft",
-      "sha256": "85600ed1ddfab1c56fe07268f5fd68073706da8cd9a2f0cf7f16bde30bb8bb3e",
-      "preview_url": "https://cdn.freesound.org/previews/856/856552_17110092-hq.ogg"
-    },
-    {
-      "sound_id": 856557,
-      "label": "rim-right",
-      "sha256": "6c24ee738d5995121fa85a432223a2afadb585f2a67b253747e2db0b3796bca0",
-      "preview_url": "https://cdn.freesound.org/previews/856/856557_17110092-hq.ogg"
-    },
-    {
-      "sound_id": 856558,
-      "label": "rim-left",
-      "sha256": "5ac219e4254f27c4a3b5b581f5c67e7c72fe91fa3d0fb2e03d021793febc1872",
-      "preview_url": "https://cdn.freesound.org/previews/856/856558_17110092-hq.ogg"
-    },
-    {
-      "sound_id": 856559,
-      "label": "rim-both-loud",
-      "sha256": "840a559e5d979e483cec2afb64e4f71a27d31c753c1bb138395303c5bd0d8253",
-      "preview_url": "https://cdn.freesound.org/previews/856/856559_17110092-hq.ogg"
-    }
-  ],
-  "files": [
-    {
-      "filename": "balloon-01.wav",
-      "kind": "balloon",
-      "round_robin": 1,
-      "sha256": "241042aeb27bf7ca310c65fb1130554c3f5501b735d4178c9a65227a3c3962b7",
-      "pcm_sha256": "d86c418410b1f009dbc0a1f1cbc81dbe6ac52b1707002f7595c48c973fd309c0",
-      "sample_rate": 44100,
-      "channels": 1,
-      "frames": 5954,
-      "anchor_frame": 0,
-      "source_sound_ids": [
-        856552,
-        856559
-      ],
-      "profile": {
-        "centroid_hz": 144.684,
-        "attack_centroid_hz": 2085.291,
-        "t90_seconds": 0.088254,
-        "t99_seconds": 0.101973,
-        "crest_db": 10.255
-      }
-    },
-    {
-      "filename": "balloon-02.wav",
-      "kind": "balloon",
-      "round_robin": 2,
-      "sha256": "9e9b9ae2067e3b8c35d4bef011aea160ac6b2c955b861b48fcdd977e9784a96e",
-      "pcm_sha256": "90a5802c2b25e55fdfd39b394f505e302aa13e4435418c494aff807a51bdfefd",
-      "sample_rate": 44100,
-      "channels": 1,
-      "frames": 5954,
-      "anchor_frame": 0,
-      "source_sound_ids": [
-        856550,
-        856559
-      ],
-      "profile": {
-        "centroid_hz": 154.871,
-        "attack_centroid_hz": 2160.392,
-        "t90_seconds": 0.087846,
-        "t99_seconds": 0.101927,
-        "crest_db": 11.393
-      }
-    },
-    {
-      "filename": "don-01.wav",
-      "kind": "don",
-      "round_robin": 1,
-      "sha256": "b0ae8c300223ca2092da3ebac7d5318978926935cc5f5de63339ca06e4552c94",
-      "pcm_sha256": "2fcc51eed16cf540288ad5b99153afea9f4ba599dc4921595852792cd4ee2163",
-      "sample_rate": 44100,
-      "channels": 1,
-      "frames": 36603,
-      "anchor_frame": 0,
-      "source_sound_ids": [
-        856552,
-        856559
-      ],
-      "profile": {
-        "centroid_hz": 106.922,
-        "attack_centroid_hz": 2085.291,
-        "t90_seconds": 0.279342,
-        "t99_seconds": 0.424104,
-        "crest_db": 13.942
-      }
-    },
-    {
-      "filename": "don-02.wav",
-      "kind": "don",
-      "round_robin": 2,
-      "sha256": "668748702af4b40922954685d4b416f6402c905f1ef7e9172f13d1a201f05c14",
-      "pcm_sha256": "5116770059c6891ce90b2f0eb39e15ee9cc37a851d9df10165c9e15638f18ad7",
-      "sample_rate": 44100,
-      "channels": 1,
-      "frames": 36603,
-      "anchor_frame": 0,
-      "source_sound_ids": [
-        856550,
-        856559
-      ],
-      "profile": {
-        "centroid_hz": 113.558,
-        "attack_centroid_hz": 2160.392,
-        "t90_seconds": 0.286984,
-        "t99_seconds": 0.403673,
-        "crest_db": 14.121
-      }
-    },
-    {
-      "filename": "don-big.wav",
-      "kind": "don_big",
-      "round_robin": 1,
-      "sha256": "38d7bee2a772c45fe935bab378f7aedaf73746fb78972fc538cf37d8c81c20cd",
-      "pcm_sha256": "29823b5ff47f93217360db5019f2c805bf5e36c0658b7fb8bdf9fec051636ecf",
-      "sample_rate": 44100,
-      "channels": 1,
-      "frames": 39470,
-      "anchor_frame": 0,
-      "source_sound_ids": [
-        856550,
-        856559
-      ],
-      "profile": {
-        "centroid_hz": 105.346,
-        "attack_centroid_hz": 2440.045,
-        "t90_seconds": 0.379365,
-        "t99_seconds": 0.557619,
-        "crest_db": 13.246
-      }
-    },
-    {
-      "filename": "ka-01.wav",
-      "kind": "ka",
-      "round_robin": 1,
-      "sha256": "7091db93a0d8bcb9a58d08e00c1052c9c057784a72ed7a445e7e04e1fb854192",
-      "pcm_sha256": "c7d95d820c95ecaa955b0a47739b1c7ab025b4a99f9c076bbef7a1b18f30215d",
-      "sample_rate": 44100,
-      "channels": 1,
-      "frames": 17949,
-      "anchor_frame": 0,
-      "source_sound_ids": [
-        856559,
-        856557
-      ],
-      "profile": {
-        "centroid_hz": 2083.859,
-        "attack_centroid_hz": 4187.299,
-        "t90_seconds": 0.061202,
-        "t99_seconds": 0.123469,
-        "crest_db": 20.018
-      }
-    },
-    {
-      "filename": "ka-02.wav",
-      "kind": "ka",
-      "round_robin": 2,
-      "sha256": "6dfcaad357908e139e98e62d748659ef0484337b7f04b66db6a4f4c4071120a8",
-      "pcm_sha256": "b8d50d62a9a71db0effbb34421958aa40776e44f0573baa271f32cb6881e96ce",
-      "sample_rate": 44100,
-      "channels": 1,
-      "frames": 17949,
-      "anchor_frame": 0,
-      "source_sound_ids": [
-        856557,
-        856558
-      ],
-      "profile": {
-        "centroid_hz": 1926.337,
-        "attack_centroid_hz": 3862.82,
-        "t90_seconds": 0.058141,
-        "t99_seconds": 0.107732,
-        "crest_db": 22.327
-      }
-    },
-    {
-      "filename": "ka-big.wav",
-      "kind": "ka_big",
-      "round_robin": 1,
-      "sha256": "dd72eb84c579eaa9ec2f04fe1e78f1cc497b5bf425b32a75788398379b1f2964",
-      "pcm_sha256": "40e876586926aecc06b91bfc60a1d00d33832fd34f334799d7c46e16921a6ea4",
-      "sample_rate": 44100,
-      "channels": 1,
-      "frames": 17949,
-      "anchor_frame": 0,
-      "source_sound_ids": [
-        856559,
-        856557,
-        856558
-      ],
-      "profile": {
-        "centroid_hz": 1986.528,
-        "attack_centroid_hz": 4484.582,
-        "t90_seconds": 0.061224,
-        "t99_seconds": 0.125624,
-        "crest_db": 19.782
-      }
-    },
-    {
-      "filename": "roll-01.wav",
-      "kind": "roll",
-      "round_robin": 1,
-      "sha256": "12bdee9caf1c8b17f2c56cce90078f25837a9670c939ceaabdd4cc524ebd9100",
-      "pcm_sha256": "19c20b070f3f23eab146d1a3b864a5827e68afe52224ccd3d7b23a2413f242a6",
-      "sample_rate": 44100,
-      "channels": 1,
-      "frames": 6615,
-      "anchor_frame": 0,
-      "source_sound_ids": [
-        856552,
-        856559
-      ],
-      "profile": {
-        "centroid_hz": 139.363,
-        "attack_centroid_hz": 2085.291,
-        "t90_seconds": 0.094785,
-        "t99_seconds": 0.113311,
-        "crest_db": 9.782
-      }
-    },
-    {
-      "filename": "roll-02.wav",
-      "kind": "roll",
-      "round_robin": 2,
-      "sha256": "2abd129bdb4e8c73aa44d071c386a8fc643f613c9b0cec1c84a339073e8bc681",
-      "pcm_sha256": "d4f9ca68263e903188eed4844a70041c38bb8f1c026331c28802771de606274b",
-      "sample_rate": 44100,
-      "channels": 1,
-      "frames": 6615,
-      "anchor_frame": 0,
-      "source_sound_ids": [
-        856550,
-        856559
-      ],
-      "profile": {
-        "centroid_hz": 154.227,
-        "attack_centroid_hz": 2160.392,
-        "t90_seconds": 0.096259,
-        "t99_seconds": 0.114195,
-        "crest_db": 11.106
-      }
-    },
-    {
-      "filename": "roll-big-01.wav",
-      "kind": "roll_big",
-      "round_robin": 1,
-      "sha256": "23fea6acc0d2c554353af445ea8aa887555ce2df3268540256922f695158909a",
-      "pcm_sha256": "7d3c290e8c18c786dd46633483d03c7ae3b83dfd83410c1262bd3e2d4dd8e82e",
-      "sample_rate": 44100,
-      "channels": 1,
-      "frames": 7717,
-      "anchor_frame": 0,
-      "source_sound_ids": [
-        856550,
-        856559
-      ],
-      "profile": {
-        "centroid_hz": 157.954,
-        "attack_centroid_hz": 2440.045,
-        "t90_seconds": 0.100317,
-        "t99_seconds": 0.129501,
-        "crest_db": 9.349
-      }
-    },
-    {
-      "filename": "roll-big-02.wav",
-      "kind": "roll_big",
-      "round_robin": 2,
-      "sha256": "edfd7d6225ac7e14d554b7ec946455d1d942f87c00e370d0cae2b3e62a22e2fd",
-      "pcm_sha256": "20289804cdb38f0b6dc6e300e7e8b0b7f32c7cc485e990db4a0a53a0055c47e5",
-      "sample_rate": 44100,
-      "channels": 1,
-      "frames": 7717,
-      "anchor_frame": 0,
-      "source_sound_ids": [
-        856550,
-        856552,
-        856559
-      ],
-      "profile": {
-        "centroid_hz": 153.15,
-        "attack_centroid_hz": 2438.852,
-        "t90_seconds": 0.094399,
-        "t99_seconds": 0.125283,
-        "crest_db": 9.633
-      }
-    }
-  ]
-}

softchart/assets/taiko_synth/README.md

@@ -0,0 +1,23 @@
+# SoftChart Modal-Resonator Taiko Kit
+
+This directory contains three deterministic, synthesized one-shot voices:
+
+- `don.wav` — membrane hit
+- `don-big.wav` — independent large membrane hit
+- `katsu.wav` — rim hit
+
+The voices are generated at 48 kHz by `scripts/build_taiko_synth.py`. The
+signal path uses seeded noise and impulse excitations, banks of decaying modal
+resonators, low-frequency pitch sweeps, band-limited stick transients, and
+offline RMS-envelope calibration.
+
+Developer-supplied reference WAVs are used only during the offline build to
+calibrate envelopes and overall levels. Reference samples, paths, hashes, and
+envelope arrays are not copied, mixed, embedded, recorded in the manifest, or
+required at runtime. The bundled WAVs contain only mathematical synthesis.
+
+`manifest.json` records the generated files, PCM hashes, onset anchors, and
+scalar acoustic profiles. The runtime validates the complete bank before use
+and performs one high-quality 48 kHz to preview-rate conversion in memory.
+
+The synthesized assets are distributed under the repository's MIT license.

softchart/assets/taiko_synth/manifest.json

@@ -0,0 +1,69 @@
+{
+  "schema_version": 2,
+  "kit_id": "softchart-modal-resonator-v1",
+  "license": "MIT",
+  "sample_rate": 48000,
+  "generator": "scripts/build_taiko_synth.py",
+  "method": "seeded noise/impulse excitation, modal resonators, decaying pitch sweep, band-limited transient calibration, and offline RMS-envelope calibration",
+  "random_seed": 20260713,
+  "reference_policy": "Reference audio is used only for offline RMS-envelope and level calibration; it is not copied, mixed, embedded, or required at runtime.",
+  "files": [
+    {
+      "filename": "don-big.wav",
+      "kind": "don_big",
+      "sha256": "9e0be6c32867328aef834d4021b6506a6c7174fe3ced9ecb264d58b50ae712de",
+      "pcm_sha256": "14e81e7f92a418f2e4950b989c9c93e5d25f9d5ed990c02838b127c46c23584f",
+      "sample_rate": 48000,
+      "channels": 1,
+      "frames": 42946,
+      "anchor_frame": 866,
+      "profile": {
+        "centroid_hz": 118.42,
+        "attack_centroid_hz": 1672.916,
+        "tail_centroid_hz": 112.667,
+        "peak_seconds_after_anchor": 0.006646,
+        "t90_seconds_after_anchor": 0.352333,
+        "t99_seconds_after_anchor": 0.508687,
+        "crest_db": 11.994
+      }
+    },
+    {
+      "filename": "don.wav",
+      "kind": "don",
+      "sha256": "b2ef1660a03f208c054dfb51c4e0778090d43a24dab592c60992c84a97e384f4",
+      "pcm_sha256": "62adc81419fb47950e1fd76e9c302085d680e8d404efd023e84b5a1d66266522",
+      "sample_rate": 48000,
+      "channels": 1,
+      "frames": 39836,
+      "anchor_frame": 866,
+      "profile": {
+        "centroid_hz": 101.648,
+        "attack_centroid_hz": 1842.387,
+        "tail_centroid_hz": 111.714,
+        "peak_seconds_after_anchor": 0.007833,
+        "t90_seconds_after_anchor": 0.248979,
+        "t99_seconds_after_anchor": 0.460375,
+        "crest_db": 12.25
+      }
+    },
+    {
+      "filename": "katsu.wav",
+      "kind": "katsu",
+      "sha256": "54e8c93363d9dd1fb4703397ba4f1b4156e64697108895edd2e8c57c743c7706",
+      "pcm_sha256": "20d38df7d06bb4519363108e1ccb61dbfe98749c41b17ec9d99f22f47af1d5ab",
+      "sample_rate": 48000,
+      "channels": 1,
+      "frames": 19537,
+      "anchor_frame": 866,
+      "profile": {
+        "centroid_hz": 1819.101,
+        "attack_centroid_hz": 2716.187,
+        "tail_centroid_hz": 1721.006,
+        "peak_seconds_after_anchor": 0.005896,
+        "t90_seconds_after_anchor": 0.074875,
+        "t99_seconds_after_anchor": 0.1385,
+        "crest_db": 20.199
+      }
+    }
+  ]
+}

softchart/preview_audio.py

@@ -1,9 +1,10 @@
-"""Deterministic sample-based arcade Taiko preview mixing.
+"""Deterministic modal-resonator Taiko preview mixing.
 
 The chart is the timing authority: :func:`parse_tja_events` converts the
 repo-emitted TJA subset to audio-clock events, including OFFSET, measure-local
-subdivisions, and piecewise BPM changes. Drum timbres come from a bundled,
-hash-validated CC0 large barrel-drum kit; no commercial-game audio is used.
+subdivisions, and piecewise BPM changes. Drum timbres are three bundled,
+hash-validated synthesized voices: Don, Big Don, and Katsu.  Private reference
+audio is neither bundled nor required at runtime.
 """
 
 from __future__ import annotations
@@ -25,7 +26,7 @@ _HIT_KIND = {"1": "don", "2": "ka", "3": "don_big", "4": "ka_big"}
 _SPAN_KIND = {"5": "roll", "6": "roll_big", "7": "balloon"}
 _ALLOWED_COMMANDS = {"#GOGOSTART", "#GOGOEND"}
 _PCM16_CEILING = int(math.floor(32767 * 10.0 ** (-1.0 / 20.0)))
-_ASSET_DIR = Path(__file__).with_name("assets") / "taiko"
+_ASSET_DIR = Path(__file__).with_name("assets") / "taiko_synth"
 
 
 @dataclass(frozen=True)
@@ -53,8 +54,10 @@ class _OpenSpan:
 @dataclass(frozen=True)
 class _Strike:
     time: float
-    kind: str
+    voice_kind: str
     pan: float
+    gain: float
+    tail_seconds: float | None
     duck_depth: float
     autoplay: bool
 
@@ -227,31 +230,47 @@ def parse_tja_events(tja_text: str) -> list[TaikoEvent]:
 
 
 _BANKS: dict[int, dict[str, tuple[_Voice, ...]]] = {}
-_REQUIRED_VOICES = {
-    "don": 2,
-    "ka": 2,
-    "don_big": 1,
-    "ka_big": 1,
-    "roll": 2,
-    "roll_big": 2,
-    "balloon": 2,
-}
-
-
-def _load_pcm16_voice(path: Path, anchor_frame: int,
-                      sample_rate: int) -> _Voice:
+_REQUIRED_VOICES = {"don": 1, "don_big": 1, "katsu": 1}
+
+
+def _measurable_anchor(samples: np.ndarray) -> int:
+    peak = float(np.max(np.abs(samples)))
+    if not math.isfinite(peak) or peak <= 1e-12:
+        raise ValueError("Taiko asset must contain finite, non-silent audio")
+    candidates = np.flatnonzero(np.abs(samples) >= peak * 10.0 ** (-30.0 / 20.0))
+    if len(candidates) == 0:
+        raise ValueError("Taiko asset has no measurable onset")
+    return int(candidates[0])
+
+
+def _load_pcm16_voice(
+    path: Path,
+    anchor_frame: int,
+    sample_rate: int,
+    source_rate: int,
+    expected_frames: int,
+    expected_pcm_hash: str,
+) -> _Voice:
     with wave.open(str(path), "rb") as source:
         if source.getnchannels() != 1 or source.getsampwidth() != 2:
             raise ValueError(f"Taiko asset must be mono PCM16: {path.name}")
-        source_rate = source.getframerate()
-        pcm = np.frombuffer(source.readframes(source.getnframes()), dtype="<i2")
-    if source_rate != 44_100:
-        raise ValueError(f"Taiko asset must be 44.1 kHz: {path.name}")
+        actual_rate = source.getframerate()
+        actual_frames = source.getnframes()
+        pcm = np.frombuffer(source.readframes(actual_frames), dtype="<i2")
+    if actual_rate != source_rate:
+        raise ValueError(f"Taiko asset sample-rate mismatch: {path.name}")
+    if actual_frames != expected_frames:
+        raise ValueError(f"Taiko asset frame-count mismatch: {path.name}")
+    if hashlib.sha256(pcm.tobytes()).hexdigest() != expected_pcm_hash:
+        raise ValueError(f"Taiko asset PCM hash mismatch: {path.name}")
     samples = pcm.astype(np.float32) / 32767.0
+    measured_anchor = _measurable_anchor(samples)
+    if measured_anchor != anchor_frame:
+        raise ValueError(f"Taiko asset onset-anchor mismatch: {path.name}")
     if sample_rate != source_rate:
         ratio = Fraction(sample_rate, source_rate).limit_denominator()
         samples = resample_poly(samples, ratio.numerator, ratio.denominator).astype(np.float32)
-        anchor_frame = int(round(anchor_frame * sample_rate / source_rate))
+        anchor_frame = _measurable_anchor(samples)
     if not 0 <= anchor_frame < len(samples):
         raise ValueError(f"Taiko asset anchor is outside the sample: {path.name}")
     return _Voice(np.ascontiguousarray(samples), anchor_frame)
@@ -266,11 +285,22 @@ def _sample_bank(sample_rate: int) -> dict[str, tuple[_Voice, ...]]:
     if not manifest_path.is_file():
         raise FileNotFoundError(f"Taiko asset manifest is missing: {manifest_path}")
     manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
-    if manifest.get("schema_version") != 1 or manifest.get("license") != "CC0-1.0":
-        raise ValueError("Taiko asset manifest must be schema 1 and CC0-1.0")
+    if manifest.get("schema_version") != 2 or manifest.get("license") != "MIT":
+        raise ValueError("Taiko synth manifest must be schema 2 and MIT licensed")
+    source_rate = int(manifest.get("sample_rate", 0))
+    if source_rate != 48_000:
+        raise ValueError("Taiko synth assets must be generated at 48 kHz")
+
+    entries = manifest.get("files")
+    if not isinstance(entries, list):
+        raise ValueError("Taiko synth manifest files must be a list")
+    listed_files = {item.get("filename") for item in entries if isinstance(item, dict)}
+    bundled_files = {path.name for path in _ASSET_DIR.glob("*.wav")}
+    if listed_files != bundled_files:
+        raise ValueError("Taiko synth manifest must cover every bundled WAV exactly")
 
     grouped: dict[str, list[tuple[int, _Voice]]] = {kind: [] for kind in _REQUIRED_VOICES}
-    for item in manifest.get("files", []):
+    for item in entries:
         kind = item.get("kind")
         if kind not in grouped:
             raise ValueError(f"unsupported Taiko asset kind in manifest: {kind!r}")
@@ -283,8 +313,17 @@ def _sample_bank(sample_rate: int) -> dict[str, tuple[_Voice, ...]]:
         file_hash = hashlib.sha256(path.read_bytes()).hexdigest()
         if file_hash != item.get("sha256"):
             raise ValueError(f"Taiko asset hash mismatch: {filename}")
-        voice = _load_pcm16_voice(path, int(item["anchor_frame"]), sample_rate)
-        grouped[kind].append((int(item["round_robin"]), voice))
+        if item.get("sample_rate") != source_rate or item.get("channels") != 1:
+            raise ValueError(f"Taiko asset format metadata mismatch: {filename}")
+        voice = _load_pcm16_voice(
+            path,
+            int(item["anchor_frame"]),
+            sample_rate,
+            source_rate,
+            int(item["frames"]),
+            str(item["pcm_sha256"]),
+        )
+        grouped[kind].append((1, voice))
 
     bank = {}
     for kind, expected_count in _REQUIRED_VOICES.items():
@@ -293,8 +332,6 @@ def _sample_bank(sample_rate: int) -> dict[str, tuple[_Voice, ...]]:
             raise ValueError(
                 f"Taiko kit requires {expected_count} {kind} voice(s), got {len(entries)}"
             )
-        if [index for index, _ in entries] != list(range(1, expected_count + 1)):
-            raise ValueError(f"Taiko {kind} round-robin indices must be contiguous from 1")
         bank[kind] = tuple(voice for _, voice in entries)
     _BANKS[sample_rate] = bank
     return bank
@@ -310,9 +347,20 @@ def _expand_strikes(events: list[TaikoEvent]) -> tuple[list[_Strike], int]:
     for event in events:
         if event.kind in {"don", "ka", "don_big", "ka_big"}:
             pan_width = 0.08 if event.kind in {"ka", "ka_big"} else 0.015
-            pan = -pan_width if ordinary_index % 2 == 0 else pan_width
+            pan = 0.0 if event.kind == "don_big" else (
+                -pan_width if ordinary_index % 2 == 0 else pan_width
+            )
+            voice_kind = {
+                "don": "don",
+                "ka": "katsu",
+                "don_big": "don_big",
+                "ka_big": "katsu",
+            }[event.kind]
+            gain = 1.12 if event.kind == "ka_big" else 1.0
             depth = 0.26 if event.kind.endswith("_big") else 0.22
-            strikes.append(_Strike(event.time, event.kind, pan, depth, False))
+            strikes.append(_Strike(
+                event.time, voice_kind, pan, gain, None, depth, False,
+            ))
             ordinary_index += 1
             continue
 
@@ -320,7 +368,9 @@ def _expand_strikes(events: list[TaikoEvent]) -> tuple[list[_Strike], int]:
             times = event.time + np.arange(event.hit_count, dtype=np.float64) * (
                 event.duration / event.hit_count
             )
-            kind = "balloon"
+            voice_kind = "don"
+            gain = 0.54
+            tail_seconds = 0.135
             depth = 0.070
         else:
             interval = 0.074 if event.kind == "roll_big" else 0.086
@@ -329,12 +379,16 @@ def _expand_strikes(events: list[TaikoEvent]) -> tuple[list[_Strike], int]:
             times = times[times < event.time + event.duration - 0.008]
             if len(times) == 0:
                 times = np.asarray([event.time])
-            kind = event.kind
+            voice_kind = "don_big" if event.kind == "roll_big" else "don"
+            gain = 0.60 if event.kind == "roll_big" else 0.56
+            tail_seconds = 0.175 if event.kind == "roll_big" else 0.150
             depth = 0.085 if event.kind == "roll_big" else 0.060
         for index, time in enumerate(times):
-            pan_width = 0.10 if kind == "roll_big" else 0.06
+            pan_width = 0.10 if voice_kind == "don_big" else 0.06
             pan = -pan_width if index % 2 == 0 else pan_width
-            strikes.append(_Strike(float(time), kind, pan, depth, True))
+            strikes.append(_Strike(
+                float(time), voice_kind, pan, gain, tail_seconds, depth, True,
+            ))
             autoplay_count += 1
     strikes.sort(key=lambda strike: strike.time)
     return strikes, autoplay_count
@@ -379,13 +433,31 @@ def _place_strike(drums: np.ndarray, voice: _Voice, strike: _Strike,
     start = int(round(strike.time * sample_rate)) - voice.anchor_frame
     sample_start = max(0, -start)
     output_start = max(0, start)
-    count = min(len(sample) - sample_start, len(drums) - output_start)
+    sample_end = len(sample)
+    if strike.tail_seconds is not None:
+        sample_end = min(
+            sample_end,
+            voice.anchor_frame + int(round(strike.tail_seconds * sample_rate)),
+        )
+    count = min(sample_end - sample_start, len(drums) - output_start)
     if count <= 0:
         return False
 
     angle = (float(np.clip(strike.pan, -1.0, 1.0)) + 1.0) * np.pi / 4.0
     left_gain, right_gain = math.cos(angle), math.sin(angle)
     segment = sample[sample_start:sample_start + count]
+    if strike.tail_seconds is not None:
+        source_indices = np.arange(sample_start, sample_start + count)
+        active_frames = source_indices - voice.anchor_frame
+        fade_start = int(round(strike.tail_seconds * sample_rate * 0.43))
+        tail_frames = max(fade_start + 1, int(round(strike.tail_seconds * sample_rate)))
+        fade_position = np.clip(
+            (active_frames - fade_start) / (tail_frames - fade_start), 0.0, 1.0,
+        )
+        envelope = 0.5 + 0.5 * np.cos(np.pi * fade_position)
+        envelope[active_frames < 0] = 1.0
+        segment = segment * envelope.astype(np.float32)
+    segment = segment * strike.gain
     drums[output_start:output_start + count, 0] += segment * left_gain
     drums[output_start:output_start + count, 1] += segment * right_gain
     return True
@@ -468,11 +540,18 @@ def synthesize_taiko_preview(
     source_frames = len(music)
     output_frames = source_frames
     for index, strike in enumerate(strikes):
-        voice = bank[strike.kind][index % len(bank[strike.kind])]
+        voices = bank[strike.voice_kind]
+        voice = voices[index % len(voices)]
         start = int(round(strike.time * sample_rate)) - voice.anchor_frame
+        voice_end = len(voice.samples)
+        if strike.tail_seconds is not None:
+            voice_end = min(
+                voice_end,
+                voice.anchor_frame + int(round(strike.tail_seconds * sample_rate)),
+            )
         output_frames = max(
             output_frames,
-            max(0, start + len(voice.samples)),
+            max(0, start + voice_end),
         )
     if output_frames > source_frames:
         music = np.pad(music, ((0, output_frames - source_frames), (0, 0)))
@@ -480,7 +559,7 @@ def synthesize_taiko_preview(
     audible_strikes: list[_Strike] = []
 
     for index, strike in enumerate(strikes):
-        voices = bank[strike.kind]
+        voices = bank[strike.voice_kind]
         voice = voices[index % len(voices)]
         if _place_strike(drums, voice, strike, sample_rate):
             audible_strikes.append(strike)