Skip to main content
This guide will walk you through setting up Resonance on your local machine. You’ll have a fully functional text-to-speech platform running in under 15 minutes.

​
Prerequisites

Before you begin, make sure you have the following:
1

Node.js 20.9 or later

Download from nodejs.org or use a version manager like nvm.
node --version  # Should be 20.9.0 or higher
2

Prisma Postgres Database

Sign up for a free database at Prisma Data Platform. You’ll need the connection string.
Any PostgreSQL database will work - Prisma Postgres is recommended for its simplicity.
3

Clerk Account (with Organizations enabled)

Create an account at clerk.com and enable Organizations in your application settings.
4

Cloudflare R2 Bucket

Set up a bucket at Cloudflare R2. The free tier includes 10GB storage.
5

Modal Account

Sign up at modal.com for serverless GPU hosting. Install the CLI:
pip install modal
modal setup
6

Polar Account (Optional)

For billing features, create an account at polar.sh. Use sandbox mode for testing.

​
Installation

1

Clone the repository

git clone https://github.com/code-with-antonio/resonance.git
cd resonance
2

Install dependencies

npm install
This will also run prisma generate automatically via the postinstall script.
3

Configure environment variables

Create a .env.local file in the root directory with the following variables:
.env.local
# Database
DATABASE_URL="postgresql://user:password@host:5432/database"

# Chatterbox TTS (Modal)
CHATTERBOX_API_URL="https://your-modal-endpoint.modal.run"
CHATTERBOX_API_KEY="your-api-key"

# Clerk
CLERK_SECRET_KEY="sk_..."
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY="pk_..."
NEXT_PUBLIC_CLERK_SIGN_IN_URL="/sign-in"
NEXT_PUBLIC_CLERK_SIGN_UP_URL="/sign-up"

# Cloudflare R2
R2_ACCOUNT_ID="your-account-id"
R2_ACCESS_KEY_ID="your-access-key"
R2_SECRET_ACCESS_KEY="your-secret-key"
R2_BUCKET_NAME="your-bucket-name"

# Polar (Billing)
POLAR_ACCESS_TOKEN="your-polar-token"
POLAR_SERVER="sandbox"
POLAR_PRODUCT_ID="your-product-id"

# App
APP_URL="http://localhost:3000"
Keep your .env.local file secure and never commit it to version control.
4

Set up the database

Run the Prisma migrations to create the database schema:
npx prisma migrate deploy
This creates two main tables:
  • Voice - Stores system and custom voice metadata
  • Generation - Stores TTS generation history and parameters

​
Deploy the TTS Engine

The TTS engine runs on Modal’s serverless GPU infrastructure. You need to deploy it before the web app can generate audio.
1

Configure R2 credentials in chatterbox_tts.py

Open chatterbox_tts.py and update the R2 configuration:
chatterbox_tts.py
R2_BUCKET_NAME = "your-bucket-name"
R2_ACCOUNT_ID = "your-account-id"
2

Create Modal secrets

Create the required secrets in your Modal dashboard:
Secret NameKeysDescription
cloudflare-r2AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEYR2 API credentials
chatterbox-api-keyCHATTERBOX_API_KEYAPI key to protect the endpoint (use any strong random string)
hf-tokenHF_TOKENHugging Face token for downloading model weights
Or create them via CLI:
modal secret create cloudflare-r2 \
  AWS_ACCESS_KEY_ID=your-r2-access-key \
  AWS_SECRET_ACCESS_KEY=your-r2-secret-key

modal secret create chatterbox-api-key \
  CHATTERBOX_API_KEY=your-strong-random-string

modal secret create hf-token \
  HF_TOKEN=your-huggingface-token
3

Deploy to Modal

modal deploy chatterbox_tts.py
This deploys Chatterbox TTS to a serverless NVIDIA A10G GPU. The container mounts your R2 bucket read-only for direct access to voice reference audio.Copy the resulting Modal URL and set it as CHATTERBOX_API_URL in your .env.local.
The first request after inactivity may take 10-15 seconds due to cold starts as Modal provisions the GPU container.
4

Generate the API client

Once deployed, generate the type-safe Chatterbox client from the OpenAPI spec:
npm run sync-api
This creates TypeScript types in src/types/chatterbox-api.ts for full type safety when calling the TTS API.

​
Seed System Voices

Resonance includes 20 pre-built voices across different categories and locales. Seed them to your database and R2 bucket: 
npx prisma db seed
This uploads the voice samples from the repository (included WAV files from Modal’s voice sample pack) and creates the corresponding database records.
The seed script creates voices in categories like Audiobook, Conversational, Narrative, Characters, Meditation, Podcast, Advertising, Voiceover, and Corporate.

​
Run the Application

Start the development server: 
npm run dev
Open http://localhost:3000 in your browser. You’ll be prompted to sign in with Clerk.
1

Sign up and create an organization

Create a new account and set up your first organization. All voices and generations are scoped to organizations.
2

Generate your first audio

Navigate to the Text-to-Speech page, select a voice, enter some text, and click Generate. Your audio will be created in seconds!
3

Clone a voice (optional)

Go to the Voices page and click “Create Voice”. Upload a 10+ second audio sample or record one directly in the browser.

​
Testing with Sandbox Mode

To test billing features without real payments, use Polar’s sandbox mode:
  1. Set POLAR_SERVER="sandbox" in your .env.local
  2. Use the test card number 4242 4242 4242 4242 with any future expiration date and any CVC
  3. All charges will be simulated - no real money will be processed
Remember to switch to POLAR_SERVER="production" when deploying to production!

​
Available Scripts

CommandDescription
npm run devStart development server on port 3000
npm run buildCreate production build
npm run startStart production server
npm run lintRun ESLint
npm run sync-apiRegenerate Chatterbox API types from OpenAPI spec

​
Next Steps

Architecture

Learn how Resonance works under the hood

Self-Hosting

Deploy Resonance to production

API Reference

Explore the tRPC API endpoints

Configuration

Customize Resonance for your needs

Build docs developers (and LLMs) love

Get started for freeTalk to us