README

earshot

Ears for coding agents.


Watch the 0.4 launch film (35 s): its sound effects are
takes from the earshot bank placed with the launch kit, plus the one CC0 recording it shows being re-made, over a
licensed music track. Play every sound in the bank on
the earshot site.

!Frames from the first launch film (0.1)

AI coding agents can now write the code that renders a film, a product demo or a game. They still cannot hear what
they made. They cannot tell a premium key press from a cheap one, notice that a hit lands 80 ms after the cut, or
hear that the music swells in the wrong place.

earshot turns sound into evidence an agent can reason about: what a file sounds like in words, how well it fits a
description, the best moment inside a long recording, whether it is a real recording or code-synthesized, a
second-by-second listening transcript of a whole film, an annotated picture of it, and a scorecard against
professional launch films. It runs locally on CPU, as a CLI, a Python API and an MCP server.

With ears, an agent can also make its own sounds in code and improve them by listening (earshot forge), and
translate a recording into code it can vary (earshot fit). Both below.

New in 0.4: the sound of a music-led launch film. 51 new sounds made in code for the soft, short, mid-register
style those films use: rounded UI pops, wood and plastic knocks, short cut hits and sub hits with a kick, gated
glockenspiel / celesta / marimba notes and chime runs, water drops, camera shutters, reverse cymbals, a thump-whoosh,
short dark risers, bright swishes, burst glitches and mid dings (the bank now holds 252). A new launch kit preset
mixes every effect against the music bed instead of at a fixed level, says where each one sits against the cut (taps
lead it, whoosh peaks land after it) and how close a run may go. And earshot fit was re-made against professional
sound effects and measured on held-out clips (below).

New in 0.3: sound for code-made films. A bank of sound effects stored as code that render by id in seconds,
with no models and no network: earshot sfx aims a whoosh, hit, click or note at a moment in the picture, and
earshot kit renders a whole film's effects with measured sync points (below).


$ earshot describe enter.ogg
  0.56 s short transient (attack 3 ms, decays in 190 ms). Sounds most like: a single mechanical keyboard key press
  (z +5.4), a soft key release click (z +3.6) ... [clear reading]. peak -0.1 dBFS, brightness 1.5 kHz ...

$ earshot match key.ogg "a deep thocky mechanical keyboard press" --alts "a clicky blue switch keyboard" "a mouse click"
  - strong (z +3.7; would rank 2 among 322 vocabulary descriptions) ...

$ earshot find keys.ogg "a single mechanical key press" --top 4
  0:03.94-0:04.19 (0.24 s stroke, z +4.1 strong); 0:10.60-0:10.86 ...

$ earshot critique film.mp4
  VERDICT: close - 21 of 23 scored metrics in range ... FIX FIRST: 1. [major] nothing reaches body level until 0:01.01 ...


 What it does

| command | wh

Top issues

Latest release

Thanks to @SmitMachhi, @yinbowen-dc, @kyexyz and @lunar-me.

- One command to install, one to update (11, closes 5): uv tool install "earshot[mcp] @ git+https://github.com/Leonxlnx/earshot", then uv tool upgrade earshot. Under uv, torch comes from the CPU-only index.
- A NaN or Inf sample is one clear error (13, closes 12). Before, most commands crashed, and match, rank and realness gave wrong answers with exit 0.
- Media globs match files only (17, closes 16).
- video.cuts: cache=False really rescans (14), and a failed scene scan is an error instead of "no cuts", now cached only when the scan