---
title: VoxSplit
emoji: 🎙️
colorFrom: purple
colorTo: pink
sdk: docker
app_port: 7860
pinned: false
---

# Audio Transcription & Gender Detection (POC)

Upload a `.wav` file and get a **diarized, timestamped transcript** (via the
[Sarvam AI](https://sarvam.ai) `saaras:v3` batch API) plus a **per-speaker
gender estimate**. The transcript is synced to audio playback — the active
segment highlights as it plays, and clicking a segment seeks to it.

## How it works

1. The WAV is uploaded to a small FastAPI backend.
2. The backend runs a Sarvam **batch STT job** with `with_diarization=True`,
   which returns speaker-labelled segments with start/end timestamps.
3. For each speaker, the backend pools all of their audio and runs the
   [`prithivMLmods/Common-Voice-Gender-Detection`](https://huggingface.co/prithivMLmods/Common-Voice-Gender-Detection)
   wav2vec2 classifier, returning softmax **female / male** probabilities. Below
   a 0.6 confidence floor (or with too little audio) the speaker is marked
   **uncertain**.
4. The frontend renders the audio player, a speaker legend, and the synced
   transcript.

> The gender model is downloaded from HuggingFace on first run (~360 MB) and
> cached. It's a trained classifier (~98% reported accuracy) but can still err
> on children, atypical voices, or noisy/short audio.

## Setup

```bash
cd audio-gender-detection
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

cp .env.example .env   # then add your Sarvam API key
```

`.env`:

```
SARVAM_API_KEY=your_sarvam_api_key_here
NUM_SPEAKERS=2
```

(You can also paste the key directly into the UI instead of using `.env`.)

## Run

```bash
uvicorn backend.main:app --reload --port 8000
```

Open http://localhost:8000

## Notes

- Diarization is **only** available through Sarvam's Batch API, so processing is
  asynchronous — longer files take longer.
- Uploaded files land in `uploads/` (gitignored). Clean it up periodically.
- `librosa`/`soundfile` need a working audio backend; on macOS these install
  cleanly via pip. On Linux you may need `libsndfile1` (`apt install libsndfile1`).