Repolode
Submit
Leonxlnx

Leonxlnx/earshot

A CPU-only toolkit that lets coding agents listen to audio: describe, match, find, critique and synthesize sound via CLI, Python API and MCP server.

View on GitHub
Stars
2,129
Forks
125
Open issues
5
Last commit
9 hours ago

What is it?

earshot gives AI coding agents the ability to hear. It describes what a sound file sounds like in words, scores how well a text description fits a recording, finds the best moments inside long audio, flags whether a sound is a real recording or code-synthesized, and produces a second-by-second listening transcript of a video with sync markers against picture cuts. It runs locally on CPU and is exposed as a CLI, a Python API and an MCP server for Claude Code and other agents.

Beyond listening, the project includes a forge that writes sounds as code: recipes of physical synthesis are rendered, scored by a critic built on the same models, and refined through search. A fit command translates an existing recording into a parameterized synthesis recipe that can be varied or morphed. A bundled bank of 201 sound effects renders by id without models or network access, with kit presets for film sound design.

The repository contains no audio or video; reference recordings used for evaluation are licensed separately. Models are downloaded once from Hugging Face at pinned revisions and cached for offline use.

Key features

  • 01Describes sounds in calibrated tags with measurements and AudioSet labels.
  • 02Scores how well a text description matches a recording, with a strength verdict.
  • 03Finds the best matching moments inside long recordings as trims.
  • 04Classifies clips as real recordings or code-synthesized.
  • 05Produces timeline transcripts and annotated sheets for video soundtracks.
  • 06Synthesizes sound effects from code recipes, scored by a built-in critic.
  • 07Exposes all tools through a CLI, Python API and MCP server.

Use cases

  • Letting a coding agent check whether generated sound effects match the intended sound.
  • Picking the best candidate from a folder of downloaded audio clips.
  • Auditing sync and loudness of a code-generated video's soundtrack.
  • Generating sound effects offline for programmatic film or UI pipelines.

Quick start

  1. 1

    Install earshot following the README instructions

  2. 2

    Check the install, models and CPU settings

    earshot doctor
  3. 3

    Describe what a sound file sounds like

    earshot describe FILE

Things to know

  • Each CLI call reloads the models, which takes about 20-40 seconds before it answers.
  • Forge reference-based search needs your own licensed reference recordings, which are not included in the repo.
  • The made-sound quality checks can be gamed by the search, so results need listening and measurement checks.
  • The optional llm command uploads audio to Gemini and needs your own API key.

In collections

Claude Code tools, skills & pluginsOpen-source AI agent frameworks & appsMCP servers

Topics

#ai-agents#audio#sound-design#mcp#claude-code#audio-analysis#speech-synthesis#cpu-inference

FAQ

What is earshot?
A CPU-only toolkit that lets coding agents listen to audio: describe, match, find, critique and synthesize sound via CLI, Python API and MCP server. earshot gives AI coding agents the ability to hear. It describes what a sound file sounds like in words, scores how well a text description fits a recording, finds the best moments inside long audio, flags whether a sound is a real recording or code-synthesized, and produces a second-by-second listening transcript of a video with sync markers against picture cuts. It runs locally on CPU and is exposed as a CLI, a Python API and an MCP server for Claude Code and other agents.
Is earshot free to use? What license does it have?
earshot is open source under the MIT license. Check the license terms before using it in commercial products.
Is earshot still maintained?
Actively maintained. The last commit to earshot was on Oct 22, 2026.
What can I use earshot for?
Letting a coding agent check whether generated sound effects match the intended sound. Picking the best candidate from a folder of downloaded audio clips. Auditing sync and loudness of a code-generated video's soundtrack. Generating sound effects offline for programmatic film or UI pipelines.
How do I install earshot?
Install earshot following the README instructions Check the install, models and CPU settings: earshot doctor Describe what a sound file sounds like: earshot describe FILE
Where can I get earshot?
The source code and installation instructions are on GitHub: https://github.com/Leonxlnx/earshot

Summary generated by AI from the project's README. GitHub stats refresh daily.

Related projects