README.md

---
title: SoftChart
emoji: 🥁
colorFrom: red
colorTo: yellow
sdk: gradio
sdk_version: 6.20.0
python_version: "3.11"
app_file: app.py
pinned: false
license: mit
models:
  - JacobLinCool/softchart-v17
  - JacobLinCool/softchart-v17-small
  - JacobLinCool/softchart-v17-tiny
  - JacobLinCool/softchart-v16
  - JacobLinCool/softchart-v16-small
  - JacobLinCool/softchart-v16-tiny
  - JacobLinCool/softchart-v15
  - JacobLinCool/softchart-planner
  - JacobLinCool/softchart-barscript
---

# 🥁 SoftChart

Generate a **Taiko no Tatsujin** chart from any song. A unified 7.9M-parameter
encoder–decoder model handles beat/downbeat fitting, slot-exact generation, and
gridless time generation; an optional planner supplies song-level density,
breathing gaps, and climax structure. All models are MIT-licensed and loaded
from the Hugging Face Hub via `from_pretrained`.

- **SoftChart v15** ([softchart-v15](https://huggingface.co/JacobLinCool/softchart-v15)) — unified slot + time + beat model; slot mode emits exact TJA lattice indices when the beat grid is trusted
- **Planner** ([softchart-planner](https://huggingface.co/JacobLinCool/softchart-planner)) — audio → song-level plan (density envelope, breathing gaps, climax)

## Difficulties

Easy, Normal, Hard, Oni and Ura. Each requests a density bucket measured on the
1 155-song corpus — median note rate 1.33 / 2.01 / 3.40 / 5.27 / 6.60 per second
— and Ura is written with the TJA header `COURSE:Edit`, the literal used by all
229 Ura charts in the corpus.

Two caveats apply to Ura on every model. It was trained on 208 charts against
roughly 1 100 per other course, so expect lower quality. And the song planner
was trained on the four base courses only, so for Ura it is asked for the Oni
plan instead; the interface says so before you generate, and the result reports
which plan it used. Turning the AI planner off avoids the substitution.

## BarScript (experimental preview)

The model menu also offers **`BarScript (preview)`**, the next-generation
model. It is published to the private repo
[`JacobLinCool/softchart-barscript`](https://huggingface.co/JacobLinCool/softchart-barscript)
and resolved in one order, most explicit first:

1. `$SC2_PACKAGE_DIR`, if set — an explicit request, and an error if that
   directory holds no package;
2. a local copy at `spaces/models/sc2_c1_v13_s1234_best/`;
3. the Hub repo, downloaded on first use.

Because the repo is **private**, the download needs a token: set `HF_TOKEN`
(on a Space, *Settings → Variables and secrets*) or run `hf auth login`. With
no token the loader says so in those words — a missing credential and a missing
model have different fixes, and reporting the first as the second sends people
looking in the wrong place. `SC2_NO_HUB=1` pins the Space to on-disk packages.
Whichever source wins, the same gates run before a note is decoded: eight
vendored serving modules checked by md5 against the package's own record, the
token table cross-checked, and the Space's log-mel front end matched to the
package's contract. A Hub snapshot is additionally verified against the
`release_manifest.json` that travels with it.

BarScript is under evaluation and has known defects. The interface lists all of
them verbatim from the model card when the option is selected, including a
non-nested difficulty ladder, over-dense output, and a uniform `/16` deployment
lattice on which triplets are arithmetically impossible. It takes no song plan,
so the Structure and AI planner switches do not reach it.

BarScript decodes onto a supplied bar timeline and refuses to generate without a
downbeat rather than anchoring the bars on an arbitrary phase. When the beat fit
passes its own quality gate, that timeline is the fitted barlines themselves —
unevenly spaced when the fit found a tempo change — and every note position and
every `#BPMCHANGE` in the exported TJA is derived from those bar edges. When the
fit misses the gate the bars are tiled from a single BPM instead and no tempo
change can be represented. The result says which of the two happened, with the
fit's inlier fraction and RMS, the number of distinct bar lengths served, and any
repair applied; a fallback is never silent.

How often the barlines are right is a separate question from whether they *can*
be uneven, and the answer is not good yet. Over 60 held-out songs (30 that change
tempo per the authored trace, 30 that do not), 16 were served a non-uniform grid
and only 8 of those actually change tempo — the verdict is a coin flip at this
sample size. Nine of the 16 span a factor of ≥ 1.9 between their longest and
shortest bar, the signature of a barline the estimator split in two rather than
of a tempo change. The interface therefore reports the spread as a measurement
and states that the two cases are not told apart, instead of announcing that a
tempo change was captured.

Per-bar **time signature** is a different matter again: nothing here estimates
meter from audio, so one estimated time signature covers the whole song.

`python spaces/scripts/test_app_wiring.py` checks the routing, the resolution
order above, the five difficulties, the Ura TJA header, and — against a recorded
trace of the app as it stood before BarScript was wired in — that the seven
published models still behave identically, call for call and byte for byte.

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. 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,
chart rendering, and taiko preview mixing. The final audio is timed from the
exported TJA itself, including `OFFSET` and `#BPMCHANGE`, so the audition and
downloadable chart share the same timing.

The generated TJA keeps the uploaded audio filename in its `WAVE` field.
Planner climax blocks are emitted as TJA `#GOGOSTART` / `#GOGOEND` sections.
The chart image uses a server-side renderer modeled on the row layout used by
MIT-licensed [tja-tools](https://github.com/WHMHammer/tja-tools), without
shipping its browser/webpack runtime.

> Code and weights are **MIT-licensed**.