How YuE's Request-Local Seed Reset Between ABC and Semantic Phases Preserves Two-Stage Arithmetic

YuE resets the random number generator to the same user-provided seed at the start of both the ABC and semantic phases, ensuring deterministic reproducibility and preventing random state leakage between the symbolic and audio generation stages.

The YuE music generation pipeline employs a unique two-stage architecture that first generates symbolic ABC notation before expanding it into full audio tokens. Central to this design is a request-local seed reset mechanism that isolates the stochastic processes of each phase while maintaining deterministic consistency across the entire generation workflow. According to the multimodal-art-projection/YuE source code, this approach guarantees that classifier-free guidance arithmetic remains stable across both generation stages.

Two-Stage Generation Architecture

YuE processes every generation request through two distinct passes:

• ABC Phase – Generates a symbolic representation of the musical score using ABC notation tokens.
• Semantic Phase – Expands the symbolic tokens into a full-length audio representation.

Both phases rely on request-local randomness through a torch.Generator object. However, rather than maintaining a single generator across both phases, the pipeline deliberately resets the random state to ensure isolation between the symbolic and audio generation processes.

The Seed Reset Mechanism in generate_tokens

The core implementation resides in src/yue2/sampling.py at lines 70-73. The generate_tokens function creates a fresh random number generator for every invocation:

# From src/yue2/sampling.py (lines 70-73)

generator = torch.Generator(device=device).manual_seed(seed)

This construction ensures that each call to generate_tokens starts from the exact same deterministic state defined by the user-provided seed. The function does not inherit or continue from any previous random state, effectively sandboxing the stochastic operations within that specific phase.

Pipeline Orchestration and Phase Isolation

The YuE2Pipeline._generate method in src/yue2/pipeline.py orchestrates the two-stage workflow by invoking generate_tokens twice with identical seeds but different phase parameters:

ABC Phase invocation (line 267):

# From src/yue2/pipeline.py (line 267)

abc_output = generate_tokens(
    phase="abc",
    seed=request.seed,
    # ... additional parameters

)

Semantic Phase invocation (line 280):

# From src/yue2/pipeline.py (line 280)

semantic_output = generate_tokens(
    phase="semantic",
    seed=request.seed,  # Same seed as ABC phase

    # ... additional parameters

)

Because each call constructs a fresh torch.Generator using manual_seed(request.seed), the semantic phase begins with the exact same random state that initialized the ABC phase. This deliberate reset prevents the random consumption patterns of the first stage from affecting the second stage.

Preserving Historical Two-Stage Arithmetic

The seed reset mechanism preserves classifier-free guidance (CFG) arithmetic integrity across both stages. The pipeline's CFG calculations depend on consistent random streams for conditional versus unconditional logit comparisons. By resetting the seed between phases:

• Deterministic reproducibility is guaranteed—identical seeds produce identical ABC tokens and audio outputs across runs.
• Arithmetic isolation prevents token-selection penalties and window sampling patterns from the ABC stage from leaking into the semantic stage.
• Stochastic consistency ensures that while each phase operates independently, both remain anchored to the same user-controlled random seed.

This isolation avoids unintended drift in the generation process while maintaining the mathematical relationships required for effective classifier-free guidance.

Practical Implementation Example

The following example demonstrates how the request-local seed maintains consistency across both generation phases:

from yue2.pipeline import YuE2Pipeline

# Initialize the pipeline

pipe = YuE2Pipeline(model_dir="model", vae_dir="vae")

# Configure request with explicit seed

request = {
    "style": "classical",
    "lyrics": "Twinkle twinkle little star",
    "seed": 42,            # User-provided seed

    "abc": None,           # Generate ABC automatically

    "cot": "off",
}

# Execute two-stage generation

result = pipe(**request)

print("ABC tokens:", result.semantic.plan.abc_ids[:10])
print("Audio length (seconds):", len(result.audio) / result.sample_rate)

Executing this code multiple times with seed=42 yields identical ABC tokens and audio output, confirming that the seed reset between phases successfully preserves the deterministic two-stage workflow. The seed parameter is defined in src/yue2/protocol.py within the SongRequest structure and can be controlled via the --seed CLI flag in src/yue2/cli.py.

Summary

• YuE's generation pipeline executes two distinct phases—ABC symbolic generation and semantic audio expansion—both utilizing request-local randomness.
• The generate_tokens function in src/yue2/sampling.py creates a fresh torch.Generator for each phase, resetting the random state to the user-provided seed.
• Both phases receive the identical seed value in src/yue2/pipeline.py (lines 267 and 280), ensuring they start from the same deterministic state.
• This reset mechanism preserves classifier-free guidance arithmetic integrity and prevents random state leakage between the symbolic and audio generation stages.
• Users can control this behavior through the seed parameter in SongRequest or the --seed CLI argument.

Frequently Asked Questions

Why does YuE reset the random seed between phases instead of continuing the random sequence?

YuE resets the seed to ensure arithmetic isolation between the ABC and semantic generation stages. If the pipeline continued the random sequence from the first phase into the second, the token sampling patterns and window penalties from the symbolic generation would influence the audio generation, causing unintended drift. By resetting to the same seed, each phase operates from an identical deterministic starting point while remaining mathematically independent.

How does the seed reset affect classifier-free guidance calculations?

The seed reset preserves CFG arithmetic consistency by ensuring that both conditional and unconditional logit comparisons within each phase draw from the same random distribution. Because each phase starts with a fresh generator seeded identically, the stochastic components of the guidance calculation (such as dropout masks or sampling noise) remain consistent within that phase without interference from previous operations.

Can I reproduce the exact same output by setting the same seed across different YuE versions?

While the request-local seed reset guarantees deterministic output for a specific code version, architectural changes to generate_tokens in src/yue2/sampling.py or model weights may alter the mapping between seeds and outputs. For exact reproducibility, you must use identical model checkpoints and pipeline versions alongside the same seed value.

Where is the user-provided seed stored in the YuE request structure?

The seed is defined in src/yue2/protocol.py within the SongRequest dataclass as an integer field. The CLI interface in src/yue2/cli.py exposes this through the --seed flag, passing the value into the pipeline's _generate method where it is forwarded to both ABC and semantic phase calls to generate_tokens.

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