Duplicate from m-a-p/SheetSage2

Co-authored-by: Ruibin Yuan <a43992899@users.noreply.huggingface.co>

.gitattributes

@@ -0,0 +1,3 @@
+*.safetensors filter=lfs diff=lfs merge=lfs -text
+*.png filter=lfs diff=lfs merge=lfs -text
+*.ttf filter=lfs diff=lfs merge=lfs -text

LICENSE

@@ -0,0 +1,424 @@
+MERT2 model-weight license
+
+The MERT2-30s and MERT2-FS checkpoint weights in model.safetensors are
+licensed under Creative Commons Attribution-NonCommercial 4.0 International
+(CC BY-NC 4.0): https://creativecommons.org/licenses/by-nc/4.0/
+
+For attribution, identify MERT2, the model name, and its source repository:
+https://huggingface.co/m-a-p/MERT-v2-30s
+https://huggingface.co/m-a-p/MERT-v2-FullSong
+
+This weight license does not replace separately applicable licenses for code
+or dependencies. See THIRD_PARTY_NOTICES.md.
+
+The official license text follows without modification.
+Source: https://creativecommons.org/licenses/by-nc/4.0/legalcode.txt
+
+Attribution-NonCommercial 4.0 International
+
+=======================================================================
+
+Creative Commons Corporation ("Creative Commons") is not a law firm and
+does not provide legal services or legal advice. Distribution of
+Creative Commons public licenses does not create a lawyer-client or
+other relationship. Creative Commons makes its licenses and related
+information available on an "as-is" basis. Creative Commons gives no
+warranties regarding its licenses, any material licensed under their
+terms and conditions, or any related information. Creative Commons
+disclaims all liability for damages resulting from their use to the
+fullest extent possible.
+
+Using Creative Commons Public Licenses
+
+Creative Commons public licenses provide a standard set of terms and
+conditions that creators and other rights holders may use to share
+original works of authorship and other material subject to copyright
+and certain other rights specified in the public license below. The
+following considerations are for informational purposes only, are not
+exhaustive, and do not form part of our licenses.
+
+     Considerations for licensors: Our public licenses are
+     intended for use by those authorized to give the public
+     permission to use material in ways otherwise restricted by
+     copyright and certain other rights. Our licenses are
+     irrevocable. Licensors should read and understand the terms
+     and conditions of the license they choose before applying it.
+     Licensors should also secure all rights necessary before
+     applying our licenses so that the public can reuse the
+     material as expected. Licensors should clearly mark any
+     material not subject to the license. This includes other CC-
+     licensed material, or material used under an exception or
+     limitation to copyright. More considerations for licensors:
+    wiki.creativecommons.org/Considerations_for_licensors
+
+     Considerations for the public: By using one of our public
+     licenses, a licensor grants the public permission to use the
+     licensed material under specified terms and conditions. If
+     the licensor's permission is not necessary for any reason--for
+     example, because of any applicable exception or limitation to
+     copyright--then that use is not regulated by the license. Our
+     licenses grant only permissions under copyright and certain
+     other rights that a licensor has authority to grant. Use of
+     the licensed material may still be restricted for other
+     reasons, including because others have copyright or other
+     rights in the material. A licensor may make special requests,
+     such as asking that all changes be marked or described.
+     Although not required by our licenses, you are encouraged to
+     respect those requests where reasonable. More considerations
+     for the public:
+    wiki.creativecommons.org/Considerations_for_licensees
+
+=======================================================================
+
+Creative Commons Attribution-NonCommercial 4.0 International Public
+License
+
+By exercising the Licensed Rights (defined below), You accept and agree
+to be bound by the terms and conditions of this Creative Commons
+Attribution-NonCommercial 4.0 International Public License ("Public
+License"). To the extent this Public License may be interpreted as a
+contract, You are granted the Licensed Rights in consideration of Your
+acceptance of these terms and conditions, and the Licensor grants You
+such rights in consideration of benefits the Licensor receives from
+making the Licensed Material available under these terms and
+conditions.
+
+
+Section 1 -- Definitions.
+
+  a. Adapted Material means material subject to Copyright and Similar
+     Rights that is derived from or based upon the Licensed Material
+     and in which the Licensed Material is translated, altered,
+     arranged, transformed, or otherwise modified in a manner requiring
+     permission under the Copyright and Similar Rights held by the
+     Licensor. For purposes of this Public License, where the Licensed
+     Material is a musical work, performance, or sound recording,
+     Adapted Material is always produced where the Licensed Material is
+     synched in timed relation with a moving image.
+
+  b. Adapter's License means the license You apply to Your Copyright
+     and Similar Rights in Your contributions to Adapted Material in
+     accordance with the terms and conditions of this Public License.
+
+  c. Copyright and Similar Rights means copyright and/or similar rights
+     closely related to copyright including, without limitation,
+     performance, broadcast, sound recording, and Sui Generis Database
+     Rights, without regard to how the rights are labeled or
+     categorized. For purposes of this Public License, the rights
+     specified in Section 2(b)(1)-(2) are not Copyright and Similar
+     Rights.
+  d. Effective Technological Measures means those measures that, in the
+     absence of proper authority, may not be circumvented under laws
+     fulfilling obligations under Article 11 of the WIPO Copyright
+     Treaty adopted on December 20, 1996, and/or similar international
+     agreements.
+
+  e. Exceptions and Limitations means fair use, fair dealing, and/or
+     any other exception or limitation to Copyright and Similar Rights
+     that applies to Your use of the Licensed Material.
+
+  f. Licensed Material means the artistic or literary work, database,
+     or other material to which the Licensor applied this Public
+     License.
+
+  g. Licensed Rights means the rights granted to You subject to the
+     terms and conditions of this Public License, which are limited to
+     all Copyright and Similar Rights that apply to Your use of the
+     Licensed Material and that the Licensor has authority to license.
+
+  h. Licensor means the individual(s) or entity(ies) granting rights
+     under this Public License.
+
+  i. NonCommercial means not primarily intended for or directed towards
+     commercial advantage or monetary compensation. For purposes of
+     this Public License, the exchange of the Licensed Material for
+     other material subject to Copyright and Similar Rights by digital
+     file-sharing or similar means is NonCommercial provided there is
+     no payment of monetary compensation in connection with the
+     exchange.
+
+  j. Share means to provide material to the public by any means or
+     process that requires permission under the Licensed Rights, such
+     as reproduction, public display, public performance, distribution,
+     dissemination, communication, or importation, and to make material
+     available to the public including in ways that members of the
+     public may access the material from a place and at a time
+     individually chosen by them.
+
+  k. Sui Generis Database Rights means rights other than copyright
+     resulting from Directive 96/9/EC of the European Parliament and of
+     the Council of 11 March 1996 on the legal protection of databases,
+     as amended and/or succeeded, as well as other essentially
+     equivalent rights anywhere in the world.
+
+  l. You means the individual or entity exercising the Licensed Rights
+     under this Public License. Your has a corresponding meaning.
+
+
+Section 2 -- Scope.
+
+  a. License grant.
+
+       1. Subject to the terms and conditions of this Public License,
+          the Licensor hereby grants You a worldwide, royalty-free,
+          non-sublicensable, non-exclusive, irrevocable license to
+          exercise the Licensed Rights in the Licensed Material to:
+
+            a. reproduce and Share the Licensed Material, in whole or
+               in part, for NonCommercial purposes only; and
+
+            b. produce, reproduce, and Share Adapted Material for
+               NonCommercial purposes only.
+
+       2. Exceptions and Limitations. For the avoidance of doubt, where
+          Exceptions and Limitations apply to Your use, this Public
+          License does not apply, and You do not need to comply with
+          its terms and conditions.
+
+       3. Term. The term of this Public License is specified in Section
+          6(a).
+
+       4. Media and formats; technical modifications allowed. The
+          Licensor authorizes You to exercise the Licensed Rights in
+          all media and formats whether now known or hereafter created,
+          and to make technical modifications necessary to do so. The
+          Licensor waives and/or agrees not to assert any right or
+          authority to forbid You from making technical modifications
+          necessary to exercise the Licensed Rights, including
+          technical modifications necessary to circumvent Effective
+          Technological Measures. For purposes of this Public License,
+          simply making modifications authorized by this Section 2(a)
+          (4) never produces Adapted Material.
+
+       5. Downstream recipients.
+
+            a. Offer from the Licensor -- Licensed Material. Every
+               recipient of the Licensed Material automatically
+               receives an offer from the Licensor to exercise the
+               Licensed Rights under the terms and conditions of this
+               Public License.
+
+            b. No downstream restrictions. You may not offer or impose
+               any additional or different terms or conditions on, or
+               apply any Effective Technological Measures to, the
+               Licensed Material if doing so restricts exercise of the
+               Licensed Rights by any recipient of the Licensed
+               Material.
+
+       6. No endorsement. Nothing in this Public License constitutes or
+          may be construed as permission to assert or imply that You
+          are, or that Your use of the Licensed Material is, connected
+          with, or sponsored, endorsed, or granted official status by,
+          the Licensor or others designated to receive attribution as
+          provided in Section 3(a)(1)(A)(i).
+
+  b. Other rights.
+
+       1. Moral rights, such as the right of integrity, are not
+          licensed under this Public License, nor are publicity,
+          privacy, and/or other similar personality rights; however, to
+          the extent possible, the Licensor waives and/or agrees not to
+          assert any such rights held by the Licensor to the limited
+          extent necessary to allow You to exercise the Licensed
+          Rights, but not otherwise.
+
+       2. Patent and trademark rights are not licensed under this
+          Public License.
+
+       3. To the extent possible, the Licensor waives any right to
+          collect royalties from You for the exercise of the Licensed
+          Rights, whether directly or through a collecting society
+          under any voluntary or waivable statutory or compulsory
+          licensing scheme. In all other cases the Licensor expressly
+          reserves any right to collect such royalties, including when
+          the Licensed Material is used other than for NonCommercial
+          purposes.
+
+
+Section 3 -- License Conditions.
+
+Your exercise of the Licensed Rights is expressly made subject to the
+following conditions.
+
+  a. Attribution.
+
+       1. If You Share the Licensed Material (including in modified
+          form), You must:
+
+            a. retain the following if it is supplied by the Licensor
+               with the Licensed Material:
+
+                 i. identification of the creator(s) of the Licensed
+                    Material and any others designated to receive
+                    attribution, in any reasonable manner requested by
+                    the Licensor (including by pseudonym if
+                    designated);
+
+                ii. a copyright notice;
+
+               iii. a notice that refers to this Public License;
+
+                iv. a notice that refers to the disclaimer of
+                    warranties;
+
+                 v. a URI or hyperlink to the Licensed Material to the
+                    extent reasonably practicable;
+
+            b. indicate if You modified the Licensed Material and
+               retain an indication of any previous modifications; and
+
+            c. indicate the Licensed Material is licensed under this
+               Public License, and include the text of, or the URI or
+               hyperlink to, this Public License.
+
+       2. You may satisfy the conditions in Section 3(a)(1) in any
+          reasonable manner based on the medium, means, and context in
+          which You Share the Licensed Material. For example, it may be
+          reasonable to satisfy the conditions by providing a URI or
+          hyperlink to a resource that includes the required
+          information.
+
+       3. If requested by the Licensor, You must remove any of the
+          information required by Section 3(a)(1)(A) to the extent
+          reasonably practicable.
+
+       4. If You Share Adapted Material You produce, the Adapter's
+          License You apply must not prevent recipients of the Adapted
+          Material from complying with this Public License.
+
+
+Section 4 -- Sui Generis Database Rights.
+
+Where the Licensed Rights include Sui Generis Database Rights that
+apply to Your use of the Licensed Material:
+
+  a. for the avoidance of doubt, Section 2(a)(1) grants You the right
+     to extract, reuse, reproduce, and Share all or a substantial
+     portion of the contents of the database for NonCommercial purposes
+     only;
+
+  b. if You include all or a substantial portion of the database
+     contents in a database in which You have Sui Generis Database
+     Rights, then the database in which You have Sui Generis Database
+     Rights (but not its individual contents) is Adapted Material; and
+
+  c. You must comply with the conditions in Section 3(a) if You Share
+     all or a substantial portion of the contents of the database.
+
+For the avoidance of doubt, this Section 4 supplements and does not
+replace Your obligations under this Public License where the Licensed
+Rights include other Copyright and Similar Rights.
+
+
+Section 5 -- Disclaimer of Warranties and Limitation of Liability.
+
+  a. UNLESS OTHERWISE SEPARATELY UNDERTAKEN BY THE LICENSOR, TO THE
+     EXTENT POSSIBLE, THE LICENSOR OFFERS THE LICENSED MATERIAL AS-IS
+     AND AS-AVAILABLE, AND MAKES NO REPRESENTATIONS OR WARRANTIES OF
+     ANY KIND CONCERNING THE LICENSED MATERIAL, WHETHER EXPRESS,
+     IMPLIED, STATUTORY, OR OTHER. THIS INCLUDES, WITHOUT LIMITATION,
+     WARRANTIES OF TITLE, MERCHANTABILITY, FITNESS FOR A PARTICULAR
+     PURPOSE, NON-INFRINGEMENT, ABSENCE OF LATENT OR OTHER DEFECTS,
+     ACCURACY, OR THE PRESENCE OR ABSENCE OF ERRORS, WHETHER OR NOT
+     KNOWN OR DISCOVERABLE. WHERE DISCLAIMERS OF WARRANTIES ARE NOT
+     ALLOWED IN FULL OR IN PART, THIS DISCLAIMER MAY NOT APPLY TO YOU.
+
+  b. TO THE EXTENT POSSIBLE, IN NO EVENT WILL THE LICENSOR BE LIABLE
+     TO YOU ON ANY LEGAL THEORY (INCLUDING, WITHOUT LIMITATION,
+     NEGLIGENCE) OR OTHERWISE FOR ANY DIRECT, SPECIAL, INDIRECT,
+     INCIDENTAL, CONSEQUENTIAL, PUNITIVE, EXEMPLARY, OR OTHER LOSSES,
+     COSTS, EXPENSES, OR DAMAGES ARISING OUT OF THIS PUBLIC LICENSE OR
+     USE OF THE LICENSED MATERIAL, EVEN IF THE LICENSOR HAS BEEN
+     ADVISED OF THE POSSIBILITY OF SUCH LOSSES, COSTS, EXPENSES, OR
+     DAMAGES. WHERE A LIMITATION OF LIABILITY IS NOT ALLOWED IN FULL OR
+     IN PART, THIS LIMITATION MAY NOT APPLY TO YOU.
+
+  c. The disclaimer of warranties and limitation of liability provided
+     above shall be interpreted in a manner that, to the extent
+     possible, most closely approximates an absolute disclaimer and
+     waiver of all liability.
+
+
+Section 6 -- Term and Termination.
+
+  a. This Public License applies for the term of the Copyright and
+     Similar Rights licensed here. However, if You fail to comply with
+     this Public License, then Your rights under this Public License
+     terminate automatically.
+
+  b. Where Your right to use the Licensed Material has terminated under
+     Section 6(a), it reinstates:
+
+       1. automatically as of the date the violation is cured, provided
+          it is cured within 30 days of Your discovery of the
+          violation; or
+
+       2. upon express reinstatement by the Licensor.
+
+     For the avoidance of doubt, this Section 6(b) does not affect any
+     right the Licensor may have to seek remedies for Your violations
+     of this Public License.
+
+  c. For the avoidance of doubt, the Licensor may also offer the
+     Licensed Material under separate terms or conditions or stop
+     distributing the Licensed Material at any time; however, doing so
+     will not terminate this Public License.
+
+  d. Sections 1, 5, 6, 7, and 8 survive termination of this Public
+     License.
+
+
+Section 7 -- Other Terms and Conditions.
+
+  a. The Licensor shall not be bound by any additional or different
+     terms or conditions communicated by You unless expressly agreed.
+
+  b. Any arrangements, understandings, or agreements regarding the
+     Licensed Material not stated herein are separate from and
+     independent of the terms and conditions of this Public License.
+
+
+Section 8 -- Interpretation.
+
+  a. For the avoidance of doubt, this Public License does not, and
+     shall not be interpreted to, reduce, limit, restrict, or impose
+     conditions on any use of the Licensed Material that could lawfully
+     be made without permission under this Public License.
+
+  b. To the extent possible, if any provision of this Public License is
+     deemed unenforceable, it shall be automatically reformed to the
+     minimum extent necessary to make it enforceable. If the provision
+     cannot be reformed, it shall be severed from this Public License
+     without affecting the enforceability of the remaining terms and
+     conditions.
+
+  c. No term or condition of this Public License will be waived and no
+     failure to comply consented to unless expressly agreed to by the
+     Licensor.
+
+  d. Nothing in this Public License constitutes or may be interpreted
+     as a limitation upon, or waiver of, any privileges and immunities
+     that apply to the Licensor or You, including from the legal
+     processes of any jurisdiction or authority.
+
+=======================================================================
+
+Creative Commons is not a party to its public
+licenses. Notwithstanding, Creative Commons may elect to apply one of
+its public licenses to material it publishes and in those instances
+will be considered the “Licensor.” The text of the Creative Commons
+public licenses is dedicated to the public domain under the CC0 Public
+Domain Dedication. Except for the limited purpose of indicating that
+material is shared under a Creative Commons public license or as
+otherwise permitted by the Creative Commons policies published at
+creativecommons.org/policies, Creative Commons does not authorize the
+use of the trademark "Creative Commons" or any other trademark or logo
+of Creative Commons without its prior written consent including,
+without limitation, in connection with any unauthorized modifications
+to any of its public licenses or any other arrangements,
+understandings, or agreements concerning use of licensed material. For
+the avoidance of doubt, this paragraph does not form part of the
+public licenses.
+
+Creative Commons may be contacted at creativecommons.org.
+

README.md

@@ -0,0 +1,201 @@
+---
+license: cc-by-nc-4.0
+library_name: transformers
+base_model: m-a-p/MERT-v2-FullSong
+base_model_relation: adapter
+tags:
+- audio
+- music
+- music-transcription
+- midi
+- abc-notation
+- custom_code
+---
+<h1 align="center">🤗 SheetSage2</h1>
+<p align="center"><strong>Music audio to editable scores</strong></p>
+<p align="center">Melody · Chords · Beats · Key · Structure</p>
+
+<p align="center">
+  <a href="https://map-yue2.github.io/">🎵&nbsp;YuE2&nbsp;project</a>
+  ·
+  <a href="#quick-start">🚀&nbsp;Quick&nbsp;start</a>
+  ·
+  <a href="#benchmarks">📊&nbsp;Benchmarks</a>
+  ·
+  <a href="#citation">📚&nbsp;Citation</a>
+</p>
+<p align="center">
+  <a href="https://huggingface.co/m-a-p/YuE2-3B"><img alt="🤗 YuE2-3B" src="https://img.shields.io/badge/YuE2--3B-374151?logo=huggingface&amp;logoColor=FFD21E" height="20" /></a>
+  &nbsp;
+  <a href="https://huggingface.co/m-a-p/YuE2-Vae"><img alt="🤗 YuE2-Vae" src="https://img.shields.io/badge/YuE2--Vae-374151?logo=huggingface&amp;logoColor=FFD21E" height="20" /></a>
+  &nbsp;
+  <a href="https://huggingface.co/m-a-p/YuE2-Vae-legacy"><img alt="🤗 YuE2-Vae-legacy" src="https://img.shields.io/badge/YuE2--Vae--legacy-374151?logo=huggingface&amp;logoColor=FFD21E" height="20" /></a>
+  &nbsp;
+  <a href="https://huggingface.co/m-a-p/MERT-v2-30s"><img alt="🤗 MERT-v2-30s" src="https://img.shields.io/badge/MERT--v2--30s-374151?logo=huggingface&amp;logoColor=FFD21E" height="20" /></a>
+  &nbsp;
+  <a href="https://huggingface.co/m-a-p/MERT-v2-FullSong"><img alt="🤗 MERT-v2-FullSong" src="https://img.shields.io/badge/MERT--v2--FullSong-374151?logo=huggingface&amp;logoColor=FFD21E" height="20" /></a>
+  &nbsp;
+  <a href="https://huggingface.co/datasets/m-a-p/WildSongBench"><img alt="🤗 WildSongBench" src="https://img.shields.io/badge/WildSongBench-374151?logo=huggingface&amp;logoColor=FFD21E" height="20" /></a>
+  &nbsp;
+  <a href="https://huggingface.co/m-a-p/SheetSage2"><img alt="SheetSage2" src="https://img.shields.io/badge/SheetSage2-374151?logo=huggingface&amp;logoColor=FFD21E" height="20" /></a>
+</p>
+
+**SheetSage2 turns music recordings into lead sheets and timed musical annotations.** Transcribe a complete song, edit its ABC or MIDI, render a piano preview, or extract embeddings and token predictions for your own tools.
+
+Built on [MERT-v2-FullSong](https://huggingface.co/m-a-p/MERT-v2-FullSong), with adapters that merge automatically when you load the model.
+
+![SheetSage2 architecture](assets/architecture.png)
+
+<a id="quick-start"></a>
+
+## 🚀 Quick start
+
+Use Python 3.10 or 3.11 and FFmpeg 6.1 with its shared libraries. Sign in with access to this repository and its MERT-v2 parent:
+
+```bash
+python -m pip install huggingface-hub==0.36.0
+huggingface-cli download m-a-p/SheetSage2 --local-dir SheetSage2
+cd SheetSage2
+python -m pip install torch==2.8.0 torchaudio==2.8.0 --index-url https://download.pytorch.org/whl/cu126
+python -m pip install -r requirements.txt
+```
+
+```python
+import torch
+from transformers import AutoModel
+
+model = AutoModel.from_pretrained(
+    "m-a-p/SheetSage2", trust_remote_code=True,
+).eval().to("cuda" if torch.cuda.is_available() else "cpu")
+
+result = model.transcribe("song.mp3", output_dir="output")
+```
+
+Files are decoded, mixed to mono and resampled automatically. Long songs use overlapping windows.
+
+| Output | File |
+|---|---|
+| Editable score | `score.abc` |
+| Melody and chord accompaniment | `transcription.mid` |
+| Separate melodies and chords | `melody_vocal.mid`, `melody_instrumental.mid`, `chords.mid` |
+| Timed annotations | `events.json`, `*.lab` |
+
+Omit `output_dir` to keep results in memory. Pass a Tensor or NumPy waveform with its sample rate:
+
+```python
+# waveform: [samples] or [channels, samples]
+result = model.transcribe(waveform, sampling_rate=24000)
+abc = result["abc"]        # str
+midi = result["midi"]      # bytes
+events = result["events"]  # list of timed events
+```
+
+Paths, encoded audio bytes and binary streams are also accepted. `result["midis"]` contains the separate MIDI parts; `result["labs"]` contains annotation text. Request `export_logits=True`, `export_scores=True` or `export_embeddings=True` for CPU tensors in `result["tensors"]`, grouped by window; add `output_hidden_states=True` for all 24 MERT layers. With `output_dir`, these tensors are saved as safetensors instead. Low-level `forward()` returns logits and optional hidden states; `generate()` returns symbolic tokens.
+
+Save a self-contained model for offline use:
+
+```python
+model.save_pretrained("sheetsage2-local")
+model = AutoModel.from_pretrained(
+    "sheetsage2-local", trust_remote_code=True, local_files_only=True,
+)
+```
+
+### Melody-only ABC for covers
+
+Set `melody_only=True` to retain both the `Vocal` and `Ins` melodies while omitting chord symbols from the ABC and chord accompaniment from playback/combined MIDI. Raw predicted annotations remain available; the default full transcription is unchanged.
+
+```python
+result = model.transcribe("song.mp3", output_dir="cover-score", melody_only=True)
+abc = result["abc"]  # Also saved as cover-score/score.abc.
+```
+
+```bash
+python infer.py song.mp3 --output cover-score --melody-only
+```
+
+Review the transcription, then pass `result["abc"]` or the saved `cover-score/score.abc` to [YuE2](https://huggingface.co/m-a-p/YuE2-3B) as `abc`, with `cot="melody"` and your target `style` and `lyrics`. If the requested ABC cannot be produced, Python raises an error (partial results are available as `error.result`) and the CLI exits with a nonzero status.
+
+### Command line and rendering
+
+```bash
+python infer.py song.mp3 --output output
+
+# Optional piano audio and printable sheet music:
+python setup_render.py
+python infer.py song.mp3 --output output --render-audio --render-score
+
+# Render existing results without loading the model:
+python render.py --input output --output rendered --audio --score pdf,svg,png
+```
+
+On minimal Linux servers, use `python setup_render.py --with-deps`. Audio follows the original MIDI timing. Scores preserve the vocal and instrumental staves. For separate piano previews, use `--render-parts vocal,instrumental,chords` with `infer.py`, or `--parts vocal,instrumental,chords` with `render.py`.
+
+Python also accepts `render_audio=True, render_score="pdf,svg,png"`. In memory mode, `result["rendered"]` contains `audio` (part → WAV bytes) and `score` (format → pages as PDF/PNG bytes or SVG text).
+
+<a id="benchmarks"></a>
+
+## 📊 Benchmarks
+
+Scores (%) on H800 with BF16 inference; higher is better. Use `preset="paper"` or `--preset paper` with the dataset prompts in [scores and settings](benchmark_results.json).
+
+| Task | Dataset | Metric | SheetSage1 | madmom | Specialist | SheetSage2 |
+|---|---|---|---:|---:|---:|---:|
+| Beat | GTZAN | F1 | 86.07 | 86.07 | **89.01** [Beat This!][beat] | 86.27 |
+| Beat | osu2017 | F1 | 91.80 | 91.80 | 89.19 [Beat This!][beat] | **93.01** |
+| Downbeat | GTZAN | F1 | 64.65 | 64.65 | 78.28 [Beat This!][beat] | **80.45** |
+| Downbeat | osu2017 | F1 | 83.47 | 83.47 | 85.90 [Beat This!][beat] | **92.90** |
+| Key | GiantSteps | Score | 43.89 | 74.62 | 72.09 [S-KEY][key] | **77.73** |
+| Key | GTZAN | Score | 54.56 | 72.05 | 74.43 [S-KEY][key] | **75.77** |
+| Chord | osu2017 | Maj/min | 79.82 | 77.42 | 84.59 [Jiang et al.][chord] | **90.08** |
+| Chord | Chords1217 | Maj/min | 72.98 | 83.52* | **84.09**† [ChordFormer][chordformer] | 83.81 |
+| Structure | HarmonixSet | Accuracy | — | — | 80.03 [SongFormer][structure] | **80.51** |
+| Structure | HarmonixSet | F1 @ 0.5 s | — | — | **70.63** [SongFormer][structure] | 67.96 |
+| Structure | HarmonixSet | F1 @ 3 s | — | — | 79.50 [SongFormer][structure] | **82.86** |
+| Melody | RWC-Pop | Vocal F1 | 62.71 | — | 62.71 [SheetSage1][sheetsage] | **82.51** |
+| Melody | RWC-Pop | Full F1 | 64.02 | — | 64.02 [SheetSage1][sheetsage] | **75.29** |
+
+Beat/downbeat F1 uses a 70 ms matching tolerance and excludes reference and predicted events before 5 s for all models. We evaluate 999 GTZAN tracks for beat, 993 for downbeat, and 142 osu2017 tracks for both. Beat This! uses its original inference settings without DBN postprocessing; scores are averaged over three released training seeds.
+
+Melody F1 uses pitch classes. SheetSage1 beat/downbeat results use madmom. *The madmom chord model includes Chords1217 in training. †ChordFormer uses five-fold cross-validation; SheetSage2 uses one checkpoint across all tracks.
+
+### Benchmark updates
+
+- **2026-09-14:** Updated beat/downbeat scores with a shared 5-second exclusion protocol. Beat This! was rerun under its original settings, averaging scores across three released seeds. Key metric labels are now consistent with the report (Score).
+
+[beat]: https://doi.org/10.5281/zenodo.14877491
+[key]: https://doi.org/10.1109/ICASSP49660.2025.10890222
+[chord]: https://archives.ismir.net/ismir2019/paper/000078.pdf
+[chordformer]: https://arxiv.org/abs/2502.11840
+[structure]: https://arxiv.org/abs/2510.02797
+[sheetsage]: https://arxiv.org/abs/2212.01884
+
+<a id="citation"></a>
+
+## 📚 Citation
+
+**Technical report coming soon.** For now, please cite [YuE](https://arxiv.org/abs/2503.08638) and [MERT](https://proceedings.iclr.cc/paper_files/paper/2024/hash/33dffa2e3d2ab74a783d1a8c292f66d9-Abstract-Conference.html) when using SheetSage2 in your research.
+
+```bibtex
+@article{yuan2025yue,
+  title = {{YuE}: Scaling Open Foundation Models for Long-Form Music Generation},
+  author = {Yuan, Ruibin and Lin, Hanfeng and Guo, Shuyue and Zhang, Ge and Pan, Jiahao and Zang, Yongyi and Liu, Haohe and Liang, Yiming and Ma, Wenye and Du, Xingjian and Du, Xinrun and Ye, Zhen and Zheng, Tianyu and Jiang, Zhengxuan and Ma, Yinghao and Liu, Minghao and Tian, Zeyue and Zhou, Ziya and Xue, Liumeng and Qu, Xingwei and Li, Yizhi and Wu, Shangda and Shen, Tianhao and Ma, Ziyang and Zhan, Jun and Wang, Chunhui and Wang, Yatian and Chi, Xiaowei and Zhang, Xinyue and Yang, Zhenzhu and Wang, Xiangzhou and Liu, Shansong and Mei, Lingrui and Li, Peng and Wang, Junjie and Yu, Jianwei and Pang, Guojian and Li, Xu and Wang, Zihao and Zhou, Xiaohuan and Yu, Lijun and Benetos, Emmanouil and Chen, Yong and Lin, Chenghua and Chen, Xie and Xia, Gus and Zhang, Zhaoxiang and Zhang, Chao and Chen, Wenhu and Zhou, Xinyu and Qiu, Xipeng and Dannenberg, Roger and Liu, Jiaheng and Yang, Jian and Huang, Wenhao and Xue, Wei and Tan, Xu and Guo, Yike},
+  journal = {arXiv preprint arXiv:2503.08638},
+  year = {2025},
+  eprint = {2503.08638},
+  archivePrefix = {arXiv},
+  url = {https://arxiv.org/abs/2503.08638}
+}
+
+@inproceedings{li2024mert,
+  title = {MERT: Acoustic Music Understanding Model with Large-Scale Self-supervised Training},
+  author = {Li, Yizhi and Yuan, Ruibin and Zhang, Ge and Ma, Yinghao and Chen, Xingran and Yin, Hanzhi and Xiao, Chenghao and Lin, Chenghua and Ragni, Anton and Benetos, Emmanouil and Gyenge, Norbert and Dannenberg, Roger and Liu, Ruibo and Chen, Wenhu and Xia, Gus and Shi, Yemin and Huang, Wenhao and Wang, Zili and Guo, Yike and Fu, Jie},
+  booktitle = {International Conference on Learning Representations},
+  year = {2024},
+  url = {https://proceedings.iclr.cc/paper_files/paper/2024/hash/33dffa2e3d2ab74a783d1a8c292f66d9-Abstract-Conference.html}
+}
+```
+
+Weights: [CC BY-NC 4.0](LICENSE). [Third-party notices](THIRD_PARTY_NOTICES.md).
+
+**YuE2 family:** [Song generation](https://huggingface.co/m-a-p/YuE2-3B) · [Music representations](https://huggingface.co/m-a-p/MERT-v2-FullSong) · [Audio decoder](https://huggingface.co/m-a-p/YuE2-Vae).

THIRD_PARTY_NOTICES.md

@@ -0,0 +1,8 @@
+# Third-party notices
+
+- MERT-v2-FullSong provides the public music encoder. Its weight terms remain CC BY-NC 4.0.
+- The BART decoder uses Hugging Face Transformers (Apache 2.0); PyTorch uses its BSD-style license.
+- abcjs 6.6.3 is distributed under MIT; its license accompanies the rendering assets.
+- Playwright is distributed under Apache 2.0. Chromium is installed separately with its accompanying notices.
+- FluidR3 piano samples by Frank Wen use CC BY 3.0 US. Attribution and source information accompany the samples.
+- Other installed dependencies retain their respective licenses.

__init__.py

@@ -0,0 +1 @@
+"""SheetSage2 standalone inference."""

audio_sheetsage2.py

@@ -0,0 +1,92 @@
+"""File decoding and waveform preparation for music transcription."""
+from pathlib import Path
+import io
+import math
+import numbers
+import shutil
+import subprocess
+
+import numpy as np
+import torch
+
+SAMPLE_RATE = 24000
+
+
+def _encoded_bytes(audio):
+    if isinstance(audio, (bytes, bytearray, memoryview)):
+        return bytes(audio)
+    if callable(getattr(audio, "read", None)):
+        position = None
+        try:
+            position = audio.tell()
+            audio.seek(0)
+        except (AttributeError, OSError, ValueError, io.UnsupportedOperation):
+            position = None
+        try:
+            value = audio.read()
+        finally:
+            if position is not None:
+                audio.seek(position)
+        if not isinstance(value, (bytes, bytearray)):
+            raise ValueError("Audio streams must return encoded audio bytes")
+        return bytes(value)
+    return None
+
+
+def load_audio(audio, *, sampling_rate=None, max_seconds=None, preset="default"):
+    if max_seconds is not None and (not math.isfinite(max_seconds) or max_seconds <= 0):
+        raise ValueError("max_seconds must be finite and positive")
+    encoded = _encoded_bytes(audio)
+    if encoded is not None and not encoded:
+        raise ValueError("Encoded audio must not be empty")
+    if isinstance(audio, (str, Path)) or encoded is not None:
+        if preset == "paper":
+            import torchaudio
+            source = io.BytesIO(encoded) if encoded is not None else str(audio)
+            info = torchaudio.info(source, backend="ffmpeg")
+            if info.num_frames <= 0:
+                raise ValueError("Cannot determine source audio length")
+            if encoded is not None:
+                source.seek(0)
+            waveform, rate = torchaudio.load(source, frame_offset=0, num_frames=int(info.num_frames),
+                                            backend="ffmpeg", channels_first=True)
+            waveform = waveform.mean(dim=0)
+            if rate != SAMPLE_RATE:
+                waveform = torchaudio.functional.resample(waveform, rate, SAMPLE_RATE)
+        else:
+            if not shutil.which("ffmpeg"):
+                raise RuntimeError("FFmpeg is required to read audio files; install it and add it to PATH")
+            source = "pipe:0" if encoded is not None else str(Path(audio).resolve())
+            command = ["ffmpeg", "-v", "error", "-nostdin", "-i", source, "-vn"]
+            if max_seconds is not None:
+                command += ["-t", str(float(max_seconds))]
+            command += ["-ac", "1", "-ar", str(SAMPLE_RATE), "-f", "f32le", "pipe:1"]
+            result = subprocess.run(command, input=encoded, capture_output=True, timeout=600, check=False)
+            if result.returncode:
+                raise ValueError("Cannot decode audio: " + result.stderr.decode(errors="replace")[-1200:])
+            waveform = torch.from_numpy(np.frombuffer(result.stdout, dtype="<f4").copy())
+    else:
+        if not isinstance(sampling_rate, numbers.Real) or not math.isfinite(sampling_rate) or sampling_rate <= 0 or sampling_rate != int(sampling_rate):
+            raise ValueError("Provide sampling_rate for an array or tensor waveform")
+        waveform = torch.as_tensor(audio, dtype=torch.float32, device="cpu")
+        if waveform.ndim == 2:
+            if waveform.shape[0] > 32:
+                raise ValueError("Multichannel audio must have shape [channels, samples]")
+            waveform = waveform.mean(dim=0)
+        if waveform.ndim != 1:
+            raise ValueError("Audio must have shape [samples] or [channels, samples]")
+        if sampling_rate != SAMPLE_RATE:
+            import torchaudio
+            waveform = torchaudio.functional.resample(waveform, int(sampling_rate), SAMPLE_RATE)
+    waveform = waveform.float().contiguous()
+    if max_seconds is not None:
+        waveform = waveform[:round(max_seconds * SAMPLE_RATE)]
+    if waveform.numel() < 1025 or not torch.isfinite(waveform).all():
+        raise ValueError("Audio must contain at least 1025 finite samples at 24 kHz")
+    return waveform
+
+
+def slice_audio(audio, start, seconds):
+    offset, count = round(start * SAMPLE_RATE), round(seconds * SAMPLE_RATE)
+    result = audio[offset:offset + count]
+    return torch.nn.functional.pad(result, (0, count - len(result)))

benchmark_results.json

@@ -0,0 +1,379 @@
+{
+  "scores": [
+    {
+      "task": "beat",
+      "dataset": "GTZAN",
+      "metric": "F1",
+      "score": 86.27,
+      "settings": {
+        "preset": "paper",
+        "sample_rate": 24000,
+        "window_seconds": 300,
+        "overlap_seconds": 100,
+        "lookahead_seconds": 0,
+        "max_length": 5120,
+        "decoding": "greedy",
+        "attention": "sdpa",
+        "weight_dtype": "float32",
+        "autocast_dtype": "bfloat16",
+        "batch_size": 1,
+        "prompts": [
+          "timestamp",
+          "downbeat_meter",
+          "key"
+        ],
+        "device": "NVIDIA H800",
+        "cuda_version": "12.6"
+      },
+      "evaluation": {
+        "num_tracks": 999,
+        "matching_tolerance_seconds": 0.07,
+        "min_event_time_seconds": 5.0,
+        "trim_reference_and_predictions": true,
+        "aggregation": "macro_average_per_track_f1"
+      }
+    },
+    {
+      "task": "beat",
+      "dataset": "osu2017",
+      "metric": "F1",
+      "score": 93.01,
+      "settings": {
+        "preset": "paper",
+        "sample_rate": 24000,
+        "window_seconds": 300,
+        "overlap_seconds": 100,
+        "lookahead_seconds": 0,
+        "max_length": 5120,
+        "decoding": "greedy",
+        "attention": "sdpa",
+        "weight_dtype": "float32",
+        "autocast_dtype": "bfloat16",
+        "batch_size": 1,
+        "prompts": [
+          "timestamp",
+          "downbeat_meter",
+          "key",
+          "chord_full"
+        ],
+        "device": "NVIDIA H800",
+        "cuda_version": "12.6"
+      },
+      "evaluation": {
+        "num_tracks": 142,
+        "matching_tolerance_seconds": 0.07,
+        "min_event_time_seconds": 5.0,
+        "trim_reference_and_predictions": true,
+        "aggregation": "macro_average_per_track_f1"
+      }
+    },
+    {
+      "task": "downbeat",
+      "dataset": "GTZAN",
+      "metric": "F1",
+      "score": 80.45,
+      "settings": {
+        "preset": "paper",
+        "sample_rate": 24000,
+        "window_seconds": 300,
+        "overlap_seconds": 100,
+        "lookahead_seconds": 0,
+        "max_length": 5120,
+        "decoding": "greedy",
+        "attention": "sdpa",
+        "weight_dtype": "float32",
+        "autocast_dtype": "bfloat16",
+        "batch_size": 1,
+        "prompts": [
+          "timestamp",
+          "downbeat_meter",
+          "key"
+        ],
+        "device": "NVIDIA H800",
+        "cuda_version": "12.6"
+      },
+      "evaluation": {
+        "num_tracks": 993,
+        "matching_tolerance_seconds": 0.07,
+        "min_event_time_seconds": 5.0,
+        "trim_reference_and_predictions": true,
+        "aggregation": "macro_average_per_track_f1"
+      }
+    },
+    {
+      "task": "downbeat",
+      "dataset": "osu2017",
+      "metric": "F1",
+      "score": 92.9,
+      "settings": {
+        "preset": "paper",
+        "sample_rate": 24000,
+        "window_seconds": 300,
+        "overlap_seconds": 100,
+        "lookahead_seconds": 0,
+        "max_length": 5120,
+        "decoding": "greedy",
+        "attention": "sdpa",
+        "weight_dtype": "float32",
+        "autocast_dtype": "bfloat16",
+        "batch_size": 1,
+        "prompts": [
+          "timestamp",
+          "downbeat_meter",
+          "key",
+          "chord_full"
+        ],
+        "device": "NVIDIA H800",
+        "cuda_version": "12.6"
+      },
+      "evaluation": {
+        "num_tracks": 142,
+        "matching_tolerance_seconds": 0.07,
+        "min_event_time_seconds": 5.0,
+        "trim_reference_and_predictions": true,
+        "aggregation": "macro_average_per_track_f1"
+      }
+    },
+    {
+      "task": "key",
+      "dataset": "GiantSteps",
+      "metric": "weighted_accuracy",
+      "score": 77.73,
+      "settings": {
+        "preset": "paper",
+        "sample_rate": 24000,
+        "window_seconds": 300,
+        "overlap_seconds": 100,
+        "lookahead_seconds": 0,
+        "max_length": 5120,
+        "decoding": "greedy",
+        "attention": "sdpa",
+        "weight_dtype": "float32",
+        "autocast_dtype": "bfloat16",
+        "batch_size": 1,
+        "prompts": [
+          "timestamp",
+          "downbeat_meter",
+          "key"
+        ],
+        "device": "NVIDIA H800",
+        "cuda_version": "12.6"
+      }
+    },
+    {
+      "task": "key",
+      "dataset": "GTZAN",
+      "metric": "weighted_accuracy",
+      "score": 75.77,
+      "settings": {
+        "preset": "paper",
+        "sample_rate": 24000,
+        "window_seconds": 300,
+        "overlap_seconds": 100,
+        "lookahead_seconds": 0,
+        "max_length": 5120,
+        "decoding": "greedy",
+        "attention": "sdpa",
+        "weight_dtype": "float32",
+        "autocast_dtype": "bfloat16",
+        "batch_size": 1,
+        "prompts": [
+          "timestamp",
+          "downbeat_meter",
+          "key"
+        ],
+        "device": "NVIDIA H800",
+        "cuda_version": "12.6"
+      }
+    },
+    {
+      "task": "chord",
+      "dataset": "osu2017",
+      "metric": "majmin",
+      "score": 90.08,
+      "settings": {
+        "preset": "paper",
+        "sample_rate": 24000,
+        "window_seconds": 300,
+        "overlap_seconds": 100,
+        "lookahead_seconds": 0,
+        "max_length": 5120,
+        "decoding": "greedy",
+        "attention": "sdpa",
+        "weight_dtype": "float32",
+        "autocast_dtype": "bfloat16",
+        "batch_size": 1,
+        "prompts": [
+          "timestamp",
+          "downbeat_meter",
+          "key",
+          "chord_full"
+        ],
+        "device": "NVIDIA H800",
+        "cuda_version": "12.6"
+      }
+    },
+    {
+      "task": "chord",
+      "dataset": "Chords1217",
+      "metric": "majmin",
+      "score": 83.81,
+      "settings": {
+        "preset": "paper",
+        "sample_rate": 24000,
+        "window_seconds": 300,
+        "overlap_seconds": 100,
+        "lookahead_seconds": 0,
+        "max_length": 5120,
+        "decoding": "greedy",
+        "attention": "sdpa",
+        "weight_dtype": "float32",
+        "autocast_dtype": "bfloat16",
+        "batch_size": 1,
+        "prompts": [
+          "timestamp",
+          "downbeat_meter",
+          "chord_full"
+        ],
+        "device": "NVIDIA H800",
+        "cuda_version": "12.6"
+      }
+    },
+    {
+      "task": "structure",
+      "dataset": "HarmonixSet",
+      "metric": "accuracy",
+      "score": 80.51,
+      "settings": {
+        "preset": "paper",
+        "sample_rate": 24000,
+        "window_seconds": 300,
+        "overlap_seconds": 100,
+        "lookahead_seconds": 0,
+        "max_length": 5120,
+        "decoding": "greedy",
+        "attention": "sdpa",
+        "weight_dtype": "float32",
+        "autocast_dtype": "bfloat16",
+        "batch_size": 1,
+        "prompts": [
+          "timestamp",
+          "downbeat_meter",
+          "structure"
+        ],
+        "device": "NVIDIA H800",
+        "cuda_version": "12.6"
+      }
+    },
+    {
+      "task": "structure",
+      "dataset": "HarmonixSet",
+      "metric": "F1@0.5s",
+      "score": 67.96,
+      "settings": {
+        "preset": "paper",
+        "sample_rate": 24000,
+        "window_seconds": 300,
+        "overlap_seconds": 100,
+        "lookahead_seconds": 0,
+        "max_length": 5120,
+        "decoding": "greedy",
+        "attention": "sdpa",
+        "weight_dtype": "float32",
+        "autocast_dtype": "bfloat16",
+        "batch_size": 1,
+        "prompts": [
+          "timestamp",
+          "downbeat_meter",
+          "structure"
+        ],
+        "device": "NVIDIA H800",
+        "cuda_version": "12.6"
+      }
+    },
+    {
+      "task": "structure",
+      "dataset": "HarmonixSet",
+      "metric": "F1@3s",
+      "score": 82.86,
+      "settings": {
+        "preset": "paper",
+        "sample_rate": 24000,
+        "window_seconds": 300,
+        "overlap_seconds": 100,
+        "lookahead_seconds": 0,
+        "max_length": 5120,
+        "decoding": "greedy",
+        "attention": "sdpa",
+        "weight_dtype": "float32",
+        "autocast_dtype": "bfloat16",
+        "batch_size": 1,
+        "prompts": [
+          "timestamp",
+          "downbeat_meter",
+          "structure"
+        ],
+        "device": "NVIDIA H800",
+        "cuda_version": "12.6"
+      }
+    },
+    {
+      "task": "melody",
+      "dataset": "RWC-Pop",
+      "metric": "vocal_pitch_class_F1",
+      "score": 82.51,
+      "settings": {
+        "preset": "paper",
+        "sample_rate": 24000,
+        "window_seconds": 300,
+        "overlap_seconds": 100,
+        "lookahead_seconds": 0,
+        "max_length": 5120,
+        "decoding": "greedy",
+        "attention": "sdpa",
+        "weight_dtype": "float32",
+        "autocast_dtype": "bfloat16",
+        "batch_size": 1,
+        "prompts": [
+          "timestamp",
+          "downbeat_meter",
+          "structure",
+          "key",
+          "chord_full",
+          "melody_full"
+        ],
+        "device": "NVIDIA H800",
+        "cuda_version": "12.6"
+      }
+    },
+    {
+      "task": "melody",
+      "dataset": "RWC-Pop",
+      "metric": "full_pitch_class_F1",
+      "score": 75.29,
+      "settings": {
+        "preset": "paper",
+        "sample_rate": 24000,
+        "window_seconds": 300,
+        "overlap_seconds": 100,
+        "lookahead_seconds": 0,
+        "max_length": 5120,
+        "decoding": "greedy",
+        "attention": "sdpa",
+        "weight_dtype": "float32",
+        "autocast_dtype": "bfloat16",
+        "batch_size": 1,
+        "prompts": [
+          "timestamp",
+          "downbeat_meter",
+          "structure",
+          "key",
+          "chord_full",
+          "melody_full"
+        ],
+        "device": "NVIDIA H800",
+        "cuda_version": "12.6"
+      }
+    }
+  ]
+}

config.json

@@ -0,0 +1,75 @@
+{
+  "architectures": [
+    "SheetSage2Model"
+  ],
+  "auto_map": {
+    "AutoConfig": "configuration_sheetsage2.SheetSage2Config",
+    "AutoModel": "modeling_sheetsage2.SheetSage2Model",
+    "AutoModelForSeq2SeqLM": "modeling_sheetsage2.SheetSage2Model",
+    "AutoProcessor": "processing_sheetsage2.SheetSage2Processor"
+  },
+  "backbone_config": {
+    "architectures": [
+      "MERT2Model"
+    ],
+    "context_seconds": 360.0,
+    "conv_depthwise_kernel_size": 31,
+    "frame_rate": 25.0,
+    "hidden_size": 1024,
+    "hop_length": 240,
+    "initializer_range": 0.02,
+    "inputs_to_logits_ratio": 960,
+    "intermediate_size": 4096,
+    "layer_norm_eps": 1e-05,
+    "minimum_input_samples": 1025,
+    "model_type": "mert2",
+    "n_fft": 2048,
+    "num_attention_heads": 16,
+    "num_hidden_layers": 24,
+    "num_mel_bins": 128,
+    "rotary_embedding_base": 10000,
+    "sampling_rate": 24000,
+    "subsampling_channels": [
+      128,
+      512,
+      1024
+    ],
+    "subsampling_depths": [
+      3,
+      4,
+      5
+    ],
+    "subsampling_layer_norm_eps": 1e-06,
+    "torch_dtype": "float32",
+    "transformers_version": "4.53.2",
+    "variant": "fs",
+    "win_length": 2048
+  },
+  "base_model_name_or_path": "m-a-p/MERT-v2-FullSong",
+  "base_model_revision": "d8ba1c745e733b3908ce6ad16ebeb17ac7600a42",
+  "base_model_sha256": "e6dd2ab187d6dd62b6521cd7d8f932e237acf0c5757745a7232082e28391350d",
+  "bos_token_id": 1,
+  "decoder_dropout": 0.1,
+  "decoder_layers": 6,
+  "decoder_start_token_id": 1,
+  "encoder_attn_implementation": "sdpa",
+  "eos_token_id": 2,
+  "hidden_size": 512,
+  "input_audio_length": 300.0,
+  "intermediate_size": 2048,
+  "is_encoder_decoder": true,
+  "lora_alpha": 128.0,
+  "lora_rank": 64,
+  "max_output_seq_len": 5120,
+  "model_type": "sheetsage2",
+  "num_attention_heads": 8,
+  "pad_token_id": 0,
+  "sampling_rate": 24000,
+  "time_hz": 100,
+  "tokenizer_fingerprint": "5ba3325af0344c7f",
+  "tokenizer_schema_version": "v1",
+  "transformers_version": "4.45.2",
+  "use_cache": true,
+  "vocab_size": 31678,
+  "weights_format": "adapter"
+}

configuration_mert2.py

@@ -0,0 +1,76 @@
+"""Configuration for MERT2 music representation models."""
+
+from transformers import PretrainedConfig
+
+
+class MERT2Config(PretrainedConfig):
+    """Architecture shared by the 30-second and full-song MERT2 encoders."""
+
+    model_type = "mert2"
+
+    def __init__(
+        self,
+        hidden_size=1024,
+        intermediate_size=4096,
+        num_hidden_layers=24,
+        num_attention_heads=16,
+        num_mel_bins=128,
+        sampling_rate=24000,
+        n_fft=2048,
+        win_length=2048,
+        hop_length=240,
+        subsampling_channels=None,
+        subsampling_depths=None,
+        conv_depthwise_kernel_size=31,
+        rotary_embedding_base=10000,
+        layer_norm_eps=1e-5,
+        subsampling_layer_norm_eps=1e-6,
+        initializer_range=0.02,
+        variant="30s",
+        context_seconds=None,
+        **kwargs,
+    ):
+        super().__init__(**kwargs)
+        self.hidden_size = int(hidden_size)
+        self.intermediate_size = int(intermediate_size)
+        self.num_hidden_layers = int(num_hidden_layers)
+        self.num_attention_heads = int(num_attention_heads)
+        self.num_mel_bins = int(num_mel_bins)
+        self.sampling_rate = int(sampling_rate)
+        self.n_fft = int(n_fft)
+        self.win_length = int(win_length)
+        self.hop_length = int(hop_length)
+        self.subsampling_channels = list(subsampling_channels or [num_mel_bins, 512, hidden_size])
+        self.subsampling_depths = list(subsampling_depths or [3, 4, 5])
+        self.conv_depthwise_kernel_size = int(conv_depthwise_kernel_size)
+        self.rotary_embedding_base = int(rotary_embedding_base)
+        self.layer_norm_eps = float(layer_norm_eps)
+        self.subsampling_layer_norm_eps = float(subsampling_layer_norm_eps)
+        self.initializer_range = float(initializer_range)
+        self.variant = str(variant)
+        self.context_seconds = float(context_seconds if context_seconds is not None else (360 if variant == "fs" else 30))
+        self.inputs_to_logits_ratio = self.hop_length * 4
+        self.frame_rate = self.sampling_rate / self.inputs_to_logits_ratio
+        self.minimum_input_samples = self.n_fft // 2 + 1
+
+        if min(self.hidden_size, self.intermediate_size, self.num_hidden_layers, self.num_attention_heads) <= 0:
+            raise ValueError("Encoder dimensions and layer counts must be positive.")
+        if self.hidden_size % self.num_attention_heads or (self.hidden_size // self.num_attention_heads) % 2:
+            raise ValueError("hidden_size must divide into an even head dimension.")
+        if len(self.subsampling_channels) != 3 or len(self.subsampling_depths) != 3:
+            raise ValueError("The subsampler must contain three channel widths and three depths.")
+        if self.subsampling_channels[0] != self.num_mel_bins or self.subsampling_channels[-1] != self.hidden_size:
+            raise ValueError("Subsampling widths must start at num_mel_bins and end at hidden_size.")
+        if min(*self.subsampling_channels, *self.subsampling_depths, self.num_mel_bins, self.sampling_rate, self.hop_length) <= 0:
+            raise ValueError("Frontend dimensions and sampling parameters must be positive.")
+        if self.n_fft < self.win_length or self.win_length <= 0 or self.n_fft % 2:
+            raise ValueError("n_fft must be even and at least win_length > 0.")
+        if self.conv_depthwise_kernel_size <= 0 or self.conv_depthwise_kernel_size % 2 != 1:
+            raise ValueError("conv_depthwise_kernel_size must be positive and odd.")
+        if self.rotary_embedding_base <= 0 or min(self.layer_norm_eps, self.subsampling_layer_norm_eps) <= 0:
+            raise ValueError("Rotary base and normalization epsilons must be positive.")
+        if self.variant not in {"30s", "fs"}:
+            raise ValueError("variant must be '30s' or 'fs'.")
+
+
+MERT2Config.register_for_auto_class()

configuration_sheetsage2.py

@@ -0,0 +1,88 @@
+"""Configuration for SheetSage2 audio-to-symbolic transcription."""
+
+from transformers import PretrainedConfig
+
+from .configuration_mert2 import MERT2Config
+
+
+class SheetSage2Config(PretrainedConfig):
+    model_type = "sheetsage2"
+
+    def __init__(
+        self,
+        vocab_size=31678,
+        hidden_size=512,
+        decoder_layers=6,
+        num_attention_heads=8,
+        intermediate_size=2048,
+        decoder_dropout=0.1,
+        input_audio_length=300.0,
+        max_output_seq_len=5120,
+        time_hz=100,
+        sampling_rate=24000,
+        lora_rank=64,
+        lora_alpha=128,
+        weights_format="adapter",
+        backbone_config=None,
+        encoder_attn_implementation="sdpa",
+        base_model_name_or_path="m-a-p/MERT-v2-FullSong",
+        base_model_revision="d8ba1c745e733b3908ce6ad16ebeb17ac7600a42",
+        base_model_sha256="e6dd2ab187d6dd62b6521cd7d8f932e237acf0c5757745a7232082e28391350d",
+        tokenizer_schema_version="v1",
+        tokenizer_fingerprint="5ba3325af0344c7f",
+        **kwargs,
+    ):
+        for name, default in (
+            ("is_encoder_decoder", True), ("tie_word_embeddings", True),
+            ("pad_token_id", 0), ("bos_token_id", 1), ("eos_token_id", 2),
+            ("decoder_start_token_id", 1),
+            ("use_cache", True),
+        ):
+            kwargs.setdefault(name, default)
+        super().__init__(**kwargs)
+        self.vocab_size = int(vocab_size)
+        self.hidden_size = int(hidden_size)
+        self.decoder_layers = int(decoder_layers)
+        self.num_attention_heads = int(num_attention_heads)
+        self.intermediate_size = int(intermediate_size)
+        self.decoder_dropout = float(decoder_dropout)
+        self.input_audio_length = float(input_audio_length)
+        self.max_output_seq_len = int(max_output_seq_len)
+        self.time_hz = int(time_hz)
+        self.sampling_rate = int(sampling_rate)
+        self.lora_rank = int(lora_rank)
+        self.lora_alpha = float(lora_alpha)
+        self.weights_format = str(weights_format)
+        self.backbone_config = dict(backbone_config or MERT2Config(variant="fs").to_dict())
+        self.backbone_config.pop("_name_or_path", None)
+        self.backbone_config.pop("auto_map", None)
+        self.encoder_attn_implementation = str(encoder_attn_implementation)
+        self.base_model_name_or_path = str(base_model_name_or_path)
+        self.base_model_revision = str(base_model_revision)
+        self.base_model_sha256 = str(base_model_sha256)
+        self.tokenizer_schema_version = str(tokenizer_schema_version)
+        self.tokenizer_fingerprint = str(tokenizer_fingerprint)
+        self.architectures = ["SheetSage2Model"]
+        self.auto_map = {
+            "AutoConfig": "configuration_sheetsage2.SheetSage2Config",
+            "AutoModel": "modeling_sheetsage2.SheetSage2Model",
+            "AutoModelForSeq2SeqLM": "modeling_sheetsage2.SheetSage2Model",
+            "AutoProcessor": "processing_sheetsage2.SheetSage2Processor",
+        }
+        if self.weights_format not in {"adapter", "merged"}:
+            raise ValueError("weights_format must be 'adapter' or 'merged'.")
+        if self.encoder_attn_implementation not in {"sdpa", "flash_attention_2"}:
+            raise ValueError("Select encoder attention 'sdpa' or 'flash_attention_2'.")
+        if min(self.vocab_size, self.hidden_size, self.decoder_layers, self.num_attention_heads,
+               self.intermediate_size, self.input_audio_length, self.max_output_seq_len,
+               self.time_hz, self.sampling_rate, self.lora_rank, self.lora_alpha) <= 0:
+            raise ValueError("Model dimensions and timing parameters must be positive.")
+        if self.hidden_size % self.num_attention_heads:
+            raise ValueError("hidden_size must be divisible by num_attention_heads.")
+        if not 0 <= self.decoder_dropout < 1:
+            raise ValueError("decoder_dropout must lie in [0, 1).")
+        if self.sampling_rate != self.backbone_config["sampling_rate"]:
+            raise ValueError("Processor and encoder sampling rates must match.")
+
+
+SheetSage2Config.register_for_auto_class()

durations_sheetsage2.py

@@ -0,0 +1,14 @@
+import numpy as np
+
+
+DURATION_TEMPLATES = np.array(
+    [
+        1, 2, 3, 4, 6, 8, 12, 16, 24, 32, 48, 64,
+        96, 128, 192, 256, 384, 512, 768, 1024,
+        1536, 2048, 3072, 4096,
+    ],
+    dtype=np.int32,
+)
+duration_boundaries = (DURATION_TEMPLATES[:-1] + DURATION_TEMPLATES[1:]) / 2
+
+

exports_sheetsage2.py

@@ -0,0 +1,200 @@
+"""Lossless decoded events/LAB/MIDI, then independently validated ABC."""
+from pathlib import Path
+import json
+from fractions import Fraction
+
+import numpy as np
+import pretty_midi
+
+from .notation_sheetsage2 import generate_abc_from_data
+from .io_sheetsage2 import atomic_write_text
+from .generation_sheetsage2 import field_text
+from .midi_sheetsage2 import build_playback, midi_bytes
+
+
+def rows_text(rows):
+    return "".join("\t".join(str(x) for x in row) + "\n" for row in rows)
+
+
+def write_rows(path, rows):
+    atomic_write_text(path, rows_text(rows))
+
+
+def interval_rows(events, field, duration):
+    rows = [[e["time"], 0, e["values"][field]] for e in events if field in e["values"]]
+    for i, row in enumerate(rows):
+        row[1] = rows[i + 1][0] if i + 1 < len(rows) else duration
+    return [r for r in rows if r[1] > r[0]]
+
+
+def rhythm_rows(events):
+    rows, meter = [], None
+    for event in events:
+        rhythm = event["values"].get("rhythm", {})
+        meter = rhythm.get("meter", meter)
+        eighth = rhythm.get("eighth_position")
+        if eighth is not None and meter is not None:
+            # The model stores eighth-note position, not denominator-beat index.
+            position = Fraction(int(eighth) * int(meter[1]), 8)
+            if position.denominator != 1:
+                raise ValueError(f"Eighth position {eighth} is off the {meter[0]}/{meter[1]} beat grid")
+            if not 0 <= position < meter[0]:
+                raise ValueError(f"Eighth position {eighth} is outside meter {meter}")
+            rows.append([float(event["time"]), int(position) + 1, int(meter[0]), int(meter[1])])
+    return rows
+
+
+def _midi(notes, paper=False):
+    midi = pretty_midi.PrettyMIDI(resolution=220 if paper else 960)
+    names = ((0, "vocal_melody"), (1, "instrumental_melody")) if paper else ((0, "Vocal"), (1, "Ins"))
+    for track, name in names:
+        instrument = pretty_midi.Instrument(program=0, name=name)
+        for start, end, pitch, source in notes:
+            if track == source and end > start:
+                instrument.notes.append(pretty_midi.Note(100, pitch, start, end))
+        midi.instruments.append(instrument)
+    return midi
+
+
+def notation_notes(notes):
+    """A monophonic notation view, retaining the exact raw prediction separately."""
+    result, diagnostics = [], []
+    for track in (0, 1):
+        ordered = sorted((list(n) for n in notes if n[3] == track), key=lambda n: (n[0], n[2], n[1]))
+        for i, note in enumerate(ordered):
+            if i + 1 < len(ordered) and note[1] > ordered[i + 1][0] + 1e-6:
+                note[1] = ordered[i + 1][0]
+                diagnostics.append(f"notation only: clipped track {track} note at {note[0]:.3f} to next onset")
+            if note[1] > note[0] + 1e-6:
+                result.append(note)
+    return sorted(result), diagnostics
+
+
+def export_result(decoded, tokenizer, output_dir=None, duration=None, paper=False, *, melody_only=False):
+    """Build ABC, MIDI and LAB in memory, optionally writing the same bytes.
+
+    Statistics retain their file-interface names. ``payload`` contains the
+    in-memory ABC text, MIDI bytes, decoded event list, LAB texts and playback.
+    melody_only removes chords from notation and playback without changing
+    decoded events or raw LAB annotations.
+    """
+    if not isinstance(melody_only, bool):
+        raise ValueError("melody_only must be True or False")
+    if duration is None:
+        raise TypeError("duration is required")
+    texts, midis, notation_midis, labs = {}, {}, {}, {}
+
+    def keep_rows(name, rows):
+        text = rows_text(rows)
+        texts[name] = text
+        if name.endswith(".lab"):
+            labs[name[:-4]] = text
+
+    events = decoded["events"]
+    notes = []
+    for event in events:
+        start = float(event["time"])
+        for note in event["values"].get("melody", ()):
+            end = max(start + 0.04, float(note["end_time"])) if paper else min(duration, float(note["end_time"]))
+            if end > start:
+                notes.append([start, end, int(note["pitch"]), int(note["track"])])
+    if not paper:
+        notes.sort()
+    texts["events.json"] = json.dumps(decoded, indent=2)
+    keep_rows("events.tsv", [["time", "global_subbeat", "fields"]] +
+               [[e["time"], e["global_subbeat"], field_text(e, tokenizer)] for e in events])
+    midis["melody"] = midi_bytes(_midi(notes, paper=paper))
+    lab_notes = [[f"{a:.6f}", f"{b:.6f}", p, t] for a, b, p, t in notes] if paper else notes
+    keep_rows("melody_full.lab", lab_notes)
+    for track, name in ((0, "vocal"), (1, "instrumental")):
+        selected = [n for n in notes if n[3] == track]
+        keep_rows(f"melody_{name}.lab", [n[:3] for n in lab_notes if n[3] == track])
+        midis[f"melody_{name}"] = midi_bytes(_midi(selected, paper=paper))
+    intervals = {}
+    for field in ("chord", "key", "structure"):
+        rows = interval_rows(events, field, duration)
+        if paper:
+            rows = [[float(e["time"]), None, e["values"][field]] for e in events if field in e["values"]]
+            for i, row in enumerate(rows):
+                row[1] = max(row[0], rows[i + 1][0]) if i + 1 < len(rows) else float(duration)
+        intervals[field] = rows
+        keep_rows(f"{field}.lab", rows)
+    if paper:
+        rows = []
+        for event in events:
+            rhythm, stamp = event["values"].get("rhythm"), event["values"].get("timestamp")
+            if rhythm is None and stamp is None:
+                continue
+            meter = rhythm.get("meter") if isinstance(rhythm, dict) else None
+            eighth = rhythm.get("eighth_position") if isinstance(rhythm, dict) else None
+            rows.append([f"{event['time']:.6f}", "" if stamp is None else f"{float(stamp):.6f}",
+                         "" if eighth is None else int(eighth), "" if meter is None else f"{meter[0]}/{meter[1]}"])
+        keep_rows("beat_meter.lab", rows)
+    raw_rhythm = [[e["time"], json.dumps(e["values"].get("rhythm", {}))]
+                  for e in events if "rhythm" in e["values"] or "timestamp" in e["values"]]
+    keep_rows("rhythm_events.lab", raw_rhythm)
+    diagnostics, abc_error, score, text = [], None, None, None
+    try:
+        beats = rhythm_rows(events)
+        keep_rows("beat.lab", beats)
+        keep_rows("downbeat.lab", [[r[0]] for r in beats if r[1] == 1])
+        if len(beats) < 2:
+            raise ValueError("At least two decoded beats are required for ABC")
+        # canonical notation's last beat is a boundary, so append it explicitly. Continue the
+        # final tempo only as far as the audio/last note and let it pad the bar.
+        abc_beats = [list(b) for b in beats]
+        period = float(np.median(np.diff([b[0] for b in beats[-9:]])))
+        if period <= 0:
+            raise ValueError("Decoded beats must increase in time")
+        end = max(duration, max((n[1] for n in notes), default=0))
+        while abc_beats[-1][0] < end - 1e-6:
+            prev = abc_beats[-1]
+            abc_beats.append([prev[0] + period, prev[1] % prev[2] + 1, prev[2], prev[3]])
+        keep_rows("notation/song_beats.txt", abc_beats)
+        notation_intervals = {}
+        for field, suffix in (("chord", "chords"), ("key", "keys"), ("structure", "structures")):
+            rows = interval_rows(events, field, duration)
+            # Clip to the actual beat domain: events beyond it have no ABC bin.
+            rows = [[max(abc_beats[0][0], a), min(abc_beats[-1][0], b), v]
+                    for a, b, v in rows if b > abc_beats[0][0] and a < abc_beats[-1][0]]
+            notation_intervals[field] = rows
+            keep_rows(f"notation/song_{suffix}.txt", rows)
+        if not interval_rows(events, "key", duration):
+            raise ValueError("No key was decoded; cannot construct a keyed ABC score")
+        clean, adjustments = notation_notes(notes)
+        diagnostics.extend(adjustments)
+        notation_midis["notation/song_melody.mid"] = midi_bytes(_midi(clean))
+        text, score = generate_abc_from_data(
+            notation_midis["notation/song_melody.mid"], abc_beats,
+            notation_intervals["chord"], notation_intervals["key"], notation_intervals["structure"],
+            melody_only=melody_only,
+        )
+        diagnostics.extend(score.diagnostics)
+        texts["score.abc"] = text
+        abc_measures = len(score.measures)
+    except (ValueError, FileNotFoundError) as exc:
+        abc_error = str(exc)
+        abc_measures = 0
+    playback, playback_midis = build_playback(
+        midis["melody"], [] if melody_only else intervals["chord"], score, duration)
+    midis.update(playback_midis)
+    texts["playback.json"] = json.dumps(playback, indent=2)
+    diagnostics.extend(playback["warnings"])
+    if output_dir is not None:
+        output_dir = Path(output_dir)
+        output_dir.mkdir(parents=True, exist_ok=True)
+        for name, content in texts.items():
+            atomic_write_text(output_dir / name, content)
+        for name, content in {**{f"{name}.mid": content for name, content in midis.items()}, **notation_midis}.items():
+            path = output_dir / name
+            path.parent.mkdir(parents=True, exist_ok=True)
+            path.write_bytes(content)
+        if abc_error is not None:
+            (output_dir / "score.abc").unlink(missing_ok=True)
+        else:
+            (output_dir / "score.browser.abc").unlink(missing_ok=True)
+    payload = dict(abc=text, midi=midis["transcription"], midis=midis,
+                   events=events, labs=labs, playback=playback)
+    return dict(melody_notes=len(notes), vocal_notes=sum(n[3] == 0 for n in notes),
+                instrumental_notes=sum(n[3] == 1 for n in notes), events=len(events),
+                abc_measures=abc_measures, abc_error=abc_error, diagnostics=diagnostics, payload=payload)

generation_sheetsage2.py

@@ -0,0 +1,634 @@
+"""Prompt grammar, cached generation and overlap context from the evaluated model."""
+import copy
+from contextlib import nullcontext
+from pathlib import Path
+import numpy as np
+import torch
+
+FULL_TASK_PROMPTS = ("timestamp", "downbeat_meter", "structure", "key", "chord_full", "melody_full")
+FIELD_TO_INDEX = {"timestamp": 0, "rhythm": 1, "structure": 2, "key": 3, "chord": 4, "melody": 5}
+
+
+class PromptGrammarState:
+    def __init__(self, tokenizer):
+        self.tokenizer = tokenizer
+        self.generated_events = 0
+        self.in_shift = True
+        self.shift_run = 0
+        self.payload_count = 0
+        self.last_field_index = -1
+        self.incomplete = None
+
+    def _allow_field_starts(self, allowed):
+        tokenizer = self.tokenizer
+        if self.last_field_index < FIELD_TO_INDEX["timestamp"]:
+            allowed[tokenizer.time_token_start : tokenizer.time_token_end] = True
+        if self.last_field_index < FIELD_TO_INDEX["rhythm"]:
+            allowed[tokenizer.meter_token_start : tokenizer.meter_token_end] = True
+            allowed[
+                tokenizer.eighth_position_token_start : tokenizer.eighth_position_token_end
+            ] = True
+        if self.last_field_index < FIELD_TO_INDEX["structure"]:
+            allowed[
+                tokenizer.structure_token_start : tokenizer.structure_token_end
+            ] = True
+        if self.last_field_index < FIELD_TO_INDEX["key"]:
+            allowed[tokenizer.key_token_start : tokenizer.key_token_end] = True
+        if self.last_field_index < FIELD_TO_INDEX["chord"]:
+            allowed[
+                tokenizer.full_chord_token_start : tokenizer.full_chord_token_end
+            ] = True
+        if self.last_field_index <= FIELD_TO_INDEX["melody"]:
+            allowed[tokenizer.pitch_token_start : tokenizer.pitch_token_end] = True
+
+    def allowed(self, device):
+        tokenizer = self.tokenizer
+        allowed = torch.zeros(tokenizer.n_tokens, dtype=torch.bool, device=device)
+        can_end = self.payload_count > 0
+
+        if can_end:
+            allowed[tokenizer.eos_token] = True
+        if self.payload_count > 0 or self.in_shift:
+            if self.shift_run < 4:
+                allowed[
+                    tokenizer.subbeat_shift_token_start : tokenizer.subbeat_shift_token_end
+                ] = True
+
+        if self.incomplete == "rhythm_after_meter":
+            allowed[
+                tokenizer.eighth_position_token_start : tokenizer.eighth_position_token_end
+            ] = True
+            return allowed
+
+        if self.incomplete == "melody_after_pitch":
+            allowed[tokenizer.duration_token_start : tokenizer.duration_token_end] = True
+            allowed[tokenizer.pitch_token_start : tokenizer.pitch_token_end] = True
+            return allowed
+
+        self._allow_field_starts(allowed)
+        return allowed
+
+    def update(self, token):
+        tokenizer = self.tokenizer
+        token = int(token)
+        token_type = tokenizer.token_type(token)
+        if token == tokenizer.eos_token:
+            return True
+        if token_type == "subbeat_shift":
+            if not self.in_shift and self.payload_count > 0:
+                self.generated_events += 1
+                self.payload_count = 0
+                self.last_field_index = -1
+                self.incomplete = None
+            self.in_shift = True
+            self.shift_run += 1
+            return False
+
+        self.in_shift = False
+        self.shift_run = 0
+        self.payload_count += 1
+        if token_type == "time":
+            self.last_field_index = FIELD_TO_INDEX["timestamp"]
+            self.incomplete = None
+        elif token_type == "meter":
+            self.last_field_index = FIELD_TO_INDEX["rhythm"]
+            self.incomplete = "rhythm_after_meter"
+        elif token_type == "eighth_position":
+            self.last_field_index = FIELD_TO_INDEX["rhythm"]
+            self.incomplete = None
+        elif token_type == "structure":
+            self.last_field_index = FIELD_TO_INDEX["structure"]
+            self.incomplete = None
+        elif token_type == "key":
+            self.last_field_index = FIELD_TO_INDEX["key"]
+            self.incomplete = None
+        elif token_type == "chord_full":
+            self.last_field_index = FIELD_TO_INDEX["chord"]
+            self.incomplete = None
+        elif token_type == "pitch":
+            self.last_field_index = FIELD_TO_INDEX["melody"]
+            self.incomplete = "melody_after_pitch"
+        elif token_type == "duration":
+            self.last_field_index = FIELD_TO_INDEX["melody"]
+            self.incomplete = None
+        else:
+            raise RuntimeError(f"Unexpected prompt token type {token_type!r}")
+        return False
+
+
+def inference_autocast(device, dtype=torch.bfloat16):
+    if device.type != "cuda" or dtype is None:
+        return nullcontext()
+    return torch.autocast(device_type="cuda", dtype=dtype)
+
+
+def select_cache_batch(cache, indices, batch_size):
+    if cache is None:
+        return None
+    batch_select = getattr(cache, "batch_select_indices", None)
+    if callable(batch_select):
+        batch_select(indices)
+        return cache
+    if torch.is_tensor(cache):
+        if cache.ndim > 0 and cache.shape[0] == batch_size:
+            return cache.index_select(0, indices)
+        return cache
+    if isinstance(cache, tuple):
+        return tuple(select_cache_batch(item, indices, batch_size) for item in cache)
+    if isinstance(cache, list):
+        return [select_cache_batch(item, indices, batch_size) for item in cache]
+    if isinstance(cache, dict):
+        return {
+            key: select_cache_batch(value, indices, batch_size)
+            for key, value in cache.items()
+        }
+    return cache
+
+
+@torch.inference_mode()
+def constrained_prompt_generate_batch(
+    model,
+    audio,
+    prompts,
+    max_sequence_length,
+    prefix_tokens=None,
+    autocast_dtype=torch.bfloat16,
+    stop_time_seconds=None,
+    progress_callback=None,
+    memory=None,
+    step_callback=None,
+):
+    tokenizer = model.tokenizer
+    prefix = list(prefix_tokens) if prefix_tokens is not None else tokenizer.prompt_prefix(prompts)
+    if not prefix or prefix[0] != tokenizer.sos_token:
+        raise ValueError("generation prefix must begin with <|sos|>")
+    if prefix[-1] == tokenizer.eos_token:
+        prefix = prefix[:-1]
+    if audio.ndim != 2 or audio.shape[0] < 1:
+        raise ValueError(f"audio must have shape [batch, samples], got {tuple(audio.shape)}")
+    states = [PromptGrammarState(tokenizer) for _ in range(audio.shape[0])]
+    stop_times = [
+        None if stop_time_seconds is None else float(stop_time_seconds)
+        for _ in states
+    ]
+    out_index = prefix.index(tokenizer.out_token)
+    for state in states:
+        for token in prefix[out_index + 1 :]:
+            state.update(token)
+    output_tokens = [list(prefix) for _ in states]
+    active_sample_ids = list(range(audio.shape[0]))
+    decoder_input = torch.tensor(
+        [prefix] * audio.shape[0],
+        dtype=torch.long,
+        device=audio.device,
+    )
+    past_key_values = None
+    if memory is None:
+        with inference_autocast(audio.device, autocast_dtype):
+            memory = model.encode(audio)
+    current_length = len(prefix)
+    while active_sample_ids and current_length < int(max_sequence_length):
+        with inference_autocast(audio.device, autocast_dtype):
+            logits, past_key_values = model.decode(
+                memory,
+                decoder_input,
+                use_cache=True,
+                past_key_values=past_key_values,
+            )
+        next_logits = logits[:, -1].float()
+        allowed = torch.stack(
+            [state.allowed(next_logits.device) for state in states],
+            dim=0,
+        )
+        masked_logits = next_logits.masked_fill(~allowed, float("-inf"))
+        next_tokens = masked_logits.argmax(dim=-1)
+        if step_callback is not None:
+            step_callback(current_length, active_sample_ids, next_logits, masked_logits)
+        next_token_values = next_tokens.tolist()
+        keep_positions = []
+        for position, (sample_id, state, stop_time, token) in enumerate(
+            zip(active_sample_ids, states, stop_times, next_token_values)
+        ):
+            output_tokens[sample_id].append(int(token))
+            finished = state.update(token)
+            if (
+                not finished
+                and stop_time is not None
+                and tokenizer.time_token_start <= int(token) < tokenizer.time_token_end
+                and tokenizer.token_to_time_id(token) / tokenizer.time_hz >= stop_time
+            ):
+                output_tokens[sample_id].append(tokenizer.eos_token)
+                finished = True
+            if not finished:
+                keep_positions.append(position)
+        current_length += 1
+        if progress_callback is not None and current_length % 64 == 0:
+            progress_callback(current_length)
+        if not keep_positions:
+            break
+
+        old_batch_size = len(active_sample_ids)
+        decoder_input = next_tokens[:, None]
+        if len(keep_positions) == old_batch_size:
+            continue
+
+        keep = torch.tensor(keep_positions, dtype=torch.long, device=audio.device)
+        active_sample_ids = [active_sample_ids[position] for position in keep_positions]
+        states = [states[position] for position in keep_positions]
+        stop_times = [stop_times[position] for position in keep_positions]
+        memory = memory.index_select(0, keep)
+        past_key_values = select_cache_batch(past_key_values, keep, old_batch_size)
+        decoder_input = decoder_input.index_select(0, keep)
+
+    for tokens in output_tokens:
+        if tokens[-1] != tokenizer.eos_token:
+            tokens.append(tokenizer.eos_token)
+    return [torch.tensor(tokens, dtype=torch.long) for tokens in output_tokens]
+
+
+@torch.inference_mode()
+def constrained_prompt_generate(
+    model,
+    audio,
+    prompts,
+    max_sequence_length,
+    prefix_tokens=None,
+    autocast_dtype=torch.bfloat16,
+    stop_time_seconds=None,
+    progress_callback=None,
+    memory=None,
+    step_callback=None,
+):
+    if audio.shape[0] != 1:
+        raise ValueError(
+            "constrained_prompt_generate expects batch size 1; "
+            "use constrained_prompt_generate_batch for batched inference"
+        )
+    return constrained_prompt_generate_batch(
+        model,
+        audio,
+        prompts,
+        max_sequence_length,
+        prefix_tokens=prefix_tokens,
+        autocast_dtype=autocast_dtype,
+        stop_time_seconds=stop_time_seconds,
+        progress_callback=progress_callback,
+        memory=memory,
+        step_callback=step_callback,
+    )[0]
+
+
+def decode_generated_tokens(tokenizer, tokens, song_id, window_index=None):
+    try:
+        return tokenizer.decode_sequence(tokens, strict=True), None
+    except ValueError as exc:
+        recoverable_errors = (
+            "empty event at subbeat",
+            "belongs to inactive output field",
+        )
+        if not any(message in str(exc) for message in recoverable_errors):
+            raise
+        decoded = tokenizer.decode_sequence(tokens, strict=False)
+        warning = {
+            "song_id": song_id,
+            "warning": "strict decode failed; recovered in non-strict decode",
+            "error": str(exc),
+        }
+        if window_index is not None:
+            warning["window_index"] = int(window_index)
+        return decoded, warning
+
+
+def event_time_map(decoded, target_seconds):
+    anchors = []
+    for event in decoded["events"]:
+        value = event["values"].get("timestamp")
+        if value is not None:
+            anchors.append((int(event["subbeat"]), float(value)))
+    if not anchors:
+        return lambda step: min(float(target_seconds), max(0.0, float(step) * 0.125))
+    anchors = sorted(dict(anchors).items())
+    steps = np.asarray([item[0] for item in anchors], dtype=np.float64)
+    times = np.asarray([item[1] for item in anchors], dtype=np.float64)
+    if len(anchors) >= 2:
+        step_seconds = float(np.median(np.diff(times) / np.maximum(np.diff(steps), 1)))
+        if not np.isfinite(step_seconds) or step_seconds <= 0:
+            step_seconds = 0.125
+    else:
+        step_seconds = 0.125
+
+    def lookup(step):
+        step = float(step)
+        if step <= steps[0]:
+            return float(np.clip(times[0] + (step - steps[0]) * step_seconds, 0, target_seconds))
+        if step >= steps[-1]:
+            return float(np.clip(times[-1] + (step - steps[-1]) * step_seconds, 0, target_seconds))
+        return float(np.interp(step, steps, times))
+
+    return lookup
+
+
+def field_text(event, tokenizer):
+    parts = []
+    for field in tokenizer.event_field_order:
+        value = event["values"].get(field)
+        if value is None:
+            continue
+        if field == "melody":
+            note_parts = []
+            for note in value:
+                duration = note["duration_bin"]
+                note_parts.append(
+                    f"pitch={note['pitch']}:track={note['track']}:dur_bin={duration}:dur_steps={note['duration_steps']}"
+                )
+            parts.append("melody=[" + ",".join(note_parts) + "]")
+        elif isinstance(value, dict):
+            parts.append(field + "=" + ",".join(f"{k}:{v}" for k, v in value.items()))
+        else:
+            parts.append(f"{field}={value}")
+    return "; ".join(parts)
+
+
+def event_start_time(event, time_lookup):
+    if "time" in event:
+        return float(event["time"])
+    return float(time_lookup(event["subbeat"]))
+
+
+def write_events_tsv(decoded, tokenizer, time_lookup, path):
+    with Path(path).open("w", encoding="utf-8") as f:
+        f.write("event_index\tsubbeat\ttime\tfields\ttokens\n")
+        for index, event in enumerate(decoded["events"]):
+            token_text = " ".join(
+                tokenizer.describe(token)
+                for field in tokenizer.event_field_order
+                for token in event["tokens_by_field"].get(field, ())
+            )
+            f.write(
+                f"{index}\t{event['subbeat']}\t{event_start_time(event, time_lookup):.6f}\t"
+                f"{field_text(event, tokenizer)}\t{token_text}\n"
+            )
+
+
+def clone_decoded_event(event):
+    return {
+        "subbeat": int(event["subbeat"]),
+        "tokens_by_field": {
+            field: [int(token) for token in tokens]
+            for field, tokens in event["tokens_by_field"].items()
+        },
+        "values": copy.deepcopy(event["values"]),
+    }
+
+
+def refresh_event_values(event, tokenizer, prompts):
+    event["values"] = {
+        field: tokenizer._decode_field(field, tokens, prompts)
+        for field, tokens in event["tokens_by_field"].items()
+        if tokens
+    }
+
+
+def set_event_local_timestamp(event, tokenizer, local_time):
+    time_id = int(round(float(local_time) * tokenizer.time_hz))
+    time_id = max(0, min(time_id, tokenizer.n_time_tokens - 1))
+    event["tokens_by_field"]["timestamp"] = [tokenizer.time_id_to_token(time_id)]
+
+
+def active_context_before(events, tokenizer, time_abs):
+    state = {}
+    for event in events:
+        event_time = event.get("time")
+        if event_time is None or float(event_time) > float(time_abs) + 1e-6:
+            continue
+        for field in ("structure", "key", "chord"):
+            tokens = event["tokens_by_field"].get(field)
+            if tokens:
+                state[field] = [int(token) for token in tokens]
+        rhythm_tokens = event["tokens_by_field"].get("rhythm", ())
+        meter_tokens = [
+            int(token)
+            for token in rhythm_tokens
+            if tokenizer.token_type(token) == "meter"
+        ]
+        if meter_tokens:
+            state["meter"] = meter_tokens[:1]
+    return state
+
+
+def apply_prefix_context(event, context, tokenizer, prompts):
+    for field in ("structure", "key", "chord"):
+        if field not in event["tokens_by_field"] and field in context:
+            event["tokens_by_field"][field] = list(context[field])
+
+    rhythm_tokens = list(event["tokens_by_field"].get("rhythm", ()))
+    has_meter = any(tokenizer.token_type(token) == "meter" for token in rhythm_tokens)
+    has_eighth = any(
+        tokenizer.token_type(token) == "eighth_position" for token in rhythm_tokens
+    )
+    if has_eighth and not has_meter and "meter" in context:
+        event["tokens_by_field"]["rhythm"] = list(context["meter"]) + rhythm_tokens
+
+    refresh_event_values(event, tokenizer, prompts)
+
+
+def build_overlap_prefix_tokens(
+    stitched_events,
+    tokenizer,
+    prompts,
+    window_start,
+    prefix_end,
+):
+    eps = 1e-4
+    source_events = [
+        event
+        for event in stitched_events
+        if float(window_start) - eps <= float(event.get("time", -1.0)) < float(prefix_end) - eps
+    ]
+    source_events.sort(
+        key=lambda event: (
+            int(
+                event.get(
+                    "global_subbeat",
+                    event.get("source_subbeat", event["subbeat"]),
+                )
+            ),
+            float(event.get("time", 0.0)),
+        )
+    )
+    first_beat_index = next(
+        (
+            index
+            for index, event in enumerate(source_events)
+            if "timestamp" in event["values"] or "rhythm" in event["values"]
+        ),
+        None,
+    )
+    if first_beat_index is None:
+        return None, None, None
+
+    source_events = source_events[first_beat_index:]
+    base_subbeat = int(
+        source_events[0].get(
+            "global_subbeat",
+            source_events[0].get("source_subbeat", source_events[0]["subbeat"]),
+        )
+    )
+    context = active_context_before(
+        stitched_events,
+        tokenizer,
+        source_events[0]["time"],
+    )
+    prefix_events = []
+    for source in source_events:
+        event = clone_decoded_event(source)
+        source_subbeat = int(
+            source.get(
+                "global_subbeat",
+                source.get("source_subbeat", source["subbeat"]),
+            )
+        )
+        event["subbeat"] = max(0, source_subbeat - base_subbeat)
+        if "timestamp" in event["tokens_by_field"]:
+            set_event_local_timestamp(
+                event,
+                tokenizer,
+                float(source["time"]) - float(window_start),
+            )
+        refresh_event_values(event, tokenizer, prompts)
+        prefix_events.append(event)
+
+    apply_prefix_context(prefix_events[0], context, tokenizer, prompts)
+    prefix_decoded = {
+        "schema_version": tokenizer.schema_version,
+        "prompts": prompts,
+        "events": prefix_events,
+        "has_eos": False,
+    }
+    return (
+        prefix_decoded,
+        tokenizer.encode_decoded_sequence(prefix_decoded),
+        base_subbeat,
+    )
+
+
+def stitched_window_events(
+    decoded,
+    time_lookup,
+    window_start,
+    accept_start,
+    accept_end,
+    song_duration,
+    window_index,
+    global_subbeat_base=0,
+):
+    accepted = []
+    eps = 1e-4
+    for event in decoded["events"]:
+        local_time = float(time_lookup(event["subbeat"]))
+        abs_time = float(window_start) + local_time
+        if abs_time < float(accept_start) - eps:
+            continue
+        if abs_time >= float(accept_end) - eps or abs_time >= float(song_duration) - eps:
+            continue
+
+        output = clone_decoded_event(event)
+        output["time"] = float(np.clip(abs_time, 0.0, song_duration))
+        output["window_index"] = int(window_index)
+        output["window_start"] = float(window_start)
+        output["source_subbeat"] = int(event["subbeat"])
+        output["global_subbeat"] = int(global_subbeat_base) + int(event["subbeat"])
+        if "timestamp" in output["values"]:
+            output["values"]["timestamp"] = output["time"]
+
+        notes = output["values"].get("melody")
+        if notes is not None:
+            fixed_notes = []
+            for note in notes:
+                fixed_note = copy.deepcopy(note)
+                duration_steps = int(fixed_note["duration_steps"])
+                local_end = float(time_lookup(int(event["subbeat"]) + duration_steps))
+                end_time = float(window_start) + local_end
+                end_time = min(
+                    float(song_duration),
+                    max(output["time"] + 0.04, end_time),
+                )
+                fixed_note["end_time"] = end_time
+                fixed_notes.append(fixed_note)
+            output["values"]["melody"] = fixed_notes
+        accepted.append(output)
+    return accepted
+
+
+def write_window_tokens(path, windows, tokenizer):
+    with Path(path).open("w", encoding="utf-8") as f:
+        for window in windows:
+            f.write(
+                f"# window_index={window['window_index']} "
+                f"start={window['start']:.6f} end={window['end']:.6f} "
+                f"prefix_end={window['prefix_end']:.6f} "
+                f"accept=[{window['accept_start']:.6f},{window['accept_end']:.6f}) "
+                f"generation_stop={window['generation_stop']} "
+                f"prefix_tokens={window['prefix_tokens']} "
+                f"tokens={int(window['tokens'].numel())}\n"
+            )
+            for index, token in enumerate(window["tokens"].tolist()):
+                f.write(f"{index}\t{token}\t{tokenizer.describe(token)}\n")
+            f.write("\n")
+
+
+@torch.inference_mode()
+def generate(model, input_values, prompts=None, *, attention_mask=None, max_length=None,
+             max_new_tokens=None, prefix_tokens=None,
+             autocast_dtype=torch.bfloat16, stop_time_seconds=None,
+             return_dict_in_generate=False, output_logits=False, output_scores=False,
+             progress_callback=None):
+    """Generate symbolic token sequences with the model's event grammar.
+
+    Inputs are 24 kHz waveforms [batch, samples]. Scores/logits are per generated
+    step, after the prompt prefix, with completed batch items filled by NaNs.
+    """
+    from transformers.utils import ModelOutput
+    if input_values.ndim == 1:
+        input_values = input_values.unsqueeze(0)
+        if attention_mask is not None and attention_mask.ndim == 1:
+            attention_mask = attention_mask.unsqueeze(0)
+    input_values = input_values.to(next(model.parameters()).device)
+    prompts = model.tokenizer.normalize_prompts(prompts or FULL_TASK_PROMPTS)
+    prefix = list(prefix_tokens) if prefix_tokens is not None else model.tokenizer.prompt_prefix(prompts)
+    prefix_length = len(prefix) - (1 if prefix and prefix[-1] == model.tokenizer.eos_token else 0)
+    if max_new_tokens is not None:
+        if max_length is not None:
+            raise ValueError("Specify max_new_tokens or max_length, not both.")
+        if not isinstance(max_new_tokens, int) or isinstance(max_new_tokens, bool) or max_new_tokens < 1:
+            raise ValueError("max_new_tokens must be a positive integer.")
+        max_length = prefix_length + max_new_tokens
+    limit = model.max_output_seq_len if max_length is None else max_length
+    if not isinstance(limit, int) or isinstance(limit, bool) or not prefix_length < limit <= model.max_output_seq_len:
+        raise ValueError("The token limit must exceed the prefix length and fit the decoder context.")
+    memory = None
+    if attention_mask is not None:
+        with inference_autocast(input_values.device, autocast_dtype):
+            memory = model.get_audio_features(input_values, attention_mask=attention_mask).encoder_last_hidden_state
+    raw, scores, positions = [], [], []
+    batch_size = input_values.shape[0]
+    def capture(position, ids, logits, masked):
+        positions.append(position)
+        for enabled, values, output in ((output_logits, logits, raw), (output_scores, masked, scores)):
+            if enabled:
+                row = torch.full((batch_size, values.shape[-1]), float('nan'), dtype=torch.float32)
+                row[ids] = values.detach().cpu()
+                output.append(row)
+    tokens = constrained_prompt_generate_batch(
+        model, input_values, prompts, limit,
+        prefix_tokens=prefix_tokens, autocast_dtype=autocast_dtype,
+        stop_time_seconds=stop_time_seconds, progress_callback=progress_callback,
+        step_callback=capture if output_logits or output_scores else None,
+        memory=memory,
+    )
+    sequences = torch.nn.utils.rnn.pad_sequence(tokens, batch_first=True, padding_value=model.tokenizer.pad_token)
+    if return_dict_in_generate or output_logits or output_scores:
+        return ModelOutput(sequences=sequences, logits=tuple(raw) if output_logits else None,
+                           scores=tuple(scores) if output_scores else None,
+                           token_positions=torch.tensor(positions, dtype=torch.long))
+    return sequences

infer.py

@@ -0,0 +1,78 @@
+"""Transcribe a music recording with SheetSage2."""
+import argparse
+from pathlib import Path
+import sys
+
+SCRIPT_DIR = Path(__file__).absolute().parent
+sys.path.insert(0, str(SCRIPT_DIR))
+
+
+def main():
+    parser = argparse.ArgumentParser(description="SheetSage2: music audio to ABC, MIDI, annotations and features")
+    parser.add_argument("audio", type=Path)
+    parser.add_argument("--output", type=Path, default=Path("output"))
+    local = SCRIPT_DIR
+    parser.add_argument("--model", default=str(local) if (local / "config.json").exists() else "m-a-p/SheetSage2")
+    parser.add_argument("--revision", help="Model and code commit on Hugging Face")
+    parser.add_argument("--device", default="auto")
+    parser.add_argument("--dtype", choices=("bf16", "fp32"), default="bf16")
+    parser.add_argument("--preset", choices=("default", "paper"), default="default")
+    parser.add_argument("--max-seconds", type=float)
+    parser.add_argument("--overlap", type=float)
+    parser.add_argument("--lookahead", type=float)
+    parser.add_argument("--prompts", nargs="+")
+    parser.add_argument("--melody-only", action="store_true",
+                        help="Keep vocal and instrumental melodies; omit chords from ABC and playback")
+    parser.add_argument("--export-logits", action="store_true")
+    parser.add_argument("--export-scores", action="store_true")
+    parser.add_argument("--export-embeddings", action="store_true")
+    parser.add_argument("--all-layers", action="store_true", help="Also export all 24 MERT block features")
+    parser.add_argument("--render-audio", action="store_true")
+    parser.add_argument("--render-score", nargs="?", const="pdf", default=False, help="pdf,svg,png (default: pdf)")
+    parser.add_argument("--render-parts", default="mix", help="mix,melody,vocal,instrumental,chords,all")
+    parser.add_argument("--local-files-only", action="store_true")
+    args = parser.parse_args()
+    if args.render_audio or args.render_score:
+        from rendering_sheetsage2 import validate_render_options
+        try:
+            validate_render_options(audio=args.render_audio, score=args.render_score, parts=args.render_parts)
+        except ValueError as exc:
+            parser.error(str(exc))
+    import torch
+    from transformers import AutoModel
+    torch.set_num_threads(min(4, torch.get_num_threads()))
+    device = "cuda" if torch.cuda.is_available() else "cpu" if args.device == "auto" else args.device
+    if args.device != "auto":
+        device = args.device
+    model = AutoModel.from_pretrained(
+        args.model, revision=args.revision, code_revision=args.revision,
+        local_files_only=args.local_files_only, trust_remote_code=True,
+    ).eval().to(device)
+    def progress(value):
+        if value["stage"] == "encoding":
+            print(f"Window {value['window']}/{value['windows']}", flush=True)
+    options = dict(dtype=args.dtype, preset=args.preset, max_seconds=args.max_seconds,
+                   overlap_seconds=args.overlap, lookahead_seconds=args.lookahead,
+                   export_logits=args.export_logits, export_scores=args.export_scores,
+                   export_embeddings=args.export_embeddings, output_hidden_states=args.all_layers,
+                   render_audio=args.render_audio, render_score=args.render_score,
+                   render_parts=tuple(args.render_parts.split(",")), progress=progress)
+    if args.prompts:
+        options["prompts"] = args.prompts
+    if args.melody_only:
+        options["melody_only"] = True
+    try:
+        result = model.transcribe(args.audio, output_dir=args.output, **options)
+    except (ValueError, RuntimeError, FileNotFoundError) as exc:
+        parser.exit(1, f"SheetSage2: {exc}\n")
+    if args.melody_only and (result.get("abc_error") or not result.get("abc")):
+        reason = result.get("abc_error") or "no ABC score was produced"
+        parser.exit(1, f"SheetSage2: melody-only ABC unavailable: {reason}. "
+                       f"Transcription outputs were saved to {args.output.resolve()}.\n")
+    print(f"Saved transcription to {args.output.resolve()}")
+    if result.get("abc_error"):
+        print(f"ABC unavailable: {result['abc_error']}. MIDI and annotations were saved.")
+
+
+if __name__ == "__main__":
+    main()

io_sheetsage2.py

@@ -0,0 +1,67 @@
+import os
+import stat
+import tempfile
+from contextlib import contextmanager
+from pathlib import Path
+
+
+def _target_path(path) -> Path:
+    target = Path(path)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    return target
+
+
+def _flush_path(path: Path) -> None:
+    with path.open("rb+") as handle:
+        os.fsync(handle.fileno())
+
+
+def _replacement_mode(target: Path) -> int:
+    try:
+        return stat.S_IMODE(target.stat().st_mode)
+    except FileNotFoundError:
+        mask = os.umask(0)
+        os.umask(mask)
+        return 0o666 & ~mask
+
+
+@contextmanager
+def atomic_output_path(path):
+    target = _target_path(path)
+    mode = _replacement_mode(target)
+    fd, tmp_name = tempfile.mkstemp(
+        # Keep the temporary basename independent of the final basename.  Some
+        # annotation IDs are already close to NAME_MAX; repeating the target
+        # name here made an otherwise valid final path fail with ENAMETOOLONG.
+        prefix=".tmp_",
+        suffix=".tmp",
+        dir=str(target.parent),
+    )
+    os.close(fd)
+    tmp_path = Path(tmp_name)
+    try:
+        yield str(tmp_path)
+        os.chmod(tmp_path, mode)
+        _flush_path(tmp_path)
+        os.replace(tmp_path, target)
+    except Exception:
+        try:
+            tmp_path.unlink()
+        except FileNotFoundError:
+            pass
+        raise
+
+
+def atomic_write_text(path, text: str, encoding: str = "utf-8", newline: str = "\n") -> str:
+    with atomic_output_path(path) as tmp_path:
+        with open(tmp_path, "w", encoding=encoding, newline=newline) as handle:
+            handle.write(text)
+            handle.flush()
+            os.fsync(handle.fileno())
+    return str(path)
+
+
+def atomic_write_pretty_midi(midi, path) -> str:
+    with atomic_output_path(path) as tmp_path:
+        midi.write(tmp_path)
+    return str(path)

labels_sheetsage2.py

@@ -0,0 +1,29 @@
+
+
+
+STRUCTURE_LABELS = ['silence', 'intro', 'outro', 'verse', 'chorus', 'bridge', 'pre-chorus', 'post-chorus',
+                                'interlude', 'fade-out', 'loop', 'rap', 'preshot', 'irregular']
+
+
+STRUCTURE_LABELS = ['silence', 'intro', 'outro', 'verse', 'chorus', 'bridge', 'pre-chorus', 'post-chorus',
+                               'interlude', 'fade-out', 'loop', 'rap', 'preshot', 'irregular', 'instrumental',
+                               'intro and verse', 'pre-chorus and chorus', 'verse and pre-chorus', 'solo', 'theme', 'development', 'variation', 'pre-outro']
+
+
+MIREX_STRUCTURE_LABEL_REDUCTION = {
+    'silence': 'silence',
+    'intro': 'intro',
+    'outro': 'outro',
+    'verse': 'verse',
+    'chorus': 'chorus',
+    'bridge': 'bridge',
+    'pre-chorus': 'verse',
+    'post-chorus': 'verse',
+    'interlude': 'inst',
+    'inst': 'inst',
+    'fade-out': 'outro',
+    'loop': 'chorus',
+    'rap': 'verse',
+    'preshot': 'inst',
+    'irregular': 'verse',
+}

midi_sheetsage2.py

@@ -0,0 +1,92 @@
+"""Original-time MIDI playback and a separate score-to-audio measure map."""
+import json
+from io import BytesIO
+from pathlib import Path
+
+import mir_eval.chord
+import numpy as np
+import pretty_midi
+
+from .io_sheetsage2 import atomic_write_text
+
+
+def chord_pitches(label):
+    if label in {"N", "X", "?"}:
+        return []
+    root, bitmap, bass = mir_eval.chord.encode(label, reduce_extended_chords=True)
+    if root < 0:
+        return []
+    # Keep inversion bass below the chord; no ABC chord-name reinterpretation.
+    upper = [48 + root + int(interval) for interval in np.flatnonzero(bitmap > 0)]
+    return sorted(set([36 + (root + bass) % 12] + upper))
+
+
+def measure_map(score, duration):
+    rows, position = [], 0.0
+    for measure in score.measures:
+        length = measure.abc_numerator / measure.abc_denominator
+        actual = measure.numerator / measure.denominator
+        start = float(score.beats[measure.start_beat].time)
+        end = float(score.beats[measure.end_beat].time)
+        rows.append(dict(index=measure.index, start=start, end=min(end, duration),
+                         score_start=position, score_end=position + length,
+                         leading_rest=length - actual if measure.pad_before else 0.0,
+                         trailing_rest=length - actual if not measure.pad_before else 0.0))
+        position += length
+    return rows
+
+
+def midi_bytes(midi):
+    """Serialize a PrettyMIDI object without touching the filesystem."""
+    stream = BytesIO()
+    midi.write(stream)
+    return stream.getvalue()
+
+
+def build_playback(melody_midi, chord_rows, score, duration):
+    """Return playback metadata and MIDI bytes, preserving MIDI tick rounding."""
+    if isinstance(melody_midi, pretty_midi.PrettyMIDI):
+        melody_midi = midi_bytes(melody_midi)
+    midi = pretty_midi.PrettyMIDI(BytesIO(melody_midi))
+    chord_track = pretty_midi.Instrument(0, name="Chords")
+    warnings = []
+    for start, end, label in chord_rows:
+        start, end = max(0.0, float(start)), min(duration, float(end))
+        try:
+            pitches = chord_pitches(label)
+        except mir_eval.chord.InvalidChordException as exc:
+            warnings.append(f"Chord playback skipped {label}: {exc}")
+            continue
+        # Rearticulate long chord spans at downbeats, including repeated bars.
+        downbeats = [b.time for b in score.beats if b.beat_id == 1] if score is not None else []
+        cuts = [start] + [time for time in downbeats if start < time < end] + [end]
+        for a, b in zip(cuts, cuts[1:]):
+            if b <= a:
+                continue
+            for pitch in pitches:
+                chord_track.notes.append(pretty_midi.Note(48, pitch, a, b))
+    midi.instruments.append(chord_track)
+    transcription = midi_bytes(midi)
+    chords = pretty_midi.PrettyMIDI(resolution=midi.resolution)
+    chords.instruments.append(chord_track)
+    midis = {"transcription": transcription, "chords": midi_bytes(chords)}
+    # Decode the serialized bytes, so playback follows the returned MIDI exactly.
+    midi = pretty_midi.PrettyMIDI(BytesIO(transcription))
+    tracks = [dict(name=instrument.name, program=int(instrument.program),
+                   notes=[dict(pitch=int(n.pitch), start=float(n.start), end=float(n.end), velocity=int(n.velocity))
+                          for n in instrument.notes]) for instrument in midi.instruments]
+    data = dict(version=1, duration=duration, midi="transcription.mid", tracks=tracks,
+                measures=measure_map(score, duration) if score is not None else [], warnings=warnings)
+    return data, midis
+
+
+def export_playback(directory, score, duration):
+    """Write playback files for an existing directory of exported annotations."""
+    directory = Path(directory)
+    chord_path = directory / "chord.lab"
+    rows = [line.split(maxsplit=2) for line in chord_path.read_text(encoding="utf-8").splitlines()] if chord_path.exists() else []
+    data, midis = build_playback((directory / "melody.mid").read_bytes(), rows, score, duration)
+    for name, content in midis.items():
+        (directory / f"{name}.mid").write_bytes(content)
+    atomic_write_text(directory / "playback.json", json.dumps(data, indent=2))
+    return data

model.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:b235f68091a5f5b644000f2b5acb57d1e70432aca2b34ab1b9cf27236e1f4274
+size 228738564

modeling_mert2.py

@@ -0,0 +1,361 @@
+"""Standalone MERT2 waveform-to-representation inference."""
+
+from dataclasses import dataclass
+from typing import Optional, Tuple
+
+import torch
+from torch import nn
+from torch.nn import functional as F
+from torchaudio.transforms import AmplitudeToDB, MelScale, Spectrogram
+from transformers import PreTrainedModel
+from transformers.utils import ModelOutput
+
+from .configuration_mert2 import MERT2Config
+
+
+@dataclass
+class MERT2ModelOutput(ModelOutput):
+    """Frame representations and their validity mask.
+
+    ``hidden_states`` contains one tensor per Conformer block, without an input
+    embedding. ``feature_attention_mask`` is True at valid output frames.
+    """
+
+    last_hidden_state: Optional[torch.FloatTensor] = None
+    hidden_states: Optional[Tuple[torch.FloatTensor, ...]] = None
+    feature_attention_mask: Optional[torch.BoolTensor] = None
+
+
+class MERT2MelFrontend(nn.Module):
+    """Power log-mel features with fixed, checkpoint-specific normalization."""
+
+    def __init__(self, config):
+        super().__init__()
+        # Filter construction requires real tensors even during meta loading.
+        with torch.device("cpu"):
+            self.register_buffer("mel_mean", torch.zeros(config.num_mel_bins, dtype=torch.float32))
+            self.register_buffer("mel_std", torch.ones(config.num_mel_bins, dtype=torch.float32))
+            self.spectrogram = Spectrogram(
+                n_fft=config.n_fft,
+                win_length=config.win_length,
+                hop_length=config.hop_length,
+                power=2.0,
+            ).float()
+            self.mel_scale = MelScale(
+                n_mels=config.num_mel_bins,
+                sample_rate=config.sampling_rate,
+                n_stft=config.n_fft // 2 + 1,
+            ).float()
+        self.amplitude_to_db = AmplitudeToDB(stype="power", top_db=None)
+
+    def _apply(self, fn, recurse=True):
+        # Preserve the original float32 values, including on model.half().
+        saved = [(module, name, value) for module in self.modules() for name, value in module._buffers.items() if value is not None]
+        super()._apply(fn, recurse=recurse)
+        for module, name, original in saved:
+            current = module._buffers[name]
+            if original.is_floating_point():
+                module._buffers[name] = (
+                    current.float() if original.is_meta else original.to(device=current.device, dtype=torch.float32)
+                )
+        return self
+
+    @torch.no_grad()
+    def forward(self, waveform):
+        with torch.autocast(device_type=waveform.device.type, enabled=False):
+            spectrum = self.spectrogram(waveform.float())
+            mel = self.amplitude_to_db(self.mel_scale(spectrum))
+            mel = mel[..., :-1].transpose(-1, -2)
+            return (mel - self.mel_mean) / self.mel_std.clamp_min(1e-5)
+
+
+class Transpose(nn.Module):
+    def forward(self, hidden_states):
+        return hidden_states.transpose(1, 2)
+
+
+class GlobalResponseNorm(nn.Module):
+    def __init__(self, dim):
+        super().__init__()
+        self.weight = nn.Parameter(torch.zeros(1, 1, dim))
+        self.bias = nn.Parameter(torch.zeros(1, 1, dim))
+
+    def forward(self, hidden_states):
+        magnitude = torch.norm(hidden_states, p=2, dim=1, keepdim=True)
+        normalized = magnitude / (magnitude.mean(dim=-1, keepdim=True) + 1e-6)
+        return self.weight * (hidden_states * normalized) + self.bias + hidden_states
+
+
+class ConvNextLayer(nn.Module):
+    def __init__(self, dim, eps):
+        super().__init__()
+        self.depthwise_block = nn.Sequential(
+            Transpose(), nn.Conv1d(dim, dim, 7, padding=3, groups=dim), Transpose()
+        )
+        self.pointwise_block = nn.Sequential(
+            nn.LayerNorm(dim, eps=eps),
+            nn.Linear(dim, 4 * dim),
+            nn.GELU(),
+            GlobalResponseNorm(4 * dim),
+            nn.Linear(4 * dim, dim),
+        )
+
+    def forward(self, hidden_states):
+        return hidden_states + self.pointwise_block(self.depthwise_block(hidden_states))
+
+
+class ConvNextBlock(nn.Module):
+    def __init__(self, in_channels, out_channels, stride, depth, eps):
+        super().__init__()
+        self.resampling_layer = (
+            nn.Sequential(
+                nn.LayerNorm(in_channels, eps=eps),
+                Transpose(),
+                nn.Conv1d(in_channels, out_channels, 2, stride=stride),
+                Transpose(),
+            )
+            if in_channels != out_channels or stride > 1 else nn.Identity()
+        )
+        self.convnext_layers = nn.Sequential(*[ConvNextLayer(out_channels, eps) for _ in range(depth)])
+
+    def forward(self, hidden_states):
+        return self.convnext_layers(self.resampling_layer(hidden_states))
+
+
+class RotaryEmbedding(nn.Module):
+    def __init__(self, config):
+        super().__init__()
+        self.head_dim = config.hidden_size // config.num_attention_heads
+        self.base = config.rotary_embedding_base
+        with torch.device("cpu"):
+            inverse_frequency = 1.0 / (
+                self.base ** (torch.arange(0, self.head_dim, 2, dtype=torch.float32) / self.head_dim)
+            )
+        self.register_buffer("inv_freq", inverse_frequency, persistent=False)
+        self._sequence_length = 0
+        self._cache_device = None
+        self._cos = None
+        self._sin = None
+
+    def _apply(self, fn, recurse=True):
+        original = self.inv_freq
+        super()._apply(fn, recurse=recurse)
+        self.inv_freq = original.to(device=self.inv_freq.device, dtype=torch.float32)
+        return self
+
+    def forward(self, hidden_states):
+        length = hidden_states.shape[1]
+        if self._cos is None or self._cache_device != hidden_states.device or length > self._sequence_length:
+            positions = torch.arange(length, device=hidden_states.device, dtype=self.inv_freq.dtype)
+            frequencies = torch.einsum("i,j->ij", positions, self.inv_freq)
+            angles = torch.cat((frequencies, frequencies), dim=-1)
+            self._cos = angles.cos()[:, None, None, :]
+            self._sin = angles.sin()[:, None, None, :]
+            self._sequence_length = length
+            self._cache_device = hidden_states.device
+        return (
+            self._cos[:length].to(hidden_states.dtype).permute(1, 0, 2, 3),
+            self._sin[:length].to(hidden_states.dtype).permute(1, 0, 2, 3),
+        )
+
+
+def rotate_half(value):
+    first, second = value.chunk(2, dim=-1)
+    return torch.cat((-second, first), dim=-1)
+
+
+class SelfAttention(nn.Module):
+    def __init__(self, config):
+        super().__init__()
+        self.config = config
+        self.num_heads = config.num_attention_heads
+        self.head_dim = config.hidden_size // self.num_heads
+        self.query_proj = nn.Linear(config.hidden_size, config.hidden_size)
+        self.key_proj = nn.Linear(config.hidden_size, config.hidden_size)
+        self.value_proj = nn.Linear(config.hidden_size, config.hidden_size)
+        self.out_proj = nn.Linear(config.hidden_size, config.hidden_size)
+
+    def forward(self, hidden_states, position_embeddings):
+        batch, time, width = hidden_states.shape
+        shape = (batch, time, self.num_heads, self.head_dim)
+        query = self.query_proj(hidden_states).reshape(shape)
+        key = self.key_proj(hidden_states).reshape(shape)
+        value = self.value_proj(hidden_states).reshape(shape)
+        cos, sin = position_embeddings
+        query = query * cos + rotate_half(query) * sin
+        key = key * cos + rotate_half(key) * sin
+        if self.config._attn_implementation == "flash_attention_2":
+            if query.device.type != "cuda" or query.dtype not in (torch.float16, torch.bfloat16):
+                raise ValueError("flash_attention_2 requires CUDA and float16/bfloat16 activations; use autocast or load a reduced-precision model.")
+            try:
+                from flash_attn import flash_attn_func
+            except ImportError as error:
+                raise ImportError("Install flash-attn to use flash_attention_2, or select attn_implementation='sdpa'.") from error
+            attended = flash_attn_func(query.contiguous(), key.contiguous(), value.contiguous(), dropout_p=0.0, causal=False)
+        else:
+            attended = F.scaled_dot_product_attention(
+                query.transpose(1, 2), key.transpose(1, 2), value.transpose(1, 2), dropout_p=0.0, is_causal=False
+            ).transpose(1, 2)
+        return self.out_proj(attended.reshape(batch, time, width))
+
+
+class FeedForward(nn.Module):
+    def __init__(self, config):
+        super().__init__()
+        self.w_1 = nn.Linear(config.hidden_size, config.intermediate_size)
+        self.w_2 = nn.Linear(config.intermediate_size, config.hidden_size)
+
+    def forward(self, hidden_states):
+        return self.w_2(F.gelu(self.w_1(hidden_states)))
+
+
+class ConvolutionModule(nn.Module):
+    def __init__(self, config):
+        super().__init__()
+        width = config.hidden_size
+        kernel = config.conv_depthwise_kernel_size
+        self.layer_norm = nn.LayerNorm(width, eps=config.layer_norm_eps)
+        self.conv_block = nn.Sequential(
+            Transpose(),
+            nn.Conv1d(width, 2 * width, 1, bias=False),
+            nn.GLU(dim=1),
+            nn.Conv1d(width, width, kernel, padding=(kernel - 1) // 2, groups=width, bias=False),
+            nn.Sequential(Transpose(), nn.LayerNorm(width, eps=config.layer_norm_eps), Transpose()),
+            nn.GELU(),
+            nn.Conv1d(width, width, 1, bias=False),
+            Transpose(),
+        )
+
+    def forward(self, hidden_states):
+        return self.conv_block(self.layer_norm(hidden_states))
+
+
+class ConformerBlock(nn.Module):
+    def __init__(self, config):
+        super().__init__()
+        width, eps = config.hidden_size, config.layer_norm_eps
+        self.ffn1_layer_norm = nn.LayerNorm(width, eps=eps)
+        self.ffn1 = FeedForward(config)
+        self.attn_layer_norm = nn.LayerNorm(width, eps=eps)
+        self.attn = SelfAttention(config)
+        self.conv_module = ConvolutionModule(config)
+        self.ffn2_layer_norm = nn.LayerNorm(width, eps=eps)
+        self.ffn2 = FeedForward(config)
+        self.final_layer_norm = nn.LayerNorm(width, eps=eps)
+
+    def forward(self, hidden_states, position_embeddings):
+        hidden_states = hidden_states + 0.5 * self.ffn1(self.ffn1_layer_norm(hidden_states))
+        hidden_states = self.attn(self.attn_layer_norm(hidden_states), position_embeddings) + hidden_states
+        hidden_states = self.conv_module(hidden_states) + hidden_states
+        hidden_states = hidden_states + 0.5 * self.ffn2(self.ffn2_layer_norm(hidden_states))
+        return self.final_layer_norm(hidden_states)
+
+
+class MERT2Model(PreTrainedModel):
+    """Encode mono waveforms into 25 Hz MERT2 frame representations.
+
+    Inputs are floating-point mono waveforms sampled at ``config.sampling_rate``.
+    Do not standardize their amplitude. An optional waveform attention mask must
+    contain a prefix of ones followed by zeros. Without a mask, every input
+    sample, including any caller-provided silence or padding, is processed.
+    """
+
+    config_class = MERT2Config
+    base_model_prefix = ""
+    main_input_name = "input_values"
+    _supports_sdpa = True
+    _supports_flash_attn_2 = True
+    _no_split_modules = ["ConvNextBlock", "ConformerBlock"]
+
+    def __init__(self, config):
+        super().__init__(config)
+        if config._attn_implementation not in {"sdpa", "flash_attention_2"}:
+            raise ValueError("MERT2 supports attn_implementation='sdpa' or 'flash_attention_2'.")
+        self.feature_extractor = MERT2MelFrontend(config)
+        channels = [config.num_mel_bins] + config.subsampling_channels
+        self.subsampling_module = nn.Sequential(*[
+            ConvNextBlock(channels[i], channels[i + 1], (1, 2, 2)[i], config.subsampling_depths[i], config.subsampling_layer_norm_eps)
+            for i in range(3)
+        ])
+        self.layers = nn.ModuleList([ConformerBlock(config) for _ in range(config.num_hidden_layers)])
+        self.embed_positions = RotaryEmbedding(config)
+        self.post_init()
+
+    def _init_weights(self, module):
+        if isinstance(module, (nn.Linear, nn.Conv1d)):
+            nn.init.normal_(module.weight, mean=0.0, std=self.config.initializer_range)
+            if module.bias is not None:
+                nn.init.zeros_(module.bias)
+        elif isinstance(module, nn.LayerNorm):
+            nn.init.ones_(module.weight)
+            nn.init.zeros_(module.bias)
+
+    def _get_feat_extract_output_lengths(self, input_lengths):
+        return input_lengths // self.config.inputs_to_logits_ratio
+
+    def _encode(self, input_values, output_hidden_states):
+        mel = self.feature_extractor(input_values)
+        input_dtype = self.subsampling_module[0].convnext_layers[0].depthwise_block[1].weight.dtype
+        hidden = self.subsampling_module(mel.to(dtype=input_dtype))
+        positions = self.embed_positions(hidden)
+        states = [] if output_hidden_states else None
+        for layer in self.layers:
+            hidden = layer(hidden, positions)
+            if states is not None:
+                states.append(hidden)
+        return hidden, tuple(states) if states is not None else None
+
+    def forward(self, input_values, attention_mask=None, output_hidden_states=None, return_dict=None):
+        """Return final frames, optionally all block states, and a frame mask.
+
+        Different valid waveform lengths are encoded separately so convolution
+        and global normalization never incorporate another sample's padding.
+        Outputs are zero-padded to the longest valid feature sequence.
+        """
+        output_hidden_states = self.config.output_hidden_states if output_hidden_states is None else output_hidden_states
+        return_dict = self.config.use_return_dict if return_dict is None else return_dict
+        if input_values.ndim != 2 or not input_values.is_floating_point() or input_values.shape[0] == 0:
+            raise ValueError("input_values must be a nonempty floating-point tensor of shape [batch, samples].")
+        if input_values.shape[1] < self.config.minimum_input_samples:
+            raise ValueError(f"Each waveform must contain at least {self.config.minimum_input_samples} samples.")
+        if not torch.isfinite(input_values).all():
+            raise ValueError("input_values must contain only finite samples.")
+        batch, samples = input_values.shape
+        if attention_mask is None:
+            hidden, states = self._encode(input_values, output_hidden_states)
+            feature_mask = torch.ones(hidden.shape[:2], dtype=torch.bool, device=hidden.device)
+        else:
+            if attention_mask.shape != input_values.shape:
+                raise ValueError("attention_mask must have the same shape as input_values.")
+            attention_mask = attention_mask.to(device=input_values.device)
+            if not ((attention_mask == 0) | (attention_mask == 1)).all():
+                raise ValueError("attention_mask must contain only zeros and ones.")
+            mask = attention_mask.bool()
+            lengths = mask.sum(dim=1)
+            expected = torch.arange(samples, device=input_values.device)[None, :] < lengths[:, None]
+            if not torch.equal(mask, expected):
+                raise ValueError("attention_mask must be right padded: valid samples followed by padding.")
+            if (lengths < self.config.minimum_input_samples).any():
+                raise ValueError(f"Each waveform must contain at least {self.config.minimum_input_samples} valid samples.")
+            feature_lengths = self._get_feat_extract_output_lengths(lengths)
+            maximum = int(feature_lengths.max().item())
+            feature_mask = torch.arange(maximum, device=input_values.device)[None, :] < feature_lengths[:, None]
+            hidden, state_values = None, None
+            for length in torch.unique(lengths, sorted=True).tolist():
+                indices = torch.where(lengths == length)[0]
+                group_hidden, group_states = self._encode(input_values.index_select(0, indices)[:, :length], output_hidden_states)
+                padding = (0, 0, 0, maximum - group_hidden.shape[1])
+                if hidden is None:
+                    hidden = group_hidden.new_zeros(batch, maximum, self.config.hidden_size)
+                    if output_hidden_states:
+                        state_values = [torch.zeros_like(hidden) for _ in self.layers]
+                hidden = hidden.index_copy(0, indices, F.pad(group_hidden, padding))
+                if state_values is not None:
+                    for i, value in enumerate(group_states):
+                        state_values[i] = state_values[i].index_copy(0, indices, F.pad(value, padding))
+            states = tuple(state_values) if state_values is not None else None
+        output = MERT2ModelOutput(last_hidden_state=hidden, hidden_states=states, feature_attention_mask=feature_mask)
+        return output if return_dict else output.to_tuple()
+
+
+MERT2Model.register_for_auto_class("AutoModel")

modeling_sheetsage2.py

@@ -0,0 +1,448 @@
+"""Hugging Face SheetSage2 model with a shared MERT-v2 encoder."""
+
+from dataclasses import dataclass
+import copy
+import hashlib
+from pathlib import Path
+import shutil
+from types import SimpleNamespace
+from typing import Optional, Tuple
+
+import torch
+from torch import nn
+from torch.nn import functional as F
+from transformers import AutoModel, BartConfig, PreTrainedModel
+from transformers.models.bart.modeling_bart import BartDecoder
+from transformers.utils import ModelOutput
+from transformers.utils.hub import cached_file
+
+from .configuration_mert2 import MERT2Config
+from .modeling_mert2 import MERT2Model
+from .configuration_sheetsage2 import SheetSage2Config
+from .tokenization_sheetsage2 import SheetSage2Tokenizer
+
+
+PROJECTIONS = ("query_proj", "key_proj", "value_proj", "out_proj")
+BASE_CODE_HASHES = {
+    "configuration_mert2.py": "77b53ec9d7ee31a599d744fb006e812c7eeaf7390deb46e2f460cf8c17b00bd6",
+    "modeling_mert2.py": "b1a3174e5649c4b26b0c90d8626f0adacfbbba111a58ed3bb72ad651945a2f5c",
+}
+
+
+def _hf_relative_dependencies():
+    # Transformers 4.45 copies direct imports into a fresh local module cache.
+    from .audio_sheetsage2 import load_audio
+    from .durations_sheetsage2 import DURATION_TEMPLATES
+    from .exports_sheetsage2 import export_result
+    from .io_sheetsage2 import atomic_write_text
+    from .labels_sheetsage2 import STRUCTURE_LABELS
+    from .midi_sheetsage2 import export_playback
+    from .notation_sheetsage2 import generate_abc_from_exports
+    from .rendering_sheetsage2 import render_outputs
+    from .schema_sheetsage2 import get_prompt_multitask_schema
+    from .tensors_sheetsage2 import WindowTensorWriter
+
+
+def _sha256(path):
+    digest = hashlib.sha256()
+    with Path(path).open("rb") as stream:
+        for block in iter(lambda: stream.read(8 << 20), b""):
+            digest.update(block)
+    return digest.hexdigest()
+
+
+@dataclass
+class SheetSage2EncoderOutput(ModelOutput):
+    """Frame features. Block states exclude the separately returned input state."""
+
+    encoder_last_hidden_state: Optional[torch.FloatTensor] = None
+    backbone_last_hidden_state: Optional[torch.FloatTensor] = None
+    mixed_hidden_state: Optional[torch.FloatTensor] = None
+    input_hidden_state: Optional[torch.FloatTensor] = None
+    backbone_hidden_states: Optional[Tuple[torch.FloatTensor, ...]] = None
+    feature_attention_mask: Optional[torch.BoolTensor] = None
+
+    @property
+    def last_hidden_state(self):
+        return self.encoder_last_hidden_state
+
+
+@dataclass
+class SheetSage2Output(ModelOutput):
+    logits: Optional[torch.FloatTensor] = None
+    past_key_values: Optional[Tuple] = None
+    decoder_hidden_states: Optional[Tuple[torch.FloatTensor, ...]] = None
+    encoder_last_hidden_state: Optional[torch.FloatTensor] = None
+    backbone_last_hidden_state: Optional[torch.FloatTensor] = None
+    mixed_hidden_state: Optional[torch.FloatTensor] = None
+    input_hidden_state: Optional[torch.FloatTensor] = None
+    backbone_hidden_states: Optional[Tuple[torch.FloatTensor, ...]] = None
+    feature_attention_mask: Optional[torch.BoolTensor] = None
+
+
+class AttentionAdapter(nn.Module):
+    def __init__(self, width, rank):
+        super().__init__()
+        self.lora_A = nn.Linear(width, rank, bias=False)
+        self.lora_B = nn.Linear(rank, width, bias=False)
+
+
+class EncoderAdapters(nn.Module):
+    def __init__(self, config):
+        super().__init__()
+        self.layers = nn.ModuleList()
+        for _ in range(config.backbone_config["num_hidden_layers"]):
+            layer = nn.Module()
+            layer.attn = nn.Module()
+            for name in PROJECTIONS:
+                setattr(layer.attn, name, AttentionAdapter(config.backbone_config["hidden_size"], config.lora_rank))
+            self.layers.append(layer)
+
+
+class SheetSage2Model(PreTrainedModel):
+    """Audio-to-symbolic model, with optional frame and decoder representations.
+
+    ``from_pretrained`` loads the pinned MERT-v2 parent and merges attention
+    adapters in float32. ``save_pretrained`` writes an independent merged model.
+    ``forward`` returns raw vocabulary logits; grammar-masked generation scores
+    are available separately through ``generate(output_scores=True)``.
+    """
+
+    config_class = SheetSage2Config
+    base_model_prefix = ""
+    main_input_name = "input_values"
+    _supports_sdpa = True
+    _tied_weights_keys = ["decoder.embed_tokens.weight", "output_projection.weight"]
+    _no_split_modules = ["ConformerBlock", "BartDecoderLayer"]
+
+    def __init__(self, config):
+        super().__init__(config)
+        self.hparams = SimpleNamespace(input_audio_length=config.input_audio_length, time_hz=config.time_hz)
+        self.max_output_seq_len = config.max_output_seq_len
+        self.tokenizer = SheetSage2Tokenizer(
+            config.input_audio_length, config.time_hz, config.tokenizer_schema_version,
+            expected_fingerprint=config.tokenizer_fingerprint,
+        )
+        if self.tokenizer.n_tokens != config.vocab_size:
+            raise ValueError("Tokenizer vocabulary size does not match the model.")
+        if config.weights_format == "adapter":
+            self.encoder = None
+            self.adapter = EncoderAdapters(config)
+        else:
+            ec = MERT2Config(**config.backbone_config)
+            ec._attn_implementation = config.encoder_attn_implementation
+            self.encoder = MERT2Model(ec)
+            self.adapter = None
+        self.layer_weight = nn.Parameter(torch.zeros(config.backbone_config["num_hidden_layers"] + 1))
+        self.encoder_projection = nn.Linear(config.backbone_config["hidden_size"], config.hidden_size)
+        dc = BartConfig(
+            vocab_size=config.vocab_size, d_model=config.hidden_size,
+            decoder_layers=config.decoder_layers, decoder_attention_heads=config.num_attention_heads,
+            decoder_ffn_dim=config.intermediate_size, max_position_embeddings=config.max_output_seq_len,
+            dropout=config.decoder_dropout, attention_dropout=config.decoder_dropout,
+            activation_dropout=config.decoder_dropout, activation_function="gelu",
+            pad_token_id=config.pad_token_id, bos_token_id=config.bos_token_id,
+            eos_token_id=config.eos_token_id, is_encoder_decoder=True, use_cache=True,
+        )
+        dc._attn_implementation = "sdpa"
+        self.token_embedding = nn.Embedding(config.vocab_size, config.hidden_size, padding_idx=config.pad_token_id)
+        self.decoder = BartDecoder(dc, embed_tokens=self.token_embedding)
+        self.decoder.gradient_checkpointing_disable()
+        self.output_projection = nn.Linear(config.hidden_size, config.vocab_size, bias=False)
+        self.output_projection.weight = self.token_embedding.weight
+        self.lora_merged = config.weights_format == "merged"
+        self.post_init()
+
+    def get_input_embeddings(self):
+        return self.token_embedding
+
+    def set_input_embeddings(self, value):
+        self.token_embedding = value
+        self.decoder.embed_tokens.weight = value.weight
+
+    def tie_weights(self):
+        super().tie_weights()
+        if hasattr(self, "decoder") and hasattr(self, "token_embedding"):
+            self.decoder.embed_tokens.weight = self.token_embedding.weight
+
+    def get_output_embeddings(self):
+        return self.output_projection
+
+    def set_output_embeddings(self, value):
+        self.output_projection = value
+
+    def _init_weights(self, module):
+        if isinstance(module, (nn.Linear, nn.Embedding)):
+            nn.init.normal_(module.weight, mean=0.0, std=0.02)
+            if getattr(module, "bias", None) is not None:
+                nn.init.zeros_(module.bias)
+            if isinstance(module, nn.Embedding) and module.padding_idx is not None:
+                module.weight.data[module.padding_idx].zero_()
+        elif isinstance(module, nn.LayerNorm):
+            nn.init.ones_(module.weight)
+            nn.init.zeros_(module.bias)
+
+    @torch.no_grad()
+    def merge_lora(self):
+        if self.lora_merged:
+            return self
+        if self.encoder is None or self.adapter is None:
+            raise RuntimeError("Load both the MERT-v2 parent and adapters before merging.")
+        scale = self.config.lora_alpha / self.config.lora_rank
+        with torch.autocast("cpu", enabled=False):
+            for layer, adapter in zip(self.encoder.layers, self.adapter.layers):
+                for name in PROJECTIONS:
+                    projection = getattr(layer.attn, name)
+                    update = getattr(adapter.attn, name)
+                    values = (projection.weight, update.lora_A.weight, update.lora_B.weight)
+                    if any(value.device.type != "cpu" or value.dtype != torch.float32 for value in values):
+                        raise ValueError("Merge adapters on CPU with float32 parameters.")
+                    projection.weight.add_((update.lora_B.weight @ update.lora_A.weight) * scale)
+        self.adapter = None
+        self.lora_merged = True
+        self.config.weights_format = "merged"
+        return self
+
+    @classmethod
+    def from_pretrained(cls, pretrained_model_name_or_path, *model_args, **kwargs):
+        base_path = kwargs.pop("base_model_path", None)
+        requested_dtype = kwargs.pop("torch_dtype", torch.float32)
+        target_device = kwargs.pop("device_map", None)
+        backend = kwargs.pop("attn_implementation", None)
+        return_loading_info = kwargs.pop("output_loading_info", False)
+        config = kwargs.pop("config", None)
+        hub_keys = ("cache_dir", "force_download", "local_files_only", "token", "revision", "subfolder")
+        hub_args = {name: kwargs[name] for name in hub_keys if name in kwargs}
+        if config is None:
+            config = cls.config_class.from_pretrained(pretrained_model_name_or_path, **hub_args)
+        if backend is not None:
+            config.encoder_attn_implementation = backend
+        if config.encoder_attn_implementation not in {"sdpa", "flash_attention_2"}:
+            raise ValueError("Select attn_implementation='sdpa' or 'flash_attention_2'.")
+        if isinstance(target_device, dict):
+            if set(target_device) != {""}:
+                raise ValueError("Use a single device for SheetSage2: device_map={'': 'cuda:0'}.")
+            target_device = target_device[""]
+        if target_device == "auto":
+            target_device = "cuda" if torch.cuda.is_available() else "cpu"
+        if requested_dtype == "auto":
+            requested_dtype = torch.float32
+        if isinstance(requested_dtype, str):
+            requested_dtype = getattr(torch, requested_dtype, None)
+        if requested_dtype not in {None, torch.float32, torch.bfloat16, torch.float16}:
+            raise ValueError("Use torch_dtype float32, bfloat16, float16, or 'auto'.")
+        # Adapters must be loaded and merged before any reduced-precision cast.
+        model, loading_info = super().from_pretrained(
+            pretrained_model_name_or_path, *model_args, config=config,
+            torch_dtype=torch.float32, attn_implementation="sdpa", output_loading_info=True, **kwargs,
+        )
+        if any(loading_info.get(name) for name in ("missing_keys", "unexpected_keys", "mismatched_keys", "error_msgs")):
+            raise ValueError(f"Incomplete or incompatible SheetSage2 weights: {loading_info}")
+        if config.weights_format == "adapter":
+            parent = str(base_path or config.base_model_name_or_path)
+            parent_hub_args = {name: hub_args[name] for name in ("cache_dir", "force_download", "local_files_only", "token") if name in hub_args}
+            parent_hub_args["revision"] = config.base_model_revision
+            expected_files = dict(BASE_CODE_HASHES, **{"model.safetensors": config.base_model_sha256})
+            for filename, expected in expected_files.items():
+                resolved = cached_file(parent, filename, **parent_hub_args)
+                if _sha256(resolved) != expected:
+                    raise ValueError(f"MERT-v2 parent integrity check failed: {filename}")
+            model.encoder = AutoModel.from_pretrained(
+                parent, trust_remote_code=True, code_revision=config.base_model_revision,
+                torch_dtype=torch.float32, attn_implementation=config.encoder_attn_implementation,
+                **parent_hub_args,
+            )
+            for name, expected in config.backbone_config.items():
+                if name in ("hidden_size", "intermediate_size", "num_hidden_layers", "num_attention_heads",
+                            "sampling_rate", "hop_length", "n_fft", "win_length", "num_mel_bins",
+                            "conv_depthwise_kernel_size", "rotary_embedding_base", "subsampling_channels",
+                            "subsampling_depths", "layer_norm_eps", "subsampling_layer_norm_eps", "variant"):
+                    if getattr(model.encoder.config, name) != expected:
+                        raise ValueError(f"MERT-v2 parent architecture mismatch: {name}")
+            model.merge_lora()
+        if requested_dtype is not None:
+            model.to(dtype=requested_dtype)
+        if target_device is not None:
+            model.to(target_device)
+        # Resource lookup follows the caller's cache and offline settings. These
+        # transient options are never written into config or model weights.
+        model._hub_resource_options = {name: hub_args[name] for name in ("cache_dir", "local_files_only", "token") if name in hub_args}
+        resource_args = dict(model._hub_resource_options, local_files_only=True,
+                             revision=config._commit_hash or hub_args.get("revision"),
+                             subfolder=hub_args.get("subfolder", ""),
+                             _raise_exceptions_for_missing_entries=False)
+        resource_config = cached_file(str(pretrained_model_name_or_path), "config.json", **resource_args)
+        model._source_snapshot = Path(resource_config).parent if resource_config else Path(pretrained_model_name_or_path)
+        model.eval().requires_grad_(False)
+        return (model, loading_info) if return_loading_info else model
+
+    def save_pretrained(self, save_directory, *args, **kwargs):
+        if not self.lora_merged or self.encoder is None:
+            raise ValueError("Load and merge the model before saving a standalone snapshot.")
+        original_config = self.config
+        source = original_config._name_or_path
+        self.config = copy.deepcopy(original_config)
+        self.config.weights_format = "merged"
+        self.config._name_or_path = ""
+        self.config.backbone_config.pop("_name_or_path", None)
+        try:
+            result = super().save_pretrained(save_directory, *args, **kwargs)
+            from .processing_sheetsage2 import SheetSage2Processor
+            SheetSage2Processor.from_model_config(self.config).save_pretrained(save_directory)
+        finally:
+            self.config = original_config
+        source_dir = getattr(self, "_source_snapshot", Path(source))
+        if source and not source_dir.is_dir():
+            from huggingface_hub import snapshot_download
+            try:
+                source_dir = Path(snapshot_download(source, revision=original_config._commit_hash,
+                                                     cache_dir=getattr(self, "_hub_resource_options", {}).get("cache_dir"),
+                                                     local_files_only=True))
+            except (OSError, ValueError):
+                source_dir = None
+        if source and source_dir is not None and source_dir.is_dir():
+            destination = Path(save_directory)
+            for name in ("infer.py", "render.py", "setup_render.py", "requirements.txt", "requirements-render.txt",
+                         "LICENSE", "THIRD_PARTY_NOTICES.md"):
+                if (source_dir / name).is_file() and (source_dir / name).resolve() != (destination / name).resolve():
+                    shutil.copy2(source_dir / name, destination / name)
+            assets = source_dir / "render_assets"
+            if (assets / "manifest.json").is_file() and assets.resolve() != (destination / "render_assets").resolve():
+                from .rendering_sheetsage2 import _verify_assets
+                try:
+                    _verify_assets(assets, audio=True)
+                except (FileNotFoundError, ValueError):
+                    pass
+                else:
+                    shutil.copytree(assets, destination / "render_assets", dirs_exist_ok=True)
+        return result
+
+    def _prepare_audio(self, input_values, attention_mask=None):
+        if self.encoder is None or not self.lora_merged:
+            raise RuntimeError("Load the model with from_pretrained before inference.")
+        if input_values.ndim != 2 or input_values.shape[0] < 1 or not input_values.is_floating_point():
+            raise ValueError("input_values must be floating-point [batch, samples].")
+        if not torch.isfinite(input_values).all():
+            raise ValueError("Audio must contain only finite samples.")
+        batch, samples = input_values.shape
+        minimum = self.encoder.config.minimum_input_samples
+        window = round(self.config.input_audio_length * self.config.sampling_rate)
+        if samples < minimum:
+            raise ValueError(f"Each waveform must contain at least {minimum} samples.")
+        if samples > window:
+            raise ValueError("Audio exceeds one model window; use transcribe for whole songs.")
+        if attention_mask is None:
+            lengths = torch.full((batch,), samples, dtype=torch.long, device=input_values.device)
+        else:
+            if attention_mask.shape != input_values.shape:
+                raise ValueError("attention_mask must have the same shape as input_values.")
+            mask = attention_mask.to(device=input_values.device)
+            if not ((mask == 0) | (mask == 1)).all():
+                raise ValueError("attention_mask must contain zeros and ones.")
+            mask = mask.bool()
+            lengths = mask.sum(1)
+            expected = torch.arange(samples, device=input_values.device)[None] < lengths[:, None]
+            if not torch.equal(mask, expected) or (lengths < minimum).any():
+                raise ValueError("attention_mask must identify a nonempty right-padded waveform.")
+            input_values = input_values.masked_fill(~mask, 0)
+        # The encoder attends to the complete fixed window, including this silence.
+        input_values = F.pad(input_values.float(), (0, window - samples))
+        stride = self.encoder.config.inputs_to_logits_ratio
+        if window % stride:
+            input_values = F.pad(input_values, (0, stride - window % stride))
+        return input_values, lengths
+
+    def get_audio_features(self, input_values, attention_mask=None, output_hidden_states=None, return_dict=True):
+        output_hidden_states = self.config.output_hidden_states if output_hidden_states is None else output_hidden_states
+        waveform, lengths = self._prepare_audio(input_values, attention_mask)
+        mel = self.encoder.feature_extractor(waveform)
+        weight_dtype = self.encoder.subsampling_module[0].convnext_layers[0].depthwise_block[1].weight.dtype
+        hidden = self.encoder.subsampling_module(mel.to(dtype=weight_dtype))
+        input_hidden = hidden if output_hidden_states else None
+        weights = torch.softmax(self.layer_weight, dim=0)
+        mixed = hidden * weights[0]
+        positions = self.encoder.embed_positions(hidden)
+        states = [] if output_hidden_states else None
+        for weight, layer in zip(weights[1:], self.encoder.layers):
+            hidden = layer(hidden, positions)
+            mixed = mixed + hidden * weight
+            if states is not None:
+                states.append(hidden)
+        memory = self.encoder_projection(mixed)
+        stride = self.encoder.config.inputs_to_logits_ratio
+        frame_mask = torch.arange(memory.shape[1], device=memory.device)[None] < ((lengths + stride - 1) // stride)[:, None]
+        output = SheetSage2EncoderOutput(
+            encoder_last_hidden_state=memory, backbone_last_hidden_state=hidden,
+            mixed_hidden_state=mixed, input_hidden_state=input_hidden,
+            backbone_hidden_states=tuple(states) if states is not None else None,
+            feature_attention_mask=frame_mask,
+        )
+        return output if return_dict else output.to_tuple()
+
+    def encode(self, audio):
+        return self.get_audio_features(audio).last_hidden_state
+
+    def _decode(self, memory, decoder_input_ids, use_cache=False, past_key_values=None, output_hidden_states=False):
+        attention_mask = None if past_key_values is not None else decoder_input_ids != self.tokenizer.pad_token
+        output = self.decoder(
+            input_ids=decoder_input_ids, attention_mask=attention_mask,
+            encoder_hidden_states=memory, encoder_attention_mask=None,
+            past_key_values=past_key_values, use_cache=use_cache,
+            output_hidden_states=output_hidden_states, return_dict=True,
+        )
+        return self.output_projection(output.last_hidden_state), output
+
+    def decode(self, memory, decoder_input_ids, use_cache=False, past_key_values=None):
+        logits, output = self._decode(memory, decoder_input_ids, use_cache, past_key_values)
+        return logits, output.past_key_values
+
+    def forward(self, input_values=None, decoder_input_ids=None, attention_mask=None,
+                encoder_outputs=None, past_key_values=None, use_cache=None,
+                output_hidden_states=None, return_dict=None):
+        output_hidden_states = self.config.output_hidden_states if output_hidden_states is None else output_hidden_states
+        use_cache = self.config.use_cache if use_cache is None else use_cache
+        if decoder_input_ids is None:
+            raise ValueError("decoder_input_ids is required for logits; use generate to transcribe audio.")
+        if encoder_outputs is None:
+            if input_values is None:
+                raise ValueError("Provide input_values or encoder_outputs.")
+            encoder_outputs = self.get_audio_features(input_values, attention_mask, output_hidden_states)
+        if torch.is_tensor(encoder_outputs):
+            encoder_outputs = SheetSage2EncoderOutput(encoder_last_hidden_state=encoder_outputs)
+        logits, decoded = self._decode(encoder_outputs.last_hidden_state, decoder_input_ids,
+                                       use_cache, past_key_values, output_hidden_states)
+        output = SheetSage2Output(
+            logits=logits, past_key_values=decoded.past_key_values,
+            decoder_hidden_states=decoded.hidden_states,
+            encoder_last_hidden_state=encoder_outputs.last_hidden_state,
+            backbone_last_hidden_state=encoder_outputs.backbone_last_hidden_state if output_hidden_states else None,
+            mixed_hidden_state=encoder_outputs.mixed_hidden_state if output_hidden_states else None,
+            input_hidden_state=encoder_outputs.input_hidden_state if output_hidden_states else None,
+            backbone_hidden_states=encoder_outputs.backbone_hidden_states if output_hidden_states else None,
+            feature_attention_mask=encoder_outputs.feature_attention_mask,
+        )
+        return_dict = self.config.use_return_dict if return_dict is None else return_dict
+        return output if return_dict else output.to_tuple()
+
+    def generate(self, input_values, **kwargs):
+        """Generate grammar-constrained symbolic tokens with autoregressive caching."""
+        from .generation_sheetsage2 import generate
+        return generate(self, input_values, **kwargs)
+
+    def transcribe(self, audio, output_dir=None, *, melody_only=False, **kwargs):
+        """Return transcription in memory; set output_dir to also save files.
+
+        Accepts a path, encoded audio bytes, binary stream, or waveform with
+        sampling_rate. Returns ABC text, MIDI bytes, timed events, and optional
+        per-window CPU tensors. With output_dir, optional tensors are saved
+        instead of retained in memory. Set melody_only=True to retain both vocal
+        and instrumental melodies while omitting chords from ABC and playback;
+        raw predicted annotations remain available. The default keeps full
+        transcription. See the model card for rendering options.
+        """
+        from .pipeline_sheetsage2 import transcribe
+        return transcribe(self, audio, output_dir=output_dir, melody_only=melody_only, **kwargs)
+
+
+SheetSage2ForConditionalGeneration = SheetSage2Model
+SheetSage2Model.register_for_auto_class("AutoModel")

notation_sheetsage2.py

@@ -0,0 +1,1570 @@
+"""Convert timed musical events into validated two-voice ABC notation."""
+
+from __future__ import annotations
+
+import math
+import os
+import re
+from collections import Counter
+from dataclasses import dataclass, replace
+from io import BytesIO
+from pathlib import Path
+from typing import Iterable, Sequence
+
+import numpy as np
+import pretty_midi
+
+from .io_sheetsage2 import atomic_write_text
+
+
+SUBBEAT_DIVISION = 4
+VOICE_IDS = ("Vocal", "Ins")
+NO_CHORDS = frozenset({"N", "X", "?"})
+
+
+class AbcRebuildError(ValueError):
+    """Base class for deterministic reconstruction failures."""
+
+
+class BeatGridError(AbcRebuildError):
+    pass
+
+
+class ChordSymbolError(AbcRebuildError):
+    pass
+
+
+class MelodyVoiceError(AbcRebuildError):
+    pass
+
+
+@dataclass(frozen=True)
+class BeatEvent:
+    time: float
+    beat_id: int
+    declared_numerator: int
+    denominator: int
+    line_no: int
+
+
+@dataclass(frozen=True)
+class Measure:
+    index: int
+    start_beat: int
+    end_beat: int
+    numerator: int
+    denominator: int
+    pickup: bool = False
+    partial: bool = False
+    inferred: bool = False
+    notated_numerator: int | None = None
+    notated_denominator: int | None = None
+    pad_before: bool = False
+
+    @property
+    def beat_count(self) -> int:
+        return self.end_beat - self.start_beat
+
+    @property
+    def start_t(self) -> int:
+        return self.start_beat * SUBBEAT_DIVISION
+
+    @property
+    def end_t(self) -> int:
+        return self.end_beat * SUBBEAT_DIVISION
+
+    @property
+    def abc_numerator(self) -> int:
+        return self.notated_numerator or self.numerator
+
+    @property
+    def abc_denominator(self) -> int:
+        return self.notated_denominator or self.denominator
+
+
+@dataclass
+class RebuiltAbcScore:
+    beats: list[BeatEvent]
+    measures: list[Measure]
+    subbeat_times: np.ndarray
+    subbeat_quarters: np.ndarray
+    subbeat_denominators: np.ndarray
+    key_arr: np.ndarray
+    chord_arr: np.ndarray
+    structure_events: list[tuple[int, str]]
+    voice_arrs: dict[str, np.ndarray]
+    diagnostics: list[str]
+    subbeat_div: int = SUBBEAT_DIVISION
+
+
+@dataclass
+class MeasureGroup:
+    measures: list[Measure]
+    structure_labels: list[str]
+    meter_changed: bool
+    key_changed: bool
+
+
+_QUALITY_TO_ABC = {
+    "maj": "",
+    "min": "m",
+    "dim": "dim",
+    "aug": "aug",
+    "7": "7",
+    "maj7": "maj7",
+    "min7": "m7",
+    "dim7": "dim7",
+    "hdim7": "m7b5",
+    "sus4": "sus4",
+    "sus2": "sus2",
+    "maj6": "6",
+    "min6": "m6",
+    "sus4(b7)": "7sus4",
+    # abc2midi and SymMusic both accept the parenthesized major seventh.
+    # Common aliases such as mmaj7/mM7 trigger abc2midi diagnostics.
+    "minmaj7": "m(maj7)",
+}
+
+_NATURAL_PITCH_CLASS = {
+    "C": 0,
+    "D": 2,
+    "E": 4,
+    "F": 5,
+    "G": 7,
+    "A": 9,
+    "B": 11,
+}
+_LETTERS = "CDEFGAB"
+_SHARP_PITCH_NAMES = ("C", "C#", "D", "D#", "E", "F", "F#", "G", "G#", "A", "A#", "B")
+_FLAT_PITCH_NAMES = ("C", "Db", "D", "Eb", "E", "F", "Gb", "G", "Ab", "A", "Bb", "B")
+_ROOT_RE = re.compile(r"^(?P<letter>[A-G])(?P<accidental>#{0,2}|b{0,2})$")
+_BASS_DEGREE_RE = re.compile(r"^(?P<accidental>#{0,2}|b{0,2})(?P<degree>[1-9]|1[0-3])$")
+
+_KEY_SIGNATURE_ACCIDENTALS = {
+    "C": 0,
+    "G": 1,
+    "D": 2,
+    "A": 3,
+    "E": 4,
+    "B": 5,
+    "F#": 6,
+    "C#": 7,
+    "F": -1,
+    "Bb": -2,
+    "Eb": -3,
+    "Ab": -4,
+    "Db": -5,
+    "Gb": -6,
+    "Cb": -7,
+    "Am": 0,
+    "Em": 1,
+    "Bm": 2,
+    "F#m": 3,
+    "C#m": 4,
+    "G#m": 5,
+    "D#m": 6,
+    "A#m": 7,
+    "Dm": -1,
+    "Gm": -2,
+    "Cm": -3,
+    "Fm": -4,
+    "Bbm": -5,
+    "Ebm": -6,
+    "Abm": -7,
+}
+
+# Keep the standard key-relative chromatic spelling.  MIDI carries only
+# pitch, not note names, so a deterministic key-based table is preferable to
+# rewriting every chromatic pitch with a single sharp/flat.  In remote sharp
+# and flat keys this deliberately permits musically useful double accidentals,
+# for example MIDI G as F## in G# minor.
+_KEY_RELATIVE_PITCH_NAMES = {
+    7: ("B#", "C#", "C##", "D#", "D##", "E#", "F#", "F##", "G#", "G##", "A#", "B"),
+    6: ("B#", "C#", "C##", "D#", "E", "E#", "F#", "F##", "G#", "G##", "A#", "B"),
+    5: ("B#", "C#", "C##", "D#", "E", "E#", "F#", "F##", "G#", "A", "A#", "B"),
+    4: ("B#", "C#", "D", "D#", "E", "E#", "F#", "F##", "G#", "A", "A#", "B"),
+    3: ("B#", "C#", "D", "D#", "E", "E#", "F#", "G", "G#", "A", "A#", "B"),
+    2: ("C", "C#", "D", "D#", "E", "E#", "F#", "G", "G#", "A", "A#", "B"),
+    1: ("C", "C#", "D", "D#", "E", "F", "F#", "G", "G#", "A", "A#", "B"),
+    0: ("C", "C#", "D", "D#", "E", "F", "F#", "G", "G#", "A", "Bb", "B"),
+    -1: ("C", "C#", "D", "Eb", "E", "F", "F#", "G", "G#", "A", "Bb", "B"),
+    -2: ("C", "C#", "D", "Eb", "E", "F", "F#", "G", "Ab", "A", "Bb", "B"),
+    -3: ("C", "Db", "D", "Eb", "E", "F", "F#", "G", "Ab", "A", "Bb", "B"),
+    -4: ("C", "Db", "D", "Eb", "E", "F", "Gb", "G", "Ab", "A", "Bb", "B"),
+    -5: ("C", "Db", "D", "Eb", "E", "F", "Gb", "G", "Ab", "A", "Bb", "Cb"),
+    -6: ("C", "Db", "D", "Eb", "Fb", "F", "Gb", "G", "Ab", "A", "Bb", "Cb"),
+    -7: ("C", "Db", "D", "Eb", "Fb", "F", "Gb", "G", "Ab", "Bbb", "Bb", "Cb"),
+}
+
+
+def _read_tsv(path: os.PathLike[str] | str, min_columns: int) -> list[tuple[int, list[str]]]:
+    rows = []
+    with open(path, "r", encoding="utf-8-sig") as handle:
+        for line_no, raw_line in enumerate(handle, 1):
+            line = raw_line.rstrip("\r\n")
+            if not line.strip():
+                continue
+            columns = line.split("\t")
+            if len(columns) < min_columns:
+                raise AbcRebuildError(
+                    f"{path}:{line_no}: expected at least {min_columns} tab-separated columns"
+                )
+            rows.append((line_no, columns))
+    return rows
+
+
+def read_beats(path: os.PathLike[str] | str) -> list[BeatEvent]:
+    return _parse_beats(_read_tsv(path, 3), path)
+
+
+def _row_entries(rows, source):
+    entries = []
+    for line_no, row in enumerate(rows, 1):
+        if len(row) < 3:
+            raise AbcRebuildError(f"{source}:{line_no}: expected at least 3 columns")
+        entries.append((line_no, [str(value) for value in row]))
+    return entries
+
+
+def _parse_beats(entries, path):
+    beats = []
+    for line_no, row in entries:
+        meter_text = row[2]
+        if len(row) >= 4:
+            numerator_text, denominator_text = meter_text, row[3]
+        elif "/" in meter_text:
+            numerator_text, denominator_text = meter_text.split("/", 1)
+        else:
+            numerator_text, denominator_text = meter_text, "4"
+        try:
+            beat = BeatEvent(
+                time=float(row[0]),
+                beat_id=int(row[1]),
+                declared_numerator=int(numerator_text),
+                denominator=int(denominator_text),
+                line_no=line_no,
+            )
+        except ValueError as exc:
+            raise BeatGridError(f"{path}:{line_no}: invalid beat row {row!r}") from exc
+        if beat.beat_id < 1:
+            raise BeatGridError(f"{path}:{line_no}: beat ID must be positive")
+        if beat.declared_numerator < 1:
+            raise BeatGridError(f"{path}:{line_no}: meter numerator must be positive")
+        if beat.denominator < 1 or beat.denominator & (beat.denominator - 1):
+            raise BeatGridError(
+                f"{path}:{line_no}: meter denominator must be a positive power of two"
+            )
+        if beats and beat.time <= beats[-1].time:
+            raise BeatGridError(f"{path}:{line_no}: beat times must be strictly increasing")
+        beats.append(beat)
+    if len(beats) < 2:
+        raise BeatGridError(f"{path}: at least two beat events are required")
+    return beats
+
+
+def read_chords(path: os.PathLike[str] | str) -> list[tuple[float, float, str]]:
+    return _parse_chords(_read_tsv(path, 3), path)
+
+
+def _parse_chords(entries, path):
+    rows = []
+    previous_end = None
+    for line_no, row in entries:
+        start, end, chord = float(row[0]), float(row[1]), row[2].strip()
+        if end <= start:
+            raise ChordSymbolError(f"{path}:{line_no}: chord end must be after start")
+        if previous_end is not None and start < previous_end - 1e-6:
+            raise ChordSymbolError(f"{path}:{line_no}: overlapping chord intervals")
+        chord_symbol_to_abc(chord)
+        rows.append((start, end, chord))
+        previous_end = end
+    return rows
+
+
+def read_keys(path: os.PathLike[str] | str) -> list[tuple[float, float, str]]:
+    return _parse_keys(_read_tsv(path, 3), path)
+
+
+def _parse_keys(entries, path):
+    rows = []
+    previous_end = None
+    for line_no, row in entries:
+        start, end, key = float(row[0]), float(row[1]), row[2].strip()
+        if end <= start:
+            raise AbcRebuildError(f"{path}:{line_no}: key end must be after start")
+        if previous_end is not None and start < previous_end - 1e-6:
+            raise AbcRebuildError(f"{path}:{line_no}: overlapping key intervals")
+        normalized = key_symbol_to_abc(key)
+        rows.append((start, end, normalized))
+        previous_end = end
+    if not rows:
+        raise AbcRebuildError(f"{path}: at least one key interval is required")
+    return rows
+
+
+def read_structures(path: os.PathLike[str] | str) -> list[tuple[float, float, str]]:
+    return _parse_structures(_read_tsv(path, 3), path)
+
+
+def _parse_structures(entries, path):
+    rows = []
+    previous_end = None
+    for line_no, row in entries:
+        start, end, label = float(row[0]), float(row[1]), row[2].strip()
+        if end <= start:
+            raise AbcRebuildError(f"{path}:{line_no}: structure end must be after start")
+        if previous_end is not None and start < previous_end - 1e-6:
+            raise AbcRebuildError(f"{path}:{line_no}: overlapping structure intervals")
+        rows.append((start, end, label))
+        previous_end = end
+    return rows
+
+
+def _mode_with_first_tiebreak(values: Sequence[int]) -> int:
+    counts = Counter(values)
+    maximum = max(counts.values())
+    return next(value for value in values if counts[value] == maximum)
+
+
+def infer_measures(
+    beats: Sequence[BeatEvent],
+    *,
+    meter_conflict: str = "infer",
+) -> tuple[list[Measure], list[str]]:
+    """Infer self-consistent measures from actual downbeat boundaries."""
+
+    if meter_conflict not in {"infer", "reject"}:
+        raise ValueError("meter_conflict must be 'infer' or 'reject'")
+    downbeat_indices = [index for index, beat in enumerate(beats) if beat.beat_id == 1]
+    if not downbeat_indices:
+        raise BeatGridError("No downbeat (beat ID 1) exists in the beat lab")
+    spans: list[tuple[int, int, bool, bool]] = []
+    if downbeat_indices[0] > 0:
+        spans.append((0, downbeat_indices[0], True, False))
+    spans.extend(
+        (start, end, False, False)
+        for start, end in zip(downbeat_indices, downbeat_indices[1:])
+    )
+    if downbeat_indices[-1] < len(beats) - 1:
+        # Exported beat labs use their last row as the score end boundary.  If
+        # that row is not a downbeat, the final bar is intentionally truncated.
+        spans.append((downbeat_indices[-1], len(beats) - 1, False, True))
+    if not spans:
+        raise BeatGridError("No positive-length measure exists between downbeats")
+
+    diagnostics = []
+    measures = []
+    for measure_index, (start, end, pickup, partial) in enumerate(spans):
+        events = list(beats[start:end])
+        beat_count = len(events)
+        if beat_count < 1:
+            raise BeatGridError(f"Measure {measure_index}: empty downbeat span")
+        ids = [event.beat_id for event in events]
+        expected_ids = list(range(ids[0], ids[0] + beat_count))
+        if ids != expected_ids:
+            line_numbers = [event.line_no for event in events]
+            raise BeatGridError(
+                f"Measure {measure_index} (beat rows {line_numbers[0]}-{line_numbers[-1]}): "
+                f"non-consecutive beat IDs {ids!r}"
+            )
+        if not pickup and ids[0] != 1:
+            raise BeatGridError(f"Measure {measure_index}: full measure does not start at beat ID 1")
+
+        denominators = [event.denominator for event in events]
+        denominator = _mode_with_first_tiebreak(denominators)
+        declared_numerators = [event.declared_numerator for event in events]
+        declared_numerator = _mode_with_first_tiebreak(declared_numerators)
+        numerator_conflict = any(value != beat_count for value in declared_numerators)
+        denominator_conflict = any(value != denominator for value in denominators)
+        pad_final_partial = (
+            partial
+            and len(set(declared_numerators)) == 1
+            and not denominator_conflict
+            and declared_numerator >= beat_count
+        )
+        inferred = pickup or partial or numerator_conflict or denominator_conflict
+        unresolved_numerator_conflict = (
+            numerator_conflict
+            and not pad_final_partial
+            and not pickup
+        )
+        if (
+            unresolved_numerator_conflict or denominator_conflict
+        ) and meter_conflict == "reject":
+            raise BeatGridError(
+                f"Measure {measure_index}: {beat_count} actual beats conflict with declarations "
+                f"{list(zip(declared_numerators, denominators))!r}"
+            )
+        if pad_final_partial and declared_numerator > beat_count:
+            diagnostics.append(
+                f"measure {measure_index}: padded final {beat_count}/{denominator} span "
+                f"to declared {declared_numerator}/{denominator} with trailing rest"
+            )
+        elif numerator_conflict:
+            diagnostics.append(
+                f"measure {measure_index}: inferred {beat_count}/{denominator} from downbeat span; "
+                f"declared numerators were {declared_numerators}"
+            )
+        if denominator_conflict:
+            diagnostics.append(
+                f"measure {measure_index}: placed denominator {denominator} at the measure boundary; "
+                f"row declarations were {denominators}"
+            )
+        measures.append(
+            Measure(
+                index=measure_index,
+                start_beat=start,
+                end_beat=end,
+                numerator=beat_count,
+                denominator=denominator,
+                pickup=pickup,
+                partial=partial,
+                inferred=inferred,
+                notated_numerator=(
+                    declared_numerator if pad_final_partial else beat_count
+                ),
+            )
+        )
+    if len(measures) >= 2:
+        first = measures[0]
+        following = measures[1]
+        first_duration = first.numerator / first.denominator
+        following_duration = (
+            following.abc_numerator / following.abc_denominator
+        )
+        if first_duration < following_duration:
+            measures[0] = replace(
+                first,
+                inferred=True,
+                notated_numerator=following.abc_numerator,
+                notated_denominator=following.abc_denominator,
+                pad_before=True,
+            )
+            diagnostics.append(
+                f"measure 0: padded leading {first.numerator}/{first.denominator} span "
+                f"to {following.abc_numerator}/{following.abc_denominator} "
+                f"with preceding rest"
+            )
+    return measures, diagnostics
+
+
+def _build_grid(beats: Sequence[BeatEvent], measures: Sequence[Measure]):
+    interval_denominators = np.zeros(len(beats) - 1, dtype=np.int32)
+    for measure in measures:
+        interval_denominators[measure.start_beat:measure.end_beat] = measure.denominator
+    if np.any(interval_denominators == 0):
+        raise BeatGridError("Downbeat spans do not cover every beat interval")
+
+    subbeat_times = []
+    subbeat_denominators = []
+    quarter_positions = [0.0]
+    current_quarter = 0.0
+    for index in range(len(beats) - 1):
+        start = beats[index].time
+        end = beats[index + 1].time
+        denominator = int(interval_denominators[index])
+        times = np.linspace(start, end, SUBBEAT_DIVISION + 1)[:-1]
+        subbeat_times.extend(float(value) for value in times)
+        subbeat_denominators.extend([denominator] * SUBBEAT_DIVISION)
+        quarter_step = 4.0 / denominator / SUBBEAT_DIVISION
+        for _ in range(SUBBEAT_DIVISION):
+            current_quarter += quarter_step
+            quarter_positions.append(current_quarter)
+    subbeat_times.append(beats[-1].time)
+    subbeat_denominators.append(int(interval_denominators[-1]))
+    return (
+        np.asarray(subbeat_times, dtype=np.float64),
+        np.asarray(quarter_positions, dtype=np.float64),
+        np.asarray(subbeat_denominators, dtype=np.int32),
+    )
+
+
+def _subbeat_boundaries(subbeat_times: np.ndarray) -> np.ndarray:
+    return (subbeat_times[:-1] + subbeat_times[1:]) / 2
+
+
+def _quantize_time(time: float, subbeat_times: np.ndarray) -> int:
+    return int(np.searchsorted(_subbeat_boundaries(subbeat_times), float(time)))
+
+
+def _fill_intervals(rows, subbeat_times, *, default, dtype):
+    result = np.full(len(subbeat_times), default, dtype=dtype)
+    for start, end, value in rows:
+        start_t = _quantize_time(start, subbeat_times)
+        end_t = _quantize_time(end, subbeat_times)
+        start_t = max(0, min(start_t, len(result) - 1))
+        end_t = max(0, min(end_t, len(result) - 1))
+        if end_t <= start_t:
+            raise AbcRebuildError(
+                f"Interval {start:.6f}-{end:.6f} ({value}) is shorter than the ABC subbeat grid"
+            )
+        result[start_t:end_t] = value
+    if len(result) > 1:
+        result[-1] = result[-2]
+    return result
+
+
+def _structure_events(rows, subbeat_times):
+    events = []
+    for start, _, label in rows:
+        t = _quantize_time(start, subbeat_times)
+        t = max(0, min(t, len(subbeat_times) - 1))
+        events.append((t, label))
+    return events
+
+
+def _classify_melody_tracks(midi: pretty_midi.PrettyMIDI):
+    classified = {"Vocal": [], "Ins": []}
+    unknown = []
+    for instrument in midi.instruments:
+        if instrument.is_drum:
+            continue
+        name = (instrument.name or "").strip().lower()
+        if "vocal" in name:
+            classified["Vocal"].append(instrument)
+        elif "ins" in name or "instrument" in name:
+            classified["Ins"].append(instrument)
+        elif instrument.notes:
+            unknown.append(instrument)
+    if unknown:
+        if not classified["Vocal"] and not classified["Ins"] and len(unknown) == 1:
+            classified["Ins"].extend(unknown)
+        else:
+            names = [instrument.name or "<unnamed>" for instrument in unknown]
+            raise MelodyVoiceError(
+                f"Cannot map non-empty melody track(s) {names!r} to fixed Vocal/Ins voices"
+            )
+    return classified
+
+
+def _notes_to_arr(notes, subbeat_times, voice_id):
+    result = np.zeros(len(subbeat_times), dtype=np.int32)
+    boundaries = _subbeat_boundaries(subbeat_times)
+    for note in sorted(notes, key=lambda item: (item.start, item.end, item.pitch)):
+        start_t = int(np.searchsorted(boundaries, note.start))
+        end_t = int(np.searchsorted(boundaries, note.end))
+        start_t = max(0, min(start_t, len(result) - 1))
+        end_t = max(0, min(end_t, len(result) - 1))
+        if end_t <= start_t:
+            raise MelodyVoiceError(
+                f"{voice_id}: MIDI note pitch={note.pitch} at {note.start:.6f}-{note.end:.6f} "
+                "cannot be represented on the decoded subbeat grid"
+            )
+        if np.any(result[start_t:end_t] != 0):
+            raise MelodyVoiceError(
+                f"{voice_id}: overlapping quantized melody notes at subbeats {start_t}:{end_t}"
+            )
+        sustain = note.pitch * 2 + 2
+        result[start_t:end_t] = sustain
+        result[start_t] = sustain + 1
+    return result
+
+
+def _pitch_class(root: str) -> tuple[int, str, str]:
+    match = _ROOT_RE.fullmatch(root)
+    if match is None:
+        raise ChordSymbolError(f"Invalid pitch spelling {root!r}")
+    letter = match.group("letter")
+    accidental = match.group("accidental")
+    offset = accidental.count("#") - accidental.count("b")
+    return (_NATURAL_PITCH_CLASS[letter] + offset) % 12, letter, accidental
+
+
+def portable_pitch_name(root: str, *, preserve_double: bool = False) -> str:
+    pitch_class, _, accidental = _pitch_class(root)
+    if preserve_double or len(accidental) <= 1:
+        return root
+    names = _SHARP_PITCH_NAMES if accidental.startswith("#") else _FLAT_PITCH_NAMES
+    return names[pitch_class]
+
+
+def _bass_degree_to_pitch(root: str, degree_text: str) -> str:
+    if _ROOT_RE.fullmatch(degree_text):
+        return portable_pitch_name(degree_text, preserve_double=True)
+    match = _BASS_DEGREE_RE.fullmatch(degree_text)
+    if match is None:
+        raise ChordSymbolError(f"Invalid chord bass degree {degree_text!r}")
+    root_pc, root_letter, root_accidental = _pitch_class(root)
+    degree = int(match.group("degree"))
+    degree_accidental = match.group("accidental")
+    scale_semitones = (0, 2, 4, 5, 7, 9, 11)
+    interval = scale_semitones[(degree - 1) % 7] + 12 * ((degree - 1) // 7)
+    interval += degree_accidental.count("#") - degree_accidental.count("b")
+    target_pc = (root_pc + interval) % 12
+
+    target_letter_index = (_LETTERS.index(root_letter) + degree - 1) % 7
+    target_letter = _LETTERS[target_letter_index]
+    natural_pc = _NATURAL_PITCH_CLASS[target_letter]
+    difference = (target_pc - natural_pc + 6) % 12 - 6
+    if difference in {-2, -1, 0, 1, 2}:
+        accidental = {-2: "bb", -1: "b", 0: "", 1: "#", 2: "##"}[difference]
+        return target_letter + accidental
+    names = _SHARP_PITCH_NAMES if "#" in (root_accidental + degree_accidental) else _FLAT_PITCH_NAMES
+    return names[target_pc]
+
+
+def chord_symbol_to_abc(chord: str) -> str | None:
+    chord = chord.strip()
+    if chord in NO_CHORDS:
+        return None
+    if ":" not in chord:
+        raise ChordSymbolError(f"Chord {chord!r} is missing the ':' quality separator")
+    root, descriptor = chord.split(":", 1)
+    if "/" in descriptor:
+        quality, bass_degree = descriptor.split("/", 1)
+    else:
+        quality, bass_degree = descriptor, None
+    if quality not in _QUALITY_TO_ABC:
+        raise ChordSymbolError(
+            f"Unsupported chord quality {quality!r} in {chord!r}; refusing to rewrite it as major"
+        )
+    chord_root = portable_pitch_name(root, preserve_double=True)
+    text = chord_root + _QUALITY_TO_ABC[quality]
+    if bass_degree:
+        text += "/" + _bass_degree_to_pitch(root, bass_degree)
+    return text
+
+
+def key_symbol_to_abc(key: str) -> str:
+    key = key.strip()
+    if ":" in key:
+        root, mode = key.split(":", 1)
+        if mode not in {"major", "minor"}:
+            raise AbcRebuildError(f"Unsupported key mode {mode!r} in {key!r}")
+    elif key.endswith("m"):
+        root, mode = key[:-1], "minor"
+    else:
+        root, mode = key, "major"
+    root_pc, _, accidental = _pitch_class(root)
+    candidate = portable_pitch_name(root) + ("m" if mode == "minor" else "")
+    if candidate in _KEY_SIGNATURE_ACCIDENTALS:
+        return candidate
+    names = _FLAT_PITCH_NAMES if "b" in accidental else _SHARP_PITCH_NAMES
+    candidate = names[root_pc] + ("m" if mode == "minor" else "")
+    if candidate not in _KEY_SIGNATURE_ACCIDENTALS:
+        fallback_names = _SHARP_PITCH_NAMES if names is _FLAT_PITCH_NAMES else _FLAT_PITCH_NAMES
+        candidate = fallback_names[root_pc] + ("m" if mode == "minor" else "")
+    if candidate not in _KEY_SIGNATURE_ACCIDENTALS:
+        raise AbcRebuildError(f"Cannot encode portable ABC key for {key!r}")
+    return candidate
+
+
+def get_key_accidentals(key: str) -> list[int]:
+    try:
+        count = _KEY_SIGNATURE_ACCIDENTALS[key]
+    except KeyError as exc:
+        raise AbcRebuildError(f"Unsupported ABC key signature {key!r}") from exc
+    accidentals = [0] * 7
+    order = "FCGDAEB" if count > 0 else "BEADGCF"
+    for letter in order[:abs(count)]:
+        accidentals[_LETTERS.index(letter)] = 1 if count > 0 else -1
+    return accidentals
+
+
+def note_to_abc(note: int, key_accidentals: Sequence[int], measure_accidentals: dict) -> str:
+    """Use key-relative spelling and write only bar-state changes.
+
+    The two target parsers propagate an accidental to the same note letter in
+    every octave until the next barline. ``measure_accidentals`` is therefore
+    keyed by letter and reset by the caller for every bar (and after an inline
+    key change). This preserves pitches across parsers while still omitting
+    repeated accidental marks.  The key-relative spelling can use double
+    accidentals in remote keys; MIDI G is F## in G# minor, for example.
+    """
+
+    accidental_count = sum(key_accidentals)
+    try:
+        pitch_name = _KEY_RELATIVE_PITCH_NAMES[accidental_count][note % 12]
+    except KeyError as exc:
+        raise AbcRebuildError(
+            f"Unsupported key signature accidental count {accidental_count}"
+        ) from exc
+    letter = pitch_name[0]
+    accidental = pitch_name[1:]
+    accidental_number = {"": 0, "#": 1, "##": 2, "b": -1, "bb": -2}[accidental]
+    octave = (note - 60) // 12
+    # Cb and B# cross the MIDI octave boundary even though their written note
+    # letter does not.
+    if note % 12 == 11 and accidental_number == -1:
+        octave += 1
+    elif note % 12 == 0 and accidental_number == 1:
+        octave -= 1
+    scale_index = _LETTERS.index(letter)
+    current_accidental = measure_accidentals.get(
+        scale_index,
+        key_accidentals[scale_index],
+    )
+    accidental_text = ""
+    if current_accidental != accidental_number:
+        measure_accidentals[scale_index] = accidental_number
+        accidental_text = {-2: "__", -1: "_", 0: "=", 1: "^", 2: "^^"}[
+            accidental_number
+        ]
+
+    if octave > 0:
+        letter = letter.lower()
+        if octave > 1:
+            letter += "'" * (octave - 1)
+    elif octave < 0:
+        letter += "," * abs(octave)
+    return accidental_text + letter
+
+
+def build_rebuilt_abc_score(
+    melody_midi_path,
+    beats_path,
+    chords_path,
+    keys_path,
+    structures_path,
+    *,
+    meter_conflict: str = "infer",
+    melody_only: bool = False,
+) -> RebuiltAbcScore:
+    beats = read_beats(beats_path)
+    keys = read_keys(keys_path)
+    structures = read_structures(structures_path)
+    chords = [] if melody_only else read_chords(chords_path)
+    midi = pretty_midi.PrettyMIDI(str(melody_midi_path))
+    return _assemble_abc_score(midi, beats, keys, structures, chords,
+                               meter_conflict=meter_conflict, melody_only=melody_only)
+
+
+def build_rebuilt_abc_score_from_data(
+    melody_midi, beats, chords, keys, structures, *, meter_conflict="infer", melody_only=False,
+) -> RebuiltAbcScore:
+    """Build from MIDI bytes/BytesIO/PrettyMIDI and beat/interval rows.
+
+    BeatEvent lists are also accepted. The file and memory interfaces share
+    interval validation, score construction, serialization and ABC validation.
+    """
+    beats = list(beats)
+    if beats and isinstance(beats[0], BeatEvent):
+        beat_entries = [(b.line_no, [str(b.time), str(b.beat_id), str(b.declared_numerator), str(b.denominator)]) for b in beats]
+    else:
+        beat_entries = _row_entries(beats, "beats")
+    beats = _parse_beats(beat_entries, "beats")
+    keys = _parse_keys(_row_entries(keys, "keys"), "keys")
+    structures = _parse_structures(_row_entries(structures, "structures"), "structures")
+    chords = [] if melody_only else _parse_chords(_row_entries(chords, "chords"), "chords")
+    if isinstance(melody_midi, (bytes, bytearray)):
+        melody_midi = BytesIO(melody_midi)
+    if not isinstance(melody_midi, (BytesIO, pretty_midi.PrettyMIDI)):
+        raise TypeError("melody_midi must be MIDI bytes, BytesIO, or PrettyMIDI")
+    midi = melody_midi if isinstance(melody_midi, pretty_midi.PrettyMIDI) else pretty_midi.PrettyMIDI(melody_midi)
+    return _assemble_abc_score(midi, beats, keys, structures, chords,
+                               meter_conflict=meter_conflict, melody_only=melody_only)
+
+
+def _assemble_abc_score(midi, beats, keys, structures, chords, *, meter_conflict, melody_only):
+    measures, diagnostics = infer_measures(beats, meter_conflict=meter_conflict)
+    subbeat_times, subbeat_quarters, subbeat_denominators = _build_grid(beats, measures)
+    classified = _classify_melody_tracks(midi)
+    voice_arrs = {}
+    for voice_id in VOICE_IDS:
+        notes = [
+            note
+            for instrument in classified[voice_id]
+            for note in instrument.notes
+        ]
+        voice_arrs[voice_id] = _notes_to_arr(notes, subbeat_times, voice_id)
+
+    key_arr = _fill_intervals(keys, subbeat_times, default=keys[0][2], dtype="<U16")
+    if melody_only:
+        # Do not even read chord labels in melody-only mode.  A constant no-chord
+        # timeline removes chord-only render boundaries, allowing held notes and
+        # rests to be serialized as their original semantic segments.
+        chord_arr = np.full(len(subbeat_times), "N", dtype="<U64")
+    else:
+        chord_arr = _fill_intervals(
+            chords,
+            subbeat_times,
+            default="N",
+            dtype="<U64",
+        )
+    return RebuiltAbcScore(
+        beats=list(beats),
+        measures=measures,
+        subbeat_times=subbeat_times,
+        subbeat_quarters=subbeat_quarters,
+        subbeat_denominators=subbeat_denominators,
+        key_arr=key_arr,
+        chord_arr=chord_arr,
+        structure_events=_structure_events(structures, subbeat_times),
+        voice_arrs=voice_arrs,
+        diagnostics=diagnostics,
+    )
+
+
+def abc_unit_denominator(score: RebuiltAbcScore) -> int:
+    values = [
+        denominator * score.subbeat_div
+        for measure in score.measures
+        for denominator in (measure.denominator, measure.abc_denominator)
+    ]
+    denominator = math.lcm(*values)
+    if denominator > 1024:
+        raise AbcRebuildError(f"Required ABC unit length 1/{denominator} is unreasonably small")
+    return denominator
+
+
+def _measure_actual_units(measure: Measure, unit_denominator: int) -> int:
+    return measure.numerator * unit_denominator // measure.denominator
+
+
+def _measure_abc_units(measure: Measure, unit_denominator: int) -> int:
+    return measure.abc_numerator * unit_denominator // measure.abc_denominator
+
+
+def _measure_padding_units(measure: Measure, unit_denominator: int) -> int:
+    return (
+        _measure_abc_units(measure, unit_denominator)
+        - _measure_actual_units(measure, unit_denominator)
+    )
+
+
+def _duration_units(score: RebuiltAbcScore, start_t: int, end_t: int, unit_denominator: int) -> int:
+    units = 0
+    for denominator in score.subbeat_denominators[start_t:end_t]:
+        divisor = int(denominator) * score.subbeat_div
+        if unit_denominator % divisor:
+            raise AbcRebuildError(
+                f"ABC L:1/{unit_denominator} cannot express a 1/{divisor} subbeat exactly"
+            )
+        units += unit_denominator // divisor
+    return units
+
+
+def estimate_tempo(score: RebuiltAbcScore) -> float:
+    seconds = score.subbeat_times[-1] - score.subbeat_times[0]
+    quarter_notes = score.subbeat_quarters[-1] - score.subbeat_quarters[0]
+    if seconds <= 0 or quarter_notes <= 0:
+        raise AbcRebuildError("Cannot estimate tempo from a zero-duration score")
+    return float(quarter_notes / seconds * 60.0)
+
+
+def _continues_pitch(value: int, next_value: int) -> bool:
+    if value <= 0:
+        return False
+    pitch = value // 2 - 1
+    return next_value == pitch * 2 + 2
+
+
+def _same_note_segment(value: int, next_value: int) -> bool:
+    if value == 0:
+        return next_value == 0
+    pitch = value // 2 - 1
+    return next_value == pitch * 2 + 2
+
+
+_SUPPORTED_DURATION_UNITS = frozenset(
+    {1, 2, 3, 4, 6, 8, 12, 16, 24, 32, 48}
+)
+
+
+def _split_duration_units(duration: int) -> list[int]:
+    """Split a duration into values accepted by strict music parsers."""
+
+    if duration <= 0:
+        raise AbcRebuildError(f"Cannot serialize non-positive duration {duration}")
+    result = []
+    remaining = int(duration)
+    while remaining:
+        if remaining in _SUPPORTED_DURATION_UNITS:
+            result.append(remaining)
+            break
+        candidates = [
+            value
+            for value in _SUPPORTED_DURATION_UNITS
+            if value < remaining
+        ]
+        if not candidates:
+            raise AbcRebuildError(
+                f"Duration {duration} cannot be split into representable ABC values"
+            )
+        chunk = max(candidates)
+        result.append(chunk)
+        remaining -= chunk
+    return result
+
+
+def _duration_text(duration: int) -> str:
+    return "" if duration == 1 else str(duration)
+
+
+def _render_duration_tokens(
+    prefix: str,
+    note_text: str,
+    duration: int,
+    *,
+    tie_out: bool,
+) -> list[str]:
+    chunks = _split_duration_units(duration)
+    tokens = []
+    for index, chunk in enumerate(chunks):
+        continues = note_text != "z" and (
+            index + 1 < len(chunks) or tie_out
+        )
+        tokens.append(
+            (prefix if index == 0 else "")
+            + note_text
+            + _duration_text(chunk)
+            + ("-" if continues else "")
+        )
+    return tokens
+
+
+def _render_voice_measure(
+    score: RebuiltAbcScore,
+    voice_id: str,
+    measure: Measure,
+    unit_denominator: int,
+) -> str:
+    voice = score.voice_arrs[voice_id]
+    show_chords = voice_id == "Vocal"
+    measure_accidentals = {}
+    current_key = str(score.key_arr[measure.start_t])
+    key_accidentals = get_key_accidentals(current_key)
+    parts = []
+    padding = _measure_padding_units(measure, unit_denominator)
+    if padding < 0:
+        raise AbcRebuildError(
+            f"Measure {measure.index}: notated meter is shorter than its decoded span"
+        )
+    leading_padding = padding if measure.pad_before else 0
+    trailing_padding = 0 if measure.pad_before else padding
+    t = measure.start_t
+    while t < measure.end_t:
+        change_points = [measure.end_t]
+        for probe in range(t + 1, measure.end_t):
+            if not _same_note_segment(int(voice[t]), int(voice[probe])):
+                change_points.append(probe)
+                break
+        for probe in range(t + 1, measure.end_t):
+            if score.key_arr[probe] != score.key_arr[probe - 1]:
+                change_points.append(probe)
+                break
+        if show_chords:
+            for probe in range(t + 1, measure.end_t):
+                if score.chord_arr[probe] != score.chord_arr[probe - 1]:
+                    change_points.append(probe)
+                    break
+        next_t = min(change_points)
+
+        prefix = ""
+        key = str(score.key_arr[t])
+        if t > measure.start_t and key != current_key:
+            current_key = key
+            key_accidentals = get_key_accidentals(current_key)
+            measure_accidentals = {}
+            prefix += f"[K:{current_key}]"
+
+        if show_chords and (t == measure.start_t or score.chord_arr[t] != score.chord_arr[t - 1]):
+            chord = str(score.chord_arr[t])
+            chord_text = chord_symbol_to_abc(chord)
+            if chord_text is not None:
+                prefix += f'"{chord_text}"'
+
+        value = int(voice[t])
+        if value == 0:
+            note_text = "z"
+        else:
+            note_text = note_to_abc(value // 2 - 1, key_accidentals, measure_accidentals)
+        duration = _duration_units(score, t, next_t, unit_denominator)
+        if t == measure.start_t and leading_padding:
+            if value == 0 and not prefix:
+                duration += leading_padding
+            else:
+                parts.extend(
+                    _render_duration_tokens(
+                        "",
+                        "z",
+                        leading_padding,
+                        tie_out=False,
+                    )
+                )
+            leading_padding = 0
+        if value == 0 and next_t == measure.end_t and trailing_padding:
+            duration += trailing_padding
+            trailing_padding = 0
+        if duration <= 0:
+            raise AbcRebuildError(f"Non-positive ABC duration at subbeats {t}:{next_t}")
+        tie_out = (
+            value > 0
+            and next_t < len(voice)
+            and _continues_pitch(value, int(voice[next_t]))
+        )
+        parts.extend(
+            _render_duration_tokens(
+                prefix,
+                note_text,
+                duration,
+                tie_out=tie_out,
+            )
+        )
+        t = next_t
+    if leading_padding:
+        raise AbcRebuildError(
+            f"Measure {measure.index}: leading rest padding was not serialized"
+        )
+    if trailing_padding:
+        parts.extend(
+            _render_duration_tokens(
+                "",
+                "z",
+                trailing_padding,
+                tie_out=False,
+            )
+        )
+    return "".join(parts)
+
+
+def _is_compressible_full_rest(rendered_measure: str) -> bool:
+    """Whether a rendered measure can be losslessly replaced by ABC ``Z``."""
+
+    cursor = 0
+    saw_note = False
+    for match in _MUSIC_ELEMENT_RE.finditer(rendered_measure):
+        if rendered_measure[cursor:match.start()]:
+            return False
+        cursor = match.end()
+        if match.group("quoted") is not None or match.group("key") is not None:
+            return False
+        saw_note = True
+        if match.group("note") != "z" or match.group("tie"):
+            return False
+    return saw_note and cursor == len(rendered_measure)
+
+
+def _render_voice_group(
+    score: RebuiltAbcScore,
+    voice_id: str,
+    measures: list[Measure],
+    unit_denominator: int,
+) -> str:
+    rendered = [
+        _render_voice_measure(
+            score,
+            voice_id,
+            measure,
+            unit_denominator,
+        )
+        for measure in measures
+    ]
+    parts = []
+    index = 0
+    while index < len(rendered):
+        if not _is_compressible_full_rest(rendered[index]):
+            parts.append(rendered[index] + "|")
+            index += 1
+            continue
+        end = index + 1
+        while (
+            end < len(rendered)
+            and _is_compressible_full_rest(rendered[end])
+        ):
+            end += 1
+        count = end - index
+        parts.append("Z" + (str(count) if count > 1 else "") + "|")
+        index = end
+    return "".join(parts)
+
+
+def _sanitize_structure_label(value: str) -> str:
+    return " ".join(str(value).split())
+
+
+def _measure_groups(score: RebuiltAbcScore) -> list[MeasureGroup]:
+    first_measure = score.measures[0]
+    active_meter = (
+        first_measure.abc_numerator,
+        first_measure.abc_denominator,
+    )
+    active_key = str(score.key_arr[first_measure.start_t])
+    active_structure = ""
+    groups: list[MeasureGroup] = []
+
+    for measure in score.measures:
+        meter = (measure.abc_numerator, measure.abc_denominator)
+        key = str(score.key_arr[measure.start_t])
+        meter_changed = meter != active_meter
+        key_changed = key != active_key
+        new_structure_labels = []
+        for t, label in score.structure_events:
+            if not measure.start_t <= t < measure.end_t:
+                continue
+            clean_label = _sanitize_structure_label(label)
+            if clean_label and clean_label != active_structure:
+                new_structure_labels.append(clean_label)
+                active_structure = clean_label
+
+        start_group = (
+            not groups
+            or len(groups[-1].measures) >= 4
+            or meter_changed
+            or key_changed
+            or bool(new_structure_labels)
+        )
+        if start_group:
+            groups.append(
+                MeasureGroup(
+                    measures=[measure],
+                    structure_labels=new_structure_labels,
+                    meter_changed=meter_changed,
+                    key_changed=key_changed,
+                )
+            )
+        else:
+            groups[-1].measures.append(measure)
+
+        active_meter = meter
+        active_key = str(score.key_arr[measure.end_t - 1])
+    return groups
+
+
+def score_to_abc(score: RebuiltAbcScore) -> str:
+    unit_denominator = abc_unit_denominator(score)
+    first_measure = score.measures[0]
+    first_key = str(score.key_arr[first_measure.start_t])
+    lines = [
+        "X:1",
+        "T:",
+        f"M:{first_measure.abc_numerator}/{first_measure.abc_denominator}",
+        f"L:1/{unit_denominator}",
+        f"Q:1/4={int(round(estimate_tempo(score)))}",
+        'V: Vocal clef=treble name="Vocal Melody" snm="Vocal"',
+        'V: Ins clef=treble name="Ins Melody" snm="Inst."',
+        f"K:{first_key}",
+    ]
+    for group in _measure_groups(score):
+        lines.extend(f"% {label}" for label in group.structure_labels)
+        first_group_measure = group.measures[0]
+        for voice_id in VOICE_IDS:
+            lines.append(f"V: {voice_id}")
+            if group.meter_changed:
+                lines.append(
+                    f"M:{first_group_measure.abc_numerator}/"
+                    f"{first_group_measure.abc_denominator}"
+                )
+            if group.key_changed:
+                lines.append(
+                    f"K:{score.key_arr[first_group_measure.start_t]}"
+                )
+            lines.append(
+                _render_voice_group(
+                    score,
+                    voice_id,
+                    group.measures,
+                    unit_denominator,
+                )
+            )
+    text = "\n".join(lines) + "\n"
+    validate_serialized_abc(text, score)
+    return text
+
+
+_MUSIC_ELEMENT_RE = re.compile(
+    r'"(?P<quoted>[^"]*)"'
+    r"|\[K:(?P<key>[^\]]+)\]"
+    r"|(?P<note>[_=^]*[A-Ga-gz][,']*)(?P<duration>\d*)(?P<tie>-?)"
+)
+
+
+def _parse_music_measure(line: str, expected: int, context: str):
+    body = line
+    if body == "Z":
+        return [], []
+    position = 0
+    cursor = 0
+    quoted_events = []
+    key_events = []
+    for match in _MUSIC_ELEMENT_RE.finditer(body):
+        gap = body[cursor:match.start()]
+        if gap.strip():
+            raise AbcRebuildError(f"{context}: unsupported serialized ABC tokens {gap!r}")
+        cursor = match.end()
+        if match.group("quoted") is not None:
+            quoted_events.append((position, match.group("quoted")))
+            continue
+        if match.group("key") is not None:
+            key_events.append((position, match.group("key")))
+            continue
+        note = match.group("note")
+        tie = match.group("tie")
+        if tie and note == "z":
+            raise AbcRebuildError(f"{context}: a rest cannot be tied")
+        duration_text = match.group("duration")
+        duration = int(duration_text) if duration_text else 1
+        if duration not in _SUPPORTED_DURATION_UNITS:
+            raise AbcRebuildError(
+                f"{context}: duration {duration} is not parser-representable"
+            )
+        position += duration
+    if body[cursor:].strip():
+        raise AbcRebuildError(
+            f"{context}: unsupported serialized ABC tokens {body[cursor:]!r}"
+        )
+    if position != expected:
+        raise AbcRebuildError(
+            f"{context}: duration {position} does not match meter duration {expected}"
+        )
+    if re.search(r"(^|[\s|])-[_=^A-Ga-g]", line):
+        raise AbcRebuildError(f"{context}: tie is written before its second note")
+    return quoted_events, key_events
+
+
+def _expected_measure_chords(
+    score: RebuiltAbcScore,
+    measure: Measure,
+    unit_denominator: int,
+) -> list[tuple[int, str]]:
+    expected = []
+    leading_padding = (
+        _measure_padding_units(measure, unit_denominator)
+        if measure.pad_before
+        else 0
+    )
+    for t in range(measure.start_t, measure.end_t):
+        if t != measure.start_t and score.chord_arr[t] == score.chord_arr[t - 1]:
+            continue
+        position = leading_padding + _duration_units(
+            score,
+            measure.start_t,
+            t,
+            unit_denominator,
+        )
+        chord = str(score.chord_arr[t])
+        text = chord_symbol_to_abc(chord)
+        if text is not None:
+            expected.append((position, text))
+    return expected
+
+
+def _expected_measure_keys(
+    score: RebuiltAbcScore,
+    measure: Measure,
+    unit_denominator: int,
+) -> list[tuple[int, str]]:
+    leading_padding = (
+        _measure_padding_units(measure, unit_denominator)
+        if measure.pad_before
+        else 0
+    )
+    return [
+        (
+            leading_padding
+            + _duration_units(score, measure.start_t, t, unit_denominator),
+            str(score.key_arr[t]),
+        )
+        for t in range(measure.start_t + 1, measure.end_t)
+        if score.key_arr[t] != score.key_arr[t - 1]
+    ]
+
+
+def _parse_voice_group(lines, cursor, voice_id, group_index):
+    expected_voice_field = f"V: {voice_id}"
+    if cursor >= len(lines) or lines[cursor] != expected_voice_field:
+        observed = lines[cursor] if cursor < len(lines) else "<end>"
+        raise AbcRebuildError(
+            f"Group {group_index}: expected {expected_voice_field}, got {observed!r}"
+        )
+    cursor += 1
+    fields = {}
+    while cursor < len(lines) and (
+        lines[cursor].startswith("M:")
+        or lines[cursor].startswith("K:")
+    ):
+        name, value = lines[cursor].split(":", 1)
+        if name in fields:
+            raise AbcRebuildError(
+                f"Group {group_index} {voice_id}: repeated {name}: field"
+            )
+        fields[name] = value
+        cursor += 1
+    if cursor >= len(lines):
+        raise AbcRebuildError(
+            f"Group {group_index} {voice_id}: missing music line"
+        )
+    music_line = lines[cursor]
+    if music_line.startswith(("V:", "M:", "K:", "%")):
+        raise AbcRebuildError(
+            f"Group {group_index} {voice_id}: invalid music line {music_line!r}"
+        )
+    cursor += 1
+    split_bars = music_line.split("|")
+    if not split_bars or split_bars[-1].strip():
+        raise AbcRebuildError(
+            f"Group {group_index} {voice_id}: music line must end with a barline"
+        )
+    serialized_bars = [bar.strip() for bar in split_bars[:-1]]
+    if any(not bar for bar in serialized_bars):
+        raise AbcRebuildError(
+            f"Group {group_index} {voice_id}: empty serialized measure"
+        )
+    bars = []
+    for bar in serialized_bars:
+        match = re.fullmatch(r"Z(?P<count>[1-4])?", bar)
+        if match is None:
+            bars.append(bar)
+            continue
+        if match.group("count") == "1":
+            raise AbcRebuildError(
+                f"Group {group_index} {voice_id}: Z1 must be written as Z"
+            )
+        bars.extend(["Z"] * int(match.group("count") or "1"))
+    if not 1 <= len(bars) <= 4:
+        raise AbcRebuildError(
+            f"Group {group_index} {voice_id}: expected 1-4 semantic measures"
+        )
+    return cursor, fields, bars
+
+
+def validate_serialized_abc(text: str, score: RebuiltAbcScore) -> None:
+    """Validate invariants that must hold before any ABC is written."""
+
+    lines = text.splitlines()
+    if not lines or lines[0] != "X:1":
+        raise AbcRebuildError("ABC must start with X:1")
+    if len(lines) < 2 or lines[1] != "T:":
+        raise AbcRebuildError("ABC title must be fixed as empty T:")
+    if any(line.startswith(("%abc-", "I:abc-creator")) for line in lines):
+        raise AbcRebuildError("ABC must not contain version or creator metadata")
+    if "%%MIDI gchordoff" in text:
+        raise AbcRebuildError("ABC must not contain %%MIDI gchordoff")
+    if "% ss2" in text:
+        raise AbcRebuildError("ABC must not contain % ss2 metadata")
+    header_voice_ids = [
+        match.group(1)
+        for line in lines
+        if (match := re.match(r"^V: (Vocal|Ins) ", line))
+    ]
+    if header_voice_ids != list(VOICE_IDS):
+        raise AbcRebuildError(f"Expected fixed Vocal/Ins voice definitions, got {header_voice_ids!r}")
+
+    header_key_index = next(
+        (
+            index
+            for index, line in enumerate(lines)
+            if index > 0
+            and line.startswith("K:")
+            and any(
+                header_index < index
+                for header_index, header_line in enumerate(lines)
+                if header_line.startswith("V: Ins ")
+            )
+        ),
+        None,
+    )
+    if header_key_index is None:
+        raise AbcRebuildError("ABC header K: field is missing")
+    first_measure = score.measures[0]
+    expected_header_meter = (
+        f"M:{first_measure.abc_numerator}/{first_measure.abc_denominator}"
+    )
+    header_meters = [
+        line
+        for line in lines[:header_key_index + 1]
+        if line.startswith("M:")
+    ]
+    if header_meters != [expected_header_meter]:
+        raise AbcRebuildError(
+            f"ABC header meters {header_meters!r} "
+            f"!= {[expected_header_meter]!r}"
+        )
+    expected_header_key = f"K:{score.key_arr[first_measure.start_t]}"
+    header_keys = [
+        line
+        for line in lines[:header_key_index + 1]
+        if line.startswith("K:")
+    ]
+    if header_keys != [expected_header_key]:
+        raise AbcRebuildError(
+            f"ABC header keys {header_keys!r} "
+            f"!= {[expected_header_key]!r}"
+        )
+
+    unit_denominator = abc_unit_denominator(score)
+    expected_groups = _measure_groups(score)
+    cursor = header_key_index + 1
+    for group_index, group in enumerate(expected_groups):
+        structure_labels = []
+        while cursor < len(lines) and lines[cursor].startswith("% "):
+            structure_labels.append(lines[cursor][2:].strip())
+            cursor += 1
+        if structure_labels != group.structure_labels:
+            raise AbcRebuildError(
+                f"Group {group_index}: structure labels "
+                f"{structure_labels!r} != {group.structure_labels!r}"
+            )
+
+        cursor, vocal_fields, vocal_bars = _parse_voice_group(
+            lines,
+            cursor,
+            "Vocal",
+            group_index,
+        )
+        cursor, ins_fields, ins_bars = _parse_voice_group(
+            lines,
+            cursor,
+            "Ins",
+            group_index,
+        )
+        if vocal_fields != ins_fields:
+            raise AbcRebuildError(
+                f"Group {group_index}: meter/key changes must be scoped to both voices"
+            )
+        first_measure = group.measures[0]
+        expected_fields = {}
+        if group.meter_changed:
+            expected_fields["M"] = (
+                f"{first_measure.abc_numerator}/{first_measure.abc_denominator}"
+            )
+        if group.key_changed:
+            expected_fields["K"] = str(
+                score.key_arr[first_measure.start_t]
+            )
+        if vocal_fields != expected_fields:
+            raise AbcRebuildError(
+                f"Group {group_index}: fields {vocal_fields!r} "
+                f"!= required changes {expected_fields!r}"
+            )
+        if (
+            len(vocal_bars) != len(group.measures)
+            or len(ins_bars) != len(group.measures)
+        ):
+            raise AbcRebuildError(
+                f"Group {group_index}: both voices must contain "
+                f"{len(group.measures)} measures"
+            )
+
+        for bar_index, measure in enumerate(group.measures):
+            expected_duration = (
+                measure.abc_numerator
+                * unit_denominator
+                // measure.abc_denominator
+            )
+            for voice_id, bars in (
+                ("Vocal", vocal_bars),
+                ("Ins", ins_bars),
+            ):
+                quoted_events, key_events = _parse_music_measure(
+                    bars[bar_index],
+                    expected_duration,
+                    f"measure {measure.index} {voice_id}",
+                )
+                expected_keys = _expected_measure_keys(
+                    score,
+                    measure,
+                    unit_denominator,
+                )
+                if key_events != expected_keys:
+                    raise AbcRebuildError(
+                        f"Measure {measure.index} {voice_id}: inline keys "
+                        f"{key_events!r} != {expected_keys!r}"
+                    )
+                if voice_id == "Vocal":
+                    expected_chords = _expected_measure_chords(
+                        score,
+                        measure,
+                        unit_denominator,
+                    )
+                    if quoted_events != expected_chords:
+                        raise AbcRebuildError(
+                            f"Measure {measure.index}: chord symbols "
+                            f"{quoted_events!r} != {expected_chords!r}"
+                        )
+                elif quoted_events:
+                    raise AbcRebuildError(
+                        f"Measure {measure.index}: chords must only be in Vocal"
+                    )
+    if cursor != len(lines):
+        raise AbcRebuildError(
+            f"Unexpected trailing ABC body lines: {lines[cursor:cursor + 5]!r}"
+        )
+
+
+def abc_paths_from_melody(
+    melody_midi_path,
+    output_path=None,
+    *,
+    melody_only=False,
+):
+    melody = Path(melody_midi_path)
+    if melody.name.endswith("_raw_full_melody.mid"):
+        raise AbcRebuildError(f"Raw melody MIDI is not a valid ABC input: {melody}")
+    if not melody.name.endswith("_melody.mid"):
+        raise AbcRebuildError(f"Expected an exact *_melody.mid input, got {melody}")
+    stem = melody.name[: -len("_melody.mid")]
+    prefix = melody.with_name(stem)
+    default_suffix = "_melody_only.abc" if melody_only else "_full.abc"
+    return {
+        "melody_midi": melody,
+        "beats": Path(str(prefix) + "_beats.txt"),
+        "chords": Path(str(prefix) + "_chords.txt"),
+        "keys": Path(str(prefix) + "_keys.txt"),
+        "structures": Path(str(prefix) + "_structures.txt"),
+        "output": (
+            Path(output_path)
+            if output_path is not None
+            else Path(str(prefix) + default_suffix)
+        ),
+    }
+
+
+def preflight_exports(
+    melody_midi_path,
+    output_path=None,
+    *,
+    melody_only=False,
+):
+    paths = abc_paths_from_melody(
+        melody_midi_path,
+        output_path=output_path,
+        melody_only=melody_only,
+    )
+    required = {"melody_midi", "beats", "keys", "structures"}
+    if not melody_only:
+        required.add("chords")
+    missing = [
+        str(path)
+        for name, path in paths.items()
+        if name in required and not path.is_file()
+    ]
+    if missing:
+        raise FileNotFoundError(
+            f"{paths['melody_midi']}: missing required companion file(s): {', '.join(missing)}"
+        )
+    return paths
+
+
+def generate_abc_from_exports(
+    melody_midi_path,
+    *,
+    output_path=None,
+    meter_conflict="infer",
+    melody_only=False,
+):
+    paths = preflight_exports(
+        melody_midi_path,
+        output_path=output_path,
+        melody_only=melody_only,
+    )
+    score = build_rebuilt_abc_score(
+        paths["melody_midi"],
+        paths["beats"],
+        paths["chords"],
+        paths["keys"],
+        paths["structures"],
+        meter_conflict=meter_conflict,
+        melody_only=melody_only,
+    )
+    return score_to_abc(score), score, paths
+
+
+def generate_abc_from_data(melody_midi, beats, chords, keys, structures, *,
+                           meter_conflict="infer", melody_only=False):
+    """Return validated ABC text and its score without filesystem access."""
+    score = build_rebuilt_abc_score_from_data(
+        melody_midi, beats, chords, keys, structures,
+        meter_conflict=meter_conflict, melody_only=melody_only,
+    )
+    return score_to_abc(score), score

pipeline_sheetsage2.py

@@ -0,0 +1,259 @@
+"""Whole-song inference with cached overlap prefixes and right-hand audio context."""
+from pathlib import Path
+import json
+import re
+import time
+
+import torch
+
+from .io_sheetsage2 import atomic_write_text
+from .audio_sheetsage2 import SAMPLE_RATE, load_audio, slice_audio
+from .generation_sheetsage2 import (
+    FULL_TASK_PROMPTS, build_overlap_prefix_tokens, constrained_prompt_generate,
+    decode_generated_tokens, event_time_map, stitched_window_events, write_window_tokens,
+)
+from .exports_sheetsage2 import export_result
+
+
+def _tensor_files(output_dir):
+    """Inventory only files owned by the optional tensor exporter."""
+    files = set()
+    tensor_dir = output_dir / "tensors"
+    if tensor_dir.is_symlink():
+        return files
+    for directory in tensor_dir.glob("window-*"):
+        if re.fullmatch(r"window-\d{4,}", directory.name) and directory.is_dir() and not directory.is_symlink():
+            for path in directory.iterdir():
+                if path.is_file() and re.fullmatch(r"(?:index\.json|audio\.safetensors|(?:tokens|decoder)-\d{4,}\.safetensors)", path.name):
+                    files.add(path)
+    return files
+
+
+def sliding_window_plan(duration, window_seconds=300.0, overlap_seconds=200.0, lookahead_seconds=100.0):
+    if not duration > 0 or not window_seconds > 0:
+        raise ValueError("Duration and window length must be positive")
+    if not 0 <= lookahead_seconds <= overlap_seconds < window_seconds:
+        raise ValueError("Require 0 <= lookahead <= overlap < window length")
+    hop = window_seconds - overlap_seconds
+    start, accepted = 0.0, 0.0
+    result = []
+    while True:
+        last = start + window_seconds >= duration - 1e-6
+        accept_end = duration if last else start + window_seconds - lookahead_seconds
+        result.append(dict(start=start, end=min(duration, start + window_seconds),
+                           accept_start=accepted, accept_end=accept_end, prefix_end=accepted,
+                           generation_stop=None if last else window_seconds - lookahead_seconds))
+        if last:
+            return result
+        accepted = accept_end
+        start = min(start + hop, duration - window_seconds)
+
+
+class Transcriber:
+    def __init__(self, model, dtype="bf16"):
+        self.model = model
+        self.device = next(model.parameters()).device
+        self.dtype = {"bf16": torch.bfloat16, "fp32": None}[dtype]
+
+    @torch.inference_mode()
+    def analyze(self, audio_path, output_dir=None, *, prompts=FULL_TASK_PROMPTS,
+                sampling_rate=None, max_seconds=None, preset="default",
+                overlap_seconds=None, lookahead_seconds=None, progress=None,
+                export_logits=False, export_scores=False, export_embeddings=False,
+                output_hidden_states=False, melody_only=False):
+        def report(stage, **fields):
+            if progress:
+                progress(dict(stage=stage, **fields))
+
+        if not isinstance(melody_only, bool):
+            raise ValueError("melody_only must be True or False")
+        if preset not in ("default", "paper"):
+            raise ValueError("preset must be default or paper")
+        defaults = (200.0, 100.0) if preset == "default" else (100.0, 0.0)
+        overlap_seconds = defaults[0] if overlap_seconds is None else overlap_seconds
+        lookahead_seconds = defaults[1] if lookahead_seconds is None else lookahead_seconds
+        if preset == "paper" and (overlap_seconds, lookahead_seconds) != defaults:
+            raise ValueError("paper preset fixes overlap=100 and lookahead=0")
+        started = time.monotonic()
+        output_dir = Path(output_dir) if output_dir is not None else None
+        if output_dir is not None:
+            output_dir.mkdir(parents=True, exist_ok=True)
+        previous_tensors = _tensor_files(output_dir) if output_dir is not None else set()
+        current_tensors = set()
+        tensor_results = []
+        prompts = self.model.tokenizer.normalize_prompts(prompts)
+        if "timestamp" not in prompts:
+            raise ValueError("timestamp is required to export timed annotations")
+        report("audio")
+        audio = load_audio(audio_path, sampling_rate=sampling_rate, max_seconds=max_seconds, preset=preset)
+        duration = len(audio) / SAMPLE_RATE
+        window_length = float(self.model.hparams.input_audio_length)
+        plan = sliding_window_plan(duration, window_length, overlap_seconds, lookahead_seconds)
+        if self.device.type == "cuda":
+            torch.cuda.reset_peak_memory_stats(self.device)
+        stitched, records, warnings = [], [], []
+        for index, window in enumerate(plan):
+            report("encoding", window=index + 1, windows=len(plan), start=window["start"])
+            segment = slice_audio(audio, window["start"], window_length)[None].to(self.device)
+            prefix, base = None, 0
+            if index:
+                _, prefix, base = build_overlap_prefix_tokens(
+                    stitched, self.model.tokenizer, prompts, window["start"], window["prefix_end"])
+                if prefix is not None:
+                    if preset == "paper" and len(prefix) >= self.model.max_output_seq_len - 16:
+                        warnings.append(f"Window {index + 1}: overlap prefix exceeded the context")
+                        prefix = None
+                    elif preset != "paper" and len(prefix) >= self.model.max_output_seq_len - 128:
+                        raise ValueError("Overlap prefix fills the context; reduce overlap_seconds")
+            tick = time.monotonic()
+            memory = None
+            tensor_record = None
+            if export_embeddings or output_hidden_states or export_logits or export_scores:
+                from .tensors_sheetsage2 import WindowTensorWriter
+                tensor_record = WindowTensorWriter(output_dir, index, window, export_logits, export_scores)
+                if export_embeddings or output_hidden_states:
+                    memory = tensor_record.audio_features(self.model, segment, self.dtype, output_hidden_states)
+            tokens = constrained_prompt_generate(
+                self.model, segment, prompts, self.model.max_output_seq_len,
+                prefix_tokens=prefix, autocast_dtype=self.dtype,
+                stop_time_seconds=(None if preset == "paper" else
+                                   window["generation_stop"] if window["generation_stop"] is not None else
+                                   min(duration - window["start"], window_length)),
+                memory=memory,
+                step_callback=tensor_record.capture if tensor_record is not None and (export_logits or export_scores) else None,
+                progress_callback=lambda n: report("decoding", window=index + 1, windows=len(plan), tokens=n),
+            )
+            if tensor_record is not None:
+                if export_embeddings:
+                    tensor_record.decoder_features(self.model, segment, tokens, self.dtype, memory)
+                tensor_data = tensor_record.finish()
+                if tensor_data is not None:
+                    tensor_results.append(tensor_data)
+                if tensor_record.directory is not None:
+                    current_tensors.update(tensor_record.directory / name for name in tensor_record.files)
+                    current_tensors.add(tensor_record.directory / "index.json")
+            if len(tokens) > self.model.max_output_seq_len:
+                warnings.append(f"Window {index + 1} reached the token limit; inspect its token coverage")
+            decoded, warning = decode_generated_tokens(self.model.tokenizer, tokens, Path(audio_path).stem if isinstance(audio_path, (str, Path)) else "audio", index)
+            if warning:
+                warnings.append(warning["error"])
+            lookup = event_time_map(decoded, window_length)
+            accepted = stitched_window_events(
+                decoded, lookup, window["start"], window["accept_start"], window["accept_end"],
+                duration, index, global_subbeat_base=base or 0,
+            )
+            stitched.extend(accepted)
+            if preset == "paper":
+                stitched.sort(key=lambda e: (float(e.get("time", 0)), int(e.get("window_index", 0)),
+                                             int(e.get("source_subbeat", e["subbeat"]))))
+            record = dict(window, window_index=index, prefix_tokens=0 if prefix is None else len(prefix),
+                          tokens=tokens, events=len(decoded["events"]), accepted_events=len(accepted),
+                          elapsed_seconds=time.monotonic() - tick)
+            records.append(record)
+            report("window_complete", window=index + 1, windows=len(plan), tokens=len(tokens))
+        if preset != "paper":
+            stitched.sort(key=lambda e: (e["time"], e["global_subbeat"]))
+        decoded = dict(schema_version=self.model.tokenizer.schema_version,
+                       prompts=list(prompts), events=stitched, has_eos=True)
+        report("notation")
+        exported = export_result(decoded, self.model.tokenizer, output_dir, duration,
+                                 paper=preset == "paper", melody_only=melody_only)
+        payload = exported.pop("payload")
+        if output_dir is not None:
+            write_window_tokens(output_dir / "tokens.txt", records, self.model.tokenizer)
+            atomic_write_text(output_dir / "tokens.json", json.dumps([
+                dict(r, tokens=r["tokens"].tolist()) for r in records
+            ]))
+        result = dict(
+            audio=Path(audio_path).name if isinstance(audio_path, (str, Path)) else "audio",
+            duration_seconds=duration, prompts=list(prompts), preset=preset, melody_only=melody_only,
+            dtype="bf16" if self.dtype and self.device.type == "cuda" else "fp32",
+            window_seconds=window_length, overlap_seconds=overlap_seconds, lookahead_seconds=lookahead_seconds,
+            windows=[dict(r, tokens=len(r["tokens"])) for r in records],
+            elapsed_seconds=time.monotonic() - started, warnings=warnings,
+            peak_gpu_mib=torch.cuda.max_memory_allocated(self.device) / 1024**2 if self.device.type == "cuda" else 0,
+            **exported,
+        )
+        if output_dir is not None:
+            atomic_write_text(output_dir / "result.json", json.dumps(result, indent=2))
+        for path in previous_tensors - current_tensors:
+            path.unlink(missing_ok=True)
+        for directory in {path.parent for path in previous_tensors - current_tensors}:
+            if directory.is_dir() and not any(directory.iterdir()):
+                directory.rmdir()
+        report("complete", **exported)
+        return dict(result, num_events=result["events"], **payload,
+                    tokens=[r["tokens"] for r in records], tensors=tensor_results,
+                    _metadata=result)
+
+
+@torch.inference_mode()
+def transcribe(model, audio, output_dir=None, *, render_audio=False, render_score=False,
+               render_parts=("mix",), dtype="bf16", melody_only=False, **kwargs):
+    """Transcribe a path, encoded audio bytes, binary stream, or waveform.
+
+    Arrays use channels-first layout and require sampling_rate. With
+    output_dir=None, all audio/results stay in memory: ABC is text, MIDI is
+    bytes, events are a list, and optional features are CPU tensors grouped by
+    window. A directory saves the standard output files and writes optional
+    tensors to disk instead of keeping them in memory. Optional
+    rendering also returns bytes/text when no output directory is given.
+    melody_only=True omits chords from ABC and MIDI playback, retaining both
+    melody voices and the original decoded events/LAB annotations. If the
+    requested melody-only ABC cannot be built, raises RuntimeError with the
+    completed transcription available as error.result.
+    """
+    if not isinstance(melody_only, bool):
+        raise ValueError("melody_only must be True or False")
+    output_dir = Path(output_dir) if output_dir is not None else None
+    if render_audio or render_score:
+        from .rendering_sheetsage2 import render_outputs, render_memory, validate_render_options
+        formats, render_parts = validate_render_options(audio=render_audio, score=render_score, parts=render_parts)
+    result = Transcriber(model, dtype=dtype).analyze(audio, output_dir, melody_only=melody_only, **kwargs)
+    metadata = result.pop("_metadata", None)
+    if metadata is None:
+        metadata = dict(result)
+    if render_audio or render_score:
+        try:
+            assets = Path(__file__).with_name("render_assets")
+            if not assets.is_dir():
+                source = getattr(model, "_source_snapshot", Path(model.config._name_or_path))
+                if (source / "render_assets").is_dir():
+                    assets = source / "render_assets"
+                else:
+                    from huggingface_hub import snapshot_download
+                    assets = Path(snapshot_download(model.config._name_or_path,
+                        revision=model.config._commit_hash, allow_patterns=["render_assets/**"],
+                        **getattr(model, "_hub_resource_options", {}))) / "render_assets"
+            # A missing score does not prevent a requested MIDI piano preview.
+            rendered = None
+            if render_audio or not result.get("abc_error"):
+                options = dict(audio=render_audio, score=() if result.get("abc_error") else formats,
+                               parts=render_parts, assets_dir=assets)
+                if output_dir is None:
+                    rendered = render_memory(midi=result["midi"], abc=result["abc"],
+                                             duration=result["duration_seconds"], **options)
+                else:
+                    rendered = render_outputs(input_dir=output_dir, output_dir=output_dir, **options)
+            result["rendered"] = rendered
+            if output_dir is not None:
+                metadata["rendered"] = rendered
+            if formats and result.get("abc_error"):
+                raise ValueError(f"ABC unavailable: {result['abc_error']}")
+        except Exception as exc:
+            result["render_error"] = str(exc)
+            metadata["render_error"] = str(exc)
+            if output_dir is not None:
+                atomic_write_text(output_dir / "result.json", json.dumps(metadata, indent=2))
+            location = f"saved to {output_dir.resolve()}" if output_dir is not None else "completed in memory"
+            error = RuntimeError(f"Transcription {location}; rendering failed: {exc}")
+            error.result = result
+            raise error from exc
+        if output_dir is not None:
+            atomic_write_text(output_dir / "result.json", json.dumps(metadata, indent=2))
+    if melody_only and not result.get("abc"):
+        reason = result.get("abc_error") or "No ABC score was produced"
+        error = RuntimeError(f"Melody-only ABC unavailable: {reason}")
+        error.result = result
+        raise error
+    return result

processing_sheetsage2.py

@@ -0,0 +1,109 @@
+"""Waveform preparation and symbolic decoding for SheetSage2."""
+
+import numbers
+
+import torch
+import torchaudio
+from transformers import ProcessorMixin
+from transformers.feature_extraction_utils import BatchFeature
+
+from .tokenization_sheetsage2 import SheetSage2Tokenizer
+
+
+def _hf_relative_dependencies():
+    # Keep standalone AutoProcessor loading compatible with Transformers 4.45.
+    from .durations_sheetsage2 import DURATION_TEMPLATES
+    from .labels_sheetsage2 import STRUCTURE_LABELS
+    from .schema_sheetsage2 import get_prompt_multitask_schema
+
+
+class SheetSage2Processor(ProcessorMixin):
+    """Prepare mono waveforms without amplitude normalization.
+
+    Pass one mono waveform, a batch tensor, or a list of mono waveforms. Use
+    ``model.transcribe`` for files and audio longer than one model window.
+    """
+
+    attributes = []
+    valid_kwargs = ["sampling_rate", "window_seconds", "time_hz", "schema_version", "tokenizer_fingerprint"]
+
+    def __init__(self, sampling_rate=24000, window_seconds=300.0, time_hz=100,
+                 schema_version="v1", tokenizer_fingerprint="5ba3325af0344c7f", **kwargs):
+        super().__init__(**{key: value for key, value in kwargs.items() if key == "chat_template"})
+        self.sampling_rate = int(sampling_rate)
+        self.window_seconds = float(window_seconds)
+        self.time_hz = int(time_hz)
+        self.schema_version = str(schema_version)
+        self.tokenizer_fingerprint = str(tokenizer_fingerprint)
+        self.tokenizer = SheetSage2Tokenizer(
+            self.window_seconds, self.time_hz, self.schema_version,
+            expected_fingerprint=self.tokenizer_fingerprint,
+        )
+
+    @property
+    def model_input_names(self):
+        return ["input_values", "attention_mask"]
+
+    @classmethod
+    def from_model_config(cls, config):
+        return cls(config.sampling_rate, config.input_audio_length, config.time_hz,
+                   config.tokenizer_schema_version, config.tokenizer_fingerprint)
+
+    def __call__(self, audio, sampling_rate=None, padding=True, return_tensors="pt",
+                 return_attention_mask=True):
+        source_rate = self.sampling_rate if sampling_rate is None else int(sampling_rate)
+        if source_rate <= 0:
+            raise ValueError("sampling_rate must be positive.")
+        if isinstance(audio, (str, bytes)):
+            raise ValueError("Pass waveform samples here; use model.transcribe for audio files.")
+        if isinstance(audio, (list, tuple)) and audio and not isinstance(audio[0], numbers.Number):
+            waveforms = [torch.as_tensor(value) for value in audio]
+        else:
+            value = torch.as_tensor(audio)
+            waveforms = list(value) if value.ndim == 2 else [value]
+        if not waveforms:
+            raise ValueError("Provide at least one waveform.")
+        prepared = []
+        maximum = round(self.window_seconds * self.sampling_rate)
+        for waveform in waveforms:
+            if waveform.ndim != 1 or not waveform.is_floating_point() or not torch.isfinite(waveform).all():
+                raise ValueError("Each waveform must be a one-dimensional finite floating-point array.")
+            waveform = waveform.to(dtype=torch.float32)
+            if source_rate != self.sampling_rate:
+                waveform = torchaudio.functional.resample(waveform, source_rate, self.sampling_rate)
+            if waveform.numel() < 1025:
+                raise ValueError("Each waveform must contain at least 1025 samples at 24 kHz.")
+            if waveform.numel() > maximum:
+                raise ValueError("Audio exceeds one model window; use model.transcribe for whole songs.")
+            prepared.append(waveform)
+        if len({str(value.device) for value in prepared}) != 1:
+            raise ValueError("All waveforms in a batch must be on the same device.")
+        if padding is False:
+            length = max(value.numel() for value in prepared)
+            if any(value.numel() != length for value in prepared):
+                raise ValueError("Use padding=True for waveforms of different lengths.")
+        elif padding is True or padding == "max_length":
+            length = maximum
+        elif padding == "longest":
+            length = max(value.numel() for value in prepared)
+        else:
+            raise ValueError("padding must be True, False, 'max_length', or 'longest'.")
+        lengths = torch.tensor([value.numel() for value in prepared], device=prepared[0].device)
+        values = torch.stack([torch.nn.functional.pad(value, (0, length - value.numel())) for value in prepared])
+        data = {"input_values": values}
+        if return_attention_mask:
+            data["attention_mask"] = (torch.arange(length, device=values.device)[None] < lengths[:, None]).long()
+        if return_tensors == "np":
+            data = {key: value.cpu().numpy() for key, value in data.items()}
+        elif return_tensors not in {None, "pt"}:
+            raise ValueError("return_tensors must be 'pt', 'np', or None.")
+        return BatchFeature(data=data)
+
+    def decode(self, token_ids, strict=True):
+        return self.tokenizer.decode_sequence(token_ids, strict=strict)
+
+    def batch_decode(self, sequences, strict=True):
+        return [self.decode(tokens, strict=strict) for tokens in sequences]
+
+
+SheetSage2Processor.register_for_auto_class()

processor_config.json

@@ -0,0 +1,11 @@
+{
+  "processor_class": "SheetSage2Processor",
+  "sampling_rate": 24000,
+  "window_seconds": 300.0,
+  "time_hz": 100,
+  "schema_version": "v1",
+  "tokenizer_fingerprint": "5ba3325af0344c7f",
+  "auto_map": {
+    "AutoProcessor": "processing_sheetsage2.SheetSage2Processor"
+  }
+}

render.py

@@ -0,0 +1,45 @@
+"""Render existing SheetSage2 MIDI and ABC outputs without loading a model."""
+import argparse
+import json
+from pathlib import Path
+import sys
+
+SCRIPT_DIR = Path(__file__).absolute().parent
+sys.path.insert(0, str(SCRIPT_DIR))
+
+from rendering_sheetsage2 import render_outputs
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--input", help="Transcription output directory.")
+    parser.add_argument("--midi", help="MIDI file with original note timing.")
+    parser.add_argument("--abc", help="ABC score file.")
+    parser.add_argument("--output", help="Output directory; defaults to --input or rendered/.")
+    parser.add_argument("--audio", action="store_true", help="Render piano WAV.")
+    parser.add_argument("--score", default="", help="Comma-separated pdf,svg,png.")
+    parser.add_argument("--parts", default="mix", help="Comma-separated mix,melody,vocal,instrumental,chords, or all (audio only).")
+    parser.add_argument("--duration", type=float, help="Minimum audio duration in seconds; preserves trailing silence.")
+    args = parser.parse_args()
+    audio = args.audio
+    score = args.score
+    if not audio and not score:
+        if args.input:
+            audio, score = True, "pdf"
+        else:
+            audio, score = bool(args.midi), "pdf" if args.abc else ""
+    if not args.input and not args.midi and not args.abc:
+        parser.error("Provide --input, --midi, or --abc.")
+    try:
+        result = render_outputs(args.input, midi=args.midi, abc=args.abc,
+                                output_dir=args.output, audio=audio, score=score,
+                                parts=args.parts, duration=args.duration)
+    except (ValueError, OSError, RuntimeError) as exc:
+        print(f"Rendering failed: {exc}", file=sys.stderr)
+        return 1
+    print(json.dumps(result, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

render_assets/DejaVuSans.ttf

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:7da195a74c55bef988d0d48f9508bd5d849425c1770dba5d7bfc6ce9ed848954
+size 757076

render_assets/LICENSE.abcjs

@@ -0,0 +1,21 @@
+Copyright (c) 2009-2024 Paul Rosen and Gregory Dyke
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+
+**This text is from: http://opensource.org/licenses/MIT**

render_assets/LICENSE.font

@@ -0,0 +1,187 @@
+Fonts are (c) Bitstream (see below). DejaVu changes are in public domain.
+Glyphs imported from Arev fonts are (c) Tavmjong Bah (see below)
+
+
+Bitstream Vera Fonts Copyright
+------------------------------
+
+Copyright (c) 2003 by Bitstream, Inc. All Rights Reserved. Bitstream Vera is
+a trademark of Bitstream, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of the fonts accompanying this license ("Fonts") and associated
+documentation files (the "Font Software"), to reproduce and distribute the
+Font Software, including without limitation the rights to use, copy, merge,
+publish, distribute, and/or sell copies of the Font Software, and to permit
+persons to whom the Font Software is furnished to do so, subject to the
+following conditions:
+
+The above copyright and trademark notices and this permission notice shall
+be included in all copies of one or more of the Font Software typefaces.
+
+The Font Software may be modified, altered, or added to, and in particular
+the designs of glyphs or characters in the Fonts may be modified and
+additional glyphs or characters may be added to the Fonts, only if the fonts
+are renamed to names not containing either the words "Bitstream" or the word
+"Vera".
+
+This License becomes null and void to the extent applicable to Fonts or Font
+Software that has been modified and is distributed under the "Bitstream
+Vera" names.
+
+The Font Software may be sold as part of a larger software package but no
+copy of one or more of the Font Software typefaces may be sold by itself.
+
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF COPYRIGHT, PATENT,
+TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL BITSTREAM OR THE GNOME
+FOUNDATION BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, INCLUDING
+ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF
+THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM OTHER DEALINGS IN THE
+FONT SOFTWARE.
+
+Except as contained in this notice, the names of Gnome, the Gnome
+Foundation, and Bitstream Inc., shall not be used in advertising or
+otherwise to promote the sale, use or other dealings in this Font Software
+without prior written authorization from the Gnome Foundation or Bitstream
+Inc., respectively. For further information, contact: fonts at gnome dot
+org.
+
+Arev Fonts Copyright
+------------------------------
+
+Copyright (c) 2006 by Tavmjong Bah. All Rights Reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the fonts accompanying this license ("Fonts") and
+associated documentation files (the "Font Software"), to reproduce
+and distribute the modifications to the Bitstream Vera Font Software,
+including without limitation the rights to use, copy, merge, publish,
+distribute, and/or sell copies of the Font Software, and to permit
+persons to whom the Font Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright and trademark notices and this permission notice
+shall be included in all copies of one or more of the Font Software
+typefaces.
+
+The Font Software may be modified, altered, or added to, and in
+particular the designs of glyphs or characters in the Fonts may be
+modified and additional glyphs or characters may be added to the
+Fonts, only if the fonts are renamed to names not containing either
+the words "Tavmjong Bah" or the word "Arev".
+
+This License becomes null and void to the extent applicable to Fonts
+or Font Software that has been modified and is distributed under the 
+"Tavmjong Bah Arev" names.
+
+The Font Software may be sold as part of a larger software package but
+no copy of one or more of the Font Software typefaces may be sold by
+itself.
+
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL
+TAVMJONG BAH BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.
+
+Except as contained in this notice, the name of Tavmjong Bah shall not
+be used in advertising or otherwise to promote the sale, use or other
+dealings in this Font Software without prior written authorization
+from Tavmjong Bah. For further information, contact: tavmjong @ free
+. fr.
+
+TeX Gyre DJV Math
+-----------------
+Fonts are (c) Bitstream (see below). DejaVu changes are in public domain.
+
+Math extensions done by B. Jackowski, P. Strzelczyk and P. Pianowski
+(on behalf of TeX users groups) are in public domain.
+
+Letters imported from Euler Fraktur from AMSfonts are (c) American
+Mathematical Society (see below).
+Bitstream Vera Fonts Copyright
+Copyright (c) 2003 by Bitstream, Inc. All Rights Reserved. Bitstream Vera
+is a trademark of Bitstream, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of the fonts accompanying this license (“Fonts”) and associated
+documentation
+files (the “Font Software”), to reproduce and distribute the Font Software,
+including without limitation the rights to use, copy, merge, publish,
+distribute,
+and/or sell copies of the Font Software, and to permit persons  to whom
+the Font Software is furnished to do so, subject to the following
+conditions:
+
+The above copyright and trademark notices and this permission notice
+shall be
+included in all copies of one or more of the Font Software typefaces.
+
+The Font Software may be modified, altered, or added to, and in particular
+the designs of glyphs or characters in the Fonts may be modified and
+additional
+glyphs or characters may be added to the Fonts, only if the fonts are
+renamed
+to names not containing either the words “Bitstream” or the word “Vera”.
+
+This License becomes null and void to the extent applicable to Fonts or
+Font Software
+that has been modified and is distributed under the “Bitstream Vera”
+names.
+
+The Font Software may be sold as part of a larger software package but
+no copy
+of one or more of the Font Software typefaces may be sold by itself.
+
+THE FONT SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF COPYRIGHT, PATENT,
+TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL BITSTREAM OR THE GNOME
+FOUNDATION
+BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, INCLUDING ANY GENERAL,
+SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, WHETHER IN AN
+ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF THE USE OR
+INABILITY TO USE
+THE FONT SOFTWARE OR FROM OTHER DEALINGS IN THE FONT SOFTWARE.
+Except as contained in this notice, the names of GNOME, the GNOME
+Foundation,
+and Bitstream Inc., shall not be used in advertising or otherwise to promote
+the sale, use or other dealings in this Font Software without prior written
+authorization from the GNOME Foundation or Bitstream Inc., respectively.
+For further information, contact: fonts at gnome dot org.
+
+AMSFonts (v. 2.2) copyright
+
+The PostScript Type 1 implementation of the AMSFonts produced by and
+previously distributed by Blue Sky Research and Y&Y, Inc. are now freely
+available for general use. This has been accomplished through the
+cooperation
+of a consortium of scientific publishers with Blue Sky Research and Y&Y.
+Members of this consortium include:
+
+Elsevier Science IBM Corporation Society for Industrial and Applied
+Mathematics (SIAM) Springer-Verlag American Mathematical Society (AMS)
+
+In order to assure the authenticity of these fonts, copyright will be
+held by
+the American Mathematical Society. This is not meant to restrict in any way
+the legitimate use of the fonts, such as (but not limited to) electronic
+distribution of documents containing these fonts, inclusion of these fonts
+into other public domain or commercial font collections or computer
+applications, use of the outline data to create derivative fonts and/or
+faces, etc. However, the AMS does require that the AMS copyright notice be
+removed from any derivative versions of the fonts which have been altered in
+any way. In addition, to ensure the fidelity of TeX documents using Computer
+Modern fonts, Professor Donald Knuth, creator of the Computer Modern faces,
+has requested that any alterations which yield different font metrics be
+given a different name.
+
+$Id$

render_assets/manifest.json

@@ -0,0 +1,106 @@
+{
+  "abcjs_version": "6.6.3",
+  "abcjs_revision": "5dc285c5a4a918d33f2ab4b3c381499847e88426",
+  "piano_revision": "cbd6b6f6d1af89ebfb69402860741288f08ff8b7",
+  "piano_source": "https://github.com/paulrosen/midi-js-soundfonts/tree/cbd6b6f6d1af89ebfb69402860741288f08ff8b7/FluidR3_GM/acoustic_grand_piano-mp3",
+  "files": {
+    "DejaVuSans.ttf": "7da195a74c55bef988d0d48f9508bd5d849425c1770dba5d7bfc6ce9ed848954",
+    "LICENSE.abcjs": "ab1072f859916529e284a8f43643146de9935041bb347a35559a96c87ce5566f",
+    "LICENSE.font": "7a083b136e64d064794c3419751e5c7dd10d2f64c108fe5ba161eae5e5958a93",
+    "abcjs-basic-min.js": "abdab74cf95c39fb9ff4ae0c96735b9c35222851f0844ce471ddd4354739bc75",
+    "renderer.js": "0756398dfe69fe1c54c8779252885fbf573d02eecbe3f2389a0b81e0f43fcd09",
+    "soundfonts/ATTRIBUTION.md": "87237050093c1d4f47f5c459f1e18b57ea6710f92d1a57b4462f8f5aa31e11be",
+    "soundfonts/acoustic_grand_piano-mp3/A0.mp3": "5c47e8142b04505c888b8edd7246a8881b4b30c4340682f0264191599df232fc",
+    "soundfonts/acoustic_grand_piano-mp3/A1.mp3": "abab379d4d0557abb93856f816b7bb395872e656533c3fe7f02048fc993834b7",
+    "soundfonts/acoustic_grand_piano-mp3/A2.mp3": "e21d9ab9b30c73c0aea921c2cd0dd59fece4cc021619927c9ff3dee71f0a9679",
+    "soundfonts/acoustic_grand_piano-mp3/A3.mp3": "02dee2fa184b9b94a5f72886c2370bd076103ebb76fc179982fa503e549dcc10",
+    "soundfonts/acoustic_grand_piano-mp3/A4.mp3": "4f1671ac831bc41c845e67b18e6c9ea200fc9b753bdffe124703b7141aa928c3",
+    "soundfonts/acoustic_grand_piano-mp3/A5.mp3": "2cccfe0aa8077bfd20bcbba470012faa0328ae97d5bd2297147c01f2b255e574",
+    "soundfonts/acoustic_grand_piano-mp3/A6.mp3": "87dab2b5bfdd8bafa575fc24b99591e87e5a0c991a8bbdc8aeb8a1e517b576d2",
+    "soundfonts/acoustic_grand_piano-mp3/A7.mp3": "ace76663dac4610a93259655f069835e6eb397b76aedf85c1f48a5036cf25687",
+    "soundfonts/acoustic_grand_piano-mp3/Ab1.mp3": "a9889722caea82aa67a8b7f600f1def8e51e095f1f423949c3a8e9dbf5c14abd",
+    "soundfonts/acoustic_grand_piano-mp3/Ab2.mp3": "b45bb57e125cdbbc3bb521ae643e67a90c0ff646d37e5b5284e5c70bfeff6c75",
+    "soundfonts/acoustic_grand_piano-mp3/Ab3.mp3": "843d633061631861c943266b4836573fe8ba8b8a10df9bd94adc380376cdb8ce",
+    "soundfonts/acoustic_grand_piano-mp3/Ab4.mp3": "e8612f8602d1c146f9b7f69a441ee518876ccdfa469457366c8064c25d9d3116",
+    "soundfonts/acoustic_grand_piano-mp3/Ab5.mp3": "31c86a311eb68761b8008359b34addfeec249d1c7d6795a52f8f2e172e3e8a05",
+    "soundfonts/acoustic_grand_piano-mp3/Ab6.mp3": "7775c09d08d344af9528edbf7abb6f59ac600e4d15efd6f139845bb107a822ed",
+    "soundfonts/acoustic_grand_piano-mp3/Ab7.mp3": "66932305995ff04e9e0244c5a408ec87c9131ab3915eac15c72c7659132ab0f2",
+    "soundfonts/acoustic_grand_piano-mp3/B0.mp3": "4422d1d2f0498aec427165415f5d665d78699e8623475215ce9b27c18b3d331f",
+    "soundfonts/acoustic_grand_piano-mp3/B1.mp3": "048003df58298d2659bff084885ad69d9531fdc03837c7ee39c8bcf68334b5b9",
+    "soundfonts/acoustic_grand_piano-mp3/B2.mp3": "be2df872b00b68adead4ca24ef68bd4a93bf0c4864d455d742171e5df91e86b7",
+    "soundfonts/acoustic_grand_piano-mp3/B3.mp3": "82c0463af9c9fe51d44aa59b71d2dccefab11c1ea98e2748ee93244f8af9169e",
+    "soundfonts/acoustic_grand_piano-mp3/B4.mp3": "5f09187820410b0f78575f232c3509f367478b7755b6eb5aa46ce6cf4c16a0e8",
+    "soundfonts/acoustic_grand_piano-mp3/B5.mp3": "4e0932827d3e9390080c4a9acd420e9b83871a5f73723feaf61d2d7f6b628b01",
+    "soundfonts/acoustic_grand_piano-mp3/B6.mp3": "d31aa62152acd598d55fb02cc024e59e0176a7dc13d27813882f299cae7baf7a",
+    "soundfonts/acoustic_grand_piano-mp3/B7.mp3": "6e1aad1cc92f17ebf6fe6161766cce279250e67a30569649481c77ab80db1677",
+    "soundfonts/acoustic_grand_piano-mp3/Bb0.mp3": "e4734f8d0285f0e5a39db7f61023510b46fb1570743b20d287479dcaa5536adb",
+    "soundfonts/acoustic_grand_piano-mp3/Bb1.mp3": "6d4face1b6559a08af3f9a49fcbc472b43e974e072156b31850ab9a230713aa3",
+    "soundfonts/acoustic_grand_piano-mp3/Bb2.mp3": "78cc11431a2a2d52294f0c714c59107a886f637806ae2cba63d50ff53585b93e",
+    "soundfonts/acoustic_grand_piano-mp3/Bb3.mp3": "6ac0f67f18e15db35553d4fcd83ceec4473ebe639e31659ce93cf8466cb06644",
+    "soundfonts/acoustic_grand_piano-mp3/Bb4.mp3": "d8f729899595116cb62ca9b7b801b4dfb9322bdf50d1bbfa847010e43a39f8f5",
+    "soundfonts/acoustic_grand_piano-mp3/Bb5.mp3": "51224d4c26f1c89b08e43865ef55d3638367f7f40fbc92e4ab88610b54d4301d",
+    "soundfonts/acoustic_grand_piano-mp3/Bb6.mp3": "394488d6cbd2c58b40f202e5acc238abdb73f261bcebd7105fb81d091113c4aa",
+    "soundfonts/acoustic_grand_piano-mp3/Bb7.mp3": "fe72a195f6036722e587e1597e54d66ec70e0ce11768e74e39bb2319bf256f80",
+    "soundfonts/acoustic_grand_piano-mp3/C1.mp3": "eb3b985e3b692cfe0c48550a26843fc3da44c7630c0b7bcfd820e87c5122cccc",
+    "soundfonts/acoustic_grand_piano-mp3/C2.mp3": "e02c5a80c03871e1889a3bb371d853f92294c1e8538ac06f70df0fd045540207",
+    "soundfonts/acoustic_grand_piano-mp3/C3.mp3": "7d0409ea3c40af25c6d3d606f12890f88f896d93c381b6eb8c58497f308b30d3",
+    "soundfonts/acoustic_grand_piano-mp3/C4.mp3": "b6d32e0d9d0c2e4b88165a2ec27b8787a970f131a03d96d065f28f158640af96",
+    "soundfonts/acoustic_grand_piano-mp3/C5.mp3": "7a4be6dae323ac5564ad1a617b554fd595e5e0a63f19c3581e3ee94c33ae2e4b",
+    "soundfonts/acoustic_grand_piano-mp3/C6.mp3": "6a0030c071ccd6c9a722455851d65b18cb86cbfe515772a6ded4c747eda339a0",
+    "soundfonts/acoustic_grand_piano-mp3/C7.mp3": "5e4cadc06eb25e2302dcc5bf1af76fe85ed258759d02c46e9169376ade83845e",
+    "soundfonts/acoustic_grand_piano-mp3/C8.mp3": "4ec066cab9362f6706b90fedc3249fa3c221769ee95ff52d7e46aaaf0a01fd16",
+    "soundfonts/acoustic_grand_piano-mp3/D1.mp3": "2389562397c7bdf2a856965b8b371eb6311be3cad2875c71d8ff4a607a242cea",
+    "soundfonts/acoustic_grand_piano-mp3/D2.mp3": "6233cc6f3670a287e33c7b8ece3b03a787ee1e169c8355432ce0b5e194bee612",
+    "soundfonts/acoustic_grand_piano-mp3/D3.mp3": "b8a5ed9cf147e10f484f3ad39930130d487b12045a35cef73f48dab401e6583b",
+    "soundfonts/acoustic_grand_piano-mp3/D4.mp3": "90539782bdbbbe714de579bfbbe6f478e07e112c6f78d03e8ee82462fbf2a569",
+    "soundfonts/acoustic_grand_piano-mp3/D5.mp3": "b25b5e541807af700f4e2272ac4c55a2f9b5cc8f176fcd9961d4456803af2b87",
+    "soundfonts/acoustic_grand_piano-mp3/D6.mp3": "46317b9dca22a75986ecfeba93ef34c8f7bc6d4e2e0223dc64b13c9a1984110b",
+    "soundfonts/acoustic_grand_piano-mp3/D7.mp3": "d7db5e63d7caa2fc62e00f55366f9a5236b3a13f7eb0d141a9823e10c7cc4209",
+    "soundfonts/acoustic_grand_piano-mp3/Db1.mp3": "84f2ba7505c515c39797eafe36295b15ee9da8adbafcfbfbfc7685532b4bdce4",
+    "soundfonts/acoustic_grand_piano-mp3/Db2.mp3": "c5d76b97326a189786aba25685c8789f59d4dc41d5fbd4d6a6aa97986b2b7d1d",
+    "soundfonts/acoustic_grand_piano-mp3/Db3.mp3": "c5bd77b92ad8411c47e509643a7d6fc9c74f3aaba2290e2f4aed6a2ba1446e88",
+    "soundfonts/acoustic_grand_piano-mp3/Db4.mp3": "f49892c4e935296db1cb785000818e6a04bf0756c4443bffa6245144fdaf3e47",
+    "soundfonts/acoustic_grand_piano-mp3/Db5.mp3": "924a70321fe728ff7a69c941029e060f529e6ada507f20357ee74039e270e588",
+    "soundfonts/acoustic_grand_piano-mp3/Db6.mp3": "5e4b55cc27db80e899ea817c546f4c0cf15b43267f426f8de53baac770f90be7",
+    "soundfonts/acoustic_grand_piano-mp3/Db7.mp3": "56c93ba30fa46db98590fd4c218fec88e87b02eaa0b177bcc0ad621fd9a506da",
+    "soundfonts/acoustic_grand_piano-mp3/Db8.mp3": "1be0e2193b729fc32a4fbb82f9f46bb4c0b2cbb67027c0f07c8eeff6460b64cf",
+    "soundfonts/acoustic_grand_piano-mp3/E1.mp3": "740bf03f7ac2a9bbd41ae10f7daf876bc8bde6fe6d355f2f2781ae70d95c762a",
+    "soundfonts/acoustic_grand_piano-mp3/E2.mp3": "316b392d51d9c27334976511643112b088a9812a8e37e598957e8acc6725aad0",
+    "soundfonts/acoustic_grand_piano-mp3/E3.mp3": "5e556a4850b93b1adba6655372c9e58913169864c52a8e6f232f4b1e901ca2dc",
+    "soundfonts/acoustic_grand_piano-mp3/E4.mp3": "48bcecf53832988af83f74aa65efd7daa34f1e3ebf10de4679363b89d54f3852",
+    "soundfonts/acoustic_grand_piano-mp3/E5.mp3": "c48cee1a11528da53e1f780a1ed36558530f053b5ed8c7033709b2002b452513",
+    "soundfonts/acoustic_grand_piano-mp3/E6.mp3": "e4de8378854d6b39b40d4cf7b022f60bda097993b492639c8a0a005f02a010e0",
+    "soundfonts/acoustic_grand_piano-mp3/E7.mp3": "e757f51d2fb54dca2c0adb4ee6a2b86459a52e2f7dfa227529558a6a0f28fd07",
+    "soundfonts/acoustic_grand_piano-mp3/Eb1.mp3": "694e89cd30008f47411336ea1b76675503bbc5383c3849df676b2cf6b51eee67",
+    "soundfonts/acoustic_grand_piano-mp3/Eb2.mp3": "708ff787e5ae2bfa45fe386e5fadc90a9339817dd245ed6e6f62532e42fad8d2",
+    "soundfonts/acoustic_grand_piano-mp3/Eb3.mp3": "bec9944789ef9e7ec3dd7f9fcdf63ed1e5e82e29447c81be3578df9b1269b4b6",
+    "soundfonts/acoustic_grand_piano-mp3/Eb4.mp3": "96586e2865651cfa0469e762f3bd40821f6e45eecf4761a86a37bc59cfebfb2c",
+    "soundfonts/acoustic_grand_piano-mp3/Eb5.mp3": "aad99b852c20c2aee66143dd103513523566716cb2f4c6ef6ac478ef84f282b0",
+    "soundfonts/acoustic_grand_piano-mp3/Eb6.mp3": "c0f4c45d7930ed90edebfd93321807cdb7346e364ba1933867c4b49ba18d5368",
+    "soundfonts/acoustic_grand_piano-mp3/Eb7.mp3": "c23b9b43ca8ece152e59ef04832b2290e96db54f9539af3162df4054c23271c7",
+    "soundfonts/acoustic_grand_piano-mp3/F1.mp3": "6b83be26ca990ee91e4d404afd5756e5d63b7a6f9ac46da068c80b2692945dba",
+    "soundfonts/acoustic_grand_piano-mp3/F2.mp3": "7bb9c26ec86e1d32194ab5ced3805e1026e638a4a5481d556a7e3f2860141c46",
+    "soundfonts/acoustic_grand_piano-mp3/F3.mp3": "ff912c3211f80dc0c4f541ebd39c1db11f21cfda684d54999f9bce87aaf0cf20",
+    "soundfonts/acoustic_grand_piano-mp3/F4.mp3": "a7426425ed95ea8652a888d850c34c4b766c7c7a11c168ed6899c38a6836be0c",
+    "soundfonts/acoustic_grand_piano-mp3/F5.mp3": "d7f046daec924ce8607ec92360e0d0e42e29e4b3a108839179e04aba4adadc51",
+    "soundfonts/acoustic_grand_piano-mp3/F6.mp3": "6f7794d298d1036ebbd514ad1b3605ffbd280556925fba05e29b83052cbf3dfd",
+    "soundfonts/acoustic_grand_piano-mp3/F7.mp3": "f49b2b54f0b913f636b5822eae373a85dbb30ec5e9a6ebc18e498fdfe0547011",
+    "soundfonts/acoustic_grand_piano-mp3/G1.mp3": "d187e74ca3a23d08248ea4073abc0893a758c8b15c4b6af16c3ba1d2394830db",
+    "soundfonts/acoustic_grand_piano-mp3/G2.mp3": "034f90b9f81e5aca0012f1ff73d731308653578a7eb4bee30efca37af5afce77",
+    "soundfonts/acoustic_grand_piano-mp3/G3.mp3": "3b75e4dfd657723b3c7a30bca0409dce8013b4083d54e703c8ec513b535cee99",
+    "soundfonts/acoustic_grand_piano-mp3/G4.mp3": "37d21e13d5cecc8c0f1645c83bfe82f6032407a3b7de3dde14021c196526664e",
+    "soundfonts/acoustic_grand_piano-mp3/G5.mp3": "2eb949282bc676f3dc96bf5008459b5fff02696e63b70ff799ff08c36bb97058",
+    "soundfonts/acoustic_grand_piano-mp3/G6.mp3": "c24ccf8d6f0c6c9818fe244d150a42c42585629db413e6b245088fdb589e9f3d",
+    "soundfonts/acoustic_grand_piano-mp3/G7.mp3": "7cc4630a06cbc11438fac85c00b640cc7677be8332105204632b687d7127ebc4",
+    "soundfonts/acoustic_grand_piano-mp3/Gb1.mp3": "6ff97bc16a3020037f46ebe4196ce2602eed8af243b567768d4cb5d47a8ba0bc",
+    "soundfonts/acoustic_grand_piano-mp3/Gb2.mp3": "95ab26a90d088fdc938673005ba2b2a4b166ee188ffbad0c7f75fb746334b043",
+    "soundfonts/acoustic_grand_piano-mp3/Gb3.mp3": "91605f55bf0265c1e526b966a3901f9c2813473ac890f4b7330ee08874c5d30f",
+    "soundfonts/acoustic_grand_piano-mp3/Gb4.mp3": "f0db7ee32b9175907ca60cf53e6c7a129ea8e7c8f6562dc7ebe6e5c81dcbdf99",
+    "soundfonts/acoustic_grand_piano-mp3/Gb5.mp3": "bd1d81203f5338ab62372f88c0b4eb5b4a3133ef58518a8770f3dfdf34f74124",
+    "soundfonts/acoustic_grand_piano-mp3/Gb6.mp3": "c5f87e3bf666919bd1e230f6945ee4af752761faa54dc1814f854e8e9d8a7920",
+    "soundfonts/acoustic_grand_piano-mp3/Gb7.mp3": "8615b92d93fa16b4051bdc8800a6430642bdcff17e26d020ec5fd83bf89db759"
+  },
+  "font_version": "DejaVu Sans 2.37",
+  "font_license_source": "https://raw.githubusercontent.com/dejavu-fonts/dejavu-fonts/version_2_37/LICENSE",
+  "abcjs_git_blob": "a56bbfc0d004c9b14ea17ad4fd6b52a61b74d255"
+}

render_assets/renderer.js

@@ -0,0 +1,165 @@
+"use strict";
+
+// These display adaptations leave the saved ABC unchanged.
+function expandRests(abc) {
+  let header = true, voice = null, meter = [4, 4], unit = [1, 8];
+  const meters = new Map();
+  return abc.split(/\r?\n/).map(line => {
+    const field = line.match(/^([A-Za-z]):\s*(.*)$/);
+    if (field) {
+      const [, key, value] = field;
+      if (key === "V") {
+        voice = value.split(/\s/)[0];
+        if (!meters.has(voice)) meters.set(voice, meter);
+      }
+      if (key === "M") {
+        const match = value.match(/^(\d+)\/(\d+)$/);
+        if (match) {
+          const next = match.slice(1).map(Number);
+          if (header || !voice) meter = next;
+          else meters.set(voice, next);
+        }
+      }
+      if (key === "L") unit = value.split("/").map(Number);
+      if (key === "K") header = false;
+      return line;
+    }
+    if (header || line.startsWith("%")) return line;
+    return line.replace(/"[^"\n]*"|\[[^\]\n]*\]|Z(\d*)\|/g, (token, count) => {
+      if (count === undefined) return token;
+      const [n, d] = meters.get(voice) || meter;
+      return (`z${n * unit[1] / (d * unit[0])}|`).repeat(Number(count || 1));
+    });
+  }).join("\n");
+}
+
+function fixSystemKeys(tune) {
+  for (const line of tune.lines) for (const staff of line.staff || []) {
+    for (const voice of staff.voices) {
+      for (let i = 0; i < voice.length && voice[i].el_type !== "note";) {
+        const event = voice[i];
+        if (event.el_type === "key" || event.el_type === "keySignature") {
+          staff.key = {...event, accidentals: event.accidentals.map(a => ({...a}))};
+          delete staff.key.impliedNaturals;
+          voice.splice(i, 1);
+        } else i++;
+      }
+    }
+  }
+}
+
+window.renderScore = async abc => {
+  document.body.innerHTML = '<div id="source"></div><main id="pages"></main>';
+  const fontStyle = document.createElement("style");
+  fontStyle.textContent = '#source text, #source span, #pages text {font-family:SheetSageSans !important}';
+  document.head.append(fontStyle);
+  const source = document.getElementById("source");
+  source.style.cssText = "position:absolute;left:-2000px;width:714px";
+  const tunes = ABCJS.renderAbc(source, expandRests(abc), {
+    staffwidth: 674, paddingtop: 12, paddingbottom: 12, paddingleft: 20, paddingright: 20,
+    oneSvgPerLine: true, print: true, add_classes: true,
+    wrap: {minSpacing: 1.8, maxSpacing: 2.7, preferredMeasuresPerLine: 4},
+    afterParsing: fixSystemKeys,
+  });
+  if (!tunes.length || !tunes.some(t => t.lines.some(l => l.staff?.length)))
+    throw new Error("ABC contains no music to render.");
+  const warnings = tunes.flatMap(t => t.warnings || []);
+  if (warnings.length) throw new Error("Invalid ABC: " + warnings.join("; "));
+  await document.fonts.ready;
+  const ns = "http://www.w3.org/2000/svg";
+  const pages = [];
+  let page, content, used = 0, systems = 0;
+  function addPage() {
+    page = document.createElementNS(ns, "svg");
+    for (const [k, v] of Object.entries({xmlns:ns, width:794, height:1123, viewBox:"0 0 794 1123"}))
+      page.setAttribute(k,v);
+    page.setAttribute("class", "score-page");
+    const fontStyle = document.createElementNS(ns, "style");
+    fontStyle.textContent = '@font-face{font-family:SheetSageSans;src:url(data:font/ttf;base64,' + window.renderFontData + ')}text{font-family:SheetSageSans !important}';
+    page.append(fontStyle);
+    const license = document.createElementNS(ns, "metadata");
+    license.textContent = window.renderFontLicense;
+    page.append(license);
+    const background = document.createElementNS(ns, "rect");
+    for (const [k,v] of Object.entries({width:794,height:1123,fill:"white"})) background.setAttribute(k,v);
+    page.append(background);
+    content = document.createElementNS(ns, "g");
+    content.setAttribute("transform", "translate(40 40)");
+    page.append(content);
+    document.getElementById("pages").append(page);
+    pages.push(page);
+    used = 0;
+  }
+  for (const svg of source.querySelectorAll("svg")) {
+    const box = svg.getBoundingClientRect();
+    if (!(box.width > 0 && box.height > 0)) continue;
+    const scale = Math.min(1, 714 / box.width);
+    const height = box.height * scale;
+    if (height > 1043) throw new Error("A staff system is taller than one page.");
+    if (!page || used + height > 1043) addPage();
+    const group = document.createElementNS(ns, "g");
+    group.setAttribute("transform", `translate(0 ${used}) scale(${scale})`);
+    const clone = svg.cloneNode(true);
+    clone.setAttribute("width",box.width);
+    clone.setAttribute("height",box.height);
+    clone.style.overflow = "visible";
+    group.append(clone);
+    content.append(group);
+    used += height;
+    systems++;
+  }
+  source.remove();
+  if (!pages.length) throw new Error("No score pages were produced.");
+  return {pages:pages.map(p => new XMLSerializer().serializeToString(p)), systems, warnings};
+};
+
+window.renderAudio = async ({tracks, duration}) => {
+  const context = new AudioContext({sampleRate:44100});
+  await context.resume();
+  const sequence = new ABCJS.synth.SynthSequence();
+  for (const track of tracks) {
+    const id = sequence.addTrack();
+    sequence.setInstrument(id, 0);
+    for (const note of track.notes) sequence.tracks[id].push({
+      cmd:"note", instrument:0, pitch:note.pitch, volume:note.velocity,
+      start:note.start, duration:note.end-note.start, gap:0,
+    });
+  }
+  sequence.totalDuration = duration;
+  const synth = new ABCJS.synth.CreateSynth();
+  const loaded = await synth.init({audioContext:context, sequence, millisecondsPerMeasure:1000,
+    options:{soundFontUrl:"https://render.invalid/soundfonts/", fadeLength:35,
+      programOffsets:{acoustic_grand_piano:0}, soundFontVolumeMultiplier:1}});
+  if (loaded.error?.length) throw new Error("Could not load piano samples: " + loaded.error.join(", "));
+  await synth.prime();
+  const buffer = synth.getAudioBuffer();
+  if (!buffer) throw new Error("The renderer returned no audio.");
+  // Simultaneous voices retain their balance; a peak guard avoids PCM clipping.
+  let peak = 0;
+  for (let c=0; c<buffer.numberOfChannels; c++) {
+    const channel = buffer.getChannelData(c);
+    for (let i=0; i<channel.length; i++) peak = Math.max(peak, Math.abs(channel[i]));
+  }
+  const gain = Math.min(0.7, peak > 0 ? 0.98 / peak : 0.7);
+  window.renderedAudio = {buffer, gain};
+  await context.close();
+  return {frames:buffer.length, sample_rate:buffer.sampleRate, channels:buffer.numberOfChannels, gain};
+};
+
+window.audioBlock = ({start, count}) => {
+  const {buffer, gain} = window.renderedAudio;
+  const frames = Math.min(count, buffer.length-start);
+  const bytes = new Uint8Array(frames*buffer.numberOfChannels*2);
+  const view = new DataView(bytes.buffer);
+  for (let c=0; c<buffer.numberOfChannels; c++) {
+    const channel = buffer.getChannelData(c);
+    for (let i=0; i<frames; i++) {
+      const sample = Math.max(-1,Math.min(1,channel[start+i]*gain));
+      view.setInt16((i*buffer.numberOfChannels+c)*2, Math.round(sample*32767), true);
+    }
+  }
+  let binary="";
+  for (let offset=0; offset<bytes.length; offset+=8192)
+    binary += String.fromCharCode(...bytes.subarray(offset,offset+8192));
+  return btoa(binary);
+};

render_assets/soundfonts/ATTRIBUTION.md

@@ -0,0 +1,11 @@
+# Piano samples
+
+FluidR3 GM by Frank Wen. License: Creative Commons Attribution 3.0 US.
+https://creativecommons.org/licenses/by/3.0/us/
+
+Pre-rendered MP3 samples from Paul Rosen's fork of gleitz/midi-js-soundfonts:
+https://github.com/paulrosen/midi-js-soundfonts
+https://raw.githubusercontent.com/paulrosen/midi-js-soundfonts/gh-pages/FluidR3_GM/acoustic_grand_piano-mp3.js
+
+The base64 samples were unpacked into individual MP3 files without changing the
+audio, for same-origin/offline ABCJS score playback. Only piano is bundled.