# earshot

> Local CPU-based toolkit that lets coding agents hear, critique and synthesize audio via CLI, Python API and MCP server.

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.

## Features
- Describe sounds in words with calibrated tags and measurements
- Match audio against text descriptions and rank candidate files
- Find best moments inside long recordings
- Real vs code-synthesized detection
- Timeline listening transcript and annotated sheet PNG for films
- Launch-video critique scorecard with timestamped fixes
- forge: synthesize and iteratively improve sounds in code
- fit: translate recordings into editable synthesis recipes
- Bank of 201 code-rendered sound effects with sfx and kit commands
- Static HTML gallery of forge outputs
- MCP server and Python API
- Runs locally on CPU

## Integrations
Claude Code, MCP, Gemini, ffmpeg, CLAP, Hugging Face

## Platforms
WINDOWS, MACOS, LINUX, API, VSC_EXTENSION, DEVELOPER_SDK, CLI

## Pricing
Open Source

## Version
v0.2.0

## Links
- Website: https://github.com/Leonxlnx/earshot
- Documentation: https://github.com/Leonxlnx/earshot/blob/main/docs/VALIDATION.md
- Repository: https://github.com/Leonxlnx/earshot
- EveryDev.ai: https://www.everydev.ai/tools/earshot