EditAtlas/diseño-sonoro

Diseño sonoro: sonidos reales sobre un vídeo terminado

El objetivo: que la película suene como si un editor con una buena biblioteca la hubiera montado. Cada sonido es un archivo real de EditAtlas, colocado en un fotograma que has mirado, con un nivel que puedes justificar con números.

Dos cosas son ciertas durante todo el proceso, así que planifícalas:

• No puedes oír. Seleccionas sonidos por sus descripciones y números medidos (sounds.py info), verificas la colocación y los niveles con check.py, y entregas a la persona una lista breve de momentos para que escuche. Nunca digas que un sonido "suena bien"; di lo que se midió y qué necesita aún oídos.
• No debes inventar. Trabaja únicamente sobre el vídeo que te dieron. Si no hay vídeo, pídelo. Si un momento necesita un sonido que la biblioteca no tiene, déjalo en silencio y menciónalo en el informe.

Todos los scripts están en scripts/ (Python 3.9+, numpy, Pillow para las láminas de fotogramas, FFmpeg con ffprobe en PATH). Ejecútalos con la ruta de la carpeta de la habilidad, desde una carpeta de trabajo propia (work/, result/); nunca escribas dentro del proyecto de la persona ni en esta carpeta de la habilidad.

python SKILL/scripts/moments.py FILM.mp4 --out work/moments             # moments.json, sheet.png, overview.png
python SKILL/scripts/moments.py FILM.mp4 --at 10.4 --out work/at        # fotogramas cada 0.1 s alrededor de un instante
python SKILL/scripts/sounds.py search "glass clink" --max-dur 2        # ids del índice público
python SKILL/scripts/sounds.py info sfx-ID sfx-ID                       # descarga única, SHA-256, números medidos
python SKILL/scripts/sounds.py sheet sfx-ID sfx-ID --out work/c.png     # forma de onda + espectrograma de candidatos
python SKILL/scripts/mix.py work/cues.json --out result/FILM_sfx.mp4    # MP4 + _track.wav + _resolved.json
python SKILL/scripts/check.py result/FILM_sfx_resolved.json --moments work/moments/moments.json --listen-out result/listen.wav

Los sonidos provienen de https://raw.githubusercontent.com/EditAtlas/sfx/main/ y se almacenan en caché en ~/.cache/editatlas-sfx (EDITATLAS_SFX_CACHE lo cambia). Con un clon local de EditAtlas/sfx, pasa --mirror PATH (antes del subcomando de sounds.py) y no se descarga nada.

1. Mira la película y su sonido

Ejecuta moments.py. Informa del audio existente (has_audio, LUFS, cuánto de él es silencio) y encuentra tres tipos de momento a partir de diferencias de píxeles: cut (corte de escena), move (movimiento que comienza o alcanza su punto máximo), land (el movimiento se detiene: algo se asienta). Luego abre overview.png y sheet.png con la herramienta de lectura: los números pasan por alto la animación suave (una insignia que se escala sobre un rostro estático no genera un corte) y reportan en exceso el movimiento de cámara. Cuando sea necesario, dibuja los fotogramas alrededor de un instante con --at T y encuentra el fotograma exacto donde la cosa aparece, aterriza o gira.

Decide qué hacer con el audio propio de la película:

Lo que ves en los números y observas	Hoja de pauta
Sin audio, o silent_share cerca de 1	"keep_audio": false: los sonidos llevan la película; se lleva a aproximadamente -16 LUFS
Solo música	"keep_audio": true: los sonidos se sitúan unos 3 LU por debajo; pon acentos en el ritmo cuando puedas
Alguien hablando (subtítulos, un rostro, un lavalier)	"keep_audio": true, "under_voice": true: aproximadamente 8 LU por debajo de la voz; menos sonidos y más ligeros
Pitidos sintetizados ya mezclados	pregunta: reemplazarlos necesita las pistas separadas; superponer sonidos reales los duplica

Pregunta a la persona cuando no esté claro si conservar el audio de la película.

2. Escribe la lista de eventos a partir de lo que viste

Una línea por momento que merezca sonido: tiempo, qué ocurre, qué tipo de sonido. Piensa como un editor:

• Una cosa que aparece (insignia, chip, botón, tarjeta de título): un pop corto, tic o campanilla suave, anchor: start.
• Una cosa que se mueve a través o una transición: un whoosh cuyo punto más fuerte coincide con la llegada, anchor: peak.
• Una cosa que aterriza con peso (logotipo, producto, sello): un impacto o golpe en el fotograma donde se detiene, anchor: peak.
• Un objeto real en pantalla (vaso, hielo, papel, llaves, una bebida): el foley correspondiente, no un sonido de interfaz.
• Estados de éxito / error: un ding para acierto, un zumbador o alerta corto para error. Una familia de sonidos de interfaz por película.
• Algo que se acumula: un riser cuyo final coincide con el clímax, anchor: end.

No todo movimiento necesita un sonido. El ritmo y el gusto con números están en references/taste.md; léelo antes de la primera hoja de pauta de una sesión.

3. Elige sonidos: lee, mide, compara

1. Busca. Si el MCP de EditAtlas está conectado, search_sfx clasifica mejor (también entiende vietnamita); de lo contrario, sounds.py search. Los títulos evitan a propósito las palabras de sus archivos fuente ("camera shutter" es "Lens Aperture Tick"), así que busca por lo que es el sonido y prueba sinónimos y el filtro de categoría.
2. sounds.py info sobre 2–4 candidatos. Lee: audible_s (cuánto se oye realmente; el archivo puede ser más largo), attack_s (0.0x = aparece de golpe, 0.3+ = crece), peak_t_s, centroid_hz (por debajo de ~1500 oscuro, por encima de ~6000 brillante), mono_loss_db (por debajo de -6 los canales se cancelan en un teléfono; mix.py reproduce entonces el canal más fuerte).
3. sounds.py sheet cuando dos candidatos se leen igual: una línea vertical marcada es un clic, una mancha es un whoosh, la energía en la parte inferior es peso.
4. Elige por lo que se mueve y lo que toca, luego por duración: un pop de chip de 0.3 s no debe ser un pop de dibujo animado de 1.8 s. Usa max_len para recortar un archivo largo, con un fundido.
5. Momentos repetidos de un mismo tipo (tres chips) quieren tomas diferentes de una misma familia (Tiny Plop 05, 06, Empty Plop 06), no el mismo archivo tres veces.

La biblioteca es escasa en algunos lugares (medido el 2026-11-07): no hay vertido de líquido ni efervescencia, no hay tono de ambiente, no hay sello, pocas gotas de agua y golpes sordos. Elige el sonido honesto más cercano y nombra el vacío en el informe en lugar de forzar uno incorrecto.

4. Escribe la hoja de pauta y renderiza

{
  "video": "work/film.mp4",
  "keep_audio": false,
  "under_voice": false,
  "cues": [
    {"t": 0.30, "id": "sfx-988dafbd36", "role": "whoosh", "label": "title lands"},
    {"t": 0.62, "id": "sfx-mi630472",  "role": "foley", "anchor": "start", "max_len": 0.9, "gain_db": -2, "label": "ice into glass"},
    {"t": 8.30, "id": "sfx-fs339114",  "role": "hit", "label": "bottle lands"},
    {"t": 0.00, "id": "sfx-c7d271e90f", "role": "ambience", "bed": true}
  ]
}

• t es el fotograma del momento en segundos. role establece el nivel y el ancla por defecto (references/taste.md).
• anchor: start coloca el inicio audible en t, peak el punto más fuerte, end el final audible.
• Por pauta: gain_db (relativo al nivel del rol), max_len, fade_in, fade_out, offset_in, pan (-1..1).
• "bed": true: un ambiente largo y estable bajo toda la película a -54 dBFS (apenas audible). Solo para películas cuyo sonido son solo efectos especiales; nunca bajo voz o música. Se entremezcla consigo mismo si la película es más larga.

Ejecuta mix.py. Imprime cada sonido con su tiempo de aterrizaje y nivel máximo, y anota cuando un momento fue tan temprano que el sonido tuvo que empezar dentro de su archivo.

5. Verifica, corrige, vuelve a verificar

Ejecuta check.py después de cada renderizado; el código de salida 1 significa que marcó algo. Lee las pistas WAV que mix.py escribió junto a _resolved.json, así que mantén esos archivos juntos cuando copies los resultados. Encuentra cada sonido en la pista renderizada por su propia forma de onda, por lo que la sync es real: cualquier desviación de más de un fotograma es un error en la hoja de pauta. También mide los gestos por cada 10 s, el silencio más largo, los impactos fuertes, las repeticiones, el silencio digital, el volumen maestro y el pico verdadero, la reducción a mono, y cuántos momentos visuales fuertes recibieron un sonido.

Para cada indicación, o bien arréglala (añade un sonido al silencio, cambia una repetición, mueve una pauta) o decide que está bien y explica por qué en el informe ("el silencio de 7.8 s es un tramo de diálogo, la voz lo lleva"). Las notas sobre ataques lentos son pistas: si el momento es el pico del sonido, cambia esa pauta a anchor: peak. Dos o tres rondas son normales.

6. Entrega

Entrega a la persona:

1. FILM_sfx.mp4 y FILM_sfx_track.wav (solo los sonidos, longitud completa, para colocar debajo de su propia edición).
2. Una tabla breve: tiempo, momento, título e id del sonido, por qué ese sonido.
3. Los números de check.py (ritmo, silencio más largo, LUFS, pico verdadero) y qué significa cada indicación restante.
4. La lista de escucha (listen.wav corta esos momentos en un solo archivo): "escucha con auriculares y una vez en un teléfono".
5. Los vacíos: momentos dejados en silencio y sonidos que la biblioteca no tenía.

Escribe el informe en el idioma de la persona. No afirmes que escuchaste.

Opcional: el motor real-sfx

La habilidad real-sfx de Clipwing (scripts MIT, por Alexander Korbanov) hace el mismo trabajo con un motor más pesado: listas de pautas con tipos, eliminación de capas sintéticas, rejillas de ritmo, una crítica de 9 ejes. Puede usar toda la biblioteca EditAtlas como su paquete principal. Consulta references/real-sfx.md para el adaptador y lo que se verificó.