README.md

---
title: Spell Recorder
emoji: ✨
sdk: gradio
sdk_version: "4.44.1"
app_file: app.py
pinned: false
---

# Spell Recorder (Gradio)

Collect microphone recordings for a small set of Harry Potter spells and store them in MongoDB for training a classifier.

Spells collected:
- Lumos
- Nox
- Alohomora
- Wingardium Leviosa
- Accio
- Reparo

## How it works
- Enter a username (used in metadata; sanitized to safe characters).
- Record with your microphone (preferred) or upload an audio file for any spell.
- Click Submit.
- Audio is resampled to 16 kHz mono and stored in MongoDB GridFS with metadata (username, spell, timestamp).
- A live counter shows how many spells are selected (recorded/uploaded) before submitting.

## Run locally

Requirements (see `requirements.txt`):
- gradio
- numpy
- soundfile
- scipy

On Windows PowerShell:

```powershell
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
python app.py
```

Then open the printed local URL in your browser.

1. Create a new Space (Gradio) in your account.
2. Upload `app.py`, `requirements.txt`, and optionally `README.md`.
3. Spaces will auto-build and run the app.
4. Submissions are stored directly in your MongoDB (GridFS), not in the Space filesystem.

Notes:
- Microphone recording is enabled in the browser; no need to upload.
- Ensure MongoDB secrets are configured; otherwise the app will display that DB is not configured.

## MongoDB configuration (Spaces secrets)
Set these in your Space → Settings → Variables and secrets:
- `MONGO_URI`: your MongoDB connection string (e.g., from MongoDB Atlas)
- `MONGO_DB`: database name (default: `spells`)
- `MONGO_BUCKET`: GridFS bucket/collection prefix (default: `recordings`)

Locally (PowerShell) you can set temporarily for a session:

```powershell
$env:MONGO_URI = "mongodb+srv://user:pass@cluster.mongodb.net/?retryWrites=true&w=majority"
$env:MONGO_DB = "spells"
$env:MONGO_BUCKET = "recordings"
python app.py
```

## Privacy and consent
- Only collect voices from people who consent to being recorded.
- Consider informing contributors how their audio will be used and stored.
- Do not collect sensitive information in the username.

## Why 16 kHz mono?
Standardizing sample rate and channels simplifies downstream model training and reduces storage.