---
license: mit
library_name: pytorch
datasets:
- JacobLinCool/taiko-1000-parsed-clean
tags:
- audio-to-symbolic
- chart-generation
- from-scratch
- hierarchical-transformer
- music
- rhythm-game
- taiko
---

# SoftChart V1.8 Hierarchical Scratch

SoftChart V1.8 generates Taiko no Tatsujin-style charts directly from log-mel audio. This release is a compact hierarchical encoder-decoder trained **from scratch** on [`JacobLinCool/taiko-1000-parsed-clean`](https://huggingface.co/datasets/JacobLinCool/taiko-1000-parsed-clean); it does not use an external pretrained model or an external song planner.

The model combines a whole-song section encoder, a local rhythmic-skeleton auxiliary head, dual time/slot generation, and a beat/downbeat head. The public Space uses time-mode generation for arbitrary uploads, then uses the beat head only to estimate BPM and quantize the exported TJA. Exact slot generation is reserved for inputs with a complete, trusted rational meter grid including a terminal edge.

## Architecture

| Item | Value |
|---|---:|
| Parameters | 8,985,091 |
| Audio encoder / chart decoder | 4 / 4 layers |
| Hidden size / attention heads | 256 / 8 |
| Feed-forward size | 960 |
| Hierarchical section encoder | 2 layers, FFN 512 |
| Vocabulary | 1,810 tokens |
| Audio input | 22,050 Hz, 128-bin log-mel |

Enabled capabilities are `hierarchical_ctx`, `aux`, `dual`, `beat_head`, and `clean_phase`. Legacy external plan conditioning is disabled.

## Frozen evaluation

The locked test split contains 120 songs and 503 authored/time charts. Exact-slot results cover only the 127 charts whose parsed authored meter has a fully bounded-safe prefix.

| Metric | Locked test |
|---|---:|
| Exact-slot micro F1 (bounded-safe prefix) | 0.6810 |
| Full-song time F1 @ 25 ms | 0.4715 |
| Full-song time F1 @ 50 ms | 0.5972 |
| Mean per-chart median timing offset | 9.39 ms |
| Don/ka accuracy on 50 ms matches | 0.6551 |

These metrics compare against one authored chart even though chart design permits multiple valid answers. They do not establish human-rated groove, fun, or playability. The release has one training seed and no fair same-split V1.6/V1.7 retraining baseline.

Known limitations include weak note-type decisions relative to onset placement, under-generation of rolls/balloons, repetitive slot-mode motifs, and beat-grid ambiguity outside stable 4/4 material.

## Use

The easiest supported interface is the [`JacobLinCool/softchart`](https://huggingface.co/spaces/JacobLinCool/softchart) Space. Programmatic loading uses the `softchart` package from the [source repository](https://github.com/JacobLinCool/SoftChart):

```python
from softchart.generate import load_hf, generate_song

model = load_hf("JacobLinCool/softchart-v18", device="cuda")
chart = generate_song(
    model,
    log_mel,
    course="oni",
    level=9,
    device="cuda",
    greedy=True,
)
```

Audio preprocessing is part of the model contract in `preprocessor_config.json`: FFmpeg decodes stereo float32 at 22,050 Hz, channels are averaged arithmetically, and a periodic-Hann STFT (`n_fft=2048`, `hop_length=256`) is projected to 128 mel bins before natural-log compression.

## Artifact provenance

- Source checkpoint SHA-256: `2a7a75f720369db03e5c114eff065de90ccc864259495463287509682c6352db`
- `model.safetensors` SHA-256: `68d924542033c1ad234ed23329e469cd5caaea4aa72dcfb83dec3a0d76f1295f`
- Preprocessing contract SHA-256: `2d8c542f628decc16b0fdd37befa9eff71b1734da29cf4556943260c2c8c2636`
- HF export round-trip verification: passed

Released under the MIT license.