AudioQL

A semantic layer* for audio.

AudioQL wraps Whisper, pyannote, YAMNet and friends behind one small API. You point it at an audio file and get a semantic timeline — a single stream of events ("speech", "laughter", "music", "silence", ...) you can query with plain English:

from audioql import Audio

audio = Audio("meeting.mp3")

audio.find("laughter")               # all the laughs
audio.find("music after applause")   # sequencing works too
audio.find("speaker:SPEAKER_00")     # one speaker's turns
audio.search("someone discussing AI")  # keyword search over the transcript

No model-specific APIs leak out. Every backend produces the same TimelineEvent, so swapping Whisper for something else doesn't change your code.

Install

The core package is small and has no AI dependencies:

pip install audioql

Model backends are optional extras — install only what you use:

pip install "audioql[whisper]"        # speech-to-text
pip install "audioql[diarization]"    # speaker diarization
pip install "audioql[events]"         # laughter, applause, music detection
pip install "audioql[all]"            # everything

Quickstart

from audioql import Audio

audio = Audio("meeting.mp3")

print(audio.duration)                  # seconds
print(audio.sample_rate)

transcript = audio.transcript()        # needs audioql[whisper]
print(transcript.text)
for seg in transcript.segments:
    print(seg.start, seg.end, seg.text)

print(audio.speakers())                # needs audioql[diarization]

for event in audio.find("laughter"):
    print(event.start, event.end, round(event.confidence, 2))

Analysis runs lazily and the results are cached, so calling timeline(), find(), transcript() and search() on the same Audio only analyzes the file once.

Configuration

Backends are configured with keyword arguments to Audio:

import os

audio = Audio(
    "meeting.mp3",
    whisper={"model": "small", "device": "cpu"},
    diarization={"hf_token": os.getenv("HF_TOKEN")},
)

hf_token also falls back to the HF_TOKEN environment variable, so most setups just work.

The diarization plugin needs a Hugging Face access token and you must accept the user conditions on the pyannote/speaker-diarization-3.1 model page.

How it works

audio file
  → loader                 (decodes to mono float32)
  → plugins                (speech, speaker, events, silence)
  → timeline builder       (merges events, fills gaps, detects questions)
  → query engine           (find / search over the timeline)

Plugins are auto-enabled when their dependencies are installed, and disabled when they're not. You can also pass plugins and disabled_plugins to take full control.

Development

python -m venv .venv
.venv\Scripts\activate     # or: source .venv/bin/activate
pip install -e ".[dev]"
pytest

License

MIT