fix(studio): admitir captions vacíos en generation.music

[cursor]

Resumen ejecutivo

Qué cambia

generation.music ya no exige un Style/caption (alt_prompt) no vacío. Letras solas o [Instrumental] vuelven a admitirse.

Para qué sirve

El contrato cerrado de #280 pedía caption no vacío aunque el schema generado lo deja en "" y ACE-Step acepta canciones solo con lyrics. Generate y el Wizard fallaban en seco.

Impacto para el usuario

En Studio → Audio → Music, Generate funciona si hay lyrics (o Instrumental) aunque Style esté vacío. MiniMax-Music3 sigue exigiendo caption en su handler.

Riesgo

• Bajo
• Medio
• Alto

Estado

• En desarrollo
• Listo para revisión
• Bloqueado por CI o revisión
• Requiere migración o acción manual

Summary

The closed Studio music envelope required a non-blank alt_prompt on both sides:

• StudioMusicParams._check_semantics called _non_blank(self.alt_prompt)
• assertMusicParams called requiredText(value.alt_prompt)

The generated catalog only requires prompt and model_type; alt_prompt defaults to "". ACE-Step treats an empty caption as empty tags. The extra blank check blocked:

1. Studio Generate after writing lyrics (or checking Instrumental) without filling Style.
2. Wizard prepare_audio + start_generation when the model omitted alt_prompt (the adapter writes '').

The _music_description field is intentionally not a caption fallback.

This change removes only the non-blank caption checks. Lyrics/prompt remain required. Music3 still rejects a blank caption in its native handler.

Overview

1. User opens Studio → Audio → Music, writes lyrics or enables Instrumental, leaves Style empty, clicks Generate.
2. createStudioMusicGenerationCommand / freeze_studio_music_spec now admit alt_prompt="" or an omitted caption.
3. ACE-Step proceeds with lyrics only. Music3 still fails later with its own Music Caption error.

Detailed changes

Backend

• studio_music_spec.py: stop requiring a non-blank alt_prompt in _check_semantics.

UI and Wizard

• musicGenerationSpec.ts: stop calling requiredText on alt_prompt. Catalog validation still enforces string/maxLength when the field is present.

Data, provenance and compatibility

No sidecar or envelope version change. Commands that already sent a caption are unchanged.

Files and ownership

• app/services/studio_music_spec.py — drop extra blank check
• ui/src/features/studio/musicGenerationSpec.ts — match generated catalog
• tests/test_studio_music_spec.py / ui/tests/musicGenerationCommands.test.ts — empty and omitted caption cases
• Left untouched: Speech residue neutralization (fix(studio): no enviar residuos de Speech en generation.music #283), duration overwrite in loadModelOptions, lyrics stash across Speech↔Music

Validation

• Date (UTC): 2026-09-09

• Base SHA: 60019e5 (feat/shared-tool-commands)

• Head SHA: dfed48b

• Validation scope: focused

• python scripts/verify_clean_repo.py

• python -m compileall -q app/services/studio_music_spec.py — OK

• Focused Python tests: /workspace/.venv/bin/pytest tests/test_studio_music_spec.py -q — 39 passed

• cd ui && npm run i18n:check

• UI tests: npx tsx --tsconfig tsconfig.app.json --import ./tests/setupI18n.ts --test tests/musicGenerationCommands.test.ts — 9 passed

• cd ui && npm run lint -- --max-warnings=0

• cd ui && npm run build

• git diff --check

• E2E/smoke checks: N/A (provider-free command tests; no live generation)

Code quality

• Score: pending CI
• Complexity trend: pending CI
• Production LOC trend: pending CI
• Regression versus main: pending CI
• Ratchet: pending CI

CI and review

• CI of this HEAD: pending

• Independent agent review of this HEAD: pending

• Human merge click (operational, not code review): pending

• Reviewed at current HEAD

• Earlier review; HEAD has changed since (stale)

• Pending

• Unavailable

Coste de la tarea

• Tests simulados: 0 tokens externos
• Tests reales: N/A
• Llamadas LLM externas: 0
• Tokens de prompt: N/A
• Tokens de respuesta: N/A
• Tokens totales: N/A
• Generaciones de imágenes/audio/vídeo: 0
• Tiempo transcurrido: N/A
• Proveedores/modelos: N/A

Notes and limitations

Does not stash lyrics/caption across Speech↔Music, and does not stop loadModelOptions from resetting duration to the model default. Those remain on #280 / #283 follow-up.

Follow-up work

• Speech residue on Music Generate: still awaiting review in fix(studio): no enviar residuos de Speech en generation.music #283
• Audio sub-tab stash for lyrics/caption
• loadModelOptions should clamp an in-range user duration instead of overwriting with the slider default

Checklist

• The executive summary is understandable without reading the code.
• The detailed Summary/Overview has not been removed or shortened.
• Tests and their actual results are recorded.
• Generated assets, secrets and local-only files are not committed.
• Required CI and Cursor/Bugbot review are complete, or the PR is clearly marked as waiting for them.