real-sfx

real-sfx: sonidos reales para un video en movimiento

El objetivo: que la película suene como si la hubiera montado una persona con una buena biblioteca de sonidos. Por lo tanto:

• El sonido nunca es sintetizado. Fuentes: las bibliotecas del usuario (config.json) y uisfx (un pack CC0 listo de sonidos de interfaz, en sí mismo sintetizado: la única excepción, solo para momentos de interfaz; "sin síntesis" lo desactiva: --ui library). Si no hay un sonido adecuado: el momento se queda en silencio y se incluye en el informe. Esto anula "sin pista: sintetizar" de motion-standards.
• No puedes oír. El sonido se lee como números, palabras e imágenes (references/listening.md). No presentes una selección como si la hubieras escuchado: di qué se verificó visualmente y mediante medición, y qué debe escuchar el usuario.
• Conserva la música y la voz cuando son esenciales para la película. El resultado es siempre un nuevo MP4 y una pista WAV separada.
• No dupliques. La síntesis horneada en el audio del render se reemplaza por los sonidos reales, no se superpone debajo de ellos (paso 1). La crítica mide esto como un número (el eje doubling).
• No modifiques el proyecto ni la carpeta de la habilidad. Coloca todos los archivos de trabajo en tu propia carpeta (work/, result/).

Dentro de Video Director

(Añadido en la copia de Video Director; no en el original de Clipwing. UPSTREAM.md enumera cada cambio.) Esta copia reside dentro de la habilidad Video Director y es ejecutada por su etapa de Sonido: ../references/sound-stage.md, "Ingeniería de sonido". Esos pasos deciden qué momentos reciben un sonido, proporcionan a esta habilidad solo esos (build/audio/sfx/events.json), fijan las grabaciones que el usuario eligió (sound_handoff.py pins), la ejecutan con --ui library, --no-loudnorm y sin capa de textura ni base, y toman solo la pista de efectos y las señales resueltas (sound_handoff.py collect). Síguelos, y lee este archivo solo para las opciones que ellos no cubren. Establece REAL_SFX_CONFIG, REAL_SFX_INDEX, REAL_SFX_TASTE, REAL_SFX_RATINGS, REAL_SFX_STEADY y REAL_SFX_STYLES como rutas bajo ~/.config/real-sfx/ (el plugin instala cada versión en una carpeta nueva, por lo que cualquier cosa escrita aquí se pierde en la siguiente actualización), y no uses --remember, que escribe en esta carpeta (también lo hace learn_style.py: copia un estilo aprendido en ~/.config/real-sfx/styles/).

Ruta rápida

Primero python scripts/setup.py check (ffmpeg, bibliotecas principal/extra, índice, uisfx) y python scripts/look.py FILM.mp4 --out work/look (fotogramas con tiempo + el sonido original debajo). Luego, según lo que tengas:

# 1. el proyecto tiene una lista de eventos (docs/cues.json, scripts/cues.json) O un script que sintetiza su sonido (audio.cjs)
python scripts/from_cues.py PROJECT_FOLDER|docs/cues.json --video RENDER.mp4 --out work/cues.json
# 2. grabación de pantalla sin lista: ui_events.py ... (references/screencast.md), luego from_cues.py work/ui/events.json
# 3. solo imagen:                    find_moments.py FILM.mp4 --out work/moments; suggest_cues.py work/moments/moments.json --out work/cues.json
# 3b. ANIMACIÓN SUAVE COLOREADA sin lista (vista previa de UI, ilustración, gráficos en movimiento): la automatización detecta 5-6 movimientos de 40.
#     paso 2, "Animación silenciosa sin lista": find_moments.py FILM --out work/moments --fine; look.py FILM --at T --span 2.4
#     --step 0.1 --out work/at.png; TU PROPIA lista de eventos a partir de los fotogramas (references/typed-cues.md) -> from_cues.py - --ui library
python scripts/mix.py work/cues.json --out result/film_sfx.mp4 --plan     # qué va dónde; luego sin --plan
python scripts/critique.py result/film_sfx_resolved_cues.json result/film_sfx_sfx_track.wav
python scripts/levels.py   result/film_sfx_resolved_cues.json result/film_sfx_sfx_track.wav --json work/edits.json
# una película cuyo sonido es SOLO SFX (sin música ni voz propia): sonidos pequeños en los huecos, luego mix.py de nuevo (paso 4, "Capa de sonidos pequeños")
python scripts/texture.py work/cues.json --moments work/moments/moments.json
# la misma película: una base (una grabación real larga y oscura debajo de toda la película; paso 4, "Base"), luego mix.py de nuevo
python scripts/bed.py work/cues.json [--list]
# números contra nueve carretes SFX terminados (paso 6, "Contra la referencia"): sin puntuaciones, no afecta el veredicto
python scripts/critique.py RESOLVED.json WAV --style clean-sfx-refs
# oídos humanos hechos baratos (paso 6): una página con las preguntas de la crítica y un veredicto de un solo toque; el modelo de enmascaramiento
python scripts/listen_page.py build work/listen --moments result/film_sfx.mp4 --critique RESOLVED.json WAV
python scripts/listen_page.py serve work/listen [--lan]        # luego: listen_page.py results work/listen --log
python scripts/mix.py work/cues.json --out result/film_sfx.mp4 --masking        # qué sonidos oculta el resto (necesita el venv)

Una carpeta de proyecto encuentra su propia lista de eventos (docs/, scripts/, assets/); el script sintetizador se lee solo cuando no hay lista. Elige todos los indicadores de from_cues.py antes de editar la hoja: ejecutarlo de nuevo borra las ediciones manuales (luego sheet.py apply). Voz en la película: mix.py ... --voice-safe (profundidad normal; --voice-depth light cuando hay muchas texturas suaves, deep solo para sonidos raros en pausas: elimina la interfaz por completo de la mezcla). La música es esencial para la película: --duck. Volumen: una base reconstruida coincide con el original por defecto; el tuyo propio: --target-lufs NUMBER. Sin índice, o las bibliotecas se movieron: python scripts/build_index.py, luego python scripts/listen.py tag-index. Sin uisfx: setup.py init --uisfx. Otra máquina: setup.py scan FOLDER, setup.py add-library NAME PATH [--tier main|extra] --index. Ejecuta los scripts desde la carpeta de la habilidad; pon entre comillas las rutas con espacios o caracteres no latinos; tu propio Python con rutas no latinas en Windows: PYTHONUTF8=1. En PowerShell, las comillas rompen los argumentos JSON: ponlos en un archivo.

De dónde vienen los sonidos

Qué se necesita	De dónde
La base: whooshes, hits, risers, pops, chimes, teclas, papel, foley, ambiente	la biblioteca principal (tier: main, ruta en config.json). Un pack ordenado con catalog.json / catalog.csv le da a cada sonido su tipo y grabación fuente, lo que evita adivinanzas a partir de nombres de archivo
Lo que le falta a la biblioteca principal: gotas graves, monedas, fallos cortos	bibliotecas de respaldo (tier: extra, marcadas ~ en los resultados): solo cuando la biblioteca principal tiene menos de tres sonidos adecuados
Packs diseñados con sus propios roles	roles granular, atmosphere, power, music_transition, voice nunca son solicitados por la selección automática: tómalos explícitamente (--role, "pick": {"role": ...})
Un momento de interfaz: clic, tic, ventana, notificación	uisfx (--ui auto) cuando la lista misma nombra tipos de interfaz (clic, chime...): from_cues dice por qué y dónde (routes: key -> library:click, pop -> uisfx:select)
Escritura	siempre el teclado real de la biblioteca, incluso con --ui auto; una secuencia de 8+ eventos click separados por 35–170 ms se reconoce como escritura por from_cues (--no-typing-detect)
Contacto físico: pelota, paso, cuenta, objeto	siempre la biblioteca: una pelota en el suelo es un golpe sordo, no select (receta abajo)

Sin biblioteca todavía: setup.py init --uisfx solo da 78 señales CC0 de interfaz. Fuentes gratuitas de grabaciones reales que vale la pena revisar (lee cada licencia): Freesound (filtro CC0), paquetes Sonniss GDC, Mixkit, Pixabay sound effects.

"De mi biblioteca", "sin síntesis" o "sonidos sintéticos": --ui library. Un acento en el logotipo o un "cha-ching" en un proyecto con sonidos de interfaz uisfx: --from-library pop,bell (nombres de tipo de la lista); para un solo sonido: sheet.py set --at T --label bell id=65. Bajo música tonal:

• los pasos de tono de las repeticiones de uisfx y de los sonidos tonales de la biblioteca (chime, pop, glass, coin) se desactivan solos cuando el proyecto tiene una partitura (--ui-pitch off|cycle);
• el tono de un sonido real se afina a las notas de la música: mix.py toma el music_ref de la hoja (la base sin efectos, la pista de música) o --music-ref FILE y desplaza un sonido tonal por semitonos enteros hasta 2 más los cents que lo colocan en una nota (2.5 en total), si eso lo pone en una nota; el ruido se deja intacto (--no-tonal-fit; scripts/tonal.py SOUND --music FILE --at T muestra las notas);
• los intervalos de las frecuencias propias del autor (tick(t, 1800 * 2 ** (4 * i / 12))) se convierten en los pasos de tono del reemplazo (melody:).

Flujo de trabajo

1. Qué hay ya en el sonido

look.py muestra el espectrograma del sonido nativo (la voz son bandas de frases, la música una alfombra con ritmo, el silencio es negro); listen.py voice FILM.mp4 da la proporción de habla y música. Tres casos:

• La música o voz del autor: permanecen, los SFX van encima (--duck / --voice-safe). Excepción (respuesta de una persona en una película real, 2026-10-19): la película fue enviada "para ser diseñada sonoramente", su sonido nativo es solo música (listen.py voice: habla 0%), y la persona la quiere sin la música, como sus propios carretes SFX limpios. Haz una versión sin música (from_cues.py ... --ui library --drop-original, luego bed.py --id ... --level -46 con un ambiente favorito), y una versión con música si es útil, y di cuál es cuál. En una elección ciega de tres (original / efectos sobre música / solo efectos) la persona eligió la última sin una sola queja. from_cues imprime BAKED: en dicha película aunque no haya síntesis horneada (habla 0%, música 84%, los ataques no coinciden con los eventos: 7% contra 9% por casualidad): esto es una falsa alarma.
• Síntesis horneada en la pista (el proyecto fue escrito para una partitura sintetizada): los sonidos reales encima de ella son duplicación. from_cues.py lo verifica por sí mismo (BAKED:, unbake:) y elimina la síntesis de la base sin tocar la música y la voz; cómo exactamente, y qué hacer si el script falla o la síntesis está dentro de la pista de música (--extra-synth): references/project-audio.md (léelo tan pronto como la salida tenga BAKED, WARN stems, unbake: not possible, o el proyecto sintetice su sonido con un script). Después de la compilación, critique.py imprime el eje doubling: la correlación de la capa con el original y con la nueva película (debería ser aproximadamente 0).
• El sonido de clips reproduciéndose dentro de la ventana de una grabación de pantalla: nativo, se conserva; los eventos dentro de esas ventanas se descartan.

2. Encontrar los momentos (de la mejor fuente a la peor)

• La lista de eventos del proyecto o el script sintetizador → from_cues.py (abajo). En detalle: references/typed-cues.md.
• Una grabación de pantalla → references/screencast.md (`ui_events.py regiones, coincidencia de pulsaciones de teclas con caracteres, sonido de clip).
• HyperFrames con data-start y sin lista: from_hyperframes.py PROJECT --out work/moments.json. "1 momentos" con 18 elementos significa que el movimiento no sigue data-start: busca un script sintetizador.
• Solo video: find_moments.py FILM --out work/moments [--roi x,y,w,h] [--from A --to B] [--fine]; tipos cut, burst, onset, settle (settle también se activa en un fotograma vacío o un bucle en reposo: mira el fotograma); look.py --moments ... dibuja los fotogramas de los momentos. Esqueleto: suggest_cues.py (references/recipes.md); un borrador es un inicio, no una respuesta. --fine para animación suave coloreada (gradientes, brillos, formas pastel que cambian de color en lugar de brillo): también lee cambios de croma, los momentos obtienen src=chroma|luma; en tres de esas películas encuentra 33–69% de los eventos que un agente anotó a partir de los fotogramas (dentro de 80 ms), frente a 13–25% solo con brillo; 3–4 veces más candidatos (15–25 por cada 10 s). Estos son candidatos: los fotogramas deciden.
• Bajo música: beats.py FILM --out work/beats.json --plot work/beats.png; con usable: true, mix.py --snap-beats (±50 ms). La cuadrícula se verifica contra el bombo (la banda baja < 125 Hz por separado): imprime cuántos golpes cayeron en un bombo dentro de 40 ms. Una cuadrícula cerca del bombo (el rastreador se posó en los charles, "0.22 s de diferencia") se mueve sobre él; una cuadrícula que no cae en nada obtiene usable: false, y --snap-beats la ignora. --plot dibuja la banda, los bombos (marcas verdes) y la cuadrícula (líneas rojas): las marcas están en las líneas, o no confíes en la cuadrícula. Si la música es tuya y se puede ajustar a la imagen: beats.py FILM --suggest-offset work/moments.json dice cuánto desplazar la música para que los cortes y golpes caigan en los tiempos (solo consejo; la música no se toca).

from_cues.py: python scripts/from_cues.py LIST|PROJECT_FOLDER|SCRIPT.cjs|- --video RENDER.mp4 --out work/cues.json (- lee la lista de stdin; se entiende un BOM de PowerShell). Qué hace y dice por sí mismo:

• es el render correcto: la lista no coincide con la imagen (VERDICT); una lista en tiempo de diseño contra un render sincronizado con la voz: un mapa de tiempo a partir de los anclajes del proyecto (timing.json con a…