muscriptor 0.2.1__tar.gz → 0.3.0__tar.gz

{muscriptor-0.2.1 → muscriptor-0.3.0}/.dockerignore

@@ -3,6 +3,7 @@
 *.safetensors
 *.wav
 *.mp3
+!web/public/headache_by_lost_deposit_1min.mp3
 *.ogg
 *.mid
 .venv

muscriptor-0.3.0/.github/workflows/deploy.yml

@@ -0,0 +1,28 @@
+name: Deploy demo
+
+on:
+  workflow_dispatch:
+
+concurrency:
+  group: deploy-demo
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up SSH access to the deployment host
+      run: |
+        mkdir -p ~/.ssh
+        chmod 700 ~/.ssh
+        # The public key is at .github/workflows/id_ed25519.pub
+        # If the machine changes, add this key to the authorized_keys of the new machine.
+        echo "${{ secrets.DEPLOYMENT_SSH_KEY }}" > ~/.ssh/id_ed25519
+        chmod 600 ~/.ssh/id_ed25519
+        ssh-keyscan muscriptor.kyutai.org >> ~/.ssh/known_hosts
+        echo "${{ secrets.DEPLOYMENT_REGISTRY_SECRET }}" | docker login rg.fr-par.scw.cloud -u nologin --password-stdin
+    - name: Deploy
+      env:
+        HF_TOKEN: ${{ secrets.DEPLOYMENT_HF_TOKEN }}
+      run: ./deploy.sh

muscriptor-0.3.0/.github/workflows/id_ed25519.pub

@@ -0,0 +1 @@
+ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOTt3l4T8vJXJWxDPQrWjXFNOf3Z4ww/vtUXBbn5reJU root@tf-muscriptor-0

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

@@ -4,6 +4,7 @@
 !headache_mastered.mid
 *.wav
 *.mp3
+!headache_by_lost_deposit_1min.mp3
 *.ogg
 *.sf2
 web/node_modules
@@ -13,3 +14,5 @@ web/tsconfig.tsbuildinfo
 *.egg-info
 __pycache__
 .DS_Store
+.claude/settings.local.json
+.claude/worktrees/

muscriptor-0.3.0/.python-version

@@ -0,0 +1 @@
+3.13

{muscriptor-0.2.1 → muscriptor-0.3.0}/Dockerfile

@@ -9,6 +9,10 @@ COPY web/package.json web/pnpm-lock.yaml ./
 RUN pnpm install --frozen-lockfile
 
 COPY web/ ./
+# The GA4 measurement ID is inlined into the JS bundle by Vite; left unset
+# (the default), the frontend is built with analytics disabled entirely.
+ARG VITE_GA_MEASUREMENT_ID=
+ENV VITE_GA_MEASUREMENT_ID=$VITE_GA_MEASUREMENT_ID
 # vite outDir is ../muscriptor/web_dist, i.e. /muscriptor/web_dist in this stage.
 RUN pnpm run build
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: muscriptor
-Version: 0.2.1
+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,16 +18,20 @@ 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
 Requires-Dist: huggingface-hub>=0.13
 Requires-Dist: mido>=1.3
-Requires-Dist: numpy>=1.24
+Requires-Dist: numpy<2,>=1.24; sys_platform == 'darwin' and platform_machine == 'x86_64'
+Requires-Dist: numpy>=1.24; sys_platform != 'darwin' or platform_machine != 'x86_64'
+Requires-Dist: packaging>=20.0
 Requires-Dist: python-multipart>=0.0.29
 Requires-Dist: safetensors>=0.4
 Requires-Dist: soundfile>=0.14.0
-Requires-Dist: torch>=2.0
+Requires-Dist: torch<2.3,>=2.0; sys_platform == 'darwin' and platform_machine == 'x86_64'
+Requires-Dist: torch>=2.0; sys_platform != 'darwin' or platform_machine != 'x86_64'
 Requires-Dist: typer>=0.10
 Requires-Dist: uvicorn[standard]>=0.48.0
 Description-Content-Type: text/markdown
@@ -50,6 +54,30 @@ MuScriptor is the first music transcription model that has been trained on a lar
 </p>
 -->
 
+## HuggingFace login (required)
+
+The model weights are hosted on [HuggingFace](https://huggingface.co/MuScriptor)
+and gated behind their CC BY-NC 4.0 license, so downloading them — including
+on the first `uvx muscriptor` run — requires a (free) HuggingFace account:
+
+1. Accept the model license on the model page, e.g.
+   [muscriptor-medium](https://huggingface.co/MuScriptor/muscriptor-medium)
+   (access is granted automatically).
+2. Authenticate on your machine:
+
+   ```bash
+   uvx hf auth login
+   ```
+
+   or set a token (create one at
+   [huggingface.co/settings/tokens](https://huggingface.co/settings/tokens)):
+
+   ```bash
+   export HF_TOKEN=hf_...
+   ```
+
+The weights are then downloaded on first use and cached locally.
+
 ## Try it locally
 
 You can try it locally with the web UI with:
@@ -58,12 +86,29 @@ You can try it locally with the web UI with:
 uvx muscriptor serve
 ```
 
+On windows, the default PyTorch backend is `cpu`, so to use the GPU on Windows, you'll need to run:
+
+```bash
+uvx --torch-backend=cu128 muscriptor serve
+```
+Use the `--torch-backend=cu128` flag every time you run a `uvx` command on Windows.
+
 or with the CLI:
 
 ```bash
 uvx muscriptor transcribe
 ```  
 
+> **Intel Macs:** PyTorch stopped shipping Intel-mac (x86_64) wheels after
+> torch 2.2.2, which supports Python ≤ 3.12, so you must tell uvx to use
+> Python 3.12:
+>
+> ```bash
+> uvx --python 3.12 muscriptor serve
+> ```
+>
+> If you install with pip/uv instead, use Python 3.10–3.12.
+
 
 ## Installation
 
@@ -92,7 +137,9 @@ weights are downloaded and cached automatically. The architecture is a transform
 
 `small` is the practical choice on CPU-only machines, `medium` is the default
 speed/accuracy trade-off, and `large` is the most accurate but really wants a
-GPU. 
+GPU. On Apple Silicon the model runs on Metal (MPS) automatically, in float16
+by default (`--dtype float32` to override) — fast enough that `large`
+transcribes several times faster than real time. 
 ## Usage
 
 ```python
@@ -165,6 +212,7 @@ class TranscriptionModel:
             batch_size: int | None = None,
             no_eos_is_ok: bool = True,
             beam_size: int = 1,
+            prelude_forcing: bool = True,
         ) -> Generator[NoteStartEvent | NoteEndEvent | ProgressEvent, None, None]:
         """Transcribe audio into a stream of note events.
 
@@ -177,24 +225,39 @@ class TranscriptionModel:
             temperature: Sampling temperature (only used when use_sampling=True).
             cfg_coef: Classifier-free guidance coefficient. Keep to 1 for the released models (they are post-RL)
             instruments: Optional list of instrument group names to
-                condition the model on (exact names, e.g.
+                restrict decoding to (exact names, e.g.
                 ["acoustic_piano", "drums"]). Run `muscriptor
                 list-instruments` (or GET /instruments on the server)
-                for the full list of valid names.
+                for the full list of valid names. When given, this is a
+                hard constraint: every program/drum token outside the
+                list is masked out during generation, so no unlisted
+                instrument can appear in the output. Leave unset to let
+                the model decode whatever instruments it detects.
             batch_size: Number of 5-second chunks processed per forward
-                pass. `None` (default) picks a value based on the device:
-                1 on CPU, 4 on GPU. Use `batch_size=1` for the lowest
-                streaming latency — larger batches process several chunks
-                together, so events belonging to later chunks of a batch
-                won't arrive until the whole batch finishes. Within a
-                batch, events are always yielded in temporal order; all
-                events from chunk N are emitted before any event from
-                chunk N+1.
+                pass. `None` (default) resolves to 1 while prelude forcing
+                is on; with `prelude_forcing=False` it picks a value based
+                on the device: 1 on CPU, 4 on GPU. Values > 1 trade
+                chunk-boundary quality for throughput and therefore require
+                `prelude_forcing=False` (ValueError otherwise). Batching
+                also delays streaming: several chunks generate together, so
+                events belonging to later chunks of a batch won't arrive
+                until the whole batch finishes. Within a batch, events are
+                always yielded in temporal order; all events from chunk N
+                are emitted before any event from chunk N+1.
             no_eos_is_ok: If True, a chunk that doesn't emit EOS within
                 the generation budget produces a warning instead of raising.
             beam_size: Beam search width. 1 (default) uses greedy decoding
                 (or sampling, with use_sampling=True); >= 2 enables beam
                 search, which is slower but can be more accurate.
+            prelude_forcing: If True (default), every chunk after the first
+                has its tie prologue — the tokens declaring which notes are
+                sustained from the previous chunk — teacher-forced from the
+                previous chunk's actually-unfinished notes, instead of
+                letting the model guess (which occasionally makes a chunk
+                restart with the wrong instruments). Requires chunks to be
+                generated strictly in order, so it only works with
+                batch_size=1 (the default); set prelude_forcing=False
+                explicitly to use larger batches.
 
         Returns:
             Generator of NoteStartEvent, NoteEndEvent and ProgressEvent
@@ -206,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(
@@ -218,6 +287,7 @@ class TranscriptionModel:
             batch_size: int | None = None,
             no_eos_is_ok: bool = True,
             beam_size: int = 1,
+            prelude_forcing: bool = True,
         ) -> bytes:
         """Same as `transcribe`, but returns a MIDI file as bytes instead
         of a generator of events. Useful when you want to save the MIDI
@@ -237,10 +307,11 @@ muscriptor transcribe audio.wav -o out.mid
 # a local safetensors path, or an hf:// / http(s):// URL
 muscriptor transcribe audio.wav --model large
 
-# Tell the model which instruments to expect (comma-separated names;
+# Restrict decoding to only the instruments listed (comma-separated names;
 # run `muscriptor list-instruments` for the full list). Case-insensitive,
 # and unambiguous abbreviations work: 'timp,dist' = timpani + distorted
-# electric guitar
+# electric guitar. Every other instrument's tokens are masked out during
+# generation, so nothing else can appear in the output.
 muscriptor transcribe audio.wav --instruments acoustic_piano,drums
 
 # Get the event stream instead of MIDI: json (single array) or
@@ -252,6 +323,13 @@ muscriptor transcribe audio.wav --format jsonl -o -
 muscriptor transcribe audio.wav --sampling -t 0.8
 muscriptor transcribe audio.wav --beam-size 4
 
+# Notes sustained across a chunk boundary are teacher-forced into the next
+# chunk's prologue by default, so a chunk can't restart them with the wrong
+# instrument. This needs chunks generated in order, so the batch size
+# defaults to 1; batching (faster on GPU, lower quality at chunk boundaries)
+# must be opted into explicitly:
+muscriptor transcribe audio.wav --no-prelude-forcing --batch-size 4
+
 # Render a stereo check-mix of the result (left channel = original audio,
 # right channel = synthesized MIDI; requires fluidsynth on PATH)
 muscriptor transcribe audio.wav -o out.mid --auralize check.wav

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

@@ -16,6 +16,30 @@ MuScriptor is the first music transcription model that has been trained on a lar
 </p>
 -->
 
+## HuggingFace login (required)
+
+The model weights are hosted on [HuggingFace](https://huggingface.co/MuScriptor)
+and gated behind their CC BY-NC 4.0 license, so downloading them — including
+on the first `uvx muscriptor` run — requires a (free) HuggingFace account:
+
+1. Accept the model license on the model page, e.g.
+   [muscriptor-medium](https://huggingface.co/MuScriptor/muscriptor-medium)
+   (access is granted automatically).
+2. Authenticate on your machine:
+
+   ```bash
+   uvx hf auth login
+   ```
+
+   or set a token (create one at
+   [huggingface.co/settings/tokens](https://huggingface.co/settings/tokens)):
+
+   ```bash
+   export HF_TOKEN=hf_...
+   ```
+
+The weights are then downloaded on first use and cached locally.
+
 ## Try it locally
 
 You can try it locally with the web UI with:
@@ -24,12 +48,29 @@ You can try it locally with the web UI with:
 uvx muscriptor serve
 ```
 
+On windows, the default PyTorch backend is `cpu`, so to use the GPU on Windows, you'll need to run:
+
+```bash
+uvx --torch-backend=cu128 muscriptor serve
+```
+Use the `--torch-backend=cu128` flag every time you run a `uvx` command on Windows.
+
 or with the CLI:
 
 ```bash
 uvx muscriptor transcribe
 ```  
 
+> **Intel Macs:** PyTorch stopped shipping Intel-mac (x86_64) wheels after
+> torch 2.2.2, which supports Python ≤ 3.12, so you must tell uvx to use
+> Python 3.12:
+>
+> ```bash
+> uvx --python 3.12 muscriptor serve
+> ```
+>
+> If you install with pip/uv instead, use Python 3.10–3.12.
+
 
 ## Installation
 
@@ -58,7 +99,9 @@ weights are downloaded and cached automatically. The architecture is a transform
 
 `small` is the practical choice on CPU-only machines, `medium` is the default
 speed/accuracy trade-off, and `large` is the most accurate but really wants a
-GPU. 
+GPU. On Apple Silicon the model runs on Metal (MPS) automatically, in float16
+by default (`--dtype float32` to override) — fast enough that `large`
+transcribes several times faster than real time. 
 ## Usage
 
 ```python
@@ -131,6 +174,7 @@ class TranscriptionModel:
             batch_size: int | None = None,
             no_eos_is_ok: bool = True,
             beam_size: int = 1,
+            prelude_forcing: bool = True,
         ) -> Generator[NoteStartEvent | NoteEndEvent | ProgressEvent, None, None]:
         """Transcribe audio into a stream of note events.
 
@@ -143,24 +187,39 @@ class TranscriptionModel:
             temperature: Sampling temperature (only used when use_sampling=True).
             cfg_coef: Classifier-free guidance coefficient. Keep to 1 for the released models (they are post-RL)
             instruments: Optional list of instrument group names to
-                condition the model on (exact names, e.g.
+                restrict decoding to (exact names, e.g.
                 ["acoustic_piano", "drums"]). Run `muscriptor
                 list-instruments` (or GET /instruments on the server)
-                for the full list of valid names.
+                for the full list of valid names. When given, this is a
+                hard constraint: every program/drum token outside the
+                list is masked out during generation, so no unlisted
+                instrument can appear in the output. Leave unset to let
+                the model decode whatever instruments it detects.
             batch_size: Number of 5-second chunks processed per forward
-                pass. `None` (default) picks a value based on the device:
-                1 on CPU, 4 on GPU. Use `batch_size=1` for the lowest
-                streaming latency — larger batches process several chunks
-                together, so events belonging to later chunks of a batch
-                won't arrive until the whole batch finishes. Within a
-                batch, events are always yielded in temporal order; all
-                events from chunk N are emitted before any event from
-                chunk N+1.
+                pass. `None` (default) resolves to 1 while prelude forcing
+                is on; with `prelude_forcing=False` it picks a value based
+                on the device: 1 on CPU, 4 on GPU. Values > 1 trade
+                chunk-boundary quality for throughput and therefore require
+                `prelude_forcing=False` (ValueError otherwise). Batching
+                also delays streaming: several chunks generate together, so
+                events belonging to later chunks of a batch won't arrive
+                until the whole batch finishes. Within a batch, events are
+                always yielded in temporal order; all events from chunk N
+                are emitted before any event from chunk N+1.
             no_eos_is_ok: If True, a chunk that doesn't emit EOS within
                 the generation budget produces a warning instead of raising.
             beam_size: Beam search width. 1 (default) uses greedy decoding
                 (or sampling, with use_sampling=True); >= 2 enables beam
                 search, which is slower but can be more accurate.
+            prelude_forcing: If True (default), every chunk after the first
+                has its tie prologue — the tokens declaring which notes are
+                sustained from the previous chunk — teacher-forced from the
+                previous chunk's actually-unfinished notes, instead of
+                letting the model guess (which occasionally makes a chunk
+                restart with the wrong instruments). Requires chunks to be
+                generated strictly in order, so it only works with
+                batch_size=1 (the default); set prelude_forcing=False
+                explicitly to use larger batches.
 
         Returns:
             Generator of NoteStartEvent, NoteEndEvent and ProgressEvent
@@ -172,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(
@@ -184,6 +249,7 @@ class TranscriptionModel:
             batch_size: int | None = None,
             no_eos_is_ok: bool = True,
             beam_size: int = 1,
+            prelude_forcing: bool = True,
         ) -> bytes:
         """Same as `transcribe`, but returns a MIDI file as bytes instead
         of a generator of events. Useful when you want to save the MIDI
@@ -203,10 +269,11 @@ muscriptor transcribe audio.wav -o out.mid
 # a local safetensors path, or an hf:// / http(s):// URL
 muscriptor transcribe audio.wav --model large
 
-# Tell the model which instruments to expect (comma-separated names;
+# Restrict decoding to only the instruments listed (comma-separated names;
 # run `muscriptor list-instruments` for the full list). Case-insensitive,
 # and unambiguous abbreviations work: 'timp,dist' = timpani + distorted
-# electric guitar
+# electric guitar. Every other instrument's tokens are masked out during
+# generation, so nothing else can appear in the output.
 muscriptor transcribe audio.wav --instruments acoustic_piano,drums
 
 # Get the event stream instead of MIDI: json (single array) or
@@ -218,6 +285,13 @@ muscriptor transcribe audio.wav --format jsonl -o -
 muscriptor transcribe audio.wav --sampling -t 0.8
 muscriptor transcribe audio.wav --beam-size 4
 
+# Notes sustained across a chunk boundary are teacher-forced into the next
+# chunk's prologue by default, so a chunk can't restart them with the wrong
+# instrument. This needs chunks generated in order, so the batch size
+# defaults to 1; batching (faster on GPU, lower quality at chunk boundaries)
+# must be opted into explicitly:
+muscriptor transcribe audio.wav --no-prelude-forcing --batch-size 4
+
 # Render a stereo check-mix of the result (left channel = original audio,
 # right channel = synthesized MIDI; requires fluidsynth on PATH)
 muscriptor transcribe audio.wav -o out.mid --auralize check.wav

muscriptor-0.3.0/muscriptor/accelerator.py

@@ -0,0 +1,69 @@
+"""Device-agnostic accelerator helpers.
+
+``torch.accelerator`` (``is_available``/``current_accelerator``/``synchronize``)
+was only added in PyTorch 2.6; on older versions we fall back to checking CUDA
+then MPS directly, in that order.
+"""
+
+import platform
+
+from packaging.version import Version
+
+import torch
+
+_HAS_TORCH_ACCELERATOR = Version(torch.__version__.split("+")[0]) >= Version("2.6")
+
+
+def _mps_available() -> bool:
+    """Whether MPS is available and worth auto-selecting.
+
+    torch <= 2.2 also reports MPS as available on Intel Macs with AMD GPUs, a
+    backend that was never solid and has since been abandoned. Passing
+    ``device="mps"`` explicitly still works there for those who want to try
+    it; this only affects auto-detection.
+    """
+    return torch.backends.mps.is_available() and platform.machine() == "arm64"
+
+
+def is_available() -> bool:
+    """Whether an accelerator (GPU) is available."""
+    if _HAS_TORCH_ACCELERATOR:
+        return torch.accelerator.is_available()
+    return torch.cuda.is_available() or _mps_available()
+
+
+def current_accelerator() -> torch.device:
+    """The current accelerator device.
+
+    Raises ``RuntimeError`` if no accelerator is available; check
+    :func:`is_available` first.
+    """
+    if _HAS_TORCH_ACCELERATOR:
+        return torch.accelerator.current_accelerator()
+    if torch.cuda.is_available():
+        return torch.device("cuda")
+    if _mps_available():
+        return torch.device("mps")
+    raise RuntimeError("No available accelerator detected.")
+
+
+def synchronize() -> None:
+    """Wait for all kernels on the current accelerator to complete.
+
+    No-op if no accelerator is available.
+    """
+    if _HAS_TORCH_ACCELERATOR:
+        # 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()
+    elif _mps_available():
+        torch.mps.synchronize()