YuE2 Protocol CoT Modes: Trade-offs of off, melody, and full for Creation, Cover, and Editing

The YuE2 protocol provides three chain-of-thought (CoT) modes that trade inference speed against symbolic control: cot="off" generates raw codec tokens fastest without ABC notation using guidance 1.01, cot="melody" produces editable melody-only ABC scaffolding with guidance 1.0 for iterative composition, and cot="full" outputs chord-annotated ABC for faithful harmonic reproduction in cover arrangements at the cost of increased token count.

The multimodal-art-projection/YuE repository implements the YuE2 protocol, a structured approach to music generation that uses chain-of-thought reasoning to convert text prompts into ABC notation before synthesizing acoustic codec tokens. Understanding the trade-offs between cot="off", cot="melody", and cot="full" is essential for optimizing generation speed, memory usage, and artistic control across creation, cover, and editing workflows.

How YuE2 CoT Modes Control the Generation Pipeline

The protocol defines three distinct processing pathways in the INSTRUCTIONS map within src/yue2/protocol.py. Each mode determines whether the model generates an intermediate symbolic representation (ABC notation) before producing acoustic codec tokens, which directly impacts latency, editability, and harmonic fidelity.

The token prefix construction differs fundamentally between modes. In src/yue2/protocol.py, the token_prefixes() method builds the initial token list that seeds the decoder. This architectural decision determines how many tokens the model must process before reaching the audio generation phase.

Detailed Comparison of CoT Modes

cot="off": Direct Codec Generation

cot="off" disables symbolic transcription entirely, making it the fastest inference path. According to the INSTRUCTIONS definition in protocol.py, this mode generates "music with codec tokens from the given conditions" without intermediate ABC representation.

Key characteristics include:

• Token Stream: The prefix contains only structural markers: EOD → ABC_START → ABC_END → MUSIC_START with no ABC tokens in between (lines 15‑19 in protocol.py).
• Guidance Scaling: Returns 1.01 via SongRequest.guidance (lines 105‑107), slightly strengthening classifier‑free guidance to compensate for the lack of symbolic anchor.
• Validation Constraint: The __post_init__ validation explicitly rejects external ABC input when cot="off" (lines 99‑101), raising an error if contradictory symbolic data is provided.
• Performance: Minimizes token count and memory overhead, making it ideal for resource‑constrained inference or deterministic audio generation where human‑readable scores are unnecessary.

cot="melody": Melody‑Only Symbolic Scaffolding

cot="melody" generates a melody‑only ABC transcription without chord symbols, providing a middle ground between speed and editability. The protocol description states this mode creates "a melody‑only ABC transcription without chord symbols, then generate music with codec tokens."

Implementation details:

• Token Structure: The positive‑branch prefix contains ABC_START → <melody‑ABC‑tokens> → ABC_END → MUSIC_START, where the melody tokens are either generated or supplied externally.
• Guidance Value: Fixed at 1.0, providing standard classifier‑free guidance strength.
• Consistency Enforcement: The negative_prefix() function (lines 33‑38) requires the exact same ABC IDs for the negative branch used in CFG, ensuring stability when symbolic scaffolds exist.
• Use Case: Best for new composition workflows where melodic contour matters but harmonic content remains flexible. The generated ABC can be inspected, tweaked, and fed back through the pipeline for iterative refinement.

cot="full": Chord‑Annotated Symbolic Control

cot="full" produces the richest symbolic representation, generating chord‑annotated ABC notation that includes both melody and harmony information. This mode is designed for scenarios requiring explicit harmonic structure.

Technical specifications:

• Symbolic Richness: The generated ABC contains both melodic lines and chord symbols, creating a detailed scaffold for the subsequent codec generation stage.
• Token Overhead: Adds more tokens than melody mode due to chord annotations, increasing compute requirements but providing the highest level of human‑interpretable control.
• Guidance: Maintains 1.0 guidance scaling like melody mode.
• Architectural Role: The token_prefixes() method encodes the full ABC via tokenizer.encode(request.abc), conditioning the acoustic model on explicit harmonic progressions.

Architectural Implications in protocol.py

The implementation in src/yue2/protocol.py reveals several critical architectural differences between modes:

Token Prefix Construction
For cot="off", token_prefixes() appends only special markers without ABC content (lines 15‑19). For melody and full, it encodes actual ABC tokens, increasing the sequence length before the MUSIC_START token appears.

External ABC Validation
The SongRequest.__post_init__ method (lines 99‑101) ensures that external ABC text is only accepted when cot is "melody" or "full", preventing contradictory inputs in pure audio generation mode.

Negative Branch Consistency
The negative_prefix() function (lines 33‑38) enforces that the negative branch for CFG contains the exact ABC IDs when using melody or full modes. This requirement is absent in off mode, which uses a simplified negative branch.

Performance vs. Control Trade‑off
Because cot="off" bypasses the symbolic stage, it reduces total token count and cuts inference time. Conversely, cot="full" adds the most tokens (melody + chords) and increases compute, but enables downstream harmony editing such as reharmonization.

Choosing the Right Mode for Your Use Case

Use Case	Recommended CoT	Reasoning
Pure audio creation (no score needed)	off	Minimal latency, no symbolic overhead, fastest generation path.
Melodic sketching / iterative editing	melody	Provides readable, editable melody without committing to specific chords.
Cover generation / arrangement	full	Preserves chord progressions and harmonic structure essential for faithful covers.
Hybrid workflows (supply custom ABC)	melody or full	Protocol validates external ABC and uses it to guide codec generation.
Resource‑constrained inference	off or melody	off consumes least memory; melody offers modest increase for symbolic insight.

Code Implementation Examples

The following examples demonstrate how to instantiate SongRequest objects for each CoT mode using the YuE2 pipeline:

from yue2.pipeline import YuE2Pipeline
from yue2.protocol import SongRequest

# 1. OFF mode – fastest raw audio generation, no ABC output

req_off = SongRequest(
    style="Jazz",
    lyrics="Improvisation in C minor",
    cot="off",           # Disables ABC generation entirely

    seed=42,
)

# 2. MELODY mode – generates melody-only ABC then audio

req_melody = SongRequest(
    style="Pop",
    lyrics="Love is in the air",
    cot="melody",        # Generates melody-only ABC without chords

    seed=123,
)

# 3. FULL mode – generates chord-annotated ABC then audio

req_full = SongRequest(
    style="Rock",
    lyrics="Feel the thunder",
    cot="full",          # Generates full ABC with chord symbols

    seed=777,
)

# Initialize pipeline and generate

pipeline = YuE2Pipeline.from_pretrained(
    model="m-a-p/YuE2-3B",
    vae="m-a-p/YuE2-Vae",
    progress=False,
)

# Generate and save artifacts

result_off = pipeline.generate(req_off)
result_melody = pipeline.generate(req_melody)
result_full = pipeline.generate(req_full)

result_off.save_artifacts("outputs/off")         # Contains only audio

result_melody.save_artifacts("outputs/melody")   # Contains audio + score.abc

result_full.save_artifacts("outputs/full")       # Contains audio + score.abc

When using melody or full modes, the pipeline automatically emits score.abc inside the output directory, enabling human inspection and manual editing of the symbolic representation before optional re‑generation.

Summary

• cot="off" provides the fastest generation with minimal memory overhead by skipping ABC notation entirely, using guidance 1.01 for stronger CFG compensation.
• cot="melody" generates editable, melody‑only ABC scaffolding ideal for iterative composition workflows where harmonic flexibility is desired.
• cot="full" produces chord‑annotated ABC notation, maximizing human‑interpretable control for cover creation and arrangement tasks at the cost of increased token count and inference time.
• Validation logic in protocol.py prevents contradictory inputs by rejecting external ABC when using off mode.
• Token prefix construction varies significantly between modes, directly impacting the decoder's workload before acoustic generation begins.

Frequently Asked Questions

Can I provide my own ABC notation when using cot="off"?

No. The SongRequest.__post_init__ validation in src/yue2/protocol.py (lines 99‑101) explicitly raises an error if you supply external ABC text while cot="off". This restriction ensures the model does not receive contradictory symbolic information when operating in pure acoustic generation mode. To use custom ABC, select cot="melody" or cot="full" depending on whether your notation includes chords.

Why does cot="off" use guidance 1.01 instead of 1.0?

The SongRequest.guidance property returns 1.01 for off mode and 1.0 for other modes (lines 105‑107 in protocol.py). This slightly higher value strengthens classifier‑free guidance to compensate for the absence of a symbolic "anchor" that would normally steer the generation. Without the ABC scaffold, the increased guidance helps maintain output quality and adherence to the text prompt.

Which mode should I choose for editing existing songs?

Use cot="melody" if you need to adjust melodic phrasing while allowing the model to interpret harmony freely, or cot="full" if you must preserve or modify specific chord progressions. Both modes generate human‑readable ABC notation that can be extracted, edited, and resubmitted to the pipeline. The cot="full" mode is particularly valuable for reharmonization workflows because the chord symbols are explicit in the generated ABC.

How does the token count differ between the three modes?

cot="off" produces the fewest tokens, appending only the markers ABC_START, ABC_END, and MUSIC_START without intermediate content. cot="melody" adds the encoded melody tokens between these markers, while cot="full" adds both melody and chord symbol tokens, resulting in the longest token sequence before acoustic generation begins. This directly impacts inference speed and memory usage, making off fastest and full most computationally expensive.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}