earshot

Overview

earshot is an open-source, CPU-only toolkit that gives AI coding agents the ability to hear, review and make sound. It turns audio into evidence an agent can reason about and runs locally as a CLI, Python API and MCP server.

Key Features

• Describe audio files with calibrated tags, AudioSet labels and measurements.
• Match descriptions, rank candidate files and find the best moments inside long recordings.
• Compare sounds, assess real versus code-synthesized audio, build listening timelines and generate annotated sheets.
• Critique launch videos against a reference profile and provide timestamped fixes.
• Generate and improve sounds in code with earshot forge and translate recordings into forge recipes with earshot fit.
• Render sounds from a bank of 201 effects and build film sound kits without models or network access.

Use Cases

• Helping coding agents verify that generated demos, games or films sound right.
• Searching a sound library with a text description and locating the best moment in a recording.
• Building and checking sound effects and kits for code-made films.
• Reviewing a launch video soundtrack against professional reference films.

Getting Started

• Install Python 3.10+ and ffmpeg/ffprobe on PATH, then clone the repository and create a virtual environment.
• Install CPU PyTorch and the package with pip install -e ".[mcp,llm,dev]".
• Run python -m earshot doctor --load to check the install, models, data files and CPU settings.

Deployment & Requirements

• Python 3.10+ and ffmpeg/ffprobe on PATH are required.
• The project runs on CPU only; no GPU is used.
• First model use downloads two open models of about 1.1 GB into a local cache.
• Offline operation can be forced with EARSHOT_OFFLINE=1, HF_HUB_OFFLINE=1 or TRANSFORMERS_OFFLINE=1; missing models are then reported as an error.

Before You Adopt

• License: MIT. Review its terms before using, modifying, or distributing the project.
• The first model use requires downloading two open models of about 1.1 GB into a cache inside the repository or EARSHOT_HOME.
• The optional Gemini audio-LLM critique is used only with the user's own key and explicit consent.