raffataff/tunetrack

TuneTrack: música para jogos com as ferramentas MCP tunetrack

O TuneTrack é a estação de trabalho musical do usuário. Você escreve a música como notas, acordes, padrões e curvas de CC; o TuneTrack as reproduz através de instrumentos reais (plugins VST3 do usuário com patches salvos, bibliotecas de amostras SFZ ou sintetizadores Faust integrados), mixa, masteriza e renderiza arquivos prontos para loop. Você não ouve, então trabalha a partir da teoria musical, dos relatórios de análise da ferramenta e da imagem do piano roll. Cada decisão deve ser deliberada. Sem loops de preenchimento, sem improvisação genérica.

Se as ferramentas estiverem faltando, o servidor MCP não está registrado: claude mcp add --scope user tunetrack -- C:\Users\Owner\Documents\TuneTrack\.venv\Scripts\tunetrack-mcp.exe.

1. Entenda o projeto primeiro

Antes de escrever uma nota, descubra para que serve a música:

• Leia o projeto do jogo: README, documentos de design, texto da história/cenário, nomes de cenas/níveis, estilo de arte (veja algumas imagens), cores do tema da IU, pastas de áudio existentes e nomenclatura de arquivos, a engine (Godot project.godot, Unity Assets/, Unreal .uproject, web).
• Decida sobre: gênero/paleta, clima (2-3 adjetivos), energia, andamento, tom/modo, tipo de cue, duração, forma de loop, formato de entrega e caminho. Se o usuário deu a intenção ("menu synthwave escuro, 100 bpm"), ela prevalece sobre sua inferência. Pergunte apenas se o projeto não der pistas.
• Registre: project_new(nome, andamento, tom, assinatura_de_tempo, resumo={gênero, clima, uso, jogo, referências, notas}).

2. Verifique a biblioteca de instrumentos

status() lista instrumentos VST3, patches (um plugin mais um som salvo, com tags), instrumentos SFZ e sintetizadores internos.

• Partes acústicas/orquestrais precisam de amostras reais: use patch:<id> (por exemplo, HALion, BBC Symphony Orchestra, patches do Spitfire LABS) ou sfz:<caminho>. Sintetizadores internos são excelentes para eletrônico, synthwave, chiptune, ambiente e lo-fi, e servem bem como camadas de suporte.
• Instrumentos VST3 como HALion Sonic e Groove Agent carregam vazios: sem um patch, eles renderizam silêncio (o render avisa). MODO DRUM funciona sem patch.
• Se a paleta que o resumo precisa estiver faltando (por exemplo, cordas orquestrais sem patch de cordas ou SFZ), diga claramente e ofereça: (a) o usuário capturar patches (patch_capture abre a janela do plugin; apenas enquanto ele estiver no computador), (b) instalar uma biblioteca gratuita (o README lista algumas), ou (c) uma versão sintetizada estilizada. Não passe um sintetizador como orquestra.
• audition("patch:<id>") verifica se um instrumento produz som e relata seu brilho. sfz_info mostra alcance e chaves de comutação.
• Patches com dynamics_cc (1 ou 11) obtêm sua intensidade desse CC, não da velocidade: sempre escreva curvas cc() para eles.

3. Planeje a forma (antes das notas)

Defina markers() para as seções e project_set(loop="5:1-21:1") para a região de loop. Formas típicas:

Cue	Duração	Forma e notas
Menu principal	45-120 s loop	Introdução opcional de 2-4 compassos (tocada uma vez) depois um loop A(8) B(8) ou A A' B A. Motivo memorável, densidade média, deixa espaço para sons da IU.
Exploração / mundo aberto	1,5-3 min loop	Arcos longos, textura esparsa, espaço para respirar, ritmo harmônico lento (1-2 compassos por acorde).
Cidade / loja	40-90 s loop	Quente, rítmico, pequeno conjunto, cativante.
Batalha	60-120 s loop	130-170 bpm, ostinato impulsionador, baixo forte, acentos e golpes, frases curtas; a seção B aumenta a intensidade.
Chefão	90-180 s loop	Modo mais escuro, graves mais pesados, um motivo que é distorcido do tema principal.
Stinger de vitória / derrota	2-8 s, one-shot	Vitória: linha ascendente para um acorde maior brilhante + prato. Derrota: linha descendente para um acorde menor ou diminuto, fade. loop="off".
Cama de ambiência	1-3 min loop	Pads/drones, movimento lento, sem pulso forte, pouca melodia.
Créditos	2-4 min, one-shot	Medley dos motivos do jogo.

Regras de loop: o loop é um número inteiro de compassos; seu último compasso deve levar de volta ao primeiro (dominante, ou uma anacruse para a primeira nota da melodia). Não deixe notas cruzarem o final do loop, a menos que você queira. Caudas de release e reverb são dobradas automaticamente no início do loop por render(loop="auto").

Música adaptativa: coloque cada camada no mesmo tom, andamento e duração, marque as faixas com layer (base, tension, combat), e renderize com layers=True para stems em camadas verticais que o jogo faz crossfade.

4. Escreva a música

Ordem: motivo, depois harmonia, baixo, frases melódicas, contracanto e partes internas, seção rítmica, dinâmica, depois variação.

Melodia

• Construa a partir de um motivo de 1-2 compassos com um ritmo e contorno reconhecíveis. Desenvolva-o com repetição, sequência (movida um grau acima), inversão, aumento rítmico. Estruture frases como pergunta (termina aberta, no 2 ou 5) e resposta (termina no 1).
• Um clímax claro por seção (nota mais alta, batida mais forte). Movimento gradual com saltos ocasionais; resolva saltos por movimento gradual na direção oposta. Mantenha-a cantável (cerca de uma oitava e uma quinta), a menos que seja uma peça instrumental de exibição.
• Deixe espaço: pausas e notas longas dão forma às frases e espaço para respirar. Nem toda batida precisa de uma nota.
• Notas do acorde em batidas fortes; notas de passagem e vizinhas em batidas fracas. Notas longas em dissonâncias são escolhas deliberadas.

Harmonia

• chords() faz a condução de vozes para você. Escolha progressões que sirvam ao clima. Varie o ritmo harmônico: 1 acorde por compasso, mais rápido nas cadências.
• Movimentos úteis: i-VI-III-VII menor (épico/heroico), i-iv-VII-III menor (nostálgico), I-V-vi-IV maior (brilhante), ii-V-I e IVmaj7-iii7-vi7 (jazzístico/aconchegante), bVI-bVII-I (triunfante), Lídio I-II (maravilha/magia), Frígio i-bII (ameaça), Dórico i-IV (aventureiro, folk), medianas cromáticas (bIII, bVI maior em tom maior) para cor cinematográfica, pontos de pedal sob acordes variáveis para tensão.
• Termine seções com cadências reais (V-i, iv-V, bVI-bVII-I). Dominantes secundárias (V/V, V7/vi) adicionam movimento progressivo.

Baixo

• Fundamentais em batidas fortes, quintas e notas de aproximação (grau ou sensível) nas mudanças de acorde. Dê a ele um ritmo que trave com o bumbo. Mantenha-o abaixo de C3 e sozinho em seu registro.

Arranjo

• Registros: baixo abaixo de C3, harmonia C3-C5, melodia acima ou claramente separada do acompanhamento. Intervalos menores que uma quinta abaixo de C3 soam turvos (a análise sinaliza isso).
• Um elemento focal por vez; contracantos respondem nas pausas da melodia (chamada e resposta).
• Construa seções adicionando e removendo camadas. B deve contrastar com A: registro diferente, densidade, ritmo ou cor harmônica.
• Orquestral: melodia nos violinos (dobrada pela flauta uma oitava acima ou trompa uma oitava abaixo para aquecer), harmonia nas violas/violoncelos/trompas, baixo nos contrabaixos/violoncelos. Trompas soam melhor em quintas e oitavas em seu registro médio; trompetes para picos de fanfarra; tímpanos em fundamentais e quintas nos finais de frase. Use role nas faixas para que as verificações de alcance se apliquem. theory(range="trompa").
• Bateria: um groove com variação a cada 4 compassos e um preenchimento nas mudanças de seção (no último tempo ou dois do compasso 8). Prato no downbeat de novas seções. Notas fantasmas (o) e swing adicionam vida.

Dinâmica e sensação

• Molde cada frase: notes_edit(op="velocity", ramp_from, ramp_to) para crescendos, acentos com >.
• Patches orquestrais controlados por CC: cc(faixa, 1, inicio, fim, 40, 100, shape="swell") em notas longas, e níveis base por seção.
• notes_edit(op="humanize", timing_ms=5-15, velocity=4-8) para partes acústicas. Mantenha chiptune e partes eletrônicas apertadas na grade.
• Staccato (') e legato (notes_edit(op="legato")) mudam muito o caráter. Use-os com propósito.

Reutilize sem monotonia de copiar e colar: arrange(op="copy") uma seção, depois varie a cópia (novo contracanto, mudança de oitava, cadência rearmonizada, bateria mais aberta).

5. Paletas de gênero (nomes de sintetizadores internos entre colchetes; prefira patches reais quando o gênero for acústico)

Gênero	Andamento	Modos / harmonia	Paleta e ritmo
Fantasia orquestral / aventura	80-120	Maior/Dórico/Lídio, i-VI-III-VII	Cordas, trompas, madeiras, harpas, tímpanos; [pluck], [bell] para cor
Épico / batalha	130-170	Menor, Frígio, i-bVI-bVII	Ostinato de cordas em colcheias/semicolcheias, stabs de metais, taiko/toms, pads de coral; [brass_synth], [reese_bass] híbrido
Aconchegante / vila / fazenda	85-110	Maior, acordes add9 e maj7	Nylon/pluck, e-piano, mallets, shaker leve; [nylon_pluck], [epiano], [mallet]
Synthwave / retro	90-118	Menor (Eólio/Dórico)	[supersaw] pads, [analog_bass] baixo em colcheias, [lead], caixa com gate, reverb grande
Chiptune (estilo NES)	120-180	Maior ou menor, arpejos rápidos para acordes	Exatamente 2 vozes [chip_pulse]/[chip_square], 1 baixo [chip_triangle], bateria [chip_noise]; sem reverb ou um mínimo; quantizado
Terror / tensão	50-80 ou sem pulso	Clusters cromáticos, trítonos, pedal	Drones [dark_pad], notas [bell] agudas esparsas, pulsos graves, silêncio como ferramenta
Ambiente / espaço	60-90	Lídio, acordes sus, mudanças lentas	[pad], [dark_pad], [bell], envios de reverb longos, automação de volume lenta
Lo-fi / chill	70-90, swing	ii7-V7-Imaj7, acordes m9	[epiano], bateria suave com swing 0.3-0.5, [saturator] e [filter] no master
Ação / EDM	120-150	Menor, four-on-the-floor	[drums] ou um kit, [reese_bass]/[analog_bass], arpejos [saw_pluck], leads [supersaw], automação de volume estilo sidechain
Puzzle / casual	100-130	Maior, notas de passagem cromáticas lúdicas	[mallet], [pluck], patches pizzicato, baixo staccato

6. Mixe e masterize

• Ganho de palco: comece as faixas em torno de -6 a -12 dB; a melodia fica no topo e os pads abaixo dela. O render relata níveis por faixa.
• Adicione um reverb compartilhado em um barramento (track_add("Reverb", kind="bus", fx=["builtin:reverb"]) ou um VST3 como ValhallaSupermassive com Mix em 100%) e envie para ele por faixa. Mais seco para música rápida ou movimentada, mais molhado para ambiente.
• Passe high-pass em tudo que não for baixo ou bumbo (builtin:eq hpf 100-200 Hz), corte 250-500 Hz nos pads se o relatório disser que está turvo.
• Panorâmica para largura (harpa esquerda, segundos violinos direita, chimbais ligeiramente fora do centro). Mantenha baixo e bumbo centrados.
• Loudness: o master é normalizado para target_lufs (padrão -16). Cues de fundo/menu geralmente ficam em -18 a -20; batalha em -14 a -16.
• Os efeitos VST3 do usuário (SSL, TDR Nova, Waves, Valhalla) podem ir em faixas, barramentos ou no master via fx_add; defina parâmetros pelo nome com texto de exibição ({"Mix": "100 %", "LowCut": "200 Hz"}).

7. Loop de revisão (sempre)

1. notes_read(faixa) para verificar suas linhas como TTN. analyze() dá verificações de tom/alcance/sobreposição/turvação mais um PNG do piano roll. Leia o PNG para verificar a forma, densidade e distribuição de registro.
2. render(). Aja em cada aviso: faixa silenciosa (nenhum patch carregado), turvação, topo abafado ou áspero, picos, limitador trabalhando muito, costura do loop. Faixas inalteradas são armazenadas em cache, então itere livremente.
3. listen(): seus ouvidos. Ele mede o áudio renderizado, não as notas, e captura o que as notas não mostram:
   • energy_arc, sections, bar_lufs: cada seção faz o que a forma diz? B deve diferir de A em nível, brilho, densidade ou quem lidera (tracks_db, most_present); construções sobem barra por barra; o último compasso do loop flui para o primeiro.
   • masking: vs_rest_db de cada faixa em sua banda principal. Mantenha o lead em 0 ou acima. Partes abaixo de cerca de -10 são mal ouvidas: levante-as, faça EQ-dip na faixa covered_by ali, mude o registro ou corte-as. pairs são partes lutando por uma banda (bumbo vs baixo em 63 Hz: deixe um dominar os graves, ou duck nele nos hits).
   • verify: renders de sonda de cada tom que cada parte usa. Eles mostram tons silenciosos ou muito mais quietos (fora do alcance do instrumento), partes que soam transpostas, ataques lentos em notas curtas, compassos com notas mas sem som (CC em 0?), e drum_notes: como cada nota de bateria realmente soa e quão alta é com velocidade igual. Confie neles acima de nomes de patches e descrições. Corrija, re-renderize, ouça novamente até que cada aviso seja corrigido ou deliberado. A primeira execução sonda-renderiza cada instrumento (segundos por faixa de plugin, armazenado em cache depois). reference="<arquivo>" compara a mixagem com uma faixa que o usuário deseja igualar.
4. Diga ao usuário o que você fez e como é construído (forma, tom, andamento, instrumentos, o motivo), dê o caminho do arquivo e ofereça play() ou o editor (ui_open()) para que ele ouça. Os ouvidos dele são o juiz final, então pergunte o que mudar.

8. Entregue

render(out="<jogo>/<diretório de áudio>/<nome>.<ogg|wav>", loop="auto"), combinando com as pastas e nomenclatura do projeto.

• Godot: .ogg. Defina Loop no dock de importação; para intro+loop use loop_offset = loop_start_sec do .loop.json.
• Unity: .ogg ou .wav. Flag Loop no AudioSource; intro+loop via dois clipes ou reprodução agendada usando .loop.json.
• Unreal: 16-bit 48 kHz .wav (bits=16); o WAV carrega um chunk de loop smpl.
• Web: .ogg mais .mp3. Use stems=True / layers=True para sistemas adaptativos e midi=True para entregar o arranjo a uma DAW (Cubase).

Notação TTN (para write)

D4:q!mf F4 A4:h | (D3 A3 F4):w | r:h C5:e. B4:s A4:q' G4:q> | E4:h~ E4:q r:q

Tom C4 = dó central (MIDI 60), F#3, Bb5, ou r para uma pausa. Acordes (C4 E4 G4). Durações w h q e s t (semínima até fusa), pontuada q., tercina e3, tempos 1.5 ou 3/2, somas h+e; pegajoso até mudar. Velocidade !pp !p !mp !mf !f !ff ou !0-127, pegajoso. ' staccato, > acento, ~ ligadura para o mesmo tom seguinte. | barra de compasso, verificada contra a assinatura de tempo (incompatibilidades voltam como avisos, então corrija-as). @6.5 move o cursor para o tempo 6,5 do intervalo escrito, para uma segunda voz em uma única chamada. Ou use mode="merge".

Tokens de padrão (para pattern): graus de acorde 1 3 5 7 9, 8 10 12 uma oitava acima, 5-/3+ mudanças de oitava, b7/#4 graus alterados acima da fundamental, . pausa, - segurar, 1> acento. Exemplo de baixos: "1 - - 1 . 1 5- ." (pop), "1 . 1 . 1 . 1 ." (colcheias, synthwave), "1 - 5- - 8 - 5- -" (sensação de walking). Arpejos: "1 5 8 10 12 10 8 5", "1 3 5 8" com taxa 0,25 para semicolcheias.