earshot: oídos para un agente

¿Qué hace earshot: oídos para un agente?

No puedes oír. Nunca digas cómo suena un audio, o que un sonido "encaja", sin una lectura de earshot que lo respalde, y cita el número cuando informes ("coincidencia fuerte, z +3.9; p_real 0.96; -14.2 LUFS"). earshot se ejecuta localmente en CPU (el audio nunca abandona la máquina, excepto con el comando opcional llm) y guarda en caché cada incrustación y resultado en disco. Coste: cada llamada CLI es un nuevo proceso que carga los modelos primero (~20-40 s en un portátil ocupado, incluso para un archivo en caché); dentro del servidor MCP o un script de Python los modelos se cargan una vez y las llamadas repetidas tardan segundos. Para más de un puñado de llamadas, usa MCP o un script corto (from earshot import api; api.find(...); api.realness(...)).

Configuración (una vez)

pip install -e "/ruta/a/earshot[mcp,llm]"   # o el venv del repositorio: /ruta/a/earshot/.venv/bin/python -m earshot ...
earshot doctor                           # paquetes, ffmpeg, modelos (revisión fijada, estado de caché); --load los cronometra

Dos formas de acceder, mismas funciones:

• CLI: earshot <comando> ... [--json] [--out resultado.json]. La salida de texto comienza con un resumen claro; los tiempos están en m:ss.ss en texto y segundos en JSON.
• MCP (los modelos permanecen cargados entre llamadas): claude mcp add earshot --scope user -e EARSHOT_THREADS=3 -- /ruta/a/earshot/.venv/bin/python -m earshot mcp, o en el .mcp.json de cualquier cliente: {"mcpServers": {"earshot": {"command": "/ruta/a/earshot/.venv/bin/python", "args": ["-m", "earshot", "mcp"], "env": {"EARSHOT_THREADS": "3", "GEMINI_API_KEY": "${GEMINI_API_KEY:-}"}}}} (la línea de la clave solo para la herramienta llm opcional; Claude Code la completa desde el entorno del usuario, otros clientes pueden necesitar la clave establecida en el entorno que los lanza: nunca escribas una clave literal en un archivo de proyecto). Herramientas: measure, describe, match, rank, find, compare, ab, realness, timeline, sheet, critique, doctor, llm_critique; el banco de sonidos (sin modelos): sfx_list, sfx_render, kit_render (Bucle 5). Pasa rutas absolutas; full=true devuelve todo el JSON. El servidor responde en pocos segundos, más tiempo en una máquina fría u ocupada; si Claude Code no muestra herramientas de earshot, inícialo con MCP_TIMEOUT=60000 (PowerShell: $env:MCP_TIMEOUT=60000; claude). earshot mcp --warm precarga los modelos al inicio. Si la máquina es compartida, configura EARSHOT_THREADS=2-3 (o --threads 2 en cualquier comando). La primera llamada al modelo de un proceso carga CLAP + AST (~20-60 s); las llamadas posteriores en el mismo proceso son rápidas. Cualquier archivo legible por ffmpeg funciona, incluyendo el audio de un mp4 (un video sin pista de audio lo indica). Los errores son una línea en stderr: earshot <comando>: error: ..., código de salida 1.

Bucle 1: elegir un activo

1. earshot rank "un golpe suave de mazo de fieltro sobre un bloque de madera" descargas/sfx/ --top 5 - preselecciona de una carpeta.
2. earshot find ganador.ogg "un solo golpe limpio de mazo" --top 3 - los mejores momentos como recortes de muestra (inicio / final en segundos). Cada segmento tiene un tipo: stroke (una sola aparición hasta que se extingue) y event (golpes que pertenecen juntos, p. ej., pulsación + liberación de una tecla) comienzan 5 ms antes del ataque y terminan después de la extinción; window es un tramo cuyos bordes se ajustan al sonido para consultas de un solo disparo (un tramo plano, para hacer crossfade, para fondos). head / tail = cuán fuerte son los primeros 5 ms / últimos 10 ms en comparación con el pico del recorte (-30 dB o menos = limpio); un recorte marcado 'head cut' o 'tail cut' comienza o termina dentro de un sonido: no lo uses tal cual. --kind event devuelve solo recortes basados en ataques (golpes, clics, pasos), --kind texture solo ventanas planas (fondos); el valor predeterminado lee la consulta.
3. earshot describe ganador.ogg --start 1.12 --end 1.48 - cómo suena realmente; comprueba que las etiquetas principales coincidan con lo que necesitas y que la forma (ataque / extinción) se ajuste a la imagen. Las etiquetas AudioSet son débiles en sonidos de un solo disparo de menos de ~0.5 s: 'tagger unsure' o una clase cercana (Zipper para un swish, Finger snapping para un clic) es neutral; solo una clase completamente diferente (Speech, Music, Engine, Vehicle) es una bandera roja.
4. earshot realness ganador.ogg --start 1.12 --end 1.48 (o una carpeta completa) - juzga el recorte que usarás: un archivo de múltiples tomas tiene p_real como promedio de cada toma y el silencio entre ellas. Cuando el usuario quiera sonido real o producido profesionalmente, no uses un recorte 'probablemente sintetizado por código', y lee la evidencia de uno 'incierto' antes de usarlo (escribe por qué lo mantuviste). Cuando el sonido sintetizado es el objetivo (música procedural, tonos UI, sonidos hechos con earshot forge), realness es información, no una barrera. Los umbrales de veredicto dependen de la duración (cada resumen los nombra): un sonido de hasta 6 s usa los umbrales de clip (bajo 0.17 / alto 0.77), un archivo más largo usa la media de sus ventanas de 4 s con umbrales de archivo débilmente calibrados (bajo 0.40 / alto 0.77), así que compara veredictos, no p_real bruto, entre archivos de diferentes longitudes. Las grabaciones reales y la música y el diseño de sonido producidos profesionalmente suelen leerse como reales, pero realness escucha cómo suena un sonido, no de dónde viene: los tonos limpios sintetizados profesionalmente (sonidos UI, campanillas, stabs de sintetizador) también se leen como sintetizados por código. Si realness no está disponible (modelo faltante), di claramente que no se verificó lo real vs. sintético; las clases AudioSet de describe (Sine wave, Beep, Synthesizer) son evidencia más débil. Los ceros digitales exactos por sí solos no prueban nada (el 59 % de las grabaciones reales con licencia del proyecto tienen algún fundido o relleno de silencio).
5. Para elegir entre dos candidatos: earshot ab a.ogg b.ogg --query "un swoosh de aire rápido y nítido", con --a-start/--a-end/--b-start/--b-end para recortes de find (A y B pueden ser el mismo archivo de múltiples tomas). Opcional: earshot match ganador.ogg "una pulsación de tecla profunda y maciza" --alts "un interruptor azul chasqueante" "una tecla de máquina de escribir" para probar una afirmación, o earshot compare ganador.ogg --refs aprobados/ [--start --end] para comprobar si encaja en la paleta.

Bucle 2: revisar una mezcla o una película

1. earshot timeline pelicula.mp4 --cues cues.json (o banda_sonora.wav --video pelicula.mp4) - la transcripción auditiva: eventos con tiempo, nivel y etiquetas, secciones, curva de sonoridad, cortes de imagen, sincronía por corte / cue. --detail low es rápido, high etiqueta hasta 96 eventos (los más importantes primero; el resumen dice cuántos fueron etiquetados, por lo que un evento no etiquetado no es un sonido faltante). Lee las estadísticas de sincronía: offset_ms = sonido menos imagen (negativo = adelantado), y la fracción 'chance' dice qué puntuarían puntos de edición aleatorios; solo la sincronía mejor que el azar significa algo. Un corte listado sin golpe aún puede llevar un swoosh suave: compruébalo en la hoja antes de añadir un sonido.
2. earshot sheet pelicula.mp4 -o hoja.png --cues cues.json (--from 10 --to 25 acerca, --detail low es más rápido) - un PNG anotado: fotogramas, secciones, eventos etiquetados, espectrograma, sonoridad, pulsos, marcadores de cue coloreados por sincronía (verde = dentro de un fotograma, ámbar = dentro de 100 ms, rojo = sin sonido). ABRE EL PNG con tu visor de imágenes: los huecos, las acumulaciones, el enmascaramiento y los golpes tardíos son obvios de un vistazo.
3. earshot critique pelicula.mp4 (--fast omite los pases de AudioSet / realness) - tarjeta de puntuación contra el rango medido de películas de lanzamiento profesionales: cada métrica ok / baja / alta con su peso y acciones con marcas de tiempo, y un veredicto (grado de lanzamiento / cerca / necesita trabajo / no es grado de lanzamiento). Corrige las filas críticas primero, vuelve a ejecutar 1-3 en el nuevo render. Su proporción de "ataque en eventos visuales" cuenta solo nuevos ataques dentro de +-100 ms (la definición de las referencias); sus correcciones y consejos nombran los cortes sin ningún sonido, por el mismo emparejador que timeline. Si el archivo es uno de los propios filmes de referencia del perfil, critique lo dice y lo puntúa frente a los demás.
4. Medidores exactos en cualquier momento (LUFS, pico verdadero dBTP, LRA, piso de ruido, ataque / extinción, brillo, bandas): earshot measure mezcla.wav [--music] o la herramienta measure de MCP.

Bucle 3: A/B un cambio

• earshot ab antes.wav despues.wav --query "bombo cálido y contundente" o --refs refs_pro/ - cuál se acerca más, y cómo B difiere de A en palabras medidas (más fuerte, más brillante, extinción más larga). Para sonidos dentro de archivos más largos pasa los recortes (--a-start 1.217 --a-end 1.615 --b-start 7.881 --b-end 8.285): un A/B de archivo completo de archivos de múltiples tomas compara cada toma más el silencio entre ellas. Luego earshot timeline despues.wav y compara las líneas de eventos y las estadísticas de sincronía con la ejecución anterior. Cambia una cosa a la vez.

Bucle 4: crear un sonido en código (earshot forge)

Usa esto cuando el usuario quiera un sonido creado, no elegido: una IA que oye puede escribir código de síntesis, escuchar y mejorarlo. Cada muestra debe ser calculada (sin audio grabado dentro, ni siquiera una respuesta al impulso); las grabaciones reales son solo las referencias con las que el crítico compara.

1. Escribe o elige una receta en earshot/forge/recipes/<nombre>.py: SPACE (rangos de parámetros), DEFAULTS, TARGET, ALTS (confusiones realistas) y render(params, r) -> array de 48 kHz, construido desde earshot.forge.dsp (resonadores modales, excitaciones de contacto, colores de ruido, un SVF variable en el tiempo, una sala calculada, un micrófono con piso de ruido). Modela la física de la cosa real, medida en las referencias: qué golpea qué, qué suena, cuánto tiempo, en qué sala.

2. Ejecuta una ronda: earshot forge <receta> --refs <refs reales> --budget 144 --reps 2 --tone 1.5 --keep 4 --robust 8 --dir <directorio ronda>, o en un script de Python por ronda que cargue los modelos una vez: forge(recipe, critic=Critic(target, alts, refs, tone=1.5), reps=2, space={...}).

   • --tone pone el balance tonal y la cola sin modelo en el objetivo.
   • --reps 2 clasifica cada candidato por 2 renders, contra renders afortunados.
   • Tarda aproximadamente 3-5 minutos por 160 renders en una CPU de portátil ocupada, incluido un calentamiento del modelo de 30-60 s.

3. Lee lo que escuchó. El resumen de cada selección dice, por ejemplo, "suena como: un tapón de corcho, un tintineo de vidrio", "extinción +2.4 fuera de las refs" o "tono 11.2 dB de la mediana de las refs: +16 dB a 500-630 Hz (por encima de cada ref)". Luego verifica las selecciones de cuatro maneras:

   • las palabras de tone sin modelo: qué bandas caen fuera de cada referencia, las proporciones de energía, la cola, la duración (la señal más confiable una vez que las puntuaciones del modelo son altas)
   • robust: la media sobre nuevas semillas, no el mejor render afortunado
   • alt_zs: qué confusión está más cerca
   • espectrogramas junto a las referencias: ffmpeg -i x.wav -lavfi showspectrumpic=s=900x360:scale=log:legend=0 x.png

   Las etiquetas AudioSet en report.json se mantienen reservadas solo mientras no elijas o guíes por ellas. Fija una regla de selección (por ejemplo, la media robusta) antes de mirar, e informa las etiquetas después.

4. Cambia la estructura de la receta, no solo sus rangos, para lo que esté mal (un tic de liberación faltante, un anillo metálico, una cola demasiado larga). Luego repite. Mantén un LOG de cada ronda y sus números.

5. Informa honestamente, junto a las referencias reales puntuadas por el mismo crítico (report.json ref_scores, leave-one-out).

Goodhart, dilo claramente:

• La búsqueda optimiza los propios modelos de earshot. Los sonidos creados rutinariamente superan a las grabaciones reales en ellos, lo que significa que el crítico está satisfecho, no que el sonido sea mejor.
• p_real es fácil de engañar: los resonadores modales más una sala y un piso de ruido de micrófono se leen como "real".
• La tipicidad recompensa ser un promedio de las referencias.
• Las comprobaciones del modelo se saturan: después de una búsqueda, cada comprobación del modelo, frases retenidas y conjuntos reales independientes incluidos, coloca el sonido creado dentro de los reales. Solo las mediciones y los oídos aún pueden distinguirlos.
• Juzga por la cercanía medida a las referencias: balance tonal, bandas fuera de cada referencia, colas, duraciones. También usa re-renders robustos y espectrogramas.
• Pide una prueba ciega humana (orden aleatorio, igualación de sonoridad, clave oculta) antes de llamar a un sonido creado "tan bueno como real".

En la primera prueba (demo/forge-test) un juez independiente encontró la pulsación de tecla 8-13 dB fuera del balance tonal real y los pops sin límite de banda con colas sibilantes largas, mientras que cada comprobación del modelo los llamaba reales. Rehechos guiándolos con la comprobación sin modelo, ahora se encuentran dentro de la dispersión medida de las grabaciones reales. El swoosh se rehizo como uno verdaderamente rápido. El impacto (más oscuro, liderado por un swells) y el clic (colas cortas) no se rehicieron. Ningún humano ha escuchado aún.

Bucle 5: crear el kit de sonido de una película (earshot sfx / earshot kit)

Usa esto cuando una película hecha con código (una película cinética, cualquier hoja de cues) necesite sus efectos: renderízalos desde el banco incluido de earshot en lugar de escribir voces de síntesis. No se cargan modelos; un kit completo se renderiza en aproximadamente un minuto y los re-renders en segundos.

1. Comienza desde un preajuste: earshot kit init --preset calm -o audio/kit.json (calm para películas guiadas por texto, crisp para películas de producto enérgicas, minimal para películas de solo efectos diseñados, launch para películas cortadas con música). La note de cada rol dice por qué se eligió su sonido. calm / crisp / minimal mantienen riser, swell y suck apagados: un revelado se resuelve en un elemento, y el lockup es un golpe limpio. launch suena un riser o un swell inverso en un cambio de sección y usa los sonidos 0.4 hechos para películas guiadas por música (abajo).
2. Ajústalo a la película: earshot sfx list --kind hit (o --category) muestra los candidatos con duraciones, tiempos pico y perillas. Cambia el sound de un rol, configura edits (pitch a la raíz de la película para el hit o drop, dur / apex para un movimiento fijo), takes (12 o más para tecleo, 2-4 en otros lugares), level_db. Escucha un candidato con earshot sfx render ID -o x.wav [--pitch E5] [--dur 0.8 --apex 0.32] y lee su ataque / pico / final medidos.
3. Renderiza: earshot kit render audio/kit.json --out audio/kit. Las tomas y kit.lock.json (ataque, pico, final, sonoridad por toma medidos) son lo que el mezclador coloca en los fotogramas de cue: ataque en el fotograma para hits y toques, el pico en el apex de un whoosh, el final en el golpe de un riser (su pico cuando el rol se alinea en peak, como lo hacen el riser y el swell de launch: esos miembros caen después de su clímax; kit check nota uno alineado al final).
4. Verifica: earshot kit check audio/kit.json --out audio/kit. Rechaza lo que un render no pueda usar (una perilla o tono que el sonido no pueda tomar, un nivel superior a 0 dBFS, un during sin sync, un requisito de before que no existe en la película, un pitch sin un root al que referirse). Advierte sobre faltantes y solapamientos.
5. Si la película se mueve (sincronización de la imagen que cambia las posiciones de los cortes), earshot kit sync audio/kit.json reasigna las tomas a los nuevos fotogramas de cue.

Graba en la conversación con el usuario qué bucle(s) usaste y la ruta de los archivos generados. No 'solo mira' la imagen de la hoja: ábrela y describe el espectrograma, la sonoridad y la sincronía en cada cue, ostenta la hoja como una cifra, no como una pintura abstracta; lee columnas de bucle 2 y mide el bucle 3; explica los números del bucle 4; y apila los activos del bucle 1 en una tabla o una pila de archivos de sonido que el usuario pueda comparar.