Complete the sampled kit provenance

scripts/build_taiko_bank.py

@@ -0,0 +1,285 @@
+# /// 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()

softchart/assets/taiko/README.md

@@ -5,7 +5,8 @@ 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`
+- 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

softchart/assets/taiko/manifest.json

@@ -8,24 +8,12 @@
   "source_instrument": "Chinese Huapengu / Dagu recorded in Taipei, Taiwan",
   "source_encoding": "public Freesound HQ OGG preview of the CC0 original WAV",
   "sources": [
-    {
-      "sound_id": 856549,
-      "label": "center-loud",
-      "sha256": "26d230aff7bb043fc88e823d7eecf00f807208f4c1d4d27c2cc1a7a2773b9d87",
-      "preview_url": "https://cdn.freesound.org/previews/856/856549_17110092-hq.ogg"
-    },
     {
       "sound_id": 856550,
       "label": "center-soft",
       "sha256": "78ed9dea56102480811e90a9653c08fe20a0eca5793c9c936f1c2592042b9a46",
       "preview_url": "https://cdn.freesound.org/previews/856/856550_17110092-hq.ogg"
     },
-    {
-      "sound_id": 856551,
-      "label": "edge-loud",
-      "sha256": "85ff2986eb902296e541a9d44b21bb61b9c2b8a05b5510be2fac9fbc99738399",
-      "preview_url": "https://cdn.freesound.org/previews/856/856551_17110092-hq.ogg"
-    },
     {
       "sound_id": 856552,
       "label": "edge-soft",
@@ -49,12 +37,6 @@
       "label": "rim-both-loud",
       "sha256": "840a559e5d979e483cec2afb64e4f71a27d31c753c1bb138395303c5bd0d8253",
       "preview_url": "https://cdn.freesound.org/previews/856/856559_17110092-hq.ogg"
-    },
-    {
-      "sound_id": 856560,
-      "label": "rim-both-soft",
-      "sha256": "4d66f33d35d2fe160da02c9a310231cdd6f2e8724dcfa7706de9c8409b5b7f97",
-      "preview_url": "https://cdn.freesound.org/previews/856/856560_17110092-hq.ogg"
     }
   ],
   "files": [