# Why YuE's effective_config Emits a cfg_negative String and Who Consumes It

> Discover why YuE's effective_config emits cfg_negative. Learn how this flag ensures reproducibility and auditability for music generation, consumed by CLI, exporters, and tests.

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

---

**The `cfg_negative` string emitted by YuE's `effective_config` method acts as a metadata flag that records which negative classifier-free-guidance (CFG) strategy was applied during music generation, consumed by the CLI, JSON artifact exporters, and test suites to ensure reproducibility and auditability.**

The YuE music generation system (multimodal-art-projection/YuE) uses the `effective_config` method in [`src/yue2/pipeline.py`](https://github.com/multimodal-art-projection/YuE/blob/main/src/yue2/pipeline.py) to snapshot exact runtime parameters for every generation request. Among these parameters, the **`cfg_negative`** field serves a specific purpose: it documents whether the negative CFG utilized only the instruction prompt or both the instruction and chain-of-thought content. This metadata travels through the entire pipeline, enabling precise debugging and configuration tracking.

## What cfg_negative Represents in YuE

The `cfg_negative` field captures the **negative classifier-free-guidance mode** applied during inference. Classifier-free guidance requires both a positive and negative prompt to steer generation, and YuE varies its negative strategy based on whether chain-of-thought reasoning is enabled.

The field contains one of two string values that indicate the exact policy used:

- **`"instruction_only"`** — Indicates the request's chain-of-thought (`cot`) is turned **off**, meaning only the instruction part of the prompt is used for constructing the negative CFG.

- **`"same_instruction_and_exact_abc"`** — Indicates the request's `cot` is **on**, meaning the negative CFG incorporates both the instruction and the exact ABC (music notation) prompt content.

## How effective_config Generates cfg_negative in pipeline.py

The logic that assigns these values resides in [`src/yue2/pipeline.py`](https://github.com/multimodal-art-projection/YuE/blob/main/src/yue2/pipeline.py) around lines 369-370 within the `effective_config` method. When constructing the configuration dictionary, the method inspects the request object's `cot` attribute to determine the appropriate negative guidance strategy.

If the request disables chain-of-thought, the method assigns `"instruction_only"` to ensure the negative prompt remains minimal. If chain-of-thought is active, it assigns `"same_instruction_and_exact_abc"` to include the full musical context in the negative guidance. This ensures the configuration precisely reflects the runtime decision made by the pipeline.

## Downstream Consumers of cfg_negative

Once `effective_config` builds the configuration dictionary, the `cfg_negative` string propagates through several system components that rely on this metadata for logging, validation, and reproducibility.

### Artifact Serialization and result.json

When a generation completes, the resulting **`SongResult`** object contains the full `config` dictionary, including `cfg_negative`. This dictionary is serialized to JSON format (e.g., in the [`result.json`](https://github.com/multimodal-art-projection/YuE/blob/main/result.json) file saved by `save_artifacts` as documented in [`docs/generation.md`](https://github.com/multimodal-art-projection/YuE/blob/main/docs/generation.md)). External tools, dashboards, and downstream scripts consume this file to record exactly which guidance strategy was applied for a given output.

### CLI and Example Scripts

The YuE CLI ([`src/yue2/cli.py`](https://github.com/multimodal-art-projection/YuE/blob/main/src/yue2/cli.py)) and example scripts such as [`main/skills/yue2-music/scripts/run_yue2.py`](https://github.com/multimodal-art-projection/YuE/blob/main/main/skills/yue2-music/scripts/run_yue2.py) and [`listen.py`](https://github.com/multimodal-art-projection/YuE/blob/main/listen.py) read the `cfg_negative` field for user-facing display and logging. When verbose mode is enabled, these tools print the configuration to help users understand why particular outputs differ based on their chain-of-thought settings.

### Integration Testing

Test suites such as [`test_progress_integration.py`](https://github.com/multimodal-art-projection/YuE/blob/main/test_progress_integration.py) consume the `cfg_negative` field to verify that the pipeline produces correct configuration values for different request modes. These assertions ensure that the CFG strategy remains consistent across software versions and that the metadata correctly reflects the active generation parameters.

## Accessing cfg_negative in Practice

You can inspect the `cfg_negative` value both before and after generation using YuE's Python API.

To check the configuration before generating:

```python
from yue2.pipeline import Pipeline

pipe = Pipeline()
request = pipe._request(style="classical", lyrics="...")
cfg = pipe.effective_config(request)

print(cfg["cfg_negative"])

# Output: "instruction_only" (if request.cot == "off")

```

To retrieve the value from a completed generation result:

```python
song = pipe(style="jazz", lyrics="...")
print(song.config["cfg_negative"])

# Output reflects the mode used for this specific generation

```

The CLI implementation in [`src/yue2/cli.py`](https://github.com/multimodal-art-projection/YuE/blob/main/src/yue2/cli.py) demonstrates verbose logging:

```python
if args.verbose:
    cfg = pipe.effective_config(request)
    print(f"CFG negative mode: {cfg['cfg_negative']}")

```

## Summary

- **`cfg_negative`** is a metadata string emitted by `effective_config` in [`src/yue2/pipeline.py`](https://github.com/multimodal-art-projection/YuE/blob/main/src/yue2/pipeline.py) that identifies the negative CFG strategy used during music generation.
- The value is determined by the chain-of-thought setting: `"instruction_only"` for `cot` off, and `"same_instruction_and_exact_abc"` for `cot` on.
- The string is stored in the `SongResult` config dictionary and serialized to JSON artifacts (e.g., [`result.json`](https://github.com/multimodal-art-projection/YuE/blob/main/result.json)) for external auditing.
- Consumers include the CLI ([`src/yue2/cli.py`](https://github.com/multimodal-art-projection/YuE/blob/main/src/yue2/cli.py)), example scripts ([`run_yue2.py`](https://github.com/multimodal-art-projection/YuE/blob/main/run_yue2.py), [`listen.py`](https://github.com/multimodal-art-projection/YuE/blob/main/listen.py)), and integration tests that validate configuration correctness.
- The field enables reproducibility by allowing developers and automated systems to verify exactly which negative guidance policy was applied to any generated song.

## Frequently Asked Questions

### What does cfg_negative mean in YuE?

The `cfg_negative` field indicates which negative prompt strategy the classifier-free guidance mechanism used during generation. It records whether the negative CFG utilized only the instruction text (`"instruction_only"`) or included both the instruction and the exact ABC music notation (`"same_instruction_and_exact_abc"`), depending on whether chain-of-thought reasoning was enabled.

### How can I check the cfg_negative value after generation?

Access the `config` dictionary on the `SongResult` object returned by the pipeline. The `cfg_negative` key contains the string value. For persisted generations, inspect the [`result.json`](https://github.com/multimodal-art-projection/YuE/blob/main/result.json) file created by `save_artifacts`, where this configuration metadata is stored alongside the audio output.

### Why does cfg_negative change based on the chain-of-thought setting?

The `effective_config` method in [`src/yue2/pipeline.py`](https://github.com/multimodal-art-projection/YuE/blob/main/src/yue2/pipeline.py) sets `cfg_negative` based on the `request.cot` attribute. When chain-of-thought is disabled, the negative CFG only needs the instruction context to avoid confusing the model with unrelated musical content. When enabled, the negative prompt must include the full ABC context to properly contrast against the chain-of-thought reasoning path.

### Which source files should I examine to understand cfg_negative implementation?

Start with [`src/yue2/pipeline.py`](https://github.com/multimodal-art-projection/YuE/blob/main/src/yue2/pipeline.py) (lines 369-370) to see the assignment logic in `effective_config`. For consumption examples, review [`src/yue2/cli.py`](https://github.com/multimodal-art-projection/YuE/blob/main/src/yue2/cli.py) for CLI logging, [`main/skills/yue2-music/scripts/run_yue2.py`](https://github.com/multimodal-art-projection/YuE/blob/main/main/skills/yue2-music/scripts/run_yue2.py) for artifact handling, and [`docs/generation.md`](https://github.com/multimodal-art-projection/YuE/blob/main/docs/generation.md) for documentation on how configuration metadata is preserved with generated artifacts.