muscriptor 0.2.2__tar.gz → 0.3.0__tar.gz

{muscriptor-0.2.2 → muscriptor-0.3.0}/.gitignore

@@ -14,3 +14,5 @@ web/tsconfig.tsbuildinfo
 *.egg-info
 __pycache__
 .DS_Store
+.claude/settings.local.json
+.claude/worktrees/

{muscriptor-0.2.2 → muscriptor-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: muscriptor
-Version: 0.2.2
+Version: 0.3.0
 Summary: Audio-to-MIDI transcription using a transformer language model
 Project-URL: Homepage, https://github.com/muscriptor/muscriptor
 Project-URL: Repository, https://github.com/muscriptor/muscriptor
@@ -18,6 +18,7 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Multimedia :: Sound/Audio :: Analysis
 Requires-Python: >=3.10
+Requires-Dist: beat-this>=1.1
 Requires-Dist: einops>=0.4
 Requires-Dist: fastapi>=0.136.3
 Requires-Dist: httpx>=0.28.1
@@ -268,6 +269,12 @@ class TranscriptionModel:
             plus a tiny duration. Note: this tokenizer does not preserve
             velocity (loudness) — only onset/offset timing, pitch, and
             instrument are recovered.
+
+            Event times may all carry the same small lag (up to ~25 ms).
+            Correcting it needs the beat grid and the whole transcription's
+            onsets, which are only available once the stream has finished, so
+            prefer `transcribe_to_midi` when precise note timing matters — it
+            measures the lag and takes it out.
         """
 
     def transcribe_to_midi(

{muscriptor-0.2.2 → muscriptor-0.3.0}/README.md

@@ -231,6 +231,12 @@ class TranscriptionModel:
             plus a tiny duration. Note: this tokenizer does not preserve
             velocity (loudness) — only onset/offset timing, pitch, and
             instrument are recovered.
+
+            Event times may all carry the same small lag (up to ~25 ms).
+            Correcting it needs the beat grid and the whole transcription's
+            onsets, which are only available once the stream has finished, so
+            prefer `transcribe_to_midi` when precise note timing matters — it
+            measures the lag and takes it out.
         """
 
     def transcribe_to_midi(

{muscriptor-0.2.2 → muscriptor-0.3.0}/muscriptor/accelerator.py

@@ -53,7 +53,15 @@ def synchronize() -> None:
     No-op if no accelerator is available.
     """
     if _HAS_TORCH_ACCELERATOR:
-        torch.accelerator.synchronize()
+        # torch.accelerator.synchronize() still tries to init CUDA even on CPU-only systems
+        # Only call it if we actually have a non-CPU accelerator
+        try:
+            current_device = torch.accelerator.current_device_index()
+            if current_device >= 0:
+                torch.accelerator.synchronize()
+        except RuntimeError:
+            # No accelerator available (CUDA not found, etc.)
+            pass
         return
     if torch.cuda.is_available():
         torch.cuda.synchronize()

{muscriptor-0.2.2 → muscriptor-0.3.0}/muscriptor/main.py

@@ -5,7 +5,7 @@ import json
 import sys
 from enum import Enum
 from pathlib import Path
-from typing import Annotated
+from typing import Annotated, Literal
 
 import typer
 
@@ -15,6 +15,7 @@ from muscriptor.tokenizer.mt3 import (
     resolve_instrument_names,
 )
 from muscriptor.transcription_model import TranscriptionModel
+from muscriptor.utils.beats import BeatDetectionError, TempoDetection
 from muscriptor.utils.download import ModelDownloadError
 
 app = typer.Typer(add_completion=False, help="muscriptor — audio-to-MIDI transcription")
@@ -196,6 +197,19 @@ def transcribe(
             ),
         ),
     ] = None,
+    # typer can't take the bool | Literal["best-effort"] union the API uses, so
+    # the CLI spells all three states as strings and converts below.
+    detect_tempo: Annotated[
+        Literal["true", "false", "best-effort"],
+        typer.Option(
+            help=(
+                "Detect the tempo and time signature from the audio and write "
+                "them into the MIDI. 'true' fails if no steady tempo is found, "
+                "'best-effort' warns and uses a placeholder 120 BPM with no "
+                "time signature, 'false' skips detection altogether."
+            ),
+        ),
+    ] = "best-effort",
 ) -> None:
     """Transcribe an audio file to MIDI."""
     instrument_names: list[str] | None = None
@@ -261,7 +275,19 @@ def transcribe(
     )
 
     if format == OutputFormat.midi:
-        midi_bytes = model.transcribe_to_midi(**kwargs)
+        try:
+            mode: TempoDetection = {
+                "true": True,
+                "false": False,
+                "best-effort": "best-effort",
+            }[detect_tempo]
+            midi_bytes = model.transcribe_to_midi(**kwargs, detect_tempo=mode)
+        except BeatDetectionError as e:
+            typer.echo(f"Error: {e}", err=True)
+            typer.echo(
+                "Pass --detect-tempo best-effort or false to continue.", err=True
+            )
+            raise typer.Exit(1)
         if is_stdout:
             sys.stdout.buffer.write(midi_bytes)
             sys.stdout.buffer.flush()
@@ -307,9 +333,7 @@ def transcribe(
             typer.echo(f"Saved JSONL to {output}", err=True)
     else:  # json
         events = [
-            e
-            for e in model.transcribe(**kwargs)
-            if not isinstance(e, ProgressEvent)
+            e for e in model.transcribe(**kwargs) if not isinstance(e, ProgressEvent)
         ]
         payload = json.dumps([_event_to_dict(e) for e in events], indent=2)
         if is_stdout:
@@ -356,10 +380,14 @@ def serve(
     ] = None,
 ):
     """Run the HTTP transcription server (POST /transcribe → SSE event stream)."""
+    import logging
+
     import uvicorn
 
     from muscriptor.server import create_app
 
+    logging.basicConfig(level=logging.INFO, format="%(levelname)s %(name)s: %(message)s")
+
     _device = None if device == "auto" else device
     typer.echo("Loading model…")
     model = _load_model(model_path, _device, dtype)

{muscriptor-0.2.2 → muscriptor-0.3.0}/muscriptor/models/lm.py

@@ -257,7 +257,7 @@ class LMModel(nn.Module):
     # Generation
     # ------------------------------------------------------------------
 
-    @torch.no_grad()
+    @torch.inference_mode()
     def generate(
         self,
         prompt: torch.Tensor | None = None,

{muscriptor-0.2.2 → muscriptor-0.3.0}/muscriptor/server.py

@@ -4,8 +4,12 @@ POST /transcribe with an audio file (multipart/form-data field `file`; WAV,
 or any format soundfile/libsndfile can read — mp3, flac, ogg, m4a, …) returns
 `text/event-stream`. Each event's data is a JSON dict tagged by `type`:
 `start` / `end` note events (same shape as `muscriptor.main._event_to_dict`),
-`progress` chunk anchors (`{completed, total}`), and a final `midi` event
-carrying the base64-encoded .mid file.
+`progress` chunk anchors (`{completed, total}`), and a final
+`transcription_complete` event carrying the base64-encoded .mid file (`data`)
+plus the detected `beat_grid`
+(`{bpm, beats_per_bar, first_downbeat, onset_delay}`, or null if no tempo was
+found). `onset_delay` is how late the streamed note times are against those
+beats: the MIDI has it taken out already, an SSE consumer has to subtract it.
 
 POST /transcribe/midi takes the same upload but blocks until transcription
 completes and returns the raw `audio/midi` bytes directly (no SSE, no
@@ -24,9 +28,9 @@ import threading
 import time
 import wave
 from pathlib import Path
-from typing import Annotated
+from typing import Annotated, Callable
 
-from fastapi import FastAPI, File, Form, HTTPException, UploadFile
+from fastapi import FastAPI, File, Form, Header, HTTPException, UploadFile
 from fastapi.responses import FileResponse, Response, StreamingResponse
 from fastapi.staticfiles import StaticFiles
 from starlette.background import BackgroundTask
@@ -36,6 +40,7 @@ from muscriptor.soundfonts import SF3_URL
 from muscriptor.tokenizer.mt3 import MT3_FULL_PLUS_GROUP_NAMES
 from muscriptor.transcription_model import TranscriptionModel
 from muscriptor.utils.audio import _read_non_wav_file, _read_wav_file
+from muscriptor.utils.beats import BeatDetectionError, TempoDetection
 from muscriptor.utils.download import download_if_necessary
 
 
@@ -77,15 +82,85 @@ def create_app(model: TranscriptionModel, web_dir: str | Path | None = None) ->
     app = FastAPI(title="muscriptor")
 
     transcribe_lock = threading.Lock()
-    lock_timeout_s = 60.0
-    # Cancel event of the run currently holding the lock (or the last one to
-    # have held it). A new /transcribe request sets it so an in-flight run
-    # stops at its next event boundary instead of transcribing to completion
-    # for a client that has moved on. This must not rely on TCP disconnects:
-    # aborts don't always reach us (e.g. port forwards / proxies that keep the
-    # upstream connection open after the browser aborts).
+    # State of the run currently holding the lock (or the last one to have held
+    # it), guarded by `cancel_guard`: its cancel event and the id of the client
+    # that started it. A new /transcribe from the SAME client (a resubmit in
+    # the same browser tab) sets the cancel event so the in-flight run stops at
+    # its next event boundary instead of transcribing to completion for a client
+    # that has moved on. A request from a DIFFERENT client never preempts — it
+    # waits for the lock like any other contender, so two independent browser
+    # windows don't kill each other's transcription. This scoping must be done
+    # here rather than by watching the socket: browser aborts don't always reach
+    # us (e.g. port forwards / proxies keep the upstream connection open after
+    # the browser aborts), so a same-tab resubmit can't be detected as a
+    # disconnect.
     cancel_guard = threading.Lock()
     current_cancel: threading.Event | None = None
+    current_client: str | None = None
+    # Bound on how long a same-client resubmit waits for the run it just
+    # cancelled to unwind and release the lock. That run stops within one
+    # chunk boundary, so this only needs to cover that latency — unlike
+    # genuine cross-client contention, which now fails instantly instead of
+    # sitting on the connection (see below).
+    preempt_wait_s = 5.0
+
+    async def acquire_transcribe_lock(
+        client_id: str | None, cancellable: bool
+    ) -> tuple[threading.Event | None, Callable[[], None]]:
+        """Acquire the single-transcription lock, preempting only a run started
+        by this same `client_id` (a resubmit): that run is signalled to stop
+        and this call waits up to `preempt_wait_s` for it to release the lock.
+        A different client — or an anonymous API caller with no id — never
+        preempts and is never preempted; it gets an immediate 503 instead of
+        waiting, so a caller retrying against another machine (e.g. behind a
+        load balancer like Traefik) doesn't have to hold the connection open.
+
+        Returns `(cancel, release)`: `cancel` is the new run's cancel event
+        (`None` when `cancellable` is False, e.g. the blocking /transcribe/midi
+        render, which can't be stopped mid-flight); `release` frees the lock at
+        most once, from whichever cleanup path runs first.
+        """
+        nonlocal current_cancel, current_client
+        deadline: float | None = None
+        while True:
+            with cancel_guard:
+                # Re-check each iteration so that even a same-client run which
+                # became "current" while we were already waiting (a resubmit
+                # that beat us to the lock) gets cancelled too — the newest
+                # request from a given client always wins.
+                preempting = (
+                    current_cancel is not None
+                    and client_id is not None
+                    and current_client == client_id
+                )
+                if preempting:
+                    current_cancel.set()
+            if not preempting:
+                acquired = await asyncio.to_thread(transcribe_lock.acquire, False)
+                if not acquired:
+                    raise HTTPException(
+                        status_code=503,
+                        detail="server busy: another transcription is in progress",
+                    )
+                break
+            if deadline is None:
+                deadline = time.monotonic() + preempt_wait_s
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                raise HTTPException(
+                    status_code=503,
+                    detail="server busy: another transcription is in progress",
+                )
+            acquired = await asyncio.to_thread(
+                transcribe_lock.acquire, True, min(0.1, remaining)
+            )
+            if acquired:
+                break
+        cancel = threading.Event() if cancellable else None
+        with cancel_guard:
+            current_cancel = cancel
+            current_client = client_id
+        return cancel, _make_release_once(transcribe_lock)
 
     @app.get("/health")
     async def health():
@@ -109,6 +184,9 @@ def create_app(model: TranscriptionModel, web_dir: str | Path | None = None) ->
     async def transcribe(
         file: Annotated[UploadFile, File()],
         instruments: Annotated[list[str], Form(default_factory=list)],
+        # "true" fails loudly on tempo detection errors, "false" doesn't even try
+        detect_tempo: Annotated[TempoDetection, Form()] = "best-effort",
+        x_client_id: Annotated[str | None, Header()] = None,
     ) -> StreamingResponse:
         data = await file.read()
         # PCM WAV goes through the stdlib reader (keeps WAV decoding byte-for-byte
@@ -135,37 +213,16 @@ def create_app(model: TranscriptionModel, web_dir: str | Path | None = None) ->
                 detail=f"unknown instrument name(s): {', '.join(unknown)}",
             )
 
-        # Preempt whoever holds the lock, then wait for it. The short acquire
-        # timeout re-signals each second so that even a run that started while
-        # we were already waiting (another preempting request that beat us to
-        # the lock) gets cancelled too — the newest request always wins.
-        nonlocal current_cancel
-        deadline = time.monotonic() + lock_timeout_s
-        while True:
-            with cancel_guard:
-                if current_cancel is not None:
-                    current_cancel.set()
-            remaining = deadline - time.monotonic()
-            if remaining <= 0:
-                raise HTTPException(
-                    status_code=503,
-                    detail="server busy: another transcription is in progress",
-                )
-            acquired = await asyncio.to_thread(
-                transcribe_lock.acquire, True, min(1.0, remaining)
-            )
-            if acquired:
-                break
-        cancel = threading.Event()
-        with cancel_guard:
-            current_cancel = cancel
-
-        # Release exactly once, from whichever path runs first. The generator's
-        # finally covers normal completion, errors and mid-stream disconnects;
-        # the StreamingResponse background task covers the case where the client
-        # disconnects *before* the generator is ever iterated (so its finally
-        # would never run) — which otherwise leaks the lock forever.
-        release_lock = _make_release_once(transcribe_lock)
+        # Acquire the single-transcription lock, preempting only a resubmit from
+        # this same client (see acquire_transcribe_lock). `release_lock` runs
+        # from whichever cleanup path fires first: the generator's finally
+        # (normal completion, errors, mid-stream disconnects) or the
+        # StreamingResponse background task (client disconnects before the
+        # generator is ever iterated, so its finally would never run) — either
+        # way the lock is released exactly once and never leaked.
+        cancel, release_lock = await acquire_transcribe_lock(
+            x_client_id, cancellable=True
+        )
 
         def gen():
             try:
@@ -205,9 +262,43 @@ def create_app(model: TranscriptionModel, web_dir: str | Path | None = None) ->
                 # with the bytes base64-encoded.
                 if cancel.is_set():
                     return
-                midi_bytes = model.events_to_midi_bytes(iter(events))
+                # Detect tempo/meter only now: it costs a few seconds of CPU and
+                # nothing before this point needs it, so the notes stream first.
+                grid = model.detect_beat_grid_for((wav, sr), detect_tempo)
+                # Measure the onset lag up here rather than leaving it to the MIDI
+                # writing, since the UI has to be told the very same number to move
+                # the notes it already drew.
+                if grid:
+                    grid = grid.with_onset_delay(
+                        [
+                            ev.start_time
+                            for ev in events
+                            if isinstance(ev, NoteStartEvent)
+                        ]
+                    )
+                midi_bytes = model.events_to_midi_bytes(iter(events), beat_grid=grid)
                 midi_b64 = base64.b64encode(midi_bytes).decode("ascii")
-                payload = json.dumps({"type": "midi", "data": midi_b64})
+                # The grid rides along so the UI can draw bar lines instead of a
+                # fixed seconds grid; null when no tempo was detected.
+                payload = json.dumps(
+                    {
+                        "type": "transcription_complete",
+                        "data": midi_b64,
+                        # Only the fields the UI draws with; `grid.beats` is an
+                        # ndarray and not JSON-serializable anyway.
+                        "beat_grid": {
+                            "bpm": grid.bpm,
+                            "beats_per_bar": grid.beats_per_bar,
+                            "first_downbeat": grid.first_downbeat,
+                            # Seconds the streamed note times sit late against
+                            # the beats; the MIDI already has it taken out, the
+                            # UI has to subtract it from the notes it drew.
+                            "onset_delay": grid.onset_delay,
+                        }
+                        if grid
+                        else None,
+                    }
+                )
                 yield f"data: {payload}\n\n"
             finally:
                 release_lock()
@@ -223,6 +314,9 @@ def create_app(model: TranscriptionModel, web_dir: str | Path | None = None) ->
     async def transcribe_midi(
         file: Annotated[UploadFile, File()],
         instruments: Annotated[list[str], Form(default_factory=list)],
+        # "true" fails loudly on tempo detection errors, "false" doesn't even try
+        detect_tempo: Annotated[TempoDetection, Form()] = "best-effort",
+        x_client_id: Annotated[str | None, Header()] = None,
     ) -> Response:
         """Transcribe an audio file and return the .mid file directly.
 
@@ -260,38 +354,28 @@ def create_app(model: TranscriptionModel, web_dir: str | Path | None = None) ->
                 detail=f"unknown instrument name(s): {', '.join(unknown)}",
             )
 
-        # Same mutual-exclusion as /transcribe (the model isn't safe to run
-        # concurrently), but no preemption: this call doesn't stream, so
-        # there's nothing to cancel mid-flight. A concurrent /transcribe
-        # request will just wait for the lock like any other contender.
-        nonlocal current_cancel
-        deadline = time.monotonic() + lock_timeout_s
-        while True:
-            with cancel_guard:
-                if current_cancel is not None:
-                    current_cancel.set()
-            remaining = deadline - time.monotonic()
-            if remaining <= 0:
-                raise HTTPException(
-                    status_code=503,
-                    detail="server busy: another transcription is in progress",
-                )
-            acquired = await asyncio.to_thread(
-                transcribe_lock.acquire, True, min(1.0, remaining)
-            )
-            if acquired:
-                break
-        with cancel_guard:
-            current_cancel = None
-
+        # Same mutual exclusion as /transcribe, via the shared helper. This run
+        # is not cancellable (it doesn't stream, so there's nothing to stop
+        # mid-flight); cancellable=False records that, so nothing tries to
+        # preempt a blocking MIDI render. A non-browser API caller sends no
+        # client id and so neither preempts nor is preempted — it just waits for
+        # the lock like any other contender.
+        _cancel, release_lock = await acquire_transcribe_lock(
+            x_client_id, cancellable=False
+        )
         try:
             midi_bytes = await asyncio.to_thread(
                 model.transcribe_to_midi,
                 (wav, sr),
                 instruments=instruments or None,
+                detect_tempo=detect_tempo,
             )
+        except BeatDetectionError as e:
+            # Only reachable with detect_tempo=true, where the caller wants an error
+            # if tempo detection fails.
+            raise HTTPException(status_code=422, detail=str(e)) from e
         finally:
-            transcribe_lock.release()
+            release_lock()
 
         return Response(
             content=midi_bytes,

{muscriptor-0.2.2 → muscriptor-0.3.0}/muscriptor/tokenizer/notes.py

@@ -9,6 +9,8 @@ from dataclasses import dataclass
 
 from mido import Message, MetaMessage, MidiFile, MidiTrack, second2tick
 
+from muscriptor.utils.beats import BAR_OFFSET_MARKER
+
 DRUM_PROGRAM = 128
 MINIMUM_NOTE_DURATION_SEC = 0.01
 
@@ -263,6 +265,8 @@ def note_event2midi(
     ticks_per_beat: int = 480,
     tempo: int = 500000,
     program_names: dict[int, str] | None = None,
+    beats_per_bar: int | None = None,
+    offset_s: float = 0.0,
 ) -> MidiFile:
     """Convert NoteEvent list to a type-1 (multi-track) MIDI file.
 
@@ -274,10 +278,25 @@ def note_event2midi(
 
     `program_names` maps a program number (DRUM_PROGRAM for drums) to the
     track name; unmapped programs fall back to "program <n>" / "drums".
+
+    `beats_per_bar` writes a time signature (denominator 4).
+    `offset_s` delays every event so bar lines land on real downbeats.
     """
     midi = MidiFile(ticks_per_beat=ticks_per_beat, type=1)
     meta_track = MidiTrack()
     meta_track.append(MetaMessage("set_tempo", tempo=tempo, time=0))
+    if beats_per_bar is not None:
+        meta_track.append(
+            MetaMessage(
+                "time_signature", numerator=beats_per_bar, denominator=4, time=0
+            )
+        )
+    if offset_s:
+        # Doesn't do anything for the MIDI but we just mark "we had to shift by this
+        # much to align the bars". Read by /auralize later
+        meta_track.append(
+            MetaMessage("marker", text=f"{BAR_OFFSET_MARKER}{offset_s:.4f}", time=0)
+        )
     midi.tracks.append(meta_track)
 
     drum_offset_events = []
@@ -302,7 +321,7 @@ def note_event2midi(
     track_ticks: dict[int, int] = {}
     current_tick = 0
     for ne in note_events:
-        absolute_tick = round(second2tick(ne.time, ticks_per_beat, tempo))
+        absolute_tick = round(second2tick(ne.time + offset_s, ticks_per_beat, tempo))
         if absolute_tick < current_tick:
             raise ValueError(
                 f"at ne.time {ne.time}, absolute_tick {absolute_tick} < current_tick {current_tick}"
@@ -328,6 +347,9 @@ def note_event2midi(
                 gm_program = ne.program
             program_to_channel[key] = ne_channel
             track.append(MetaMessage("track_name", name=name, time=0))
+            # MuseScore ignores set_tempo in a conductor track that has no notes,
+            # so repeat it here. Harmless for hosts that read the meta track.
+            track.append(MetaMessage("set_tempo", tempo=tempo, time=0))
             track.append(
                 Message(
                     "program_change", program=gm_program, time=0, channel=ne_channel

{muscriptor-0.2.2 → muscriptor-0.3.0}/muscriptor/transcription_model.py

@@ -14,7 +14,6 @@ from pathlib import Path
 
 import torch
 import torch.nn.functional as F
-
 from safetensors.torch import load_file
 
 import muscriptor.accelerator
@@ -27,12 +26,11 @@ from muscriptor.events import (
     decode_model_tokens,
 )
 from muscriptor.models.lm import LMModel, TorchAutocast
-from muscriptor.utils.download import download_companion, download_if_necessary
 from muscriptor.modules.conditioners import (
-    MelSpectrogramConditioner,
     ClassConditioner,
-    ConditioningProvider,
     ConditioningAttributes,
+    ConditioningProvider,
+    MelSpectrogramConditioner,
     WavCondition,
 )
 from muscriptor.tokenizer.mt3 import (
@@ -47,6 +45,13 @@ from muscriptor.tokenizer.notes import (
     validate_notes,
 )
 from muscriptor.utils.audio import load_audio, resample
+from muscriptor.utils.beats import (
+    BeatDetectionError,
+    BeatGrid,
+    TempoDetection,
+    detect_grid,
+)
+from muscriptor.utils.download import download_companion, download_if_necessary
 from muscriptor.utils.midi import notes_to_midi
 
 
@@ -84,6 +89,7 @@ def _resolve_source(weights_path: str | Path | None) -> str | Path:
         return _HF_REPO_TEMPLATE.format(size=weights_path)
     return weights_path
 
+
 _SAMPLE_RATE = 16000
 # Must match the segment duration used during training / evaluation.
 _SEGMENT_DURATION = 5.0
@@ -360,6 +366,11 @@ class TranscriptionModel:
         ``prelude_forcing=False`` explicitly to trade chunk-boundary quality
         for batched throughput.
 
+        The event times may all carry the same small lag (up to ~25 ms) due to model
+        bias. Taking it out needs the beat grid and every onset in the transcription,
+        which only exist once the stream has finished, so prefer
+        :meth:`transcribe_to_midi` when precise note timing matters.
+
         Interleaved with the note events are coarse :class:`ProgressEvent`
         anchors (``completed`` of ``total`` chunks): one up front with
         ``completed == 0``, then one as each chunk finishes. Consumers that
@@ -451,9 +462,7 @@ class TranscriptionModel:
             file=sys.stderr,
         )
 
-    def _resolve_batch_size(
-        self, batch_size: int | None, prelude_forcing: bool
-    ) -> int:
+    def _resolve_batch_size(self, batch_size: int | None, prelude_forcing: bool) -> int:
         """Default the batch size, favouring transcription quality.
 
         Prelude forcing needs chunks generated strictly in order, so while it
@@ -620,8 +629,10 @@ class TranscriptionModel:
         no_eos_is_ok: bool = True,
         beam_size: int = 1,
         prelude_forcing: bool = True,
+        detect_tempo: TempoDetection = "best-effort",
     ) -> bytes:
         """Same as :meth:`transcribe` but returns a MIDI file as bytes."""
+        beat_grid = self.detect_beat_grid_for(audio, detect_tempo)
         events = self.transcribe(
             audio,
             use_sampling=use_sampling,
@@ -633,10 +644,41 @@ class TranscriptionModel:
             beam_size=beam_size,
             prelude_forcing=prelude_forcing,
         )
-        return self.events_to_midi_bytes(events)
+        return self.events_to_midi_bytes(events, beat_grid=beat_grid)
+
+    def detect_beat_grid_for(
+        self,
+        audio: str | Path | tuple[torch.Tensor, int],
+        mode: TempoDetection = "best-effort",
+    ) -> BeatGrid | None:
+        """Detect the beat grid of `audio`, or None if there isn't a usable one.
+
+        Accepts the same input forms as :meth:`transcribe`.
+        `mode` decides what a failed detection means: raise (True), skip detection
+        entirely (False), or warn and fall back to the placeholder tempo
+        ("best-effort").
+
+        The grid carries the tracked beat times along, so that writing the MIDI
+        can move the transcription's onsets onto them (see BeatGrid.onset_delay).
+        """
+        if mode is False:
+            return None
+        tensor, sample_rate = audio if isinstance(audio, tuple) else (audio, None)
+        try:
+            return detect_grid(self._load_wav(tensor, sample_rate), _SAMPLE_RATE)
+        except BeatDetectionError as e:
+            if mode is True:
+                raise
+            print(
+                f"Warning: {e}; falling back to the placeholder tempo",
+                file=sys.stderr,
+            )
+            return None
 
     def events_to_midi_bytes(
-        self, events: Iterator[NoteStartEvent | NoteEndEvent | ProgressEvent]
+        self,
+        events: Iterator[NoteStartEvent | NoteEndEvent | ProgressEvent],
+        beat_grid: BeatGrid | None = None,
     ) -> bytes:
         """Reassemble Notes from a NoteStart/NoteEnd stream and serialize MIDI.
 
@@ -674,7 +716,7 @@ class TranscriptionModel:
         # don't drift from earlier reference outputs.
         notes = validate_notes(notes, fix=True)
         notes = trim_overlapping_notes(notes, sort=True)
-        midi = notes_to_midi(notes, program_names=program_names)
+        midi = notes_to_midi(notes, program_names=program_names, beat_grid=beat_grid)
         buf = io.BytesIO()
         midi.save(file=buf)
         return buf.getvalue()