music-generator

Music Generator

Um sistema de geração de música procedural que cria música original através de um pipeline estrito e mensurável. Todas as decisões são tomadas pelo agente; os scripts as executam. O pipeline usa medições objetivas e portões de qualidade em vez de palpites subjetivos.

Quando Usar

Use esta habilidade quando:

• Criar música original para vídeo, jogos, anúncios, podcasts ou narrações
• Gerar trilhas sonoras a partir de descrições de clima (ex.: "crescendo cinematográfico tenso", "lo-fi calmo")
• Clonar instrumentos a partir de gravações
• Mixar ou masterizar stems existentes
• Pontuar para vídeo com cortes/diálogos
• Corrigir música robótica, chata ou desbalanceada
• Trabalhar com estilos culturais específicos (carnático, árabe, africano, leste asiático, etc.)

Início Rápido

Execute a partir do diretório da habilidade com seu ambiente virtual:

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

Configuração inicial: veja references/setup.md.

Fluxo de Trabalho

Siga estas etapas em ordem. Nunca pule etapas.

Etapa	Ação	Saída	Verificação
1	Criar projeto	python scripts/setup_project.py --new-project <dir> --title "<Título>" (adicione --ambience apenas se solicitado)	Estrutura do projeto com direction/, presets/, scores/, out/, reports/, STATUS.md
2	Pesquisar	python scripts/research_kb.py <dir> --topic "<tópico>" --tags <tags>. Adicione fontes da web via TinyFish. Para ambiência/efeitos, use --sounds e documente referências reais com licenças/medições.	reports/research_<tópico>.md com citações da base de conhecimento e fontes
3	Ficha de direção	Copie templates/direction_sheet.json para <dir>/direction/direction_<título>.json. Preencha todos os campos conforme references/music-direction.md. Para vídeo, execute scripts/video_score.py primeiro.	Ficha completa com job, feel (clima), seções, motivos, hits, mix_intent, spatial_staging
4	Criar presets	python scripts/presets.py scaffold instruments/vocals/environments/sfx <nome> --project <dir>. Cada um precisa de posicionamento espacial único.	Presets no projeto com character, spatial.azimuth/distance
5	Escrever partitura	Crie <dir>/scores/<título>_score.json (declarativa, referencia presets). Use templates/custom_score_template.py para controle exato.	JSON válido com faixas referenciando presets
6	Renderizar e verificar	python scripts/pipeline.py <dir>/scores/<título>_score.json --project <dir>	out/master.wav (cópia da versão mais recente), out/master_vNN.wav, out/versions.json, tags <master>.json, stems/, midi/, reports/ci_report.json com 0 FAIL
7	Revisar	Altere UMA alavanca por vez (references/music-direction.md §6). Execute novamente a etapa 6 até ficar verde (máx. 5 tentativas).	Todos os portões passam
8	Ouvir e entregar	python scripts/listen.py out/master.wav --direction direction/<ficha>.json	Verificar e relatar resultados

Metadados e versões de entrega

A certificação escreve três coisas automaticamente, após a aprovação do portão musical:

• out/master_vNN.wav — cada renderização certificada ganha seu próprio arquivo de versão. Versões anteriores são mantidas; uma re-renderização nunca sobrescreve uma.
• out/master.wav — uma cópia da versão mais recente, para ferramentas que esperam um único master.
• out/versions.json — cada versão com seu timestamp, medições e a mudança que a conquistou (as falhas de portão que foram limpas, ou primeira renderização certificada).
• out/master.json — as tags padrão escritas ao lado do master.

De onde vêm as tags: valores padrão em presets/metatdats/metadata.json (artista, álbum, direitos autorais, licença, editora, ISRC, idioma), depois valores derivados da partitura (título, gênero de piece_type, ano, um comentário factual tom · BPM · piece_type), e por fim as substituições do próprio metadata.json do projeto. Escreva valores reais em <project>/metadata.json em vez de em scripts.

Regras para um agente:

• Nunca exclua ou sobrescreva um arquivo master_vNN.wav ou um registro em versions.json. Se uma entrega precisar de uma gravação limpa, ela se torna uma nova versão.
• Verifique o registro após uma renderização: python scripts/helpers/version_manager.py list --project <dir>.
• A compressão MP3 é manual, nunca parte do pipeline: python scripts/helpers/compress_mp3.py out/master_vNN.wav -o <arquivo>.mp3 -b 320k. Ela carrega as tags auxiliares para o MP3.
• As linhas de portão meta.tags e meta.version apenas rastreiam este registro. Elas avisam, nunca falham, e são INFO na primeira renderização de uma peça.

Princípios Chave

• Modular: Som/espaço em presets/, notas em scores/, intenção em direction/. Nenhum script monolítico.
• Baseado em pesquisa: Cada instrumento/vocal/cultura personalizado precisa de citações de pesquisa da base de conhecimento.
• Dados sobre código: Novos sons usam dados de cena ("scene"/"scene_layers"), não geradores Python.
• Uma mudança por vez: Ao corrigir falhas de portão, altere exatamente um parâmetro e meça novamente.
• Meça, não adivinhe: Use métricas e diagnósticos do pipeline. Gosto não é medido.
• Toda peça ganha um preset de mix: Controla ganho, dinâmica, sidechain, masterização.

Rotas por Tarefa

Tarefa	Referências Chave
Pontuação/cortes de vídeo	references/video-scoring.md, scripts/video_score.py
Vocais/coros/hums	references/vocals-and-choirs.md, references/vocal-engine.md
Estilos culturais/fusão	knowledgebase/README.md, references/cultural-soul.md, references/genre-fusion.md
Efeitos sonoros/ambiência/foley	references/sound-effects.md, references/physical-scene.md, references/environments-as-presets.md
Orquestra SFZ	references/sfz-libraries.md, scripts/sfz_libs.py
Clonagem/extração de instrumentos	references/instrument-cloning.md, references/extraction.md
Mixagem/masterização	references/mixing-and-mastering.md, scripts/mixer.py, scripts/mix_diagnostics.py
Falhas de portão	references/quality-gate.md, scripts/gate_profiles.py

Template de Saída

Pronto: out/master.wav (Xs, -X.X LUFS, -X.X dBTP), midi/<título>_score.mid, stems/ (N), reports/ci_report.json.
O que é: <clima, tom, BPM, instrumentos, presets>.
Portões: <N passaram, 0 falharam após K tentativas>; ouça: <leituras>.
Não verificado: gosto, realismo de instrumento real, ajuste no vídeo final.
Próximo: <uma mudança sugerida>.

Notas e Limites

• SoundFont GM usado por padrão; bibliotecas SFZ opcionais. Sem palavras cantadas na síntese padrão (coros/hums são texturas).
• listen.py requer modelo earshot (python scripts/setup_project.py --ears para instalar).
• Espacialização para fones de ouvido apenas para presets com spatial.binaural: true.
• Diagnósticos de mix relatam, mas não bloqueiam portões (portões bloqueadores estão no portão de qualidade).
• Veja AGENTS.md para regras completas e references/troubleshooting-and-limits.md para limites completos.