AGENTS.md

AGENTS.md

Project identity

• Repository: minimax-music3-latent-refiner
• Hub release: terminusresearch/minimax-music3-latent-refiner-v0.10
• Purpose: restore damaged audio in MiniMax Music 3 DAV latent space.
• Selected weights: refiner3-bridge-hybrid/checkpoint-1000.
• v0.10 is the public release number for the selected bridge hybrid. It is not the later replanner-8k-v10-incontext-dpo-src experiment.
• The release model has 137,253,888 parameters. It was trained for 1,000 new steps after warm-starting the bridge checkpoint.

Architecture invariants

• Audio rate: 44,100 Hz stereo.
• DAV hop: 512 waveform samples.
• DAV latent rate: 25 * 441 / 128 = 86.1328125 frames/second.
• DAV latents: [batch, 128, frames] externally and [batch, frames, 128] inside the refiner.
• MERT input: 24,000 Hz mono.
• MERT hidden states: 13 layers, 768 channels, linearly interpolated to DAV frame count.
• Main MERT conditioning layer: 7.
• Refiner: width 768, 12 blocks, 12 heads, head dimension 64.
• Block-to-MERT map: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 11].
• CLAP conditioning comes from the degraded source audio, not the clean target.
• In-context layout is [degraded reference tokens, bridge target tokens]. Both halves use the same RoPE positions.
• The degraded latent stream is also injected per frame through degraded_in_proj.
• Restore sampling starts from degraded DAV latents at bridge time 1 and integrates to time 0.
• Normalization tensors are required. Never run the checkpoint without normalization.safetensors.

Release behavior

• Default sampler: deterministic 32-step Euler bridge.
• Training windows were 30 seconds.
• Longer inputs must use overlapping windows by default. Direct long-sequence inference is supported by RoPE but is not the quality baseline.
• The package must preserve exact state-dict key compatibility with the SimpleTuner experiment checkpoint.
• An external ComfyUI AUDIO_VAE_ENCODER input takes precedence over the bundled encoder.
• ComfyUI's stock MiniMax Music 3 VAE is decoder-only. Do not call its encode method.

Repository layout

• src/minimax_music3_latent_refiner/model.py: checkpoint-compatible refiner.
• src/minimax_music3_latent_refiner/dav.py: full DAV encoder/decoder.
• src/minimax_music3_latent_refiner/pipeline.py: conditioning, sampling, windowing, and audio I/O.
• src/minimax_music3_latent_refiner/diffusers_patch.py: opt-in pipeline attachment.
• comfyui_node/: ComfyUI custom node package.
• examples/: command-line and Diffusers examples.
• scripts/: release conversion and verification utilities.
• tests/: unittest tests.

Development rules

• Use .venv and python -m unittest -v.
• Keep inference code independent of SimpleTuner imports.
• Do not copy DDP, DPO, dataset, or training-only code into this repository.
• Do not silently change tensor layout, frame rate, normalization, or conditioning source.
• Do not add fallback inference paths. Unsupported checkpoint or encoder formats must fail with a specific error.
• New behavior requires a focused unit test and one real-audio verification when it affects inference.
• Never commit or push unless the user explicitly requests it.

Public text privacy

Never publish local machine identity in commits, model cards, Hub metadata, logs, examples, or validation notes.

Forbidden public text includes:

• Local absolute paths.
• Local account names or workstation usernames.
• Private pod paths.
• Raw terminal output containing local identity.
• Co-author trailers containing personal names or email addresses.

Use repository-relative paths and generic commands. Before any GitHub or Hugging Face publication, scan the exact public payload. If local identity is found, stop and report only:

Blocked: local machine identity was found in public text.