Optional fast timing provider

[s3d-i]

Hi, I’m working on Pulsefield/Pulsefield-model, mainly around real-time osu!mania map generation(currently still reserach-stage).

One part that may already be useful to Mapperatorinator is the timing module. On my device, it usually runs in around 3–4 seconds per song, and in my own tests it has been quite reliable. It uses heuristic grid fitting / fractional BPM refinement, and it can handle some complex subdivision cases such as 1/7-beat snapping.

I have not run a full benchmark against Mapperatorinator’s current timing path yet, so I don’t want to overclaim. I’m opening this issue first just to ask whether you would be interested in an optional external timing provider / timing import path.

The rough idea would be:

• keep Mapperatorinator’s current timing behavior as default;
• optionally allow timing from another provider, such as Pulsefield;
• convert the result into Mapperatorinator’s existing timing events / context;
• add a small benchmark if this direction sounds interesting.

Would this kind of optional timing provider be something you’d be open to?

[OliBomby]

Sounds interesting. If it's fast and good for multi-bpm songs, then it will add real value.
I want to try out your timing module on a few mp3's to see if its any good. How can I do that?

[s3d-i]

Thanks. The easiest way right now is to run the small CLI in the Pulsefield repo. It is not a polished package yet; it is currently a repo module around BeatThis probabilities + our grid fitter.

git clone https://github.com/Pulsefield/Pulsefield-model.git
cd Pulsefield-model

# Needed for mp3/audio decoding
ffmpeg -version

Install deps with uv:

# Apple Silicon / macOS MPS
uv sync --extra mps

# Linux + NVIDIA CUDA
uv sync --extra cuda

Then run timing on an mp3:

# Apple Silicon
uv run python -m pulsefield_model.timing.fit_audio "/path/to/song.mp3" --device mps --float16

# NVIDIA
uv run python -m pulsefield_model.timing.fit_audio "/path/to/song.mp3" --device cuda --float16

# CPU fallback, slower
uv run python -m pulsefield_model.timing.fit_audio "/path/to/song.mp3" --device cpu

The plain text output includes the fitted song segments directly, for example:

source: /path/to/song.mp3
provider: beat-this
checkpoint: final0
device: mps
canonicalization: none
frame_count: ...
fit_seconds: ...
score: ...
segments:
  1. offset_ms=240.000 beat_length_ms=468.750 bpm=128.000 meter=4
  2. offset_ms=45008.099 beat_length_ms=405.709 bpm=147.889 meter=4

For integration or easier inspection, use JSON:

uv run python -m pulsefield_model.timing.fit_audio "/path/to/song.mp3" \
  --device mps --float16 --json > timing.json

jq '.segments' timing.json

Each segment has:

{
  "offset_ms": 240.0,
  "beat_length_ms": 468.75,
  "bpm": 128.0,
  "meter": 4
}

Useful flags:

--json                         # emit machine-readable report
--device mps|cuda|cpu           # runtime device
--float16                       # faster on my MPS/CUDA runs
--checkpoint final0             # BeatThis checkpoint/name/path; final0 is current default
--min-bpm 60 --max-bpm 260      # constrain search range if needed
--max-segments 24               # allow more BPM/offset sections on multi-BPM songs
--canonicalization none         # preserve fitted tempo, default
--canonicalization bpm-80-160   # fold BPM aliases into [80, 160)
--super-timing-shifts           # extra 0/5/10/15 ms shifted passes for offset-stability inspection
--super-timing-shift-ms 7.5     # custom shifted pass; repeatable
--double-tempo-score-ratio-threshold 0.95

--super-timing-shifts does not replace Mapperatorinator super timing; it just reruns the BeatThis provider on slightly padded audio and reports aligned segment grids under super_timing.runs in JSON. It is useful when checking whether the predicted offset is stable.

There is also a Python entry point if you want to call it directly:

from pathlib import Path
from pulsefield_model.timing.fit_audio import fit_audio_file
from pulsefield_model.timing.grid_fitting import GridFitterConfig

report = fit_audio_file(
    Path("/path/to/song.mp3"),
    device="mps",      # or "cuda" / "cpu"
    float16=True,
    fitter_config=GridFitterConfig(max_segments=24, canonicalization="none"),
)

print(report["segments"])

A couple caveats: this is a compact timing-grid fitter, not a dense redline generator, and I would still judge the output by listening/visual inspection rather than only by .osu red timing agreement. On my MPS setup I usually see roughly 2-4 seconds per normal-length song after setup/model warmup; CPU will be slower.