muscriptor 0.1.0__tar.gz → 0.2.1__tar.gz

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

@@ -7,9 +7,9 @@
 *.mid
 .venv
 web/node_modules
-web/dist
-# Regenerated inside the web-builder stage from MuseScore_General.sf2.
-web/public/soundfonts
+# Built fresh in the web-builder stage; a stale local build must not leak
+# into the runtime image via `COPY muscriptor/`.
+muscriptor/web_dist
 .git
 .gitignore
 __pycache__

{muscriptor-0.1.0 → muscriptor-0.2.1}/.github/workflows/pypi.yml

@@ -15,6 +15,15 @@ jobs:
     - uses: actions/checkout@v2
     - name: Install uv
       uses: astral-sh/setup-uv@v7
+    - uses: actions/setup-node@v4
+      with:
+        node-version: 22
+    - name: Build frontend into muscriptor/web_dist
+      run: |
+        corepack enable
+        pnpm install --frozen-lockfile
+        pnpm run build
+      working-directory: web
     - name: Build wheels
       run: uv build
     - name: Publish package distributions to PyPI

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

@@ -7,8 +7,7 @@
 *.ogg
 *.sf2
 web/node_modules
-web/dist
-web/public/soundfonts/
+muscriptor/web_dist/
 web/tsconfig.tsbuildinfo
 /dist
 *.egg-info

{muscriptor-0.1.0 → muscriptor-0.2.1}/Dockerfile

@@ -8,14 +8,8 @@ RUN corepack enable
 COPY web/package.json web/pnpm-lock.yaml ./
 RUN pnpm install --frozen-lockfile
 
-# Download the soundfonts: the .sf3 the frontend streams from /soundfonts/,
-# and the .sf2 for /auralize (to /MuseScore_General.sf2, one level above the
-# package root — the runtime stage copies it from here). Runs in its own
-# layer so day-to-day source changes don't re-trigger the 253 MB download.
-COPY web/scripts/prepare-soundfonts.mjs scripts/
-RUN node scripts/prepare-soundfonts.mjs
-
 COPY web/ ./
+# vite outDir is ../muscriptor/web_dist, i.e. /muscriptor/web_dist in this stage.
 RUN pnpm run build
 
 
@@ -38,15 +32,24 @@ RUN --mount=type=cache,target=/root/.cache/uv \
     --mount=type=bind,source=uv.lock,target=uv.lock \
     uv sync --no-install-project
 
+# Pre-fetch the soundfonts (253 MB: .sf2 for /auralize, .sf3 for the web UI)
+# into the HF hub cache so a fresh container doesn't download them on first
+# use. Runs off just the two files it needs, before the full source COPY,
+# so day-to-day code changes don't re-trigger the download.
+COPY muscriptor/soundfonts.py muscriptor/utils/download.py /tmp/prewarm/
+RUN /app/.venv/bin/python -c "\
+import sys; sys.path.insert(0, '/tmp/prewarm'); \
+import soundfonts, download; \
+download.download_if_necessary(soundfonts.SF2_URL); \
+download.download_if_necessary(soundfonts.SF3_URL)" \
+    && rm -rf /tmp/prewarm
+
 COPY pyproject.toml uv.lock README.md ./
-# SoundFont for auralization; auralize() defaults to <repo-root>/MuseScore_General.sf2.
-# Reuse the copy the web-builder stage downloaded — no need for it in the context.
-COPY --from=web-builder /MuseScore_General.sf2 ./
 COPY muscriptor/ ./muscriptor/
 RUN --mount=type=cache,target=/root/.cache/uv \
     uv sync
 
-COPY --from=web-builder /web/dist ./web/dist
+COPY --from=web-builder /muscriptor/web_dist ./muscriptor/web_dist
 
 
 EXPOSE 8000

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: muscriptor
-Version: 0.1.0
+Version: 0.2.1
 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
@@ -27,7 +27,7 @@ Requires-Dist: numpy>=1.24
 Requires-Dist: python-multipart>=0.0.29
 Requires-Dist: safetensors>=0.4
 Requires-Dist: soundfile>=0.14.0
-Requires-Dist: torch<2.7,>=2.0
+Requires-Dist: torch>=2.0
 Requires-Dist: typer>=0.10
 Requires-Dist: uvicorn[standard]>=0.48.0
 Description-Content-Type: text/markdown
@@ -41,7 +41,7 @@ Description-Content-Type: text/markdown
 MuScriptor is a multi-instrument music transcription model developed by [Kyutai](https://kyutai.org) and [Mirelo](https://www.mirelo.ai).
 MuScriptor is the first music transcription model that has been trained on a large scale dataset of 170k songs from classical music to heavy metal.
 
-[Online Demo](https://muscriptor.kyutai.org) | [Paper] (coming soon) | [HuggingFace](https://huggingface.co/MuScriptor)
+[Online Demo](https://muscriptor.kyutai.org) | [Paper](https://arxiv.org/abs/2607.08168v1) | [HuggingFace](https://huggingface.co/MuScriptor)
 
 <!-- TODO: record the demo GIF (web UI piano roll), save it as assets/demo.gif,
      then uncomment:
@@ -276,11 +276,15 @@ uv sync
 cd web && pnpm install && pnpm run build && cd ..
 ```
 
-`pnpm run build` is required once — the FastAPI server auto-mounts
-`web/dist/` if it exists. The first build downloads two soundfonts:
-`MuseScore_General.sf2` (215 MB, to the repo root, used by `/auralize`) and
-`MuseScore_General.sf3` (38 MB, the compressed build the UI plays); later
-builds skip files already on disk.
+`pnpm run build` is required once — it outputs to `muscriptor/web_dist/`,
+which the FastAPI server auto-mounts if it exists (and which ships inside
+the PyPI wheel, so `uvx muscriptor serve` works without a checkout).
+
+The soundfonts are not bundled: the server fetches
+`MuseScore_General.sf2` (215 MB, used by `/auralize`) and
+`MuseScore_General.sf3` (38 MB, the compressed build the UI plays) from
+[MuScriptor/assets](https://huggingface.co/MuScriptor/assets) on first use
+and caches them locally (see `muscriptor/soundfonts.py`).
 
 ### Run
 
@@ -305,8 +309,8 @@ a WAV onto the page.
   is local-only.
 - Playback runs a full SoundFont synthesizer ([SpessaSynth](https://github.com/spessasus/spessasynth_lib))
   in the browser, fed with `MuseScore_General.sf3` — the same soundfont the
-  `/auralize` endpoint uses, served by the app itself from `/soundfonts/`,
-  no third-party CDN.
+  `/auralize` endpoint uses, served by the app itself from `/soundfonts/`
+  (cached server-side), no third-party CDN.
 
 ## License
 
@@ -322,15 +326,14 @@ distributed under its own (MIT) license.
 
 ## Citation
 
-<!-- TODO: fill in the BibTeX entry when the paper is out:
 ```bibtex
-@techreport{muscriptor2026,
-  title  = {MuScriptor: ...},
-  author = {...},
-  year   = {2026},
-  url    = {...},
+@misc{rouard2026muscriptoropenmodelmultiinstrument,
+      title={MuScriptor: An Open Model for Multi-Instrument Music Transcription}, 
+      author={Simon Rouard and Michael Krause and Axel Roebel and Carl-Johann Simon-Gabriel and Alexandre Défossez},
+      year={2026},
+      eprint={2607.08168},
+      archivePrefix={arXiv},
+      primaryClass={cs.SD},
+      url={https://arxiv.org/abs/2607.08168}, 
 }
 ```
--->
-
-The paper is coming soon — a citation entry will be added here with it.

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

@@ -7,7 +7,7 @@
 MuScriptor is a multi-instrument music transcription model developed by [Kyutai](https://kyutai.org) and [Mirelo](https://www.mirelo.ai).
 MuScriptor is the first music transcription model that has been trained on a large scale dataset of 170k songs from classical music to heavy metal.
 
-[Online Demo](https://muscriptor.kyutai.org) | [Paper] (coming soon) | [HuggingFace](https://huggingface.co/MuScriptor)
+[Online Demo](https://muscriptor.kyutai.org) | [Paper](https://arxiv.org/abs/2607.08168v1) | [HuggingFace](https://huggingface.co/MuScriptor)
 
 <!-- TODO: record the demo GIF (web UI piano roll), save it as assets/demo.gif,
      then uncomment:
@@ -242,11 +242,15 @@ uv sync
 cd web && pnpm install && pnpm run build && cd ..
 ```
 
-`pnpm run build` is required once — the FastAPI server auto-mounts
-`web/dist/` if it exists. The first build downloads two soundfonts:
-`MuseScore_General.sf2` (215 MB, to the repo root, used by `/auralize`) and
-`MuseScore_General.sf3` (38 MB, the compressed build the UI plays); later
-builds skip files already on disk.
+`pnpm run build` is required once — it outputs to `muscriptor/web_dist/`,
+which the FastAPI server auto-mounts if it exists (and which ships inside
+the PyPI wheel, so `uvx muscriptor serve` works without a checkout).
+
+The soundfonts are not bundled: the server fetches
+`MuseScore_General.sf2` (215 MB, used by `/auralize`) and
+`MuseScore_General.sf3` (38 MB, the compressed build the UI plays) from
+[MuScriptor/assets](https://huggingface.co/MuScriptor/assets) on first use
+and caches them locally (see `muscriptor/soundfonts.py`).
 
 ### Run
 
@@ -271,8 +275,8 @@ a WAV onto the page.
   is local-only.
 - Playback runs a full SoundFont synthesizer ([SpessaSynth](https://github.com/spessasus/spessasynth_lib))
   in the browser, fed with `MuseScore_General.sf3` — the same soundfont the
-  `/auralize` endpoint uses, served by the app itself from `/soundfonts/`,
-  no third-party CDN.
+  `/auralize` endpoint uses, served by the app itself from `/soundfonts/`
+  (cached server-side), no third-party CDN.
 
 ## License
 
@@ -288,15 +292,14 @@ distributed under its own (MIT) license.
 
 ## Citation
 
-<!-- TODO: fill in the BibTeX entry when the paper is out:
 ```bibtex
-@techreport{muscriptor2026,
-  title  = {MuScriptor: ...},
-  author = {...},
-  year   = {2026},
-  url    = {...},
+@misc{rouard2026muscriptoropenmodelmultiinstrument,
+      title={MuScriptor: An Open Model for Multi-Instrument Music Transcription}, 
+      author={Simon Rouard and Michael Krause and Axel Roebel and Carl-Johann Simon-Gabriel and Alexandre Défossez},
+      year={2026},
+      eprint={2607.08168},
+      archivePrefix={arXiv},
+      primaryClass={cs.SD},
+      url={https://arxiv.org/abs/2607.08168}, 
 }
 ```
--->
-
-The paper is coming soon — a citation entry will be added here with it.

{muscriptor-0.1.0 → muscriptor-0.2.1}/muscriptor/main.py

@@ -137,8 +137,8 @@ def transcribe(
         typer.Option(
             "--soundfont",
             help=(
-                "Path to a .sf2 SoundFont for auralization. "
-                "Defaults to the bundled MuseScore_General.sf2."
+                "Path to a .sf2 SoundFont for auralization. Defaults to "
+                "MuseScore_General.sf2, downloaded once and cached locally."
             ),
         ),
     ] = None,
@@ -307,7 +307,7 @@ def serve(
     _device = None if device == "auto" else device
     typer.echo("Loading model…")
     model = TranscriptionModel.load_model(weights_path=model_path, device=_device)
-    web_dir = Path(__file__).resolve().parent.parent / "web" / "dist"
+    web_dir = Path(__file__).resolve().parent / "web_dist"
     fastapi_app = create_app(model, web_dir=web_dir if web_dir.is_dir() else None)
     uvicorn.run(fastapi_app, host=host, port=port)
 

{muscriptor-0.1.0 → muscriptor-0.2.1}/muscriptor/server.py

@@ -22,14 +22,16 @@ from pathlib import Path
 from typing import Annotated
 
 from fastapi import FastAPI, File, Form, HTTPException, UploadFile
-from fastapi.responses import Response, StreamingResponse
+from fastapi.responses import FileResponse, Response, StreamingResponse
 from fastapi.staticfiles import StaticFiles
 from starlette.background import BackgroundTask
 
 from muscriptor.events import NoteEndEvent, NoteStartEvent, ProgressEvent
+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.download import download_if_necessary
 
 
 def _make_release_once(lock: threading.Lock):
@@ -85,6 +87,16 @@ def create_app(model: TranscriptionModel, web_dir: str | Path | None = None) ->
     async def list_instruments():
         return {"instruments": list(MT3_FULL_PLUS_GROUP_NAMES.keys())}
 
+    @app.get("/soundfonts/MuseScore_General.sf3")
+    async def soundfont() -> FileResponse:
+        """Compressed soundfont for the web UI's in-browser synthesizer.
+
+        Fetched from SF3_URL on first request (in a worker thread, so the
+        event loop keeps serving) and cached locally.
+        """
+        path = await asyncio.to_thread(download_if_necessary, SF3_URL)
+        return FileResponse(path, media_type="application/octet-stream")
+
     @app.post("/transcribe")
     async def transcribe(
         file: Annotated[UploadFile, File()],

muscriptor-0.2.1/muscriptor/soundfonts.py

@@ -0,0 +1,19 @@
+"""Runtime sources for the MuseScore General soundfonts.
+
+Neither file ships in the package: both are fetched lazily through
+:func:`muscriptor.utils.download.download_if_necessary` and cached locally
+(``hf://`` URLs land in the HuggingFace hub cache). The upstream origin is
+MuseScore's distribution mirror,
+https://ftp.osuosl.org/pub/musescore/soundfont/MuseScore_General/, re-hosted
+at https://huggingface.co/MuScriptor/assets (MIT license).
+"""
+
+# Full soundfont (215 MB), rendered server-side by fluidsynth — the
+# /auralize endpoint and the CLI's --auralize flag.
+# SHA-256: ee51d2c4b1525e70f19a45909c4fd7a2e26d91d115fa89dbf5a6bc413d8b9bf3
+SF2_URL = "hf://MuScriptor/assets/MuseScore_General.sf2"
+
+# Vorbis-compressed build (38 MB) of the same soundfont, served to the web
+# UI's in-browser spessasynth_lib synthesizer (GET /soundfonts/…).
+# SHA-256: 5b85b6c2c61d10b2b91cddd41efcce7b25cd31c8271d511c73afafbef20b6fa3
+SF3_URL = "hf://MuScriptor/assets/MuseScore_General.sf3"

{muscriptor-0.1.0 → muscriptor-0.2.1}/muscriptor/utils/auralization.py

@@ -16,9 +16,14 @@ from pathlib import Path
 import numpy as np
 import soundfile as sf
 
+from muscriptor.soundfonts import SF2_URL
 from muscriptor.utils.audio import load_audio
+from muscriptor.utils.download import download_if_necessary
 
-_DEFAULT_SOUNDFONT = Path(__file__).parent.parent.parent / "MuseScore_General.sf2"
+# Pre-downloaded copy at the repo root (kept for checkouts and Docker images
+# that already have one); absent that, the soundfont is fetched from SF2_URL
+# and cached under ~/.cache/muscriptor/.
+_LOCAL_SOUNDFONT = Path(__file__).parent.parent.parent / "MuseScore_General.sf2"
 _SAMPLE_RATE = 44100
 
 
@@ -29,12 +34,16 @@ def _load_mono_44k(path: Path) -> np.ndarray:
 
 
 def _resolve_soundfont(soundfont_path: str | Path | None) -> Path:
-    soundfont_path = Path(soundfont_path) if soundfont_path else _DEFAULT_SOUNDFONT
+    if soundfont_path is None:
+        if _LOCAL_SOUNDFONT.exists():
+            return _LOCAL_SOUNDFONT
+        return download_if_necessary(SF2_URL)
+    soundfont_path = Path(soundfont_path)
     if not soundfont_path.exists():
         raise FileNotFoundError(
             f"SoundFont not found: {soundfont_path}\n"
-            "Pass --soundfont /path/to/file.sf2 or ensure the bundled "
-            "MuseScore_General.sf2 is present in the muscriptor project root."
+            "Pass --soundfont /path/to/file.sf2, or omit it to use "
+            "MuseScore_General.sf2 (downloaded once and cached)."
         )
     return soundfont_path
 
@@ -85,8 +94,9 @@ def synthesize(
     Args:
         midi_path: Path to the MIDI file to synthesize.
         output_path: Destination WAV file path.
-        soundfont_path: Path to a ``.sf2`` SoundFont file.
-            Defaults to the bundled MuseScore_General.sf2.
+        soundfont_path: Path to a ``.sf2`` SoundFont file.  Defaults to
+            MuseScore_General.sf2, downloaded on first use and cached
+            locally (see :mod:`muscriptor.soundfonts`).
 
     Raises:
         RuntimeError: If fluidsynth is not available or fails.
@@ -112,8 +122,9 @@ def auralize(
         midi_path: Path to the MIDI file to synthesize.
         original_audio_path: Path to the source audio file (any format soundfile supports).
         output_path: Destination WAV file path.
-        soundfont_path: Path to a ``.sf2`` SoundFont file.
-            Defaults to the bundled MuseScore_General.sf2.
+        soundfont_path: Path to a ``.sf2`` SoundFont file.  Defaults to
+            MuseScore_General.sf2, downloaded on first use and cached
+            locally (see :mod:`muscriptor.soundfonts`).
 
     Raises:
         RuntimeError: If fluidsynth is not available or fails.

{muscriptor-0.1.0 → muscriptor-0.2.1}/muscriptor/utils/download.py

@@ -1,6 +1,7 @@
 """Weight download utility with caching in ~/.cache/muscriptor/."""
 
 import hashlib
+import os
 import urllib.request
 from pathlib import Path
 from huggingface_hub import hf_hub_download
@@ -40,7 +41,15 @@ def download_if_necessary(url: str | Path) -> Path:
         if dest.exists():
             return dest
         print(f"Downloading {filename} …")
-        urllib.request.urlretrieve(url, dest)
+        # Download to a per-process temp file, then rename: an interrupted or
+        # concurrent download must never leave a partial file at `dest`, where
+        # it would be mistaken for a complete one forever after.
+        tmp = dest.with_name(f"{dest.name}.part{os.getpid()}")
+        try:
+            urllib.request.urlretrieve(url, tmp)
+            os.replace(tmp, dest)
+        finally:
+            tmp.unlink(missing_ok=True)
         return dest
 
     # Local file — nothing to download, just check it's there.