Skip to content

Ears for coding agents: let AI hear, review and make sound. CPU-only, open source.

Release 0.3.0

Leonxlnx0121eb67ee9b
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 42e5850..fef0625 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,9 +1,10 @@
# Changelog
-## 0.3.0 - unreleased (0.3.0.dev0)
+## 0.3.0 - 2026-10-19
The sound engine of a film: the forge's delivered sounds as a bank, one-sound renders aimed at the picture, a
-model-free audit, and film kits. Reference: [docs/SFX.md](docs/SFX.md).
+model-free audit, and film kits. Reference: [docs/SFX.md](docs/SFX.md). This release also ships the 0.2.1 fixes
+below (#1, #2), which were not released on their own. No new dependencies.
### Added
@@ -92,6 +93,8 @@ model-free audit, and film kits. Reference: [docs/SFX.md](docs/SFX.md).
## 0.2.1 - 2026-10-17
+Not released separately: these fixes ship in 0.3.0.
+
Two fixes from a careful outside review (thanks, @markblundeberg).
### Fixed
diff --git a/README.md b/README.md
index 305fa5e..819a365 100644
--- a/README.md
+++ b/README.md
@@ -20,6 +20,10 @@ professional launch films. It runs locally on CPU, as a CLI, a Python API and an
With ears, an agent can also **make its own sounds in code** and improve them by listening (`earshot forge`), and
**translate a recording into code** it can vary (`earshot fit`). Both below.
+**New in 0.3: sound for code-made films.** A bank of 201 sound effects stored as code that render by id in seconds,
+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 whole film's effects with measured sync points ([below](#sound-for-films-bank-sfx-kits)).
+
```
$ earshot describe enter.ogg
0.56 s short transient (attack 3 ms, decays in 190 ms). Sounds most like: a single mechanical keyboard key press
@@ -52,6 +56,8 @@ $ earshot critique film.mp4
| `measure FILE` | objective measurements only (no models): LUFS, true peak, LRA, envelope, spectrum, tempo / key |
| `forge RECIPE --refset CAT` | make a sound in code and improve it by listening (see below) |
| `fit FILE -o recipe.py` | translate a recording into a forge recipe module that re-renders it, with knobs and morphs (see below) |
+| `sfx render ID -o x.wav` | a sound from the shipped bank of 201, aimed at the picture (`--dur`, `--apex`, `--pitch`) and audited; `sfx list`, `sfx check` (no models) |
+| `kit init / render / check` | a film's sound kit: one bank sound per role, rendered into cached takes with measured onset / peak / end (no models) |
| `gallery DIR -o page.html` | one static HTML listening page of forge outputs: players, spectrograms, numbers |
| `llm FILE --yes-upload` | optional audio-LLM critique (Gemini), only with your own key and explicit consent |
| `mcp` | the same tools as an MCP server for Claude Code and other agents |
@@ -59,8 +65,8 @@ $ earshot critique film.mp4
Every command prints a plain-language summary first; `--json` gives the full result, `--out f.json` saves it. Errors
are one line on stderr (`earshot <command>: error: ...`, exit 1). Each CLI call is a new process and loads the models
-(~20-40 s) before it answers: for more than a few calls use the MCP server (models stay loaded) or one Python script
-with `from earshot import api`.
+(~20-40 s) before it answers (`measure`, `sfx` and `kit` load none): for more than a few calls use the MCP server
+(models stay loaded) or one Python script with `from earshot import api`.
What an agent sees when it listens to that film with `earshot sheet` (frames, labelled sound events, spectrogram,
loudness, sync to the beat):
diff --git a/earshot/__init__.py b/earshot/__init__.py
index f688976..00b0045 100644
--- a/earshot/__init__.py
+++ b/earshot/__init__.py
@@ -12,7 +12,7 @@ or explicitly: `from earshot import api` / `from earshot.describe import describ
"""
import importlib
-__version__ = '0.3.0.dev0'
+__version__ = '0.3.0'
# modules that are callable as their main function (see _callable.py)
_CALLABLE = {'describe', 'match', 'compare', 'realness', 'timeline', 'sheet', 'critique', 'profile'}
diff --git a/pyproject.toml b/pyproject.toml
index f635d12..49d7de7 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
[project]
name = "earshot"
-version = "0.3.0.dev0"
+version = "0.3.0"
description = "Ears for coding agents: describe, match, search, compare, time-align and critique sound files an agent cannot hear."
readme = "README.md"
requires-python = ">=3.10"