Editor de Audio#

El Editor de Audio es la herramienta de autoría para cada asset de música, ambiente, SFX y voz del proyecto. Un asset de audio es un archivo: el runtime resuelve un id directamente a una ruta por convención (resolveMusic/resolveAmbient/resolveSfx en shell/audio.js), y no hay ningún registro que decida qué sonidos existen. Sí existe un registro pequeño y opcional — projects/<id>/audio.json — pero sólo anota cómo reproducir un sample (puntos de loop, fades); nunca decide qué existe, y un proyecto sin él se comporta exactamente como siempre. Ver Marcas de loop. Los tokens de efecto MUSIC/SOUND/STOPMUSIC y el track SCENEAUDIO de una escena (cubierto en la página del Orquestador de Escenas) pasan todos por esos mismos resolvers — todo el trabajo de este editor es producir archivos bien formados en una ruta que alguno de ellos pueda encontrar, nada más (ver la nota de cierre para una brecha real entre dónde escribe este editor y dónde resuelve de verdad un id simple). Esos tokens (y AMBIENCE/VOICE) también llevan su propio volumen, panorama estéreo y — para música y ambiente — loop con crossfade opcionales, editables como mini-perillas directamente sobre el token en los editores de efectos; esa sintaxis está cubierta completa en la referencia de tokens de efecto, no acá.

Llegas a él desde el Hub (con el dev server corriendo). El panel izquierdo elige un archivo fuente — filtrable por categoría (Todos / Música / SFX / Ambiente / Voz) — con controles de reproducción y acciones de Mover / Eliminar / Verificar refs debajo. El área central de rack es la cadena de efectos. Una barra de exportación en la parte inferior escribe el resultado procesado de vuelta al proyecto.

El rack de efectos Pedalboard#

El rack es una cadena de pedales (nodos de efecto) aplicados en orden, de izquierda a derecha, sobre el archivo fuente seleccionado. La cadena se dibuja como un camino de señal real — un nodo IN, una flecha hacia tu primer pedal, una flecha al siguiente, y así hasta OUT — así el orden de procesamiento siempre es visible de un vistazo. Cada pedal es uno de diez tipos — HighpassFilter, LowpassFilter, Distortion, Compressor, Gain, Reverb, Delay, PitchShift, Chorus, Convolution (este último toma una ruta absoluta a un WAV de respuesta al impulso como archivo IR) — cada uno con sus propios parámetros tipados (frecuencia de corte, drive, umbral/ratio/ataque/release, tamaño de sala/amortiguamiento/mojado/seco, tiempo de retardo/feedback/mix, semitonos, etc.). Los pedales se pueden desactivar individualmente sin quitarlos de la cadena, y guardar/recargar como presets con nombre (GET /api/audio-presets, respaldado por tools/audio_fx/presets.py — radio_am, telephone, clean vienen como punto de partida).

Las cadenas largas se desplazan hacia los costados — agarra cualquier zona vacía del fondo del rack y arrastra para desplazarte, sin tener que ir a cazar la barra de scroll. Hay dos formas de reordenar pedales:

• Arrastrar un pedal por su encabezado para levantarlo y soltarlo en otro punto de la cadena; una tarjeta fantasma sigue tu puntero y la posición de destino se resalta mientras te mueves.
• Re-empalmar desde un conector. Agarra la punta de flecha entre dos pedales y arrástrala hasta otro pedal — ese pedal salta a ocupar la posición de la flecha, y el resto de la cadena se re-enlaza solo alrededor del hueco que deja. Es una forma rápida de decir "haz pasar la señal por este pedal, acá" sin tener que arrastrar el pedal en sí por todo el rack.

Ambos gestos desplazan el rack automáticamente cuando arrastras cerca de sus bordes, y soltar en un punto inválido (el mismo pedal ya presente, o espacio vacío) simplemente vuelve todo a su lugar — no cambia nada.

El procesamiento es del lado del servidor, no Web Audio — la UI del rack es un espejo del DSP real, no el DSP en sí. PLUGIN_DEFS en audio-editor.html se mantiene deliberadamente sincronizado con PLUGIN_MAP en tools/audio_fx/chain.py; el navegador solo serializa la cadena a JSON y la envía. El procesamiento de audio real corre a través de la librería Pedalboard de Spotify en un venv de Python dedicado (C:\Users\alex_\musicgen-env\Scripts\python.exe — no el Python del sistema), invocado por dev_server.py como tools.audio_fx process --in <archivo> --chain <json> --out <wav>. Procesar y escuchar hace POST a /api/audio-process, escribe un WAV de vista previa temporal bajo .tmp/audio_fx/ (ignorado por git), y permite hacer A/B entre A: procesado y B: original en el mismo reproductor <audio>. El arranque en frío (primera llamada a Pedalboard) puede tardar 5-15 segundos — la UI muestra un contador de tiempo transcurrido y una pista después de 6s, y se rinde con un mensaje de timeout pasados los 100s.

Editor de onda (ediciones previas a la cadena)#

Un panel colapsable de Onda decodifica el archivo fuente en samples crudos (vía el AudioContext del navegador) y dibuja una forma de onda sobre la que se puede arrastrar para seleccionar. Seis operaciones se aplican a la selección: fade in, fade out, recortar a la selección, borrar selección, silenciar, reverse, más un normalizar de todo el buffer (pico a -0.1 dBFS) que ignora la selección. Cada operación se agrega a una lista de ediciones ordenada en vez de mutar el audio en el lugar — deshacer simplemente saca el último elemento de la lista y la reproduce de nuevo desde la decodificación original. Este replay está deliberadamente espejado en ambos lados: el redibujado en vivo del navegador usa una implementación JS, y el tools/audio_fx/edits.py del lado del servidor (apply_edits(), numpy puro) es el gemelo exacto-a-byte que realmente corre al procesar/exportar — su docstring de módulo dice directamente que hay que mantener a los dos sincronizados. Las ediciones siempre corren antes de la cadena de efectos (las ediciones reforman la línea de tiempo — recortar/borrar cambian la cantidad de samples — así que parámetros de pedal como los segundos de un Delay siguen siendo significativos contra el buffer post-edición). Las ediciones de onda son por archivo: cambiar a otra fuente con ediciones sin guardar pide primero una confirmación de descarte. La cadena de pedales, en cambio, persiste entre archivos por diseño, así que nunca está en riesgo cuando cambias de fuente.

Zoom y navegación#

Colocar un punto de loop es un trabajo a nivel de muestra, y con el archivo entero a la vista un píxel de un track de tres minutos son varios cientos de muestras. Rueda para hacer zoom en el cursor, ⇧rueda o alt+arrastrar para desplazarte, y los botones − / + / Zoom sel. / Todo hacen lo mismo con una lectura del rango visible. Si arrastras una selección más allá del borde del canvas, la vista se desplaza sola, así que una selección puede seguir siendo más larga que lo que cabe en pantalla.

Pasados unos dos píxeles por muestra la vista cambia de columnas de picos a las muestras reales unidas por una línea (con un punto por muestra cuando hay lugar) — un cruce por cero tiene que verse como un cruce si vas a poner un punto de loop encima.

La franja fina debajo del canvas es la vista general: el archivo entero, siempre, con todo lo que queda fuera de la ventana actual oscurecido y la región de loop teñida. Haz clic o arrastra ahí para mover la vista. Todavía no hay zoom vertical (de amplitud), así que un tramo muy bajito se sigue viendo plano por más que te acerques — de eso se está encargando el salto automático al cruce por cero.

Marcas de loop#

Todo lo de arriba reescribe las muestras. Esta fila — la franja debajo de la barra de edición, marcada LOOP — hace lo contrario: escribe sólo projects/<id>/audio.json, nunca el wav. Es la forma de decir "este clip arranca en 0.4 s y loopea entre 1.24 s y 8.75 s" sin cortar el archivo, así que después puedes cambiar de opinión.

Por sample puedes fijar un offset de inicio, un modo de loop (One-shot / Continuo / Ping-pong), los puntos de loop y fade in / fade out. Arrastra una selección y pulsa Loop = selección para promoverla a región de loop, o arrastra directamente los tiradores S / A / B sobre la onda. Al soltar, los marcadores saltan al cruce por cero más cercano — ese salto es la diferencia entre un loop que chasquea y uno que no. ▶ Loop previsualiza exactamente lo que hará el runtime, ping-pong incluido.

El runtime mezcla esto con lo que haya pedido el punto de uso, y el punto de uso siempre gana:

default del motor  <  audio.json  <  descriptor de sala/escena  <  la cola del token

Ausentes a propósito: volumen y paneo. Eso es del token (|vol=, |pan=) y de los sliders de bus del jugador. Una segunda autoridad de volumen peleándose con ésos es una fábrica de bugs — si un sample suena simplemente muy fuerte, normalízalo y hornéalo.

Un sample marcado Continuo o Ping-pong sigue sonando hasta que algo lo pare, y para eso está el token STOPSOUND:<id>. Ojo: un SFX en loop arrancado por una regla no sobrevive a un guardar/cargar — el ambiente de sala sí, porque el descriptor de la sala lo vuelve a disparar al entrar.

Las marcas son sólo para WAV, y se hace cumplir. Carga un MP3 o un OGG y toda la franja LOOP se apaga, con el motivo en el badge: exporta a WAV primero, o carga el sonido en formato WAV original. No es una preferencia. Un contenedor con pérdida no puede honrar una marca exacta a nivel de muestra ni en principio — los codificadores meten un delay de priming al inicio y rellenan el final, y los decodificadores no recortan eso igual — así que unos puntos que cuadran perfecto en este editor derivan en el juego, sin nada en el archivo del proyecto que lo explique. El servidor se niega a guardar una entrada así, y el runtime ignora la que haya entrado por otra vía. En el port de Godot existe la misma frontera por el otro lado: sólo AudioStreamWAV tiene inicio/fin de loop y ping-pong.

Un archivo marcado antes de que existiera esta regla sigue mostrando sus marcas y todavía se puede limpiar: pulsa Quitar marcas y después Guardar marcas — guardar desde una fuente bloqueada es la vía de limpieza, y te dice cuántas entradas no-WAV descartó.

Las marcas describen el archivo en disco. Mientras tengas ediciones de onda sin aplicar, el canvas muestra una línea de tiempo que todavía no existe en disco, así que la edición de marcas se deshabilita y los marcadores se ocultan — si no, los estarías poniendo sobre audio al que no se refieren. Guarda (o resetea) las ediciones y vuelven a cuadrar.

Exportar → OGG vía el normalizador#

Procesar y escuchar es una vista previa no destructiva. Exportar es lo que realmente escribe en el proyecto: eliges un formato (WAV, OGG o MP3), una carpeta destino (music / ambience / sfx — bajo el árbol canónico assets/audio/<tipo>/), y un nombre de salida, y entonces /api/audio-export hace el trabajo real. Si no hay ningún pedal activo y ninguna edición de onda, exportar toma un atajo de passthrough (una copia directa de archivo — sin ida y vuelta al venv). De lo contrario corre el mismo paso tools.audio_fx process usado para la vista previa (ediciones, después cadena) hacia un WAV temporal, y:

• El formato WAV copia ese archivo temporal directamente a assets/audio/<tipo>/<nombre>.wav.
• Los formatos OGG y MP3 le pasan el WAV temporal a tools/audio_normalizer — el único camino de codificación del proyecto (una herramienta Python separada, solo stdlib, impulsada por ffmpeg, documentada en tools/audio_normalizer/README.md). OGG elige el preset ambient (Vorbis -q:a 4, ~128kbps) para el destino ambience y el preset music (Vorbis -q:a 5, ~160kbps) para todo lo demás; MP3 usa siempre music_mp3 (libmp3lame VBR, ~165kbps), porque no hay un preset MP3 específico para ambiente. En ambos casos la salida del normalizador (basada en el stem del archivo) se renombra después al nombre que elegiste.

MP3 está por una razón concreta: resolveMusic() le pone .mp3 por defecto a los ids pelados y los proyectos reales tienen su música en ese formato, así que exportar a OGG cambia en silencio la extensión que toda referencia tendría que seguir. No es el formato al que ir para material nuevo — Vorbis pesa menos con la misma calidad. Que OGG y MP3 estén disponibles depende de tu build de ffmpeg (libvorbis, libmp3lame); el editor consulta al arrancar y apaga el formato que no puede producir, nombrando el encoder que falta en el tooltip.

Guardar sobre el original#

Exportar siempre acuña un archivo nuevo, y eso tiene una consecuencia que conviene decir sin vueltas: todas las referencias del proyecto siguen apuntando al original sin editar. Recortas un tema, lo exportas, y el juego sigue reproduciendo la versión sin recortar — el archivo editado nace huérfano salvo que vayas a re-apuntar cada referencia a mano.

Guardar sobre el original resuelve eso. Hornea lo mismo que exportaría (la cadena de pedales y las ediciones de onda, en ese orden) directo en el archivo fuente, conservando su ruta y su extensión. No hay nada que re-apuntar, porque nada se movió.

Es destructivo, así que pregunta antes — y el confirm dice qué estás cambiando:

• el archivo exacto que se reemplaza y qué se hornea (cuántos pedales, cuántas ediciones);
• el cambio de duración, cuando lo hay. Este es el punto que vale la pena leer: un recorte acorta el clip, y las escenas o cutscenes timadas contra él pueden desincronizarse;
• un aviso de pérdida de generación si la fuente es con pérdida (.ogg, .mp3), porque re-codificar cuesta calidad que una copia WAV no cuesta;
• que el deshacer vive solo hasta que recargues.

Se guarda una copia previa en .tmp/audio_fx/backup/ (fuera de assets/, así que no aparece ni en el selector de archivos ni en git status), y Deshacer guardado la restaura como copia pura de bytes — sin re-codificar, así que recuperas los bytes originales y no una tercera generación. Ese deshacer es una comodidad de la sesión, no una red de seguridad: commitea lo que te importe antes de pisarlo.

Qué formatos se pueden guardar en el lugar depende de tu build de ffmpeg, no de una lista fija. WAV no necesita encoder (el archivo procesado ya es WAV), OGG necesita libvorbis y MP3 necesita libmp3lame; el editor consulta /api/audio-caps al arrancar y deshabilita el botón con el motivo en el tooltip cuando falta alguno. MP3 está soportado justamente porque los proyectos reales tienen su música en .mp3 (y resolveMusic le pone esa extensión por defecto a los ids pelados) — sin él, el botón estaría apagado exactamente en los archivos que más se editan. .flac, .m4a y .aac quedan solo para exportar: las necesidades de AAC de Apple ya se resuelven automáticamente al exportar, y FLAC es un formato de archivo maestro, no de distribución.

El destino SFX siempre se exporta en mono; el propio preset sfx del normalizador (WAV PCM mono, siguiendo la convención de resolveSfx) se usa cuando archivos crudos se convierten fuera de este flujo vía el propio CLI del normalizador — la opción OGG de la barra de exportación apunta en realidad a música/ambiente, ya que los one-shots de SFX son convencionalmente WAV para latencia de decodificación cero.

Panel MusicGen#

Un panel colapsable de MusicGen genera música original localmente vía el modelo MusicGen de Meta (small/medium, presets de duración de 5-30s, un slider de temperatura, y un modo opcional de melodía que condiciona la generación al archivo fuente actualmente cargado). La generación es asíncrona — se sondea un id de trabajo cada 2s hasta terminar — y el primer uso de un modelo dado dispara el gate compartido de consentimiento de descarga de modelo del proyecto (pesos de varios gigabytes, advertencia única) antes de descargar nada. Las generaciones terminadas se listan a la derecha con acciones de reproducir/importar, aterrizando de vuelta en el mismo árbol assets/audio/ una vez importadas. Cada generación también tiene un botón para eliminarla, útil para limpiar tomas de prueba que no quieres conservar — pide confirmación antes de borrar el archivo.

Gestión de archivos#

Más allá de la autoría, la barra de acciones del panel lateral cubre el mantenimiento de assets: Verificar refs escanea el proyecto en busca de cualquier cosa que apunte al archivo seleccionado antes de tocarlo; Mover reubica un archivo entre carpetas de categoría (bloqueado si se encuentran referencias — mover un archivo referenciado lo rompería silenciosamente, el mismo riesgo que eliminarlo); Eliminar requiere la misma verificación de refs limpia antes de armar un botón de confirmación. Un modal de Importar copia un archivo crudo directamente al árbol canónico assets/audio/<tipo>/ sin ninguna conversión — el camino del normalizador es solo para el flujo de rack de efectos/exportación, no para meter material fuente crudo al proyecto en primer lugar.

Modo Voice FX#

El rack también corre embebido: lanzado con ?voicefx=1&input=<toma>&char=&line=&lang=&take= (parámetros de query provistos por el flujo de grabación de tomas en otra parte de la suite de editores), oculta el selector de archivo y los controles de exportación, carga la toma dada directamente en la cadena, y redirige Exportar a /api/voice/apply-fx — horneando la cadena sobre esa línea de voz como una nueva toma en vez de escribir un asset genérico de música/ambiente/sfx. El mismo rack, los mismos pedales, un destino de guardado distinto.

Flujo de trabajo#

1. Elige un archivo fuente del panel lateral (filtrado por categoría), o genera uno nuevo vía MusicGen.
2. Construye una cadena de pedales — agrega pedales individualmente o carga un preset, ajusta parámetros, arrastra un pedal o re-empalma un conector para reordenar, desactiva cualquier pedal sin perder su configuración.
3. Opcionalmente abre primero el editor de onda y recorta/aplica fade/silencia/invierte/ normaliza la región que te interesa — las ediciones se aplican antes de la cadena.
4. Procesa y escucha, haz A/B contra el original hasta que suene bien.
5. Exporta: elige WAV u OGG, una carpeta destino, y un nombre — este es el paso que realmente escribe en assets/audio/<tipo>/.
6. Usa Verificar refs antes de Mover o Eliminar cualquier asset existente.

Un id simple resuelve a la carpeta legacy, no a donde este editor exporta — pero los pickers te ahorran la trampa. Exportar siempre aterriza en el árbol canónico más nuevo assets/audio/<tipo>/ (music/sfx/ambience/vox). Un id simple — sin / — todavía resuelve a la vieja usanza, contra el layout legacy plano: resolveMusic → assets/music/<id>, resolveAmbient → assets/ambient/<id>, resolveSfx → assets/sfx/<id>.wav, completando una extensión por defecto (.mp3 para música, .ogg para ambiente) solo cuando el id no trae una ya — los resolvers son conscientes de la extensión ahora, así que song.ogg se respeta tal cual. La vía de escape es cualquier valor que contenga /: se trata como ruta literal relativa al proyecto, saltándose la convención por completo. Eso es exactamente lo que los pickers de audio ahora guardan — el path completo del archivo, p. ej. assets/audio/music/<nombre>.ogg — así que cablear un MUSIC:/SOUND:/SCENEAUDIO a través de su picker llega directo a tu exportación fresca. La convención legacy de id simple solo muerde si tipeas a mano un stem y esperas que encuentre el árbol canónico: no lo hará. Elige el archivo (o tipea la ruta completa assets/audio/<tipo>/<nombre>.<ext>) y estás listo.