# SnoreStopper v2

SnoreStopper is a self-hosted Python + web UI project for collecting night audio samples, labeling snore events, and training a local classifier.

This starter build gives you:
- Audio input device discovery from the server machine
- On-demand audio sample capture to compressed FLAC files
- Spectrogram generation for each sample
- Browser-based labeling workflow (`snore`, `not_snore`, `unclear`)
- Local model training with scikit-learn
- Per-sample detection using the trained model
- Overnight sample gathering with configurable clip interval
- Snore watch proposal queue with thumbs up/down review gating before training

## Project Layout

```text
SnoreStopper_v2/
  data/
    raw/                # Recorded FLAC clips
    spectrograms/       # PNG spectrogram images
    models/             # Trained model artifacts
    meta/               # Metadata JSON (samples, labels)
  src/snorestopper/
    main.py             # FastAPI app and endpoints
    audio.py            # Device listing and recording
    features.py         # Audio IO + spectrogram + features
    training.py         # Local model training/prediction
    storage.py          # Metadata persistence
    schemas.py          # API request/response models
  web/
    index.html
    styles.css
    app.js
  requirements.txt
  pyproject.toml
```

## Quick Start (Windows PowerShell)

1. Create and activate a virtual environment.
```powershell
python -m venv .venv
.\.venv\Scripts\Activate.ps1
```

2. Install dependencies.
```powershell
python -m pip install --upgrade pip
pip install -r requirements.txt
```

3. Start the local server.
```powershell
uvicorn --app-dir src snorestopper.main:app --reload --host 127.0.0.1 --port 8000
```

4. Open the app.
- Browser: `http://127.0.0.1:8000`
- API docs: `http://127.0.0.1:8000/docs`

## Typical Workflow

1. Choose an input device and record short clips over several nights.
2. Review each clip and spectrogram.
3. Label clips in the UI.
4. Train the model locally from your labeled dataset.
5. Start an overnight run with `auto_watch` enabled to capture clips and queue predictions.
6. Approve or invert watch proposals with thumbs up/down in the review queue.
7. Retrain the model from approved labels.

## Overnight + Snore Watch Flow

- `Overnight Gatherer` captures clips on a fixed interval for N hours.
- If `auto_watch` is enabled, each clip is scored by the local model.
- Predictions are stored as pending proposals and are **not** used for training yet.
- You decide per clip:
  - `Thumbs Up` -> proposal becomes approved training label
  - `Thumbs Down` -> proposal is inverted (`snore <-> not_snore`) and approved for training
- Manual labels still work and can override watch proposals.

## Notes

- This is intentionally self-hosted and local-first: all recorded data, labels, and model artifacts stay on your machine.
- The current model is a baseline (RandomForest + handcrafted spectral features) so you can get to a working loop quickly.
- Recording quality and label quality are the main drivers of model performance.

## Environment Variables (Optional)

- `SNORESTOPPER_ROOT`: Override project root directory
- `SNORESTOPPER_SAMPLE_RATE`: Default `16000`
- `SNORESTOPPER_CHANNELS`: Default `1`
- `SNORESTOPPER_MIN_DURATION`: Default `2`
- `SNORESTOPPER_MAX_DURATION`: Default `90`
- `SNORESTOPPER_MODEL_FILE`: Default `snore_classifier.joblib`

## Next Build Targets

- Scheduled overnight capture jobs
- Better event segmentation and confidence thresholds
- Hardware trigger module for anti-snoring actions
- User profiles and per-user local models