Resonator

AI-powered text-to-speech workspace built on Kokoro TTS.
Generate audio, organize it in projects, and manage it through a full React + FastAPI stack.

---

What Resonator does

Resonator converts text to speech using local Kokoro model assets, then helps users manage generated audio in a project-focused workspace.

Core capabilities

• Text-to-speech generation with bundled Kokoro voices
• Generation controls for speed, pitch, sample rate, and output format (WAV/MP3/OGG)
• Async generation jobs with status polling and cancellation
• Project workspace with folders, collections, tags, search, and bulk actions
• Audio storage management via Supabase Storage (upload, browse, download, delete)
• Authentication flows (email/password, OTP verification, password reset, optional Google OAuth)

---

Quick architecture

flowchart LR
    A[React + TypeScript frontend] -->|REST API| B[FastAPI backend]
    B --> C[Kokoro model assets]
    B --> D[(SQLite or PostgreSQL)]
    B --> E[Supabase Storage]

Loading

---

Tech stack

Layer	Stack
Frontend	React 18, TypeScript, Vite, Tailwind CSS, Radix UI
Backend	Python 3.11, FastAPI, SQLAlchemy, Uvicorn
Audio	Kokoro, PyTorch, TorchAudio, Pydub
Data	SQLite (local default), PostgreSQL (recommended for production)
Storage	Supabase Storage
Auth	Session-first auth, OTP email verification, optional Google OAuth

---

Repository layout

.
├── frontend/
│   ├── src/components/
│   ├── src/pages/
│   └── src/services/
├── backend/
│   ├── app/routes/
│   ├── app/services/
│   ├── app/middleware/
│   ├── database/
│   └── models/kokoro/
└── README.md

---

Local setup

1) Clone and download model assets

git clone https://github.com/rishabhmandavlia/Resonator.git
cd Resonator
git lfs install
git lfs pull

Yes, cd Resonator is the correct directory after cloning from that URL.

Check these exist before running the API:

• backend/models/kokoro/kokoro-v1_0.pth
• files inside backend/models/kokoro/voices/

2) Backend setup (FastAPI)

Create backend/.env:

ENVIRONMENT=development
SECRET_KEY=replace-with-a-long-random-secret
OAUTH_TOKEN_ENCRYPTION_SECRET=replace-with-a-different-long-random-secret
ALLOWED_ORIGINS=http://localhost:3000
FRONTEND_URL=http://localhost:3000

# Optional locally (SQLite default if omitted)
# DATABASE_URL=postgresql://user:password@host:5432/dbname

# Required for generated audio + storage library
SUPABASE_URL=https://<project-ref>.supabase.co
SUPABASE_SERVICE_ROLE_KEY=<service-role-key>
SUPABASE_STORAGE_BUCKET=audio-generations

# Optional Google OAuth
# GOOGLE_OAUTH_CLIENT_ID=<client-id>
# GOOGLE_OAUTH_CLIENT_SECRET=<client-secret>
# OAUTH_CALLBACK_BASE_URL=http://localhost:8000

Run backend:

cd backend
python -m venv .venv

# Windows PowerShell
.\.venv\Scripts\Activate.ps1

# macOS/Linux
# source .venv/bin/activate

python -m pip install --upgrade pip
pip install -r requirements.txt
uvicorn app.main:app --reload --port 8000

Backend URLs:

• API root: http://localhost:8000
• Swagger docs: http://localhost:8000/docs

3) Frontend setup (Vite)

Create frontend/.env:

VITE_API_URL=http://localhost:8000

Run frontend:

cd frontend
bun install
bun run dev

Frontend URL: http://localhost:3000

---

Commands

Frontend (frontend/)

Command	Purpose
bun run dev	Start dev server
bun run build	Build production assets to frontend/build/
bun run preview	Preview production build
bun run type-check	TypeScript checks

Backend (backend/)

Command	Purpose
python -m compileall app database	Quick compile/syntax validation

---

API surface (high-level)

Prefix	Responsibility
/api/auth	Auth, OTP verification, session/account management, OAuth
/api/projects	Projects, generations, folders, collections, tags, sharing, analytics, voices
/api/audio	Storage browsing, upload/download, proxying, deletion
/health	Health check

---

Deployment notes

• Use PostgreSQL in production (SQLite is for local/dev convenience).
• Keep SUPABASE_SERVICE_ROLE_KEY backend-only.
• Set secure cookie + strict origins in production:
  • AUTH_SESSION_COOKIE_SECURE=true
  • HTTPS FRONTEND_URL
  • restricted ALLOWED_ORIGINS
• Set VITE_API_URL to your deployed backend origin.
• If using Vercel frontend deploys, keep vercel.json SPA rewrites.