🧭 Decision Guide
Why trending now: The material shows that it entered GitHub Trending on 2026-09-13 with 210 new stars that day. The README also presents the 2026-09-12 WildSongBench results, a 6.9632 SongBench Avg, editable symbolic planning, zero-shot covers, and agentic editing; these release details and features can explain the current attention.
Try it if you
-
You have Linux, Python 3.12, and an NVIDIA GPU with BF16 support and at least 24 GB VRAM.The README's “Quick start” explicitly lists Linux, Python 3.12, NVIDIA GPU with BF16 support, and 24 GB VRAM.
-
You need to inspect or modify melody, chords, and an ABC score before rendering a full song.The README's “White-box music generation through symbolic planning” section says melody and chords can be inspected and edited by a person or agent.
-
You want to use the same YuE2-3B checkpoint for zero-shot covers or agentic editing.The README's “Zero-shot covers and agentic editing” section says both tasks use the same generation checkpoint.
-
You want to reproduce the 192-prompt WildSongBench evaluation.The README's “Reproduce the benchmarks” section directs users to the WildSongBench reproduction instructions.
Skip it if you
-
Your environment is not the Linux, Python 3.12, and NVIDIA BF16 setup specified by the README.The README's “Quick start” lists only that environment and provides no Windows, macOS, or alternative-backend procedure.
-
Your device has less than 24 GB VRAM and cannot meet the YuE2 Quick start hardware requirement.The README's “Quick start” explicitly requires 24 GB VRAM.
-
You only need direct lyric-and-style-to-audio generation and do not need editable score, melody, or chord intermediates.The README describes YuE2's key distinction as an editable composition, while `cot="off"` is provided for direct generation.
-
You require one aggregate metric to prove significant superiority over every competitor.The README's “Benchmarks” section says rankings vary by metric and that the small gap between the highest means does not establish statistical significance.
Requirements
- Linux · Python 3.12 · NVIDIA GPU with BF16 support and 24 GB VRAM
- Model files download from Hugging Face on first use.
- YuE2 produces 48 kHz stereo audio without quantization.
- Python runtime is installed separately with `pip install .`.
First step (verbatim from README)
git clone https://github.com/multimodal-art-projection/YuE.git
Watch out
-
The first run downloads models from Hugging Face; the README does not quantify network or local-storage requirements.The README's “Quick start” says model files download from Hugging Face on first use.
-
The benchmark uses YuE2-Vae-legacy, not the default YuE2-Vae decoder.The README's “Benchmarks” section says both YuE2 settings use the benchmark decoder YuE2-Vae-legacy.
-
best-of-8 and standard YuE2 use different candidate counts; the former selects from eight candidates.The README's “Benchmarks” section says standard YuE2 selects from two candidates and best-of-8 selects from eight.
-
The output directory contains more than audio.flac, including the score, semantic tokens, acoustic latents, and settings.The README's “Quick start” section says outputs/first-song retains these artifacts.
-
MERT2 is not required for generation, but SheetSage2's encoder uses MERT-v2-FullSong.The README's “Models and resources” section says MERT2 feature extraction is optional and lists SheetSage2's encoder.
Alternatives
-
Suno v5:When you prioritize WildSongBench MuLan 0.5428 or PER 8.10% over YuE2's SongBench Avg 6.7316.README “Benchmarks”
-
Suno v4.5:When PER is the priority in the README's WildSongBench table: Suno v4.5 scores 5.80%, below YuE2's 8.44%.README “Benchmarks”
-
LeVo 2:When AudioBox PQ is the priority: LeVo 2 scores 8.3966, above YuE2 best-of-8's 8.2714.README “Benchmarks”
Not stated in the README
- The README does not state the download sizes of YuE2-3B, YuE2-Vae, or SheetSage2.
- The README does not state per-song latency, peak VRAM, or the additional cost of best-of-8.
- The README does not state whether Windows, macOS, AMD GPUs, or CPUs are supported.
- The README does not state copyright, training-data provenance, or commercial-use boundaries for generated songs.
- The README does not state length limits for long lyrics, long songs, or multilingual input.
- The README does not compare the audio quality of the default YuE2-Vae decoder with YuE2-Vae-legacy.
- The repository has 1 release and 10 recent commits; the README does not state future API stability or compatibility guarantees.
💡 Deep Analysis
6
No
I need a reproducible WildSongBench comparison between YuE2, Suno v5, and Suno v6. Can I interpret the README's 6.9632 and 6.7316 scores as single-generation quality?
No. The scores should not be read as single-generation quality because they use different candidate-selection protocols, and the README explicitly says ranking differences are not statistically established.
- YuE2 best-of-8 reports a SongBench Avg of 6.9632 after selecting from eight candidates, while standard YuE2 reports 6.7316 with two candidates. The former is therefore not a one-shot result.
- Both YuE2 rows in the comparison use the YuE2-Vae-legacy benchmark decoder. Switching to the default VAE would not reproduce the table.
- The README directs users to the WildSongBench standard-yue2 reproduction instructions and notes that rankings vary by metric; YuE2 does not lead every MuLan or PER measure.
- The saved output includes generation settings and model identities, which helps document configurations but does not replace the evaluation protocol.
The README does not provide the complete candidate-selection implementation, confidence intervals, or significance tests, so these means cannot establish universal superiority.
- Benchmarks: YuE2 best-of-8 has SongBench Avg 6.9632; YuE2 has 6.7316
- Benchmarks: “Standard YuE2 selects from two candidates; best-of-8 selects from eight”
- Benchmarks: both YuE2 settings use symbolic planning and the YuE2-Vae-legacy benchmark decoder
- Benchmarks: “Rankings vary by metric; the small gap between the highest means does not establish statistical significance”
Yes
I use Python 3.12 on Linux and have an NVIDIA GPU with BF16 support and 24 GB of VRAM. Is YuE2 suitable for running an open model locally to generate 48 kHz stereo songs?
Yes, because your environment matches the prerequisites stated in the README.
- The Quick start requires Linux, Python 3.12, an NVIDIA GPU with BF16 support, and at least 24 GB of VRAM; your setup satisfies these requirements.
- YuE2 runs without quantization and produces 48 kHz stereo audio. The Python API can load
m-a-p/YuE2-3Bwithdevice="cuda". - The first run downloads model files from Hugging Face, so network access, cache storage, and repository permissions can still affect startup.
- The output directory retains the score, semantic tokens, acoustic latents, generation settings, and model identities, which is useful for experiments and reproducibility.
The README does not state remaining VRAM under different song lengths, candidate counts, or concurrency levels. It also provides no standard deployment path for CPUs, AMD GPUs, or mobile devices.
- Quick start: “Linux · Python 3.12 · NVIDIA GPU with BF16 support and 24 GB VRAM”
- Quick start: “YuE2 produces 48 kHz stereo audio without quantization”
- Quick start: “Model files download from Hugging Face on first use”
- Quick start: the output retains the score, semantic tokens, acoustic latents, generation settings, and model identities
python examples/generate.py --output outputs/first-song
Yes
I want an agent to preserve the original audio and score, change the same English song to jazz harmony, and output two versions for comparison. Is YuE2 suitable as the backend for this multi-turn editing workflow?
Yes, because the README provides an agent skill and treats scores, lyrics, and version comparison as explicit workflow objects.
- The
yue2-musicskill teaches an agent to generate songs, transcribe and cover recordings, edit ABC scores, check musical invariants, and organize listening comparisons. - Its example request directly matches your workflow: create an English piano-pop song, keep the original audio and score, make a jazz-harmony version, and compare both versions.
- The Python API separates the process into
plan(),generate_semantic(),synthesize(), anddecode(), allowing an agent to edit scores or lyrics between planning and rendering. save_artifacts()preserves audio, scores, semantic tokens, acoustic latents, generation settings, and model identities, supporting version tracking and rollback.
However, the README does not identify supported agent frameworks or provide designs for concurrent jobs, error recovery, permission isolation, or long-conversation state management. Those integration details remain your responsibility.
- Agent skill: `yue2-music` supports song generation, transcription and covering, ABC score editing, musical-invariant checks, and listening comparisons
- Agent skill: the example includes English piano-pop, keeping the original audio and score, jazz harmony, and comparing versions
- How it works: `plan()` → `generate_semantic()` → `synthesize()` → `decode()`
- Quick start: `song.save_artifacts("outputs/my-song")` and the listed output artifacts
No
I have no ABC-score experience and only want to audition songs immediately from lyrics and a style prompt. Given the need for Python 3.12, Linux, and 24 GB of VRAM, is YuE2 a better fit than prompt-only generation for me?
No. YuE2 is not the simplest instant-audition tool for your goal because its value depends on score planning and a local hardware environment that you do not want to manage.
- The default new-song workflow is
cot="full", which first creates an editable melody-and-chord plan. This adds an intermediate artifact beyond entering a prompt. - The project requires Linux, Python 3.12, an NVIDIA GPU with BF16 support, and at least 24 GB of VRAM. The first run also downloads models from Hugging Face.
- The documented learning curve includes ABC scores, planning modes, transcription, and staged generation; the project explicitly describes this as costly for users who only want immediate playback.
cot="off"can generate directly from lyrics and style, but it gives up explicit score control. It does not remove the local installation or hardware requirements.
The README provides no hosted web workflow, CPU inference path, mobile deployment option, or installation-free standard route.
- Quick start: `cot="full"` is the default for new songs
- Quick start: Linux, Python 3.12, BF16-capable NVIDIA GPU, and 24 GB VRAM
- User experience: users need to understand ABC scores, planning modes, transcription, and staged generation
- Quick start: `cot="off"` — “Generate directly from lyrics and style”
It depends
I need to preserve the vocal melody and lyric order from an original recording while changing the accompaniment to jazz. Which YuE2 mode—`full`, `melody`, or `off`—best fits this cover constraint?
It depends: use melody when preserving the melody matters more than preserving harmony; use full when the original chords and structure must also remain stable.
- The README describes
cot="melody"as “Use a melody plan with free accompaniment” and explicitly recommends it for covers, making it suitable for changing the accompaniment style. cot="full"provides an editable melody-and-chord plan. In the 948-work cover evaluation, full-score YuE2 achieved 0.647 CLEWS mAP, compared with 0.006 without a score.cot="off"generates directly from lyrics and style, removing explicit score control and therefore conflicting with a strong melody-preservation requirement.- SheetSage2 transcription becomes the control input. Errors from complex rhythms, polyphony, or noisy recordings can propagate into the cover.
The README does not guarantee simultaneous preservation of singer identity, lyric pronunciation, melody, and target style. It also gives no transcription accuracy for your specific recording.
- Quick start: `cot="melody"` — “Use a melody plan with free accompaniment; recommended for covers”
- Quick start: `cot="full"` — “Generate an editable melody-and-chord plan”
- Benchmarks: on 948 works, full-score CLEWS mAP is 0.647 versus 0.006 without a score
- Benchmarks: “melody-only covers offer more freedom to change the arrangement”
Yes
I already have an ABC score and want to try different styles and decoders without replanning the melody. Does YuE2 support reusing the score as an intermediate artifact?
Yes. YuE2 treats an ABC score as an explicit input in full or melody mode and exposes a staged API suitable for reuse.
- The Quick start explicitly supports
abc=..., allowing a user-provided score in eitherfullormelodymode. cot="full"controls an editable melody-and-chord plan, whilecot="melody"preserves the melody with free accompaniment. These map to full-structure reuse and arrangement-focused adaptation.- The generation guide is specifically referenced for exact-plan reuse and decoder selection, indicating that the score need not be replanned for every rendering.
- The pipeline is separated into
plan(),generate_semantic(),synthesize(), anddecode(), while saving scores, tokens, latents, and model identities for comparison.
The README does not define the supported ABC grammar, invalid-score error behavior, or guarantee identical rhythm, timbre, or vocal expression after changing decoders.
- Quick start: `abc=...` — “Supply your own score in `full` or `melody` mode”
- Quick start: the behavior definitions for `cot="full"` and `cot="melody"`
- How it works: the generation guide covers exact-plan reuse and decoder selection
- Quick start / How it works: the staged API and persisted scores, tokens, latents, and model identities
✨ Highlights
-
YuE2 best-of-8 reaches 6.9632 SongBench Avg
-
Melody and chords can be inspected and edited before rendering
-
The same checkpoint supports zero-shot covers and agentic editing
-
Runtime requires Python 3.12, BF16, and 24 GB VRAM
🔧 Engineering
-
YuE2-3B turns lyrics and style into a melody-and-chord plan and full song
-
The Python API runs in stages: plan, generate_semantic, synthesize, and decode
-
SheetSage2 transcribes recordings into scores for zero-shot covers and editing
⚠️ Risks
-
Quick start specifies only Linux, Python 3.12, NVIDIA BF16, and 24 GB VRAM
-
Models download from Hugging Face on first use; README gives no download size
-
SongBench rankings vary by metric, and the top mean gap is not statistically significant
-
best-of-8 uses eight candidates; README does not state added time or memory
👥 For who?
-
Python music-generation developers with Linux and a 24 GB NVIDIA GPU
-
Agent developers who need to inspect ABC scores, melodies, and chords
-
Tool developers building zero-shot covers and new arrangements from recordings