/earshot

name: earshot
description: Listen with earshot whenever you must judge, choose, trim, verify or compare sound you cannot hear - picking a sound effect, music or ambience from candidates, finding the cleanest moment in a recording, checking whether audio reads as a real recording or as code-synthesized, reviewing a soundtrack or a video's audio (what happens when, sync to picture, loudness, mix), A/B-ing a mix change, making a sound in code and improving it by listening (earshot forge), or giving a code-made film its sound effects from the shipped bank (earshot sfx / kit). Use it before telling anyone how audio sounds.

earshot: ears for an agent

You cannot hear. Never say how audio sounds, or that a sound "fits", without an earshot reading behind it, and quote the number when you report ("strong match, z +3.9; p_real 0.96; -14.2 LUFS"). earshot runs locally on CPU (audio never leaves the machine, except with the optional `llm` command) and caches every embedding and result on disk. Cost: each CLI call is a new process that loads the models first (~20-40 s on a busy laptop, even for a cached file); inside the MCP server or one Python script the models load once and repeat calls take seconds. For more than a handful of calls, use MCP or a short script (`from earshot import api; api.find(...); api.realness(...)`).

Setup (once)

pip install -e "/path/to/earshot[mcp,llm]"   # or the repo venv: /path/to/earshot/.venv/bin/python -m earshot ...
earshot doctor                           # packages, ffmpeg, models (pinned revision, cache state); --load times them

Two ways in, same functions:

• **CLI**: `earshot <command> ... [--json] [--out result.json]`. Text output starts with a plain summary; times are

m:ss.ss in text and seconds in JSON.

• **MCP** (models stay loaded between calls): `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", "GEMINI_API_KEY": "${GEMINI_API_KEY:-}"}}}}` (the key line only for the optional llm tool; Claude Code fills it from the user's environment, other clients may need the key set in the environment that launches them: never write a literal key into a project file). Tools: measure, describe, match, rank, find, compare, ab, realness, timeline, sheet, critique, doctor, llm_critique; the sound bank (no models): sfx_list, sfx_render, kit_render (Loop 5). Pass absolute paths; `full=true` returns all JSON. The server answers within a few seconds, longer on a cold or busy machine; if Claude Code shows no earshot tools, start it with `MCP_TIMEOUT=60000` (PowerShell: `$env:MCP_TIMEOUT=60000; claude`). `earshot mcp --warm` preloads the models at startup. If the machine is shared, set `EARSHOT_THREADS=2-3` (or `--threads 2` on any command). The first model call of a process loads CLAP + AST (~20-60 s); later calls in the same process are fast. Any ffmpeg-readable file works, including the audio of an mp4 (a video with no audio track says so). Errors are one line on stderr: `earshot <command>: error: ...`, exit 1.

Loop 1: choose an asset

1. `earshot rank "a soft felt mallet hit on a wooden block" downloads/sfx/ --top 5` - shortlist from a folder. 2. `earshot find winner.ogg "a single clean mallet hit" --top 3` - the best moments as sample trims (start / end in seconds). Each segment has a kind: `stroke` (one onset until it decays) and `event` (strokes that belong together, e.g. a key's down + up) start 5 ms before the attack and end after the decay; `window` is a stretch whose edges find snapped onto the sound for one-shot queries (a plain stretch, to be crossfaded, for beds). `head` / `tail` = how loud the first 5 ms / last 10 ms are against the trim's peak (-30 dB or lower = clean); a trim marked 'head cut' or 'tail cut' starts or ends inside a sound: do not use it as is. `--kind event` returns onset-based trims only (hits, clicks, steps), `--kind texture` plain windows only (beds); the default reads the query. 3. `earshot describe winner.ogg --start 1.12 --end 1.48` - what it actually sounds like; check the top tags fit what you need and the shape (attack / decay) fits the picture. AudioSet labels are weak on one-shots under ~0.5 s: 'tagger unsure' or a near class (Zipper for a swish, Finger snapping for a click) is neutral; only an outright different class (Speech, Music, Engine, Vehicle) is a red flag. 4. `earshot realness winner.ogg --start 1.12 --end 1.48` (or a whole folder) - judge the trim you will use: a multi-take file's p_real is a mean over every take and the silence between them. When the user wants real or professionally produced sound, do not use a 'likely code-synthesized' trim, and read the evidence of an 'uncertain' one before using it (write why you kept it). When synthesized sound is the point (procedural music, UI tones, sounds made with earshot forge), realness is information, not a gate. The verdict thresholds depend on length (each summary names them): a sound up to 6 s uses the clip thresholds (lo 0.17 / hi 0.77), a longer file the mean of its 4 s windows with weakly calibrated file thresholds (lo 0.40 / hi 0.77), so compare verdicts, not raw p_real, across files of different lengths. Real recordings and professionally produced music and sound design usually read real, but realness hears how a sound sounds, not where it came from: clean professionally synthesized tones (UI sounds, chimes, synth stabs) also read as code-synthesized. If realness is unavailable (model missing), say plainly that real-vs-synthetic was not checked; describe's AudioSet classes (Sine wave, Beep, Synthesizer) are weaker evidence. Exact digital zeros alone prove nothing (59% of the project's licensed real recordings have some edit or fade padd