Auto-MIDI

Auto-MIDI é um pacote TypeScript experimental que gera música de fundo programaticamente para vídeos produzidos por IA. A saída é um MIDI General MIDI multitrilha acompanhado de um manifesto JSON verificável, com harmonia, estrutura métrica e cues sincronizadas.

A versão 0.2.0 introduz o algoritmo 3, com planejamento de frases, progressão completa antes da cadência e desempenho adequado a composições longas. O algoritmo 2 permanece selecionável e reproduz byte a byte as composições da versão 0.1.0.

Recursos

• Núcleo síncrono, determinístico, sem filesystem e compatível com Node.js e browser.
• Builds ESM e CommonJS, declarações TypeScript e CLI para Node.js.
• Presets ambient, lofi e upbeat.
• Tonalidade maior/menor, tônica, BPM, volume, seed e progressão em graus romanos.
• Trilhas separadas de harmonia, baixo, melodia e bateria.
• Frases determinísticas de quatro compassos com variações de motivo, baixo, comping e fills.
• Intro/corpo/outro conforme a duração e cadência final de um tempo na tônica.
• Cues no tick mais próximo, com articulação própria de cada preset.
• Manifesto com seções, batidas, cues e chordTimeline no algoritmo 3.
• Renderização opcional de prévias WAV/MP3 em scripts de desenvolvimento.

Requisitos e instalação

Node.js 22 ou mais recente é necessário para a API Node e o CLI:

npm install auto-midi

Para trabalhar no repositório:

git clone https://github.com/rnahumaf/Auto-MIDI.git
cd Auto-MIDI
npm install

As dependências de runtime são @tonejs/[email protected], para o modelo de eventos MIDI, e [email protected], para teoria musical.

API

import { writeFile } from "node:fs/promises";
import { generateMusic } from "auto-midi";

const result = generateMusic({
  durationSeconds: 30,
  style: "upbeat",
  tonic: "D",
  mode: "major",
  progression: ["I", "V", "vi", "IV"],
  bpm: 120,
  volume: 0.72,
  seed: "release-video-v3",
  cues: [
    { id: "feature-1", timeSeconds: 6.4, intensity: 0.8 },
    { id: "cta", timeSeconds: 23.75, intensity: 1 }
  ]
});

await writeFile("output/video.mid", result.midi);
await writeFile("output/video.json", JSON.stringify(result.manifest, null, 2));

generateMusic() retorna { midi: Uint8Array, manifest }. Quando seed é omitida, o gerador cria uma e a registra no manifesto. IDs explícitos de cues devem ser únicos.

O algoritmo 3 é o padrão. Sua chordTimeline informa símbolo, início e fim em ticks e segundos, além de source: "progression" | "cadence". A progressão percorre todos os graus; somente o último tempo é reservado para a resolução na tônica. Durações menores que um tempo usam a tônica em toda a música.

Reproduzir o algoritmo anterior

Quem depende dos bytes produzidos no 0.1.0 deve fixar a versão do algoritmo junto da seed:

const legacy = generateMusic({
  durationSeconds: 30,
  style: "lofi",
  seed: "projeto-existente",
  algorithmVersion: 2
});

O manifesto do algoritmo 2 continua com o formato anterior e omite chordTimeline. Novos projetos devem usar o padrão 3.

volume controla CC7 nas quatro trilhas; velocities preservam a dinâmica do arranjo. Graus romanos minúsculos isolados, como vi, são normalizados para acordes menores. Sufixos como m7, 7 e Maj7 podem ser explícitos.

CLI

auto-midi generate --config examples/app-demo.json --out output/app-demo
auto-midi generate --config examples/app-demo.json --out output/legado --algorithm-version 2
auto-midi --version
auto-midi --help

O comando grava <prefixo>.mid e <prefixo>.json por arquivos temporários no diretório de destino, evitando deixar apenas metade do par em uma falha. --algorithm-version substitui o valor do JSON.

Limites e validação

• Duração: positiva e no máximo 3.600 segundos.
• BPM: 30 a 300; volume e intensidade: 0 a 1.
• Até 1.000 cues, 64 graus na progressão, seed com 256 caracteres, ID com 128 e grau com 32.
• Uma cue é arredondada ao tick mais próximo. Na fronteira final, ela é limitada ao tick anterior.
• MIDI não fixa o timbre final; o resultado depende do sintetizador e do SoundFont usados pelo consumidor.

Browser

O entry point principal não usa filesystem nem APIs nativas do Node. O CI empacota o build ESM para platform: "browser" e executa uma geração de fumaça. O CLI e os scripts de prévia continuam exclusivos de Node.js.

Desenvolvimento

npm run typecheck       # valida TypeScript 7
npm test                # testes musicais, regressão e bundle browser
npm run test:package    # instala o tarball e testa ESM, CJS e CLI
npm run benchmark       # benchmark manual de uma hora
npm run demo            # gera MIDI e manifesto de exemplo
npm run preview:demo    # gera nove prévias WAV/MP3 locais
npm run validate:skills # quick_validate.py nas três skills
npm run pack:check      # inspeciona o pacote npm

O GitHub Actions executa a matriz Windows/Ubuntu com Node.js 22, 24 e 26.

Prévias de áudio

A renderização não integra a API pública. scripts/render-preview.mjs usa spessasynth_core somente em desenvolvimento e um SoundFont fornecido por download explícito:

npm run preview:setup
npm run preview:demo

O GeneralUser GS fica no diretório ignorado output/, validado por SHA-256 e nunca entra no pacote. MP3 requer FFmpeg no PATH. Veja docs/PREVIEW_RENDERING.md.

Documentação

• Histórico e migração
• Contexto de produto
• Contrato de agentes
• Estrutura musical
• Arranjos MIDI
• Sincronização de cues

Licença

MIT. Consulte LICENSE.