Build Hum recording and generation Space

.dockerignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+.pytest_cache/
+.venv/
+.env
+*.wav
+*.mp3

.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+.pytest_cache/
+.venv/
+.env
+*.wav
+*.mp3

Dockerfile

@@ -0,0 +1,31 @@
+FROM python:3.12-slim
+
+ENV DEBIAN_FRONTEND=noninteractive \
+    PYTHONUNBUFFERED=1 \
+    HF_HOME=/home/user/.cache/huggingface \
+    GRADIO_ANALYTICS_ENABLED=False
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    ffmpeg fluidsynth libsndfile1 libgomp1 && \
+    rm -rf /var/lib/apt/lists/*
+
+# SheetSage2's published code uses the older Transformers API. Separate
+# processes keep that runtime independent of YuE2's pinned dependencies.
+RUN python -m venv /opt/sheet && /opt/sheet/bin/pip install --no-cache-dir \
+    torch==2.8.0 torchaudio==2.8.0 transformers==4.45.2 \
+    numpy==1.26.4 scipy==1.15.3 huggingface-hub==0.36.0 \
+    safetensors==0.7.0 soundfile==0.13.1 pretty_midi==0.2.11 mido==1.3.3
+
+RUN python -m venv /opt/yue && /opt/yue/bin/pip install --no-cache-dir \
+    'https://huggingface.co/m-a-p/YuE2-3B/resolve/29b3558dd46954a0cd9021dc76d5c91864a0f1c7/yue2_infer-0.1.5-py3-none-any.whl'
+
+RUN python -m venv /opt/ui && /opt/ui/bin/pip install --no-cache-dir \
+    gradio==5.49.1 numpy==1.26.4 scipy==1.15.3 soundfile==0.13.1 \
+    librosa==0.11.0 pretty_midi==0.2.11 mido==1.3.3
+
+RUN useradd -m -u 1000 user
+WORKDIR /home/user/app
+COPY --chown=user:user . /home/user/app
+USER user
+EXPOSE 7860
+CMD ["/opt/ui/bin/python", "app.py"]

README.md

@@ -1,10 +1,40 @@
 ---
 title: Hum
-emoji: ⚡
-colorFrom: green
-colorTo: green
+emoji: 🎵
+colorFrom: indigo
+colorTo: blue
 sdk: docker
-pinned: false
+app_port: 7860
+fullWidth: true
+short_description: Turn a hummed melody into an instrument, or explore YuE2.
+models:
+  - m-a-p/SheetSage2
+  - m-a-p/MERT-v2-FullSong
+  - m-a-p/YuE2-3B
+  - m-a-p/YuE2-Vae
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Hum
+
+Upload a short hum or record one in the browser. The default mode extracts a
+source-timed melody with SheetSage2 and renders **one** SoundFont instrument.
+The continuous-F0 mode is a diagnostic synth following the voice pitch and
+amplitude. YuE2 solo and arrangement modes use the SheetSage2 ABC score, but
+are experimental: YuE2 can introduce voices or other sounds and does not
+preserve source timing exactly.
+
+Output audio is downloadable 320 kbit/s CBR MP3. Source recordings remain in
+the Space's temporary job directory; they are not committed or used to train
+models. The Space should remain private while testing personal recordings.
+
+GPU recommendation: L40S 48 GB, one queued inference at a time, with idle
+sleep enabled. Models are downloaded at first use and cached on the Space's
+ephemeral disk. A cold restart can require another download.
+
+Model licenses and source: [SheetSage2](https://huggingface.co/m-a-p/SheetSage2),
+[MERT-v2-FullSong](https://huggingface.co/m-a-p/MERT-v2-FullSong),
+[YuE2-3B](https://huggingface.co/m-a-p/YuE2-3B),
+[YuE2-Vae](https://huggingface.co/m-a-p/YuE2-Vae).
+
+This is a research prototype; a single owner-reviewed recording is development
+evidence, not a general accuracy guarantee.

app.py

@@ -0,0 +1,82 @@
+"""Hum research Space: record, choose a rendering path, hear the result."""
+
+from __future__ import annotations
+
+import gradio as gr
+
+from logic import INSTRUMENTS
+from pipeline import MODES, generate
+
+
+SOLO_STYLE = (
+    "instrumental solo {instrument}, clear single melody, intimate dry recording, "
+    "natural instrumental tone"
+)
+ARRANGEMENT_STYLE = (
+    "instrumental chamber pop, {instrument} melody, acoustic bass, "
+    "brushed drums, soft strings, warm intimate mood"
+)
+
+
+def suggest_prompt(mode: str, instrument: str) -> str:
+    name = INSTRUMENTS[instrument][1]
+    template = ARRANGEMENT_STYLE if mode == "YuE2 · композиция (эксперимент)" else SOLO_STYLE
+    return template.format(instrument=name)
+
+
+def run(audio: str | None, mode: str, instrument: str, style: str, seed: int,
+        progress: gr.Progress = gr.Progress(track_tqdm=False)):
+    try:
+        return generate(audio, mode, instrument, style, seed, progress)
+    except Exception as error:
+        raise gr.Error(str(error)) from error
+
+
+CSS = """
+.gradio-container {max-width: 1000px !important; margin: auto !important;}
+#hero {padding: 20px 4px 10px 4px;}
+#hero h1 {font-size: clamp(2.5rem, 6vw, 4.5rem); letter-spacing: -.045em; margin: 0;}
+#hero p {font-size: 1.08rem; max-width: 720px; line-height: 1.55; color: #566179;}
+.note {border: 1px solid #d9e0ed; border-radius: 16px; padding: 14px 18px;
+       background: linear-gradient(120deg,#f5f7ff,#f1fbfc); color: #3e4b64;}
+"""
+
+
+with gr.Blocks(title="Hum · напев в инструмент", css=CSS, theme=gr.themes.Soft()) as demo:
+    gr.HTML("""<div id='hero'><h1>Hum <span style='color:#6474db'>♪</span></h1>
+    <p>Напойте фразу в микрофон или загрузите короткую запись. Hum извлечёт
+    мелодию и сыграет её инструментом. Можно отдельно сравнить непрерывный
+    контур и экспериментальную генерацию YuE2.</p></div>""")
+    with gr.Row():
+        with gr.Column(scale=5):
+            audio = gr.Audio(label="Ваш напев", sources=["microphone", "upload"],
+                             type="filepath", format="wav")
+            mode = gr.Radio(list(MODES), value="SheetSage2 · один инструмент",
+                            label="Режим")
+            instrument = gr.Dropdown(list(INSTRUMENTS), value="Флейта", label="Инструмент")
+            with gr.Accordion("Настройки YuE2", open=False):
+                style = gr.Textbox(label="Style prompt", lines=2,
+                                   value=suggest_prompt("YuE2 · соло (эксперимент)", "Флейта"),
+                                   info="Используется только в режимах YuE2; поле lyrics пустое.")
+                seed = gr.Number(label="Seed", value=4096, precision=0)
+            go = gr.Button("Превратить в музыку", variant="primary", size="lg")
+        with gr.Column(scale=5):
+            result = gr.Audio(label="Результат · MP3 320 кбит/с", interactive=False)
+            with gr.Row():
+                midi = gr.File(label="Ноты · MIDI")
+                abc = gr.File(label="Ноты · ABC")
+            details = gr.JSON(label="Детали запуска")
+            gr.HTML("""<div class='note'><b>Текущая цель:</b> один инструмент и
+            приблизительно исходное время — режим SheetSage2. Непрерывный
+            контур — простой диагностический синтезатор. YuE2 может изменить
+            длительность, добавить инструменты или человеческие звуки;
+            отсутствие вокала в нём не гарантируется.</div>""")
+    mode.change(suggest_prompt, inputs=[mode, instrument], outputs=style)
+    instrument.change(suggest_prompt, inputs=[mode, instrument], outputs=style)
+    go.click(run, inputs=[audio, mode, instrument, style, seed],
+             outputs=[result, midi, abc, details], show_progress="full")
+
+
+if __name__ == "__main__":
+    demo.queue(max_size=8, default_concurrency_limit=1)
+    demo.launch(server_name="0.0.0.0", server_port=7860, show_error=True)

logic.py

@@ -0,0 +1,71 @@
+"""Small deterministic contracts shared by the Space workers."""
+
+from __future__ import annotations
+
+from pathlib import Path
+import re
+
+
+MAX_SECONDS = 35.0
+INSTRUMENTS = {
+    "Флейта": (73, "flute"),
+    "Кларнет": (71, "clarinet"),
+    "Фортепиано": (0, "acoustic piano"),
+    "Виолончель": (42, "cello"),
+}
+
+
+def instrumental_abc(native: str, keep_chords: bool = False) -> str:
+    """Move the native Vocal melody into Ins, failing on unknown ABC layout."""
+    lines = native.splitlines()
+    header = []
+    body = []
+    in_body = False
+    for line in lines:
+        if line == "V: Vocal":
+            in_body = True
+        (body if in_body else header).append(line)
+    if not body or not any(line.startswith("V: Vocal ") for line in header):
+        raise ValueError("SheetSage2 ABC has no expected Vocal melody")
+    header = [line for line in header if not line.startswith(("V: Vocal ", "V: Ins "))]
+    key_index = next((i for i, line in enumerate(header) if line.startswith("K:")), None)
+    if key_index is None:
+        raise ValueError("ABC has no key signature")
+    header.insert(key_index, 'V: Ins clef=treble name="Instrumental Melody" snm="Ins"')
+    out = []
+    index = 0
+    moved = 0
+    while index < len(body):
+        line = body[index]
+        if line.startswith("%") or not line.strip():
+            out.append(line)
+            index += 1
+            continue
+        if (index + 3 >= len(body) or body[index] != "V: Vocal"
+                or body[index + 2] != "V: Ins"
+                or not re.fullmatch(r"Z\d*\|", body[index + 3])):
+            raise ValueError("Unexpected SheetSage2 ABC voice layout")
+        melody = body[index + 1]
+        if not keep_chords:
+            melody = re.sub(r'"[^"\n]*"', "", melody)
+        out.extend(("V: Ins", melody))
+        moved += 1
+        index += 4
+    if not moved:
+        raise ValueError("No melody bars in SheetSage2 ABC")
+    result = "\n".join(header + out) + "\n"
+    if "Vocal" in result or (not keep_chords and any('"' in line for line in out)):
+        raise ValueError("Vocal label or unexpected chord survived conversion")
+    return result
+
+
+def validate_duration(seconds: float) -> None:
+    if not 0.4 <= seconds <= MAX_SECONDS:
+        raise ValueError(f"Нужен напев от 0,4 до {MAX_SECONDS:g} секунд; сейчас {seconds:.1f} с.")
+
+
+def work_file(root: Path, name: str) -> Path:
+    path = root / name
+    if path.parent != root or path.name != name:
+        raise ValueError("Invalid work file name")
+    return path

pipeline.py

@@ -0,0 +1,244 @@
+"""Audio ingest, source-timed renderers, and isolated GPU workers."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+from pathlib import Path
+import subprocess
+import sys
+import tempfile
+import time
+
+from logic import INSTRUMENTS, instrumental_abc, validate_duration
+
+
+ROOT = Path(__file__).resolve().parent
+SHEET_PYTHON = Path(os.environ.get("HUM_SHEET_PYTHON", "/opt/sheet/bin/python"))
+YUE_PYTHON = Path(os.environ.get("HUM_YUE_PYTHON", "/opt/yue/bin/python"))
+MODES = {
+    "SheetSage2 · один инструмент": "sheet",
+    "Непрерывная высота · synth": "contour",
+    "YuE2 · соло (эксперимент)": "yue_solo",
+    "YuE2 · композиция (эксперимент)": "yue_arrangement",
+}
+
+
+def command(args: list[str], log: Path, timeout: int = 900) -> None:
+    with log.open("a") as stream:
+        process = subprocess.run(args, stdout=stream, stderr=subprocess.STDOUT,
+                                 text=True, timeout=timeout, check=False)
+    if process.returncode:
+        tail = "\n".join(log.read_text(errors="replace").splitlines()[-18:])
+        raise RuntimeError(f"Шаг завершился с кодом {process.returncode}:\n{tail}")
+
+
+def probe(source: Path) -> float:
+    if not source.is_file() or source.stat().st_size > 30 * 1024 * 1024:
+        raise ValueError("Файл отсутствует или больше 30 МБ.")
+    result = subprocess.run([
+        "ffprobe", "-v", "error", "-select_streams", "a:0",
+        "-show_entries", "stream=duration", "-of", "json", str(source),
+    ], capture_output=True, text=True, check=True)
+    streams = json.loads(result.stdout).get("streams", [])
+    if not streams:
+        raise ValueError("В файле нет звуковой дорожки.")
+    duration = float(streams[0]["duration"])
+    validate_duration(duration)
+    return duration
+
+
+def decode(source: Path, folder: Path, log: Path) -> tuple[Path, Path, float]:
+    duration = probe(source)
+    pcm48, pcm24 = folder / "source-48k.wav", folder / "source-24k.wav"
+    for rate, target in ((48000, pcm48), (24000, pcm24)):
+        command(["ffmpeg", "-nostdin", "-v", "error", "-y", "-i", str(source),
+                 "-vn", "-ac", "1", "-ar", str(rate), "-c:a", "pcm_f32le",
+                 str(target)], log, timeout=120)
+    return pcm48, pcm24, duration
+
+
+def source_sha256(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as stream:
+        for block in iter(lambda: stream.read(1 << 20), b""):
+            digest.update(block)
+    return digest.hexdigest()
+
+
+def transcribe(pcm24: Path, folder: Path, log: Path) -> tuple[Path, Path, Path]:
+    command([str(SHEET_PYTHON), str(ROOT / "sheet_worker.py"),
+             str(pcm24), str(folder)], log, timeout=900)
+    return folder / "notes.mid", folder / "melody.abc", folder / "full.abc"
+
+
+def render_instrument(midi_path: Path, folder: Path, instrument: str,
+                      duration: float, log: Path) -> Path:
+    import numpy as np
+    import pretty_midi
+    import soundfile as sf
+
+    if instrument not in INSTRUMENTS:
+        raise ValueError("Неизвестный инструмент")
+    source = pretty_midi.PrettyMIDI(str(midi_path))
+    notes = [n for track in source.instruments for n in track.notes]
+    if not notes:
+        raise RuntimeError("SheetSage2 не нашёл нот в напеве")
+    midi = pretty_midi.PrettyMIDI(initial_tempo=120, resolution=10000)
+    track = pretty_midi.Instrument(program=INSTRUMENTS[instrument][0], name="Melody")
+    for note in notes:
+        track.notes.append(pretty_midi.Note(velocity=90, pitch=note.pitch,
+                                            start=note.start, end=note.end))
+    midi.instruments.append(track)
+    rendered_midi = folder / "instrument.mid"
+    midi.write(str(rendered_midi))
+    soundfont = Path(pretty_midi.__file__).parent / "TimGM6mb.sf2"
+    if not soundfont.is_file():
+        raise RuntimeError("SoundFont missing from pretty_midi installation")
+    raw = folder / "instrument-tail.wav"
+    command(["fluidsynth", "-ni", "-C", "0", "-R", "0", "-r", "48000",
+             "-z", "64", "-g", ".2", "-o", "player.timing-source=sample",
+             "-o", "synth.min-note-length=0", "-T", "wav", "-O", "float",
+             "-F", str(raw), str(soundfont), str(rendered_midi)], log, timeout=120)
+    audio, rate = sf.read(raw, dtype="float32", always_2d=True)
+    if rate != 48000 or not np.isfinite(audio).all():
+        raise RuntimeError("Синтезатор вернул повреждённое аудио")
+    frames = round(duration * rate)
+    audio = np.pad(audio, ((0, max(0, frames - len(audio))), (0, 0)))[:frames]
+    output = folder / "raw.wav"
+    sf.write(output, audio, rate, subtype="FLOAT")
+    return output
+
+
+def render_contour(source: Path, folder: Path) -> Path:
+    import librosa
+    import numpy as np
+    from scipy.ndimage import median_filter
+    import soundfile as sf
+
+    y, rate = sf.read(source, dtype="float32")
+    if rate != 48000 or y.ndim != 1:
+        raise ValueError("Expected mono 48 kHz input")
+    reduced = librosa.resample(y, orig_sr=rate, target_sr=16000)
+    f0, voiced, _ = librosa.pyin(reduced, sr=16000, fmin=55., fmax=1000.,
+                                 frame_length=1024, hop_length=160, center=True)
+    times = np.arange(len(f0)) * .01
+    keep = times < len(y) / rate
+    times, f0, voiced = times[keep], f0[keep], voiced[keep]
+    squares = np.r_[0., np.cumsum(np.square(y, dtype=np.float64))]
+    left = np.maximum(0, np.rint((times - .01) * rate).astype(int))
+    right = np.minimum(len(y), np.rint((times + .01) * rate).astype(int))
+    rms = np.sqrt((squares[right] - squares[left]) / np.maximum(1, right - left))
+    threshold = max(10 ** (-60 / 20), float(np.percentile(rms, 95)) * 10 ** (-35 / 20))
+    active = voiced & np.isfinite(f0) & (f0 > 0) & (rms >= threshold)
+    boundaries = np.flatnonzero(np.diff(np.r_[False, active, False]))
+    wave = np.zeros(len(y), dtype=np.float32)
+    for first, last in zip(boundaries[::2], boundaries[1::2]):
+        pitch = median_filter(69 + 12 * np.log2(f0[first:last] / 440),
+                              size=3, mode="nearest")
+        start = max(0, round((times[first] - .005) * rate))
+        end = min(len(y), round((times[last - 1] + .005) * rate))
+        t = np.arange(start, end) / rate
+        envelope = np.interp(t, times[first:last], rms[first:last])
+        fade = min(round(.005 * rate), len(t) // 2)
+        if fade:
+            envelope[:fade] *= np.linspace(0, 1, fade)
+            envelope[-fade:] *= np.linspace(1, 0, fade)
+        frequency = 440 * 2 ** ((np.interp(t, times[first:last], pitch) - 69) / 12)
+        phase = 2 * np.pi * np.cumsum(frequency) / rate
+        harmonics = np.sin(phase) + .25 * np.sin(2 * phase) + .08 * np.sin(3 * phase)
+        wave[start:end] = envelope * harmonics * np.sqrt(2 / (1 + .25**2 + .08**2))
+    if not np.any(wave):
+        raise RuntimeError("Не удалось выделить звучащую высоту напева")
+    output = folder / "raw.wav"
+    sf.write(output, wave, rate, subtype="FLOAT")
+    return output
+
+
+def render_yue(score_path: Path, folder: Path, instrument: str, mode: str,
+               style: str, seed: int, log: Path) -> Path:
+    if instrument not in INSTRUMENTS:
+        raise ValueError("Неизвестный инструмент")
+    if not 0 <= seed < 2**31:
+        raise ValueError("Seed должен быть целым числом от 0 до 2³¹−1")
+    style = style.strip()
+    if not style or len(style) > 500:
+        raise ValueError("Промпт YuE2 должен содержать 1–500 символов")
+    conditioned = instrumental_abc(score_path.read_text(), keep_chords=mode == "yue_arrangement")
+    abc_path = folder / "instrumental.abc"
+    abc_path.write_text(conditioned)
+    request = {"abc_path": str(abc_path), "style": style,
+               "seed": seed, "cot": "full" if mode == "yue_arrangement" else "melody"}
+    request_path = folder / "yue-request.json"
+    request_path.write_text(json.dumps(request, ensure_ascii=False, indent=2) + "\n")
+    command([str(YUE_PYTHON), str(ROOT / "yue_worker.py"),
+             str(request_path), str(folder)], log, timeout=1800)
+    return folder / "raw.wav"
+
+
+def encode_mp3(source: Path, destination: Path, log: Path) -> None:
+    import numpy as np
+    import soundfile as sf
+
+    audio, rate = sf.read(source, dtype="float32", always_2d=True)
+    if not len(audio) or not np.isfinite(audio).all():
+        raise RuntimeError("Результат пустой или содержит повреждённые отсчёты")
+    peak = float(np.max(np.abs(audio)))
+    if peak <= 1e-8:
+        raise RuntimeError("Результат слишком тихий")
+    gain = min(4., .95 / peak)
+    safe = destination.with_suffix(".safe.wav")
+    sf.write(safe, audio * gain, rate, subtype="PCM_24")
+    command(["ffmpeg", "-nostdin", "-v", "error", "-y", "-i", str(safe),
+             "-codec:a", "libmp3lame", "-b:a", "320k", "-ar", "48000",
+             str(destination)], log, timeout=120)
+    if not destination.is_file() or destination.stat().st_size < 1000:
+        raise RuntimeError("MP3 не создан")
+
+
+def generate(source: str, mode_label: str, instrument: str, prompt: str,
+             seed: int, progress=None) -> tuple[str, str | None, str | None, dict]:
+    if not source or mode_label not in MODES:
+        raise ValueError("Загрузите или запишите напев и выберите режим")
+    mode = MODES[mode_label]
+    folder = Path(tempfile.mkdtemp(prefix="hum-"))
+    log = folder / "run.log"
+    began = time.monotonic()
+    uploaded = Path(source)
+    digest = source_sha256(uploaded)
+    if progress:
+        progress(.02, desc="Проверяю и декодирую напев")
+    pcm48, pcm24, duration = decode(uploaded, folder, log)
+    midi = abc = None
+    if mode == "contour":
+        if progress:
+            progress(.35, desc="Оцениваю непрерывную высоту")
+        raw = render_contour(pcm48, folder)
+    else:
+        if progress:
+            progress(.18, desc="SheetSage2 извлекает ноты и ABC")
+        midi, melody_abc, full_abc = transcribe(pcm24, folder, log)
+        abc = melody_abc if mode != "yue_arrangement" else full_abc
+        if mode == "sheet":
+            if progress:
+                progress(.7, desc="Играю ноты одним инструментом")
+            raw = render_instrument(midi, folder, instrument, duration, log)
+        else:
+            if progress:
+                progress(.55, desc="YuE2 генерирует музыку на GPU")
+            raw = render_yue(abc, folder, instrument, mode, prompt, int(seed), log)
+            abc = folder / "instrumental.abc"
+    if progress:
+        progress(.9, desc="Готовлю MP3 320 кбит/с")
+    mp3 = folder / "hum-result.mp3"
+    encode_mp3(raw, mp3, log)
+    metadata = {"mode": mode_label, "instrument": instrument if mode != "contour" else None,
+                "source_sha256": digest, "source_seconds": round(duration, 3),
+                "result_seconds": round(__import__("soundfile").info(raw).duration, 3),
+                "source_timing_preserved": mode in ("sheet", "contour"),
+                "vocal_absence_guaranteed": mode in ("sheet", "contour"),
+                "elapsed_seconds": round(time.monotonic() - began, 2),
+                "notes": "YuE2 may add vocals, instruments, or change timing" if mode.startswith("yue") else None}
+    (folder / "result.json").write_text(json.dumps(metadata, ensure_ascii=False, indent=2) + "\n")
+    return str(mp3), str(midi) if midi else None, str(abc) if abc else None, metadata

sheet_worker.py

@@ -0,0 +1,56 @@
+"""One isolated SheetSage2 CUDA transcription per request."""
+
+from __future__ import annotations
+
+import importlib
+import json
+from pathlib import Path
+import shutil
+import sys
+
+import numpy as np
+import soundfile as sf
+import torch
+from transformers import AutoModel
+
+
+SHEETSAGE_REV = "eab522a8168e8b8b8c4856bf8609cd86198f01fe"
+
+
+def run(source: Path, output: Path) -> None:
+    if not torch.cuda.is_available():
+        raise RuntimeError("SheetSage2 requires the configured NVIDIA GPU")
+    waveform, rate = sf.read(source, dtype="float32", always_2d=True)
+    if rate != 24000 or waveform.shape[1] != 1 or not np.isfinite(waveform).all():
+        raise ValueError("Expected finite mono 24 kHz PCM")
+    torch.manual_seed(1024)
+    np.random.seed(1024)
+    model = AutoModel.from_pretrained(
+        "m-a-p/SheetSage2", revision=SHEETSAGE_REV, trust_remote_code=True,
+        torch_dtype=torch.float32, attn_implementation="sdpa",
+    ).eval().to("cuda")
+    native = output / "native"
+    result = model.transcribe(waveform[:, 0], sampling_rate=24000,
+                              output_dir=native, dtype="fp32", preset="default",
+                              melody_only=False)
+    if result.get("abc_error") or not (native / "score.abc").is_file():
+        raise RuntimeError(f"SheetSage2 could not export ABC: {result.get('abc_error')}")
+    package = model.__class__.__module__.rsplit(".", 1)[0]
+    exporter = importlib.import_module(package + ".exports_sheetsage2").export_result
+    events = json.loads((native / "events.json").read_text())
+    melody = exporter(events, model.tokenizer, output / "melody-only",
+                      duration=result["duration_seconds"], melody_only=True)
+    if melody.get("abc_error") or not (output / "melody-only/score.abc").is_file():
+        raise RuntimeError(f"SheetSage2 could not export melody ABC: {melody.get('abc_error')}")
+    shutil.copy2(native / "score.abc", output / "full.abc")
+    shutil.copy2(output / "melody-only/score.abc", output / "melody.abc")
+    shutil.copy2(native / "melody_vocal.mid", output / "notes.mid")
+    (output / "sheet.json").write_text(json.dumps({
+        "model": "m-a-p/SheetSage2", "revision": SHEETSAGE_REV,
+        "duration_s": result["duration_seconds"],
+        "source_timeline": True,
+    }, indent=2) + "\n")
+
+
+if __name__ == "__main__":
+    run(Path(sys.argv[1]), Path(sys.argv[2]))

test_logic.py

@@ -0,0 +1,56 @@
+"""Contracts that prevent vocal ABC leakage and accidental timing expansion."""
+
+from __future__ import annotations
+
+import unittest
+
+from logic import instrumental_abc, validate_duration
+
+
+NATIVE = '''X:1
+M:4/4
+L:1/16
+V: Vocal clef=treble name="Vocal Melody" snm="Vocal"
+V: Ins clef=treble name="Ins Melody" snm="Inst."
+K:B
+% chorus
+V: Vocal
+"Bm"z12F,4|
+V: Ins
+Z1|
+V: Vocal
+Z|
+V: Ins
+Z1|
+'''
+
+
+class LogicTest(unittest.TestCase):
+    def test_move_melody_to_instrument_without_chord_or_voice(self):
+        result = instrumental_abc(NATIVE)
+        self.assertNotIn("Vocal", result)
+        self.assertNotIn('"Bm"', result)
+        self.assertIn("z12F,4|", result)
+        self.assertIn("V: Ins\nz12F,4|", result)
+        self.assertIn("V: Ins\nZ|", result)
+        self.assertLess(result.index("V: Ins clef"), result.index("K:B"))
+
+    def test_composition_keeps_chords_but_no_vocal_slot(self):
+        result = instrumental_abc(NATIVE, keep_chords=True)
+        self.assertIn('"Bm"z12F,4|', result)
+        self.assertNotIn("Vocal", result)
+
+    def test_unknown_layout_fails(self):
+        with self.assertRaises(ValueError):
+            instrumental_abc(NATIVE.replace("Z1|", "z16|", 1))
+
+    def test_duration_bounds(self):
+        validate_duration(0.4)
+        validate_duration(35)
+        for seconds in (0.1, 35.1):
+            with self.assertRaises(ValueError):
+                validate_duration(seconds)
+
+
+if __name__ == "__main__":
+    unittest.main()

yue_worker.py

@@ -0,0 +1,51 @@
+"""One isolated YuE2 CUDA generation from the reviewed SheetSage ABC form."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+import sys
+
+import numpy as np
+import soundfile as sf
+import torch
+from yue2 import YuE2Pipeline
+
+
+YUE_REV = "29b3558dd46954a0cd9021dc76d5c91864a0f1c7"
+VAE_REV = "9a94e1d0ea9f8087e98f77fa88df4a4068104d2a"
+
+
+def run(request_path: Path, output: Path) -> None:
+    if not torch.cuda.is_available() or not torch.cuda.is_bf16_supported():
+        raise RuntimeError("YuE2 requires a BF16-capable NVIDIA GPU")
+    request = json.loads(request_path.read_text())
+    score = Path(request["abc_path"]).read_text()
+    pipe = YuE2Pipeline.from_pretrained(
+        "m-a-p/YuE2-3B", vae="m-a-p/YuE2-Vae",
+        revision=YUE_REV, vae_revision=VAE_REV,
+        device="cuda", backend="torch-eager", quantization="none",
+        offload_ar=False, memory_budget_gib=44, progress=True,
+    )
+    try:
+        song = pipe(style=request["style"], lyrics="", cot=request["cot"],
+                    abc=score, seed=request["seed"], cfg_scale=1.0,
+                    semantic_sampling={"max_tokens": 1100})
+        audio = np.asarray(song.audio, dtype=np.float32)
+        if audio.ndim != 2 or audio.shape[1] != 2 or not np.isfinite(audio).all():
+            raise RuntimeError("YuE2 returned invalid stereo audio")
+        if not len(audio) or float(np.max(np.abs(audio))) == 0:
+            raise RuntimeError("YuE2 returned silence")
+        sf.write(output / "raw.wav", audio, song.sample_rate, subtype="FLOAT")
+        (output / "yue.json").write_text(json.dumps({
+            "model": "m-a-p/YuE2-3B", "revision": YUE_REV,
+            "vae_revision": VAE_REV, "duration_s": len(audio) / song.sample_rate,
+            "truncated": song.truncated, "timing": song.timing,
+            "source_timeline": False, "vocal_absence_guaranteed": False,
+        }, indent=2) + "\n")
+    finally:
+        pipe.close()
+
+
+if __name__ == "__main__":
+    run(Path(sys.argv[1]), Path(sys.argv[2]))