# leonxlnx/earshot architecture

> Architecture diagram of the GitHub repository leonxlnx/earshot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/leonxlnx/earshot
- Repository: https://github.com/leonxlnx/earshot

## Overview

Earshot gives coding agents audio analysis, sound search, film-level listening and critique, plus code-based sound generation and fit-to-recipe workflows. The main path is an agent request through a CLI, Python API or MCP surface, into the relevant analysis or synthesis capability and back as a readable report or media artifact. The graph preserves the README’s major product branches; unsampled modules are represented by their exact paths, but their internal calls are omitted unless documented or visible in the index.

Main entry points: [`earshot/cli.py`](https://github.com/leonxlnx/earshot/blob/main/earshot/cli.py) (CLI), [`earshot/timeline.py`](https://github.com/leonxlnx/earshot/blob/main/earshot/timeline.py) (Listening timeline), [`earshot/models/clap.py`](https://github.com/leonxlnx/earshot/blob/main/earshot/models/clap.py) (CLAP model), [`earshot/search.py`](https://github.com/leonxlnx/earshot/blob/main/earshot/search.py) (Rank and find)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Agent interfaces"]
  node_cli["CLI<br/>[cli.py]"]
  node_api["Python API<br/>[api.py]"]
  node_mcp["MCP server<br/>[mcp_server.py]"]
end

subgraph group_analysis["Audio understanding"]
  node_describe["Describe audio<br/>[describe.py]"]
  node_match["Match description<br/>[match.py]"]
  node_search["Rank and find<br/>[search.py]"]
  node_compare["Compare sounds<br/>[compare.py]"]
  node_realness["Assess realness<br/>[realness.py]"]
  node_features["Measure audio<br/>[features.py]"]
end

subgraph group_film["Film listening"]
  node_timeline["Listening timeline<br/>[timeline.py]"]
  node_video["Video inspection<br/>[video.py]"]
  node_sheet["Annotated sheet<br/>[sheet.py]"]
  node_critique["Film scorecard<br/>[critique.py]"]
  node_profile["Reference profile<br/>[profile.py]"]
end

subgraph group_forge["Sound creation"]
  node_forge["Forge workflow<br/>[__init__.py]"]
  node_recipes["Synthesis recipes"]
  node_dsp["Synthesis DSP<br/>[dsp.py]"]
  node_searchopt["Candidate search<br/>[search.py]"]
  node_critic["Sound critic<br/>[critic.py]"]
  node_polish["Artifact polish<br/>[polish.py]"]
  node_tone["Reference tone checks<br/>[tone.py]"]
  node_fit["Fit recording to code"]
  node_bank["Bank SFX and kits<br/>[bank.py]"]
end

subgraph group_runtime["Shared runtime"]
  node_audio["Audio decoding<br/>[audio.py]"]
  node_vocab["Sound vocabulary<br/>[vocab.py]"]
  node_clap["CLAP model<br/>[clap.py]"]
  node_ast["AudioSet model<br/>[ast.py]"]
  node_hub["Model cache and loading<br/>[hub.py]"]
  node_config["Runtime configuration<br/>[config.py]"]
  node_report["Result formatting<br/>[report.py]"]
end

node_agent(("Coding agent"))

node_agent -->|"invokes"| node_cli
node_agent -->|"uses"| node_api
node_agent -->|"uses"| node_mcp
node_cli -->|"routes command"| node_describe
node_cli -->|"routes command"| node_match
node_cli -->|"routes commands"| node_search
node_cli -->|"routes commands"| node_compare
node_cli -->|"routes command"| node_realness
node_cli -->|"routes measure"| node_features
node_cli -->|"routes command"| node_timeline
node_cli -->|"routes command"| node_sheet
node_cli -->|"routes command"| node_critique
node_cli -->|"routes command"| node_profile
node_cli -->|"routes command"| node_forge
node_cli -->|"routes command"| node_fit
node_cli -->|"routes commands"| node_bank
node_cli -->|"formats errors"| node_report
node_search -->|"embeds and scores"| node_vocab
node_search -->|"loads segments"| node_audio
node_match -->|"scores descriptions"| node_vocab
node_features -->|"loads audio"| node_audio
node_vocab -->|"embeds audio and text"| node_clap
node_clap -->|"ensures model"| node_hub
node_clap -->|"reads settings"| node_config
node_hub -->|"reads cache settings"| node_config
node_timeline -->|"loads soundtrack"| node_audio
node_timeline -->|"inspects picture"| node_video
node_timeline -->|"measures events"| node_features
node_timeline -->|"labels spans"| node_clap
node_timeline -->|"tags audio"| node_ast
node_critique -->|"scores against profile"| node_profile
node_forge -->|"renders recipes"| node_recipes
node_forge -->|"optimizes candidates"| node_searchopt
node_searchopt -->|"scores candidates"| node_critic
node_searchopt -->|"pre-screens renders"| node_dsp
node_critic -->|"checks artifacts"| node_polish
node_critic -->|"checks tonal balance"| node_tone
node_fit -.->|"generates recipe code"| node_dsp
node_bank -->|"aims sounds at picture"| node_video
node_describe -.->|"returns summary"| node_report
node_timeline -->|"formats results"| node_report

click node_cli "https://github.com/leonxlnx/earshot/blob/main/earshot/cli.py"
click node_api "https://github.com/leonxlnx/earshot/blob/main/earshot/api.py"
click node_mcp "https://github.com/leonxlnx/earshot/blob/main/earshot/mcp_server.py"
click node_describe "https://github.com/leonxlnx/earshot/blob/main/earshot/describe.py"
click node_match "https://github.com/leonxlnx/earshot/blob/main/earshot/match.py"
click node_search "https://github.com/leonxlnx/earshot/blob/main/earshot/search.py"
click node_compare "https://github.com/leonxlnx/earshot/blob/main/earshot/compare.py"
click node_realness "https://github.com/leonxlnx/earshot/blob/main/earshot/realness.py"
click node_features "https://github.com/leonxlnx/earshot/blob/main/earshot/features.py"
click node_timeline "https://github.com/leonxlnx/earshot/blob/main/earshot/timeline.py"
click node_video "https://github.com/leonxlnx/earshot/blob/main/earshot/video.py"
click node_sheet "https://github.com/leonxlnx/earshot/blob/main/earshot/sheet.py"
click node_critique "https://github.com/leonxlnx/earshot/blob/main/earshot/critique.py"
click node_profile "https://github.com/leonxlnx/earshot/blob/main/earshot/profile.py"
click node_forge "https://github.com/leonxlnx/earshot/blob/main/earshot/forge/__init__.py"
click node_recipes "https://github.com/leonxlnx/earshot/tree/main/earshot/forge/recipes"
click node_dsp "https://github.com/leonxlnx/earshot/blob/main/earshot/forge/dsp.py"
click node_searchopt "https://github.com/leonxlnx/earshot/blob/main/earshot/forge/search.py"
click node_critic "https://github.com/leonxlnx/earshot/blob/main/earshot/forge/critic.py"
click node_polish "https://github.com/leonxlnx/earshot/blob/main/earshot/forge/polish.py"
click node_tone "https://github.com/leonxlnx/earshot/blob/main/earshot/forge/tone.py"
click node_fit "https://github.com/leonxlnx/earshot/tree/main/earshot/forge/fit"
click node_bank "https://github.com/leonxlnx/earshot/blob/main/earshot/forge/bank.py"
click node_audio "https://github.com/leonxlnx/earshot/blob/main/earshot/audio.py"
click node_vocab "https://github.com/leonxlnx/earshot/blob/main/earshot/vocab.py"
click node_clap "https://github.com/leonxlnx/earshot/blob/main/earshot/models/clap.py"
click node_ast "https://github.com/leonxlnx/earshot/blob/main/earshot/models/ast.py"
click node_hub "https://github.com/leonxlnx/earshot/blob/main/earshot/models/hub.py"
click node_config "https://github.com/leonxlnx/earshot/blob/main/earshot/config.py"
click node_report "https://github.com/leonxlnx/earshot/blob/main/earshot/report.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_api,node_mcp toneBlue
class node_describe,node_match,node_search,node_compare,node_realness,node_features toneAmber
class node_timeline,node_video,node_sheet,node_critique,node_profile toneMint
class node_forge,node_recipes,node_dsp,node_searchopt,node_critic,node_polish,node_tone,node_fit,node_bank toneRose
class node_audio,node_vocab,node_clap,node_ast,node_hub,node_config,node_report,node_agent toneIndigo
```

## Components

### Agent interfaces

- [CLI](https://github.com/leonxlnx/earshot/blob/main/earshot/cli.py): `earshot/cli.py`
- [Python API](https://github.com/leonxlnx/earshot/blob/main/earshot/api.py): `earshot/api.py`
- [MCP server](https://github.com/leonxlnx/earshot/blob/main/earshot/mcp_server.py): `earshot/mcp_server.py`

### Audio understanding

- [Describe audio](https://github.com/leonxlnx/earshot/blob/main/earshot/describe.py): `earshot/describe.py`
- [Match description](https://github.com/leonxlnx/earshot/blob/main/earshot/match.py): `earshot/match.py`
- [Rank and find](https://github.com/leonxlnx/earshot/blob/main/earshot/search.py): `earshot/search.py`
- [Compare sounds](https://github.com/leonxlnx/earshot/blob/main/earshot/compare.py): `earshot/compare.py`
- [Assess realness](https://github.com/leonxlnx/earshot/blob/main/earshot/realness.py): `earshot/realness.py`
- [Measure audio](https://github.com/leonxlnx/earshot/blob/main/earshot/features.py): `earshot/features.py`

### Film listening

- [Listening timeline](https://github.com/leonxlnx/earshot/blob/main/earshot/timeline.py): `earshot/timeline.py`
- [Video inspection](https://github.com/leonxlnx/earshot/blob/main/earshot/video.py): `earshot/video.py`
- [Annotated sheet](https://github.com/leonxlnx/earshot/blob/main/earshot/sheet.py): `earshot/sheet.py`
- [Film scorecard](https://github.com/leonxlnx/earshot/blob/main/earshot/critique.py): `earshot/critique.py`
- [Reference profile](https://github.com/leonxlnx/earshot/blob/main/earshot/profile.py): `earshot/profile.py`

### Sound creation

- [Forge workflow](https://github.com/leonxlnx/earshot/blob/main/earshot/forge/__init__.py): `earshot/forge/__init__.py`
- [Synthesis recipes](https://github.com/leonxlnx/earshot/tree/main/earshot/forge/recipes): `earshot/forge/recipes`
- [Synthesis DSP](https://github.com/leonxlnx/earshot/blob/main/earshot/forge/dsp.py): `earshot/forge/dsp.py`
- [Candidate search](https://github.com/leonxlnx/earshot/blob/main/earshot/forge/search.py): `earshot/forge/search.py`
- [Sound critic](https://github.com/leonxlnx/earshot/blob/main/earshot/forge/critic.py): `earshot/forge/critic.py`
- [Artifact polish](https://github.com/leonxlnx/earshot/blob/main/earshot/forge/polish.py): `earshot/forge/polish.py`
- [Reference tone checks](https://github.com/leonxlnx/earshot/blob/main/earshot/forge/tone.py): `earshot/forge/tone.py`
- [Fit recording to code](https://github.com/leonxlnx/earshot/tree/main/earshot/forge/fit): `earshot/forge/fit`
- [Bank SFX and kits](https://github.com/leonxlnx/earshot/blob/main/earshot/forge/bank.py): `earshot/forge/bank.py`

### Shared runtime

- [Audio decoding](https://github.com/leonxlnx/earshot/blob/main/earshot/audio.py): `earshot/audio.py`
- [Sound vocabulary](https://github.com/leonxlnx/earshot/blob/main/earshot/vocab.py): `earshot/vocab.py`
- [CLAP model](https://github.com/leonxlnx/earshot/blob/main/earshot/models/clap.py): `earshot/models/clap.py`
- [AudioSet model](https://github.com/leonxlnx/earshot/blob/main/earshot/models/ast.py): `earshot/models/ast.py`
- [Model cache and loading](https://github.com/leonxlnx/earshot/blob/main/earshot/models/hub.py): `earshot/models/hub.py`
- [Runtime configuration](https://github.com/leonxlnx/earshot/blob/main/earshot/config.py): `earshot/config.py`
- [Result formatting](https://github.com/leonxlnx/earshot/blob/main/earshot/report.py): `earshot/report.py`

### Other components

- **Coding agent**

## Connections

- Coding agent → CLI: invokes
- Coding agent → Python API: uses
- Coding agent → MCP server: uses
- CLI → Describe audio: routes command
- CLI → Match description: routes command (evidence: `earshot/match.py`)
- CLI → Rank and find: routes commands (evidence: `earshot/search.py`)
- CLI → Compare sounds: routes commands
- CLI → Assess realness: routes command
- CLI → Measure audio: routes measure (evidence: `earshot/features.py`)
- CLI → Listening timeline: routes command (evidence: `earshot/timeline.py`)
- CLI → Annotated sheet: routes command
- CLI → Film scorecard: routes command
- CLI → Reference profile: routes command
- CLI → Forge workflow: routes command (evidence: `earshot/forge/__init__.py`)
- CLI → Fit recording to code: routes command
- CLI → Bank SFX and kits: routes commands
- CLI → Result formatting: formats errors (evidence: `earshot/cli.py`)
- Rank and find → Sound vocabulary: embeds and scores (evidence: `earshot/search.py`)
- Rank and find → Audio decoding: loads segments (evidence: `earshot/search.py`)
- Match description → Sound vocabulary: scores descriptions (evidence: `earshot/match.py`)
- Measure audio → Audio decoding: loads audio (evidence: `earshot/features.py`)
- Sound vocabulary → CLAP model: embeds audio and text (evidence: `earshot/vocab.py`)
- CLAP model → Model cache and loading: ensures model (evidence: `earshot/models/clap.py`)
- CLAP model → Runtime configuration: reads settings (evidence: `earshot/models/clap.py`)
- Model cache and loading → Runtime configuration: reads cache settings (evidence: `earshot/models/hub.py`)
- Listening timeline → Audio decoding: loads soundtrack (evidence: `earshot/timeline.py`)
- Listening timeline → Video inspection: inspects picture (evidence: `earshot/timeline.py`)
- Listening timeline → Measure audio: measures events (evidence: `earshot/timeline.py`)
- Listening timeline → CLAP model: labels spans (evidence: `earshot/timeline.py`)
- Listening timeline → AudioSet model: tags audio (evidence: `earshot/timeline.py`)
- Film scorecard → Reference profile: scores against profile
- Forge workflow → Synthesis recipes: renders recipes (evidence: `earshot/forge/__init__.py`)
- Forge workflow → Candidate search: optimizes candidates (evidence: `earshot/forge/__init__.py`)
- Candidate search → Sound critic: scores candidates (evidence: `earshot/forge/search.py`)
- Candidate search → Synthesis DSP: pre-screens renders (evidence: `earshot/forge/search.py`)
- Sound critic → Artifact polish: checks artifacts (evidence: `earshot/forge/critic.py`)
- Sound critic → Reference tone checks: checks tonal balance (evidence: `earshot/forge/critic.py`)
- Fit recording to code → Synthesis DSP: generates recipe code
- Bank SFX and kits → Video inspection: aims sounds at picture
- Describe audio → Result formatting: returns summary
- Listening timeline → Result formatting: formats results (evidence: `earshot/timeline.py`)