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

> Explore YuE2 protocol's CoT modes: off, melody, and full. Understand the trade-offs for creation, cover, and editing use cases and choose the best option for your needs.

- Repository: [multimodal-art-projection/YuE](https://github.com/multimodal-art-projection/YuE)
- Tags: deep-dive
- Published: 2026-09-14

---

**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`](https://github.com/multimodal-art-projection/YuE/blob/main/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`](https://github.com/multimodal-art-projection/YuE/blob/main/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`](https://github.com/multimodal-art-projection/YuE/blob/main/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`](https://github.com/multimodal-art-projection/YuE/blob/main/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`](https://github.com/multimodal-art-projection/YuE/blob/main/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:

```python
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`](https://github.com/multimodal-art-projection/YuE/blob/main/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`](https://github.com/multimodal-art-projection/YuE/blob/main/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`](https://github.com/multimodal-art-projection/YuE/blob/main/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.