Music Tracker

El Music Tracker de JARU IDE es el editor integrado para crear música secuenciada dentro de un proyecto JARU. Está pensado para música chiptune, melodías de juegos, intros, menús, demos y pequeños efectos musicales que después pueden reproducirse desde las VMs de JARU usando el módulo Sound.

En lugar de trabajar con una pista de audio cerrada como MP3 u OGG, el tracker guarda notas, instrumentos, tempo, volumen y comandos en un formato editable. Durante el build, JARU IDE compila ese recurso a un fichero binario compacto que la VM puede cargar y reproducir.

Flujo de trabajo

El flujo completo del Music Tracker es:

Music Tracker de JARU IDE
  -> guarda Music/*.jms
  -> Resource Builder compila la canción
  -> genera Build/flash/Music/*.jmu
  -> la VM reproduce el .jmu con Sound.loadMusic()

Esto permite tratar la música como un recurso del proyecto, igual que imágenes, sprites, mapas o código fuente. El usuario edita la canción visualmente desde el IDE y el sistema de build se encarga de convertirla al formato que entiende la VM.

Formato editable .jms

Los ficheros .jms son los recursos musicales editables del proyecto. Internamente guardan la canción como datos de tracker: configuración global, instrumentos y filas.

Un .jms contiene información como:

• format: identifica el recurso como canción de tracker.
• tickMs: duración base del tick musical.
• volume: volumen global inicial.
• loop: indica si la canción debe repetirse.
• loopStartRow: fila desde la que empieza el bucle.
• rowTicks: duración por defecto de cada fila.
• instruments: lista de instrumentos chiptune.
• rows: filas con notas, instrumentos, volumen, silencios y comandos.

Ejemplo simplificado:

{
  "version": 1,
  "format": "tracker",
  "tickMs": 72,
  "volume": 185,
  "loop": true,
  "loopStartRow": 0,
  "rowTicks": 8,
  "instruments": [
    { "id": 0, "name": "Pulse", "type": "tone", "wave": "pulse", "volume": 154, "duty": 18 },
    { "id": 3, "name": "Snare", "type": "noise", "noiseMode": "white", "volume": 113, "decayTicks": 3 }
  ],
  "rows": [
    { "ch0": { "note": 60, "inst": 0 }, "cmd": { "type": "tempo", "tickMs": 72 } },
    { "noise": { "period": 5, "inst": 3 } },
    { "cmd": { "type": "end" } }
  ]
}

Normalmente el usuario no necesita editar este JSON a mano. JARU IDE lo carga, lo muestra como tracker y lo guarda desde la interfaz visual.

Exportación a .jmu

El formato .jmu es el resultado compilado de una canción JARU. Es un fichero binario compacto pensado para que la VM pueda reproducir música sin cargar un editor ni procesar el JSON original.

Durante el build:

• JARU IDE localiza los recursos de música del proyecto.
• El compilador de música lee los .jms.
• Valida filas, canales, instrumentos y comandos.
• Escribe los datos musicales en .jmu.
• Copia el resultado a la carpeta de recursos generada, normalmente Build/flash/Music.

El fichero .jms es el formato de trabajo. El fichero .jmu es el formato de ejecución.

Filas, canales y comandos

La interfaz principal organiza la canción en filas. Cada fila puede contener información para varios canales:

• Canales tonales para melodía, bajo o armonía.
• Canal de ruido para percusión y efectos.
• Columna de comandos para tempo, final de canción, bucles u otros controles.

Las celdas pueden representar:

• Una nota musical, como C-4 o D#5.
• Un silencio o celda vacía, como ---.
• Un corte de nota, como OFF.
• Un instrumento asociado a la nota.
• Volumen por celda cuando se necesita ajustar la dinámica.
• Comandos globales de reproducción.

El editor también incluye controles de tempo, volumen, duración por fila y loop.

Importación MIDI

El importador MIDI permite convertir un fichero .mid o .midi en una canción editable por el tracker. No se trata de reproducir MIDI directamente, sino de adaptar el contenido musical a los canales, instrumentos y comandos de JARU.

El importador puede:

• Analizar canales y pistas MIDI.
• Cuantizar notas a la resolución del tracker.
• Asignar voces a canales tonales.
• Importar percusión como canal de ruido cuando sea posible.
• Incorporar cambios de tempo.
• Adaptar volumen, pitch bend y modulación cuando encajan con el formato de JARU.

Después de importar, la canción queda como recurso .jms, por lo que puede editarse, retocarse y compilarse igual que una canción creada desde cero.

Editor de instrumentos

El Music Tracker incluye un editor de instrumentos chiptune. Los instrumentos definen cómo suenan las notas del tracker.

Los instrumentos pueden configurar:

• Tipo: tone o noise.
• Forma de onda: square, triangle, saw, pulse o sine.
• Volumen.
• Duty para sonidos de pulso.
• Envolvente ADSR: ataque, decay, sustain y release.
• Vibrato LFO: profundidad, velocidad y retardo.
• Parámetros de ruido para percusión o efectos.

El editor incluye previsualización para probar el sonido antes de usarlo en la canción.

Reproducción con Sound.loadMusic

Una vez compilada, la canción puede reproducirse desde código JARU con el módulo Sound:

use Sound

Sound.init()

if (Sound.loadMusic("Music/theme.jmu")) then
    Sound.playMusic(true)
end

También se puede controlar la reproducción con funciones como:

• Sound.playMusic(loop)
• Sound.pauseMusic()
• Sound.resumeMusic()
• Sound.stopMusic()
• Sound.seekMusic(ms)
• Sound.unloadMusic()

Para más detalle sobre el runtime de audio, consulta la referencia del módulo Sound.

Limitaciones actuales

El Music Tracker está en desarrollo y todavía puede cambiar. Las limitaciones principales son:

• El formato .jms está pensado como formato editable interno de JARU IDE.
• La importación MIDI es una conversión aproximada, no una reproducción MIDI completa.
• La música secuenciada usa el formato .jmu; no reemplaza el uso de audio PCM cuando se necesitan samples.
• La calidad del resultado MIDI depende de la complejidad de la canción original y de cómo se asignen sus canales al tracker.
• Algunas opciones de instrumentos, comandos o ergonomía del editor pueden evolucionar en próximas versiones.

La intención es que el Music Tracker sea una herramienta práctica para crear música ligera, editable y portable dentro del ecosistema JARU.