Coding agents can now write the code that renders a product demo, a launch film or a game. They still cannot hear what they made. earshot gives them ears: it turns sound into evidence an agent can reason about, runs locally on CPU, and ships as a CLI, a Python API and an MCP server.
This guide sets it up as an MCP server for Claude Code and walks through three real jobs: picking the right sound file, finding a moment in a long recording, and checking a launch film's audio against the picture.
Install
You need Python 3.10+ and ffmpeg / ffprobe on your PATH. No GPU is used.
git clone https://github.com/Leonxlnx/earshot && cd earshot
python -m venv .venv
.venv/bin/python -m pip install torch --index-url https://download.pytorch.org/whl/cpu
.venv/bin/python -m pip install -e ".[mcp,llm,dev]"
.venv/bin/python -m earshot doctor --load
On Windows use .venv/Scripts/python. The first model use downloads two open models (about 1.1 GB) into .cache/hf inside the repo. earshot doctor --fetch downloads them up front. After that earshot loads them from the cache and never contacts the Hub.
Add it to Claude Code as an MCP server
claude mcp add earshot --scope user -e EARSHOT_THREADS=3 -- /path/to/earshot/.venv/bin/python -m earshot mcp
Or in any client's .mcp.json:
{"mcpServers": {"earshot": {"command": "/path/to/earshot/.venv/bin/python", "args": ["-m", "earshot", "mcp"],
"env": {"EARSHOT_THREADS": "3"}}}}
Why MCP and not just the CLI: each CLI call is a new process that loads the models (about 20 to 40 seconds) before it answers. The MCP server keeps them warm after the first call. On a slow machine, start Claude Code with MCP_TIMEOUT=60000.
Job 1: Pick the best sound from a pile of downloads
You have ten candidate key-press files and want the one that fits. Rank them against a description, then get a verdict on the winner:
earshot rank "a single mechanical key press" candidates/*.ogg
earshot match key.ogg "a deep thocky mechanical keyboard press" --alts "a clicky blue switch keyboard" "a mouse click"
match returns a verdict (strong, plausible, weak or no match) with a z score, and describe FILE tells you in words what a file sounds like.
Job 2: Find the exact moment in a long recording
earshot find keys.ogg "a single mechanical key press" --top 4
You get the best moments as start and end seconds, ready to trim. If the top moments do not match what you hear, try two or three phrasings of the description.
Job 3: Check a launch film's sound against the picture
earshot critique film.mp4
earshot sheet film.mp4 -o sheet.png
critique scores the video against a profile of 7 professional launch films and lists fixes with timestamps. sheet draws an annotated PNG (frames, labelled sound events, spectrogram, loudness, sync markers) for agents that read images. Keep in mind the score means "close to those 7 films", not an absolute quality grade.
Bonus: make a sound in code
earshot forge writes a sound as a synthesis recipe, renders candidates and scores them by listening:
earshot forge --list
earshot forge keypress --refs path/to/real/keypresses/ --budget 144 --variants 4 --dir made/keypress
Open made/keypress/report.md and made/keypress/audition.wav to hear the picks next to the references. The reference recordings are licensed and not in the repo, so bring your own with --refs. The README is honest that the search can please its own models without the sound getting better, so judge by ear and by the model-free measurements.
Use cases with copy-paste prompts
- Pick the best sound file from a set of downloads
- Find the exact moment of a sound in a long recording
- Check a launch film's sound and sync with an agent
- Generate a sound effect in code and listen to it
Get one email every Monday with the week's hottest AI repos and exactly how to use them: subscribe free at dedupedai.com
Top comments (0)