earshot

earshot is an open-source Python toolkit from Leonxlnx that turns sound into evidence a coding agent can reason about. It runs locally on CPU as a CLI, a Python API and an MCP server, and can describe, match, search, critique and also generate audio.

What It Is

earshot gives AI coding agents "ears". An agent can ask what a file sounds like in words, how well it fits a description, where the best moment inside a long recording is, and whether a clip is a real recording or code-synthesized. For films it produces a second-by-second listening transcript, an annotated PNG sheet of frames, events, spectrogram and loudness, and a scorecard against a profile of seven professional launch films, with timestamped fixes.

Output of each command starts with a plain-language summary; --json gives the full result. Analysis relies on two open models (CLAP and an AudioSet tagger) plus model-free measurements such as LUFS, true peak and spectrum.

Making Sounds with forge and fit

earshot forge lets an agent write a sound as a code recipe of physical synthesis (modal resonators, filtered noise, a computed room and microphone). A critic built from earshot scores renders, an evolutionary search mutates the best, and the agent rewrites the recipe after reading the critic's feedback. Outputs include WAVs, a report, a comparison image and an audition file. earshot fit translates a recording into a forge recipe module that can re-render it, vary it or morph between two recordings. The README discloses that the search optimizes earshot's own models and recommends judging results by measurements, spectrograms and human blind tests.

Sound for Films

A shipped bank of 201 sound effects renders by id 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 film's effects with measured sync points. earshot gallery builds a static HTML listening page of forge outputs.

Setup Path

It needs Python 3.10+ and ffmpeg on PATH, runs CPU-only, and downloads two open models (about 1.1 GB) on first use. It can be registered as an MCP server for Claude Code or other clients, and two agent skills ship in the repo. An optional audio-LLM critique uses the user's own Gemini key with explicit consent. The code is MIT licensed.