pulsefield-r1-restored

Pulsefield R1 Restored

A 3,084,432-parameter 4-key osu!mania continuation model, published from the completed staged R1 restoration at 6,750,000 source-onset exposures. It generates lane assignments, taps and long-note starts/releases from a short playable seed and a supplied event-time schedule.

GitHub source on main · Generation guide · Restoration method · Preview gallery

This research checkpoint takes oracle event times and required onset positions, plus a complete seed prefix. It does not infer timing from audio. Audio features are not inputs to this model. It uses Pulsefield's custom PyTorch generation command; it is not a Transformers AutoModel checkpoint.

Rendered generation previews

These are actual outputs of the published checkpoint at sampling seed 17. Yellow notes are taps; cyan notes are long notes. Read each panel from bottom to top, then continue with the next panel to its right. The renderer uses row-aware spacing, so vertical distance is not a uniform measure of elapsed time; use the timestamps.

Each image is the middle page of that chart's existing full render, after the supplied seed. The examples are illustrative outputs, not a quality benchmark.

Alone — generated continuation

Descent — generated continuation

Slash Dot Slash — generated continuation

View all six rendered examples, including Odin, Epistrofi and Lilith. The repository includes PNG and SVG previews, complete generated .osu files, and the portable conditions needed to regenerate them. Audio is not bundled. The complete files retain the supplied seed at their beginning.

Quick start

Install uv and the Hugging Face CLI. Then clone the source and check out this commit from main:

git clone https://github.com/Pulsefield/Pulsefield-model.git
cd Pulsefield-model
git checkout --detach 8f1310322ba1f64a1ca259893e76376daf36396e

# Apple Silicon/macOS dependency set; generation below runs on CPU.
uv sync --locked --python 3.10 --extra mps
hf download sed-i/pulsefield-r1-restored --local-dir artifacts/hf-r1

On Linux with NVIDIA, replace --extra mps with --extra cuda in the setup and run commands. The published reproduction check used macOS arm64, Python 3.10.20, PyTorch 2.11.0 and one CPU thread. CUDA reproduction has not been checked.

Keep the source checkout clean. Downloaded model files and generation outputs belong under the ignored artifacts/ directory. This is a digest-pinned runner: it checks both the checkpoint and condition before generation.

Generate the included Alone example:

uv run --locked --python 3.10 --extra mps python -m \
  pulsefield_model.research.bounded_typed_continuation.generate_hydra \
  checkpoint_file=artifacts/hf-r1/checkpoint.pt \
  checkpoint_sha256=4b3ec1561e33d0ebe2756cfe13571ec414fd5bb470b430f0c578545863115f70 \
  condition_file=artifacts/hf-r1/examples/alone/condition.json \
  condition_sha256=bfce659d94bbb13a9206d762b04962abab15737ff8ec0d490ff156c5b1244348 \
  output_dir=artifacts/r1-alone-generated \
  device=cpu cpu_threads=1 seed=17

Use a fresh output directory for every run. A completed run writes generated.osu, rows.jsonl, decisions.jsonl and result.json. Check that result.json reports status: completed and reparse_pass: true. The run also contains a generation-state checkpoint.pt; use this repository's root checkpoint.pt as the model weights for new generations.

The included Alone output has SHA-256:

df93c3c33a8053af0abe0d6b4dc0586aeb3e14aad375165a1ecbe17ebe1f4821

The six included examples were regenerated with the pinned main commit; every .osu matched its original generation byte-for-byte. See verification.json. Exact stochastic reproduction depends on the numerical environment; changing device, PyTorch version or seed can change the result.

Use your own chart conditions

Prepare a condition from an existing native 4K .osu chart. This copies its candidate times, required onset positions and the complete prefix through the thirtieth note head, including all heads on that final seed row. It does not give the generator suffix lane assignments, suffix note types or the release times of newly generated long notes.

R1_SOURCE=/absolute/path/to/source.osu
R1_SOURCE_SHA=$(python3 -c 'import hashlib,sys; print(hashlib.sha256(open(sys.argv[1], "rb").read()).hexdigest())' "$R1_SOURCE")

uv run --locked --python 3.10 --extra mps python -m \
  pulsefield_model.research.bounded_typed_continuation.condition_hydra \
  "source_file='$R1_SOURCE'" "source_sha256=$R1_SOURCE_SHA" \
  output_file=artifacts/my-r1-condition.json arm=r1 seed_notes=30

The preparation command prints condition_sha256. Use that value and artifacts/my-r1-condition.json in the generation command above, with another fresh output directory. The input must have at least 30 heads and a remaining suffix. Preparation also requires a fresh output file.

A hand-authored condition can be used instead; the condition schema and example describe its timing, seed and crossing-long-note fields. No corpus catalog, training cache or source suffix labels are required for generation.

By default, export uses a generic header. To preserve the input chart's playback metadata and timing/SV points, also pass these two arguments to the generation command:

"presentation_source='$R1_SOURCE'" "presentation_sha256=$R1_SOURCE_SHA"

Presentation metadata never enters prediction. To play the export, supply the matching audio separately; the model does not load or package it. See the generation guide for resource limits, paused runs and exact recovery.

Checkpoint and training lineage

checkpoint.pt is the original training checkpoint, byte-for-byte unchanged (39,997,453 bytes), including architecture, weights and training state. Inference only needs this checkpoint and a portable condition. Resuming training additionally requires the original pinned plans, caches and native preference pools, which are not distributed here.

The staged restoration trained plain R1 through 4.5M exposures, added observed seed conditioning through 5M and landmark memory through 6M, then added head routing through 6.25M, release routing through 6.5M and row response through 6.75M. It is separate from the 35M teacher configuration. The restoration reconstructs the staged method; it does not recover the byte identity or establish the quality of historical deleted weights.

The checkpoint retains its original training source_revision, cdbc6870d9e6471a5dcb75d8a77f55c30544bf78. The documented main commit has the same Git source tree, 7a11bfe51e474f6e2e822a885076ab33a1add843. All GitHub code and guide links above point to that main commit. release.json records the stage hashes and completed parent-freeze audits; model_config.json contains the exact architecture.

Scope and limitations

This is an experimental oracle-time continuation baseline for inspecting and researching generated 4K structure. It is not an end-to-end audio-to-chart model or a finished Pulsefield V3 system. Training uses source-chart supervision and mechanically derived native preferences; those preferences are not human quality labels.

Mechanical checks establish legal physical rows and faithful osu! export. They do not certify playability, difficulty, musical interpretation, coherent long-form structure or human-like organization. The restoration's quality review remains pending for long-form repetition, long-note/tap balance and local response behavior. The six example counts describe full exported files, including their supplied seeds; they are not held-out quality metrics.

Files and license

• checkpoint.pt: original restored R1 response checkpoint.
• model_config.json, release.json, verification.json: architecture, lineage and reproduction evidence.
• examples/: six portable conditions, full generated charts and example metadata.
• previews/, PREVIEWS.md: rendered PNG/SVG previews and gallery.
• SHA256SUMS: release-file checksums.

The release uses AGPL-3.0-only, matching Pulsefield Model's license on main; the full text is included in LICENSE. Original source charts and music remain attributable to their respective creators; no audio or full original source charts are included.