Metadata-Version: 2.4
Name: voxpulse
Version: 1.0.0
Summary: A lightweight, fast, and AI-powered custom wake word detection system.
Home-page: https://github.com/itzabhishekgour/VoxPulse
Author: Abhishek Gour
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: scipy
Requires-Dist: librosa
Requires-Dist: sounddevice
Requires-Dist: audiomentations
Requires-Dist: tensorflow
Requires-Dist: soundfile
Requires-Dist: scikit-learn
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# VoxPulse - Custom Wake Word Detection Framework

VoxPulse is a lightweight, offline, and 100% private DIY custom wake-word detection library for Python. Instead of relying on pre-trained corporate wake words like "Alexa" or "Hey Siri", VoxPulse empowers developers to train their own voice assistants with any custom name, in any language!

---

## Why VoxPulse? (Pros & Cons)

### Pros (The Good Stuff)
* **100% Privacy:** Everything runs locally on your machine. No internet required, no voice data is sent to the cloud.
* **Auto-Data Pipeline:** You just provide raw `.wav` recordings. VoxPulse automatically handles background noise mixing, time-stretching, pitch-shifting, and Mel-Spectrogram feature extraction.
* **CPU & Battery Efficient:** Features RMS Silence Gating. The AI model goes to sleep when the room is silent (CPU usage drops to ~0%) and only triggers the neural network when someone speaks.
* **Lightweight:** Uses a custom 2D Convolutional Neural Network (CNN) compiled into TensorFlow Lite (`.tflite`), making it blazing fast even on low-end hardware.

### Cons (The Limitations)
* **DIY Approach:** Since it's a custom framework, there is no pre-trained model. You must spend 5 minutes recording your own voice and room noise to use it.
* **Environment Sensitive:** The accuracy heavily depends on the quality of the background noise (`negative` dataset) you provide during training.

---

## How to Use VoxPulse (Quick Start Guide)

### Step 1: Install the Library
Install VoxPulse directly via pip:
```bash
pip install voxpulse
```

### Step 2: Prepare Your Dataset
Create a folder named `dataset` in your project directory with two sub-folders:

* **dataset/positive/** - Record and save 10-15 short `.wav` files of you saying your custom wake word (e.g., "Hey Friday"). Keep them around 1 to 1.5 seconds long.
* **dataset/negative/** - Record a single 5-10 minute `.wav` file of your normal room background noise (fan sounds, typing, distant talking) and place it here.

### Step 3: Train Your Custom Model
Create a python script (e.g., `train.py`) and run the auto-pipeline:

```python
from voxpulse.model import VoxPulseTrainer

# This single command will automatically augment data, extract features, and train the CNN!
trainer = VoxPulseTrainer(dataset_dir="dataset")
trainer.train_and_export(epochs=20, export_name="my_custom_model.tflite")
```

### Step 4: Run the Inference Engine
Once your `.tflite` model is generated, you can use it to trigger any Python function in real-time. Create `run.py`:

```python
from voxpulse.inference import VoxPulseEngine

def trigger_my_action():
    print("Custom Wake Word Detected! Executing action...")
    # Add your automation code here (e.g., open Spotify, turn on lights)

# Load your newly trained model
engine = VoxPulseEngine(model_path="my_custom_model.tflite", threshold=0.70)

# Start listening in the background
engine.start_listening(on_detect_callback=trigger_my_action)
```

---

## Under the Hood (Architecture)

VoxPulse abstracts away the complexity of audio machine learning. When you call the training function, it executes the following pipeline automatically:

```mermaid
graph TD
    A[Raw Audio: dataset/positive] -->|Step 1: Auto-Augmentation| B[Pitch Shift & Time Stretch]
    D[Background Noise: dataset/negative] -->|Mix Noise| B
    B -->|Step 2: Mel-Spectrogram| C[Feature Matrices]
    C -->|Step 3: CNN Training| E[Keras Sequential Model]
    E -->|Step 4: Compilation| F[Lightweight TFLite Model]
```
