stem-mix-workflow.md

Reproducible stem mix workflow

Raw performance artifacts and downstream mix intent have different validity boundaries:

• composition_hash covers score, vocal performance source, arrangement, and renderer settings. Vocal/instrument stems depend on this hash.
• mix_hash covers composition_hash plus effect chains and section dynamics. A mix depends on both, so changing EQ invalidates the mix without forcing the original Editor to synthesize vocals again.

Ordering and alignment

Every selected artifact is verified against its SHA-256 and composition hash. Instrument stems use timeline_origin=song_start; the mixer inserts the exact pre-measure duration derived from meter and initial tempo. Original-Editor vocal stems use project_start and need no delay.

The deterministic render order is:

1. resample/convert one stem to stereo float;
2. apply that track's section gain automation with explicit edge ramps;
3. apply enabled effects in manifest order;
4. sum tracks with normalize=0;
5. apply mix-bus section automation;
6. apply enabled mix-bus effects in order;
7. encode 16- or 24-bit PCM and measure the result.

Automation is pre-effect, so a reverb/delay tail follows the level driven into the effect. No limiter, normalization, makeup, pan correction, or stereo centering is hidden. If the agent wants one, it must be present in the manifest.

Typed effects

• gain: dB;
• pan: normalized −1 left to +1 right power balance;
• highpass / lowpass: cutoff, Q, one/two poles;
• equalizer: center frequency, Q, dB gain, wet mix;
• compressor: threshold dB, ratio, attack/release, makeup, knee, detector, mix;
• deesser: normalized intensity, maximum de-essing, frequency focus;
• reverb: reproducible two-tap room approximation;
• delay: delay time and feedback decay;
• limiter: ceiling, attack, release, with latency compensation and no auto gain.

The room effect is deliberately described as a bounded multi-tap approximation, not a studio convolution reverb. High-quality VST/DAW rendering remains outside the requested scope.

Minimal sequence

1. Inspect the manifest and select current stem artifact IDs.
2. Upsert one chain per target with vocaloid_upsert_manifest_effect_chain.
3. Upsert individual section decisions with vocaloid_upsert_manifest_section_dynamic.
4. Inspect the new mix_hash.
5. Call vocaloid_render_stem_mix with explicit sample rate and bit depth.
6. Inspect returned LUFS/LRA, true/sample peak, clipping, per-channel RMS, and filter graph. Revise the manifest and render a new slugged revision when the measurements or listening intent call for it.

{
  "name": "vocaloid_render_stem_mix",
  "arguments": {
    "manifest_path": "songs/ame-no-ato.song.json",
    "expected_revision": 27,
    "stem_artifact_ids": [
      "vocal-stem-lead-r22",
      "vocal-stem-harmony-r22",
      "instrument-stem-shamisen-r23",
      "instrument-stem-taiko-r23"
    ],
    "output_path": "artifacts/ame-no-ato-mix-r27.wav",
    "sample_rate": 48000,
    "bit_depth": 24,
    "reference_lufs": -16,
    "reference_true_peak_dbfs": -1,
    "response_format": "json"
  }
}

The loudness and peak targets in this call are analysis references only. They do not normalize the mix. Use an explicit gain/compressor/limiter revision or the separate two-pass mastering tool after the source mix is clean.