Metadata-Version: 2.5
Name: audel
Version: 1.0.0
Summary: Ears for AI Agents — a machine-graded audio feedback loop coding agents consume to self-correct before claiming done.
Project-URL: Homepage, https://github.com/amitpatole/audel
Project-URL: Repository, https://github.com/amitpatole/audel
Project-URL: Issues, https://github.com/amitpatole/audel/issues
Author-email: Amit Patole <amit.patole@gmail.com>
License: MIT
License-File: LICENSE
Keywords: agents,ai,asr,audio,llm,mcp,speech,voice
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Sound/Audio :: Analysis
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.11
Requires-Dist: agentsensory>=0.1
Requires-Dist: filelock>=3.12
Requires-Dist: numpy>=1.26
Requires-Dist: platformdirs>=4.0
Requires-Dist: pydantic-settings>=2.2
Requires-Dist: pydantic>=2.6
Requires-Dist: typer>=0.12
Provides-Extra: all
Requires-Dist: anthropic>=0.40; extra == 'all'
Requires-Dist: fastapi>=0.110; extra == 'all'
Requires-Dist: faster-whisper>=1.0; extra == 'all'
Requires-Dist: google-genai>=0.3; extra == 'all'
Requires-Dist: httpx>=0.27; extra == 'all'
Requires-Dist: librosa>=0.10; extra == 'all'
Requires-Dist: mcp>=1.2; extra == 'all'
Requires-Dist: playwright>=1.44; extra == 'all'
Requires-Dist: pyjwt[crypto]>=2.15; extra == 'all'
Requires-Dist: python-multipart>=0.0.9; extra == 'all'
Requires-Dist: torch>=2.2; extra == 'all'
Requires-Dist: transformers>=4.40; extra == 'all'
Requires-Dist: uvicorn[standard]>=0.29; extra == 'all'
Provides-Extra: asr
Requires-Dist: faster-whisper>=1.0; extra == 'asr'
Provides-Extra: clap
Requires-Dist: librosa>=0.10; extra == 'clap'
Requires-Dist: torch>=2.2; extra == 'clap'
Requires-Dist: transformers>=4.40; extra == 'clap'
Provides-Extra: cloud
Requires-Dist: anthropic>=0.40; extra == 'cloud'
Requires-Dist: google-genai>=0.3; extra == 'cloud'
Requires-Dist: httpx>=0.27; extra == 'cloud'
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Provides-Extra: mcp
Requires-Dist: mcp>=1.2; extra == 'mcp'
Provides-Extra: oidc
Requires-Dist: pyjwt[crypto]>=2.15; extra == 'oidc'
Provides-Extra: render
Requires-Dist: playwright>=1.44; extra == 'render'
Provides-Extra: serve
Requires-Dist: fastapi>=0.110; extra == 'serve'
Requires-Dist: python-multipart>=0.0.9; extra == 'serve'
Requires-Dist: uvicorn[standard]>=0.29; extra == 'serve'
Description-Content-Type: text/markdown

# Audel — ears for AI agents and media pipelines

[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.23609200.svg)](https://doi.org/10.5281/zenodo.23609200)

Audel **hears** audio and then **listens** to it. It returns a machine verdict (`pass`, `warn` or
`fail`) with findings grounded to the millisecond, so an agent or a pipeline can fix the problem
before it ships.

- **Hearing** asks whether the signal is healthy and on spec. It grades every track against a
  delivery spec (EBU R128, R128 s1, ATSC A/85, OP-59, ARIB TR-B32, Netflix-style speech-gated,
  Spotify, YouTube, Apple), covering integrated, short-term and momentary loudness, true peak,
  clipping, silence, truncation, dead or inverted or out-of-phase channels, DC offset, mains hum
  and noise floor.
- **Listening** asks whether the right thing was said and whether a person could follow it. It
  checks script adherence with time-grounded omissions and substitutions, required and forbidden
  wording, pace, dead air, intelligibility, captions (SRT and WebVTT text, offset, reading rate)
  and language per track. With an opt-in model it also checks whether key messages landed and how
  they were delivered.

Hearing and offline listening never touch the network. Model-assisted understanding can run
entirely on your own hardware through an on-prem Ollama server.

## Install

```bash
pip install audel                 # light base: ffmpeg + DSP
pip install "audel[asr]"          # local faster-whisper: listening
pip install "audel[serve,oidc]"   # REST service with JWT auth
audel doctor
audel demo                        # broken clip -> FAIL, fixed clip -> PASS, no key
```

Audel needs `ffmpeg` on the PATH.

## Use it

```bash
audel check  promo.wav --spec ebu_r128_s1
audel listen read.wav --script script.txt --captions read.srt --require "terms and conditions apply"
audel qc     master.wav --spec atsc_a85 --html qc.html --json qc.json
```

```python
from audel import check, listen

heard = await check("promo.wav", spec="ebu_r128_s1")
listened = await listen("read.wav", script=open("script.txt").read())
print(listened.verdict, listened.listening.script_adherence)
```

## Run it as a service

`audel serve` provides sync grading and async jobs. It can ingest from signed object-store URLs,
and it exposes Prometheus metrics and a JSON audit log. Auth is per-tenant tokens or OIDC JWT,
with optional mutual TLS, per-tenant rate limits, and an egress policy (`allow`, `local-only` or
`deny`). A hardened container and Helm chart ship in the repository. See
[Running as a service](https://amitpatole.github.io/audel/deployment/) and the
[threat model](https://amitpatole.github.io/audel/security/).

## How accurate is it

`audel bench` reports precision and recall per check. It runs on a seeded synthetic corpus out
of the box, and on your own labelled deliverables with `--corpus`. Measure it on your material
before you make it a gate. See [Checks reference](https://amitpatole.github.io/audel/checks/).

## Part of a family

Audel is the ears. [AgentVision](https://github.com/amitpatole/agent-vision) is the eyes and
[Verel](https://github.com/amitpatole/verel) is the brain. All three speak one contract,
[`agentsensory`](https://pypi.org/project/agentsensory/), and `pip install "verel[hearing]"`
pulls in the whole stack.

📖 **Docs:** [amitpatole.github.io/audel](https://amitpatole.github.io/audel/) ·
**Changelog:** [CHANGELOG.md](CHANGELOG.md) · **Security:** [SECURITY.md](SECURITY.md)

## License

MIT © Amit Patole
