Metadata-Version: 2.4
Name: sonarwise
Version: 0.1.2
Summary: Pluggable audio perception engine. Hear. Search. Retrieve.
Author-email: Venkatkumar Rajan <venkatkumarr.vk99@gmail.com>
License: Apache 2.0
Project-URL: Homepage, https://github.com/VK-Ant/sonarwise
Project-URL: Documentation, https://github.com/VK-Ant/sonarwise#readme
Project-URL: Repository, https://github.com/VK-Ant/sonarwise
Project-URL: Issues, https://github.com/VK-Ant/sonarwise/issues
Keywords: audio,speech,retrieval,RAG,transcription,diarization,speaker-recognition,audio-events,whisper,CLAP,perception,search,embeddings,voice-activity-detection,sound-classification
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Sound/Audio :: Analysis
Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24.0
Requires-Dist: tqdm>=4.65.0
Requires-Dist: pyyaml>=6.0
Provides-Extra: whisper
Requires-Dist: openai-whisper>=20231117; extra == "whisper"
Provides-Extra: faster-whisper
Requires-Dist: faster-whisper>=1.0.0; extra == "faster-whisper"
Provides-Extra: clap
Requires-Dist: transformers>=4.30.0; extra == "clap"
Requires-Dist: torch>=2.0.0; extra == "clap"
Requires-Dist: torchaudio>=2.0.0; extra == "clap"
Provides-Extra: diarization
Requires-Dist: pyannote.audio>=3.1.0; extra == "diarization"
Requires-Dist: torch>=2.0.0; extra == "diarization"
Provides-Extra: speaker
Requires-Dist: speechbrain>=1.0.0; extra == "speaker"
Requires-Dist: torch>=2.0.0; extra == "speaker"
Provides-Extra: events
Requires-Dist: torch>=2.0.0; extra == "events"
Requires-Dist: torchaudio>=2.0.0; extra == "events"
Provides-Extra: live
Requires-Dist: sounddevice>=0.4.6; extra == "live"
Provides-Extra: vad
Requires-Dist: silero-vad>=5.0.0; extra == "vad"
Requires-Dist: torch>=2.0.0; extra == "vad"
Provides-Extra: all
Requires-Dist: openai-whisper>=20231117; extra == "all"
Requires-Dist: transformers>=4.30.0; extra == "all"
Requires-Dist: torch>=2.0.0; extra == "all"
Requires-Dist: torchaudio>=2.0.0; extra == "all"
Requires-Dist: pyannote.audio>=3.1.0; extra == "all"
Requires-Dist: speechbrain>=1.0.0; extra == "all"
Requires-Dist: sounddevice>=0.4.6; extra == "all"
Requires-Dist: silero-vad>=5.0.0; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Dynamic: license-file

<p align="center">
  <img src="https://raw.githubusercontent.com/VK-Ant/sonarwise/main/assets/sonarwise_ai.png" alt="sonarwise" width="800"/>
</p>

<h1 align="center">sonarwise</h1>
<p align="center"><b>Pluggable audio perception engine. Hear. Search. Retrieve.</b></p>

<p align="center">
  <a href="https://pypi.org/project/sonarwise"><img src="https://img.shields.io/pypi/v/sonarwise?color=blue" alt="PyPI"/></a>
  <a href="https://github.com/VK-Ant/sonarwise/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-blue" alt="License"></a>
  <a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-3.9+-green" alt="Python"></a>
</p>

---

**sonarwise** indexes any audio like meetings, calls, podcasts, factory floors, lectures and makes it searchable by text, speaker, sound events, or audio similarity. Every component is pluggable: swap transcription, embedding, diarization, or storage without changing your code.

## Features

- **Transcription** : Whisper, Faster Whisper, or bring your own ASR
- **Audio Embeddings** : CLAP joint text-audio space for semantic search
- **Speaker Diarization** : know who said what (pyannote)
- **Speaker Registry** : track speakers across files by voiceprint
- **Audio Event Detection** : detect alarms, machinery, glass breaks, and 50+ sound types
- **Live Streaming** : real-time transcription with keyword and event callbacks
- **Export** : SRT, VTT, JSON, CSV, TXT, meeting notes
- **Pluggable Architecture** : every component swappable via base classes
- **CLI** : full command-line interface

## Install

```bash
# Core (no ML dependencies)
pip install sonarwise

# With all features
pip install sonarwise[all]

# Pick what you need
pip install sonarwise[whisper]          # Whisper transcription
pip install sonarwise[faster-whisper]   # Faster Whisper (CTranslate2)
pip install sonarwise[clap]            # CLAP audio embeddings
pip install sonarwise[diarization]     # Speaker diarization
pip install sonarwise[speaker]         # Speaker identification
pip install sonarwise[events]          # Audio event detection
pip install sonarwise[live]            # Live microphone capture
```

**Requires:** ffmpeg (`sudo apt install ffmpeg` or `brew install ffmpeg`)

## Quick Start

```python
from sonarwise import SonarWise

sw = SonarWise(diarization=True, events=True)

# Index audio
sw.index("meeting.wav")
sw.index_folder("./recordings/")

# Search by text
results = sw.query("budget discussion", top_k=5)
for r in results:
    print(f"[{r.speaker_name}] {r.transcript} (score: {r.score})")

# Search by audio similarity
results = sw.query_audio("alarm_clip.wav", top_k=5)

# Search by speaker
results = sw.query("budget", speaker="Ant", top_k=5)

# Search by event
results = sw.query_events(event="machine_fault", top_k=5)
```

## Speaker Intelligence

```python
# Register a speaker
sw.register_speaker("Ant", reference_audio="ant_voice.wav")

# Query by speaker
results = sw.query("budget", speaker="Ant")

# Speaker timeline
timeline = sw.speaker_timeline("meeting.wav")

# Speaker stats
stats = sw.speaker_stats("meeting.wav")

# Find speaker across files
presence = sw.find_speaker_across(speaker="Ant", folders=["./meetings/"])
```

## Live Mode

```python
sw = SonarWise(mode="live", diarization=True, events=True)

@sw.on("transcript")
def on_speech(segment):
    print(f"[{segment.speaker_name}] {segment.transcript}")

@sw.on("keyword", words=["budget", "deadline", "risk"])
def on_keyword(segment):
    send_alert(segment.transcript)

@sw.on("sound_event", events=["alarm", "glass_break"])
def on_danger(event):
    trigger_alert(event)

sw.listen(source="microphone")
```

## Plug Any Model

Every component is swappable:

```python
from sonarwise import SonarWise
from sonarwise.core.transcriber import BaseTranscriber

class MyTranscriber(BaseTranscriber):
    def transcribe(self, audio):
        return my_model.process(audio)

sw = SonarWise(transcriber=MyTranscriber())
```

**Pluggable slots:**

| Component | Base Class | Default |
|-----------|-----------|---------|
| Transcriber | `BaseTranscriber` | Whisper |
| Audio Embedder | `BaseAudioEmbedder` | CLAP |
| Vector Store | `BaseVectorStore` | SQLite |
| Chunker | `BaseChunker` | Silero VAD |
| Diarizer | `BaseDiarizer` | pyannote |
| Speaker Embedder | `BaseSpeakerEmbedder` | ECAPA-TDNN |
| Event Classifier | `BaseEventClassifier` | PANNs |
| Stream Listener | `BaseStreamListener` | sounddevice |

## CLI

```bash
sonarwise index meeting.wav
sonarwise query "budget discussion"
sonarwise speakers meeting.wav
sonarwise timeline meeting.wav
sonarwise listen --source microphone --on-keyword "budget,risk"
sonarwise export meeting.wav --format srt
sonarwise stats
```

## Export

```python
sw.export("meeting.wav", format="srt", output="subtitles.srt")
sw.export("meeting.wav", format="json", output="segments.json")
sw.export("meeting.wav", format="txt", output="transcript.txt")
sw.export("meeting.wav", format="notes", output="meeting_notes.md")
```

## Ecosystem

sonarwise is part of the VK-Ant AI perception ecosystem:

| Library | Purpose | Tagline |
|---------|---------|---------|
| [SightRAG](https://github.com/VK-Ant/SightRAG) | Visual perception | See. Search. Retrieve. |
| [sonarwise](https://github.com/VK-Ant/sonarwise)| Audio perception | Hear. Search. Retrieve. |
| [adaptive-intelligence](https://github.com/VK-Ant/adaptive-intelligence) | Reasoning & memory | Learn. Remember. Adapt. |
| [llmevalkit](https://github.com/VK-Ant/llmevalkit) | Evaluation | Evaluate. Score. Improve. |

## License

Apache 2.0

## Author

Built by **Venkatkumar Rajan**

- GitHub: https://github.com/VK-Ant
- Portfolio: https://vk-ant.github.io/Venkatkumar
