generador-de-musica

Generador de Música

Un sistema de generación musical procedural que crea música original a través de un pipeline estricto y medible. Todas las decisiones las toma el agente; los scripts las ejecutan. El pipeline utiliza mediciones objetivas y compuertas de calidad en lugar de suposiciones subjetivas.

Cuándo Usarlo

Usa este skill cuando:

• Crear música original para video, juegos, anuncios, podcasts o locuciones
• Generar bandas sonoras a partir de descripciones de ambiente (p. ej., "tensión cinematográfica ascendente", "lo-fi tranquilo")
• Clonar instrumentos a partir de grabaciones
• Mezclar o masterizar pistas existentes
• Componer música para video con cortes/diálogos
• Arreglar música robótica, plana o desbalanceada
• Trabajar con estilos culturales específicos (carnático, árabe, africano, esteasiático, etc.)

Inicio Rápido

Ejecuta desde el directorio del skill con su entorno virtual:

• Windows: .venv/Scripts/python.exe
• Unix: .venv/bin/python

Configuración inicial: consulta references/setup.md.

Flujo de Trabajo

Sigue estos pasos en orden. Nunca te saltes pasos.

Paso	Acción	Salida	Verificación
1	Crear proyecto	python scripts/setup_project.py --new-project <dir> --title "<Título>" (añade --ambience solo si se solicita)	Estructura de proyecto con direction/, presets/, scores/, out/, reports/, STATUS.md
2	Investigar	python scripts/research_kb.py <dir> --topic "<tema>" --tags <etiquetas>. Añade fuentes web mediante TinyFish. Para ambiente/efectos, usa --sounds y documenta referencias reales con licencias/mediciones.	reports/research_<tema>.md con citas de la base de conocimiento y fuentes
3	Hoja de dirección	Copia templates/direction_sheet.json a <dir>/direction/direction_<título>.json. Rellena todos los campos según references/music-direction.md. Para video, ejecuta primero scripts/video_score.py.	Hoja completa con trabajo, ambiente, secciones, motivos, hits, intención de mezcla, escenario espacial
4	Crear presets	python scripts/presets.py scaffold instruments/vocals/environments/sfx <nombre> --project <dir>. Cada uno necesita una ubicación espacial única.	Presets en el proyecto con carácter, azimuth/distancia espacial
5	Escribir partitura	Crea <dir>/scores/<título>_score.json (declarativa, referencia a presets). Usa templates/custom_score_template.py para control exacto.	JSON válido con pistas que referencian presets
6	Renderizar y compuertas	python scripts/pipeline.py <dir>/scores/<título>_score.json --project <dir>	out/master.wav (copia de la versión más reciente), out/master_vNN.wav, out/versions.json, etiquetas <master>.json, stems/, midi/, reports/ci_report.json con 0 FALLOS
7	Revisar	Cambia UNA palanca a la vez (references/music-direction.md §6). Vuelve a ejecutar el paso 6 hasta que esté en verde (máximo 5 intentos).	Todas las compuertas pasan
8	Escuchar y entregar	python scripts/listen.py out/master.wav --direction direction/<hoja>.json	Verifica y reporta resultados

Metadatos de entrega y versiones

La certificación escribe tres cosas automáticamente, después de que la compuerta musical pase:

• out/master_vNN.wav — cada render certificado obtiene su propio archivo de versión. Las versiones anteriores se conservan; un nuevo render nunca sobrescribe una existente.
• out/master.wav — una copia de la versión más reciente, para herramientas que esperan un único master.
• out/versions.json — cada versión con su marca de tiempo, mediciones y el cambio que la generó (los fallos de compuerta que superó, o primer render certificado).
• out/master.json — las etiquetas estándar escritas junto al master.

De dónde vienen las etiquetas: valores predeterminados en presets/metadata/metadata.json (artista, álbum, copyright, licencia, editor, ISRC, idioma), luego valores derivados de la partitura (título, género de piece_type, año, un comentario factual key · BPM · piece_type), luego las sobrescrituras del metadata.json del proyecto. Escribe valores reales en <project>/metadata.json en lugar de en los scripts.

Reglas para un agente:

• Nunca elimines ni sobrescribas un master_vNN.wav o un registro de versions.json. Si una entrega necesita una toma limpia, se convierte en una nueva versión.
• Verifica el registro después de un render: python scripts/helpers/version_manager.py list --project <dir>.
• La compresión MP3 es manual, nunca forma parte del pipeline: python scripts/helpers/compress_mp3.py out/master_vNN.wav -o <archivo>.mp3 -b 320k. Transfiere las etiquetas sidecar al MP3.
• Las filas de compuertas meta.tags y meta.version solo rastrean este registro. Advierten, nunca fallan, y son INFO en el primer render de una pieza.

Principios Clave

• Modular: Sonido/espacio en presets/, notas en scores/, intención en direction/. Sin scripts monolíticos.
• Basado en investigación: Cada instrumento/voz/cultura personalizados necesitan citas de investigación de la base de conocimiento.
• Datos sobre código: Los nuevos sonidos usan datos de escena ("scene"/"scene_layers"), no generadores Python.
• Un cambio a la vez: Al solucionar fallos de compuerta, cambia exactamente un parámetro y vuelve a medir.
• Mide, no adivines: Usa métricas y diagnósticos del pipeline. El gusto no se mide.
• Cada pieza tiene un preset de mezcla: Controla la ganancia, dinámica, sidechain, masterización.

Rutas por Tarea

Tarea	Referencias Clave
Composición para video/cortes	references/video-scoring.md, scripts/video_score.py
Voces/coros/hums	references/vocals-and-choirs.md, references/vocal-engine.md
Estilos culturales/fusión	knowledgebase/README.md, references/cultural-soul.md, references/genre-fusion.md
SFX/ambiente/foley	references/sound-effects.md, references/physical-scene.md, references/environments-as-presets.md
Orquesta SFZ	references/sfz-libraries.md, scripts/sfz_libs.py
Clonación/extracción de instrumentos	references/instrument-cloning.md, references/extraction.md
Mezcla/masterización	references/mixing-and-mastering.md, scripts/mixer.py, scripts/mix_diagnostics.py
Fallos de compuerta	references/quality-gate.md, scripts/gate_profiles.py

Plantilla de Salida

Hecho: out/master.wav (Xs, -X.X LUFS, -X.X dBTP), midi/<título>_score.mid, stems/ (N), reports/ci_report.json.
QuÉ es: <ambiente, tonalidad, BPM, instrumentos, presets>.
Compuertas: <N pasan, 0 fallan tras K intentos>; escuchar: <lecturas>.
No verificado: gusto, realismo de instrumentos reales, ajuste en el video final.
Siguiente: <un cambio sugerido>.

Notas y Límites

• Por defecto se usa GM SoundFont; las librerías SFZ son opcionales. Sin palabras cantadas en síntesis estándar (los coros/hums son texturas).
• listen.py requiere el modelo earshot (python scripts/setup_project.py --ears para instalarlo).
• Espacialización para auriculares solo para presets con spatial.binaural: true.
• Los diagnósticos de mezcla reportan pero no bloquean compuertas (las compuertas bloqueantes están en la compuerta de calidad).
• Consulta AGENTS.md para reglas completas y references/troubleshooting-and-limits.md para límites completos.