voxpulse 1.0.0

A lightweight, fast, and AI-powered custom wake word detection system.

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:

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:

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:

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:

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]