QUICKSTART.md

HFStudio - Quick Start Guide

🚀 Running Locally for Development

Prerequisites

• Node.js 18+ and npm
• Python 3.8+

Option 1: Quick Start (Recommended)

# Run both frontend and backend
./run_dev.sh

This will:

• Start the backend API server on http://localhost:11110
• Start the frontend dev server on http://localhost:11111
• Install dependencies automatically

Option 2: Manual Setup

Terminal 1 - Backend

cd backend

# Install dependencies
pip install -r requirements.txt

# Run the server
python -m hfstudio.cli --dev

# Or install as package and run
pip install -e .
hfstudio --dev

Backend will run on http://localhost:11110

• API docs: http://localhost:11110/docs
• ReDoc: http://localhost:11110/redoc

Terminal 2 - Frontend

cd frontend

# Install dependencies
npm install

# Run dev server
npm run dev

Frontend will run on http://localhost:11111

📁 Project Structure

hfstudio/
├── frontend/          # Svelte UI (port 11111)
│   └── src/
│       ├── routes/   # Page components
│       └── app.css   # Tailwind styles
├── backend/          # Python API (port 11110)
│   └── hfstudio/
│       ├── server.py # FastAPI server
│       └── cli.py    # CLI interface
└── run_dev.sh       # Dev startup script

🎨 UI Features

• Text Input: Large textarea for text-to-speech input
• Voice Selection: Choose from available voices
• Model Selection: Switch between TTS models
• Parameter Controls: Adjust speed, stability, similarity
• Mode Toggle: Switch between API and Local execution
• Audio Player: Play and download generated speech

🔧 Development Tips

Frontend Changes

• Edit files in frontend/src/
• Hot reload is enabled - changes appear instantly
• Tailwind classes are available

Backend Changes

• Edit files in backend/hfstudio/
• With --dev flag, server auto-reloads on changes
• Test API endpoints at http://localhost:11110/docs

Adding New Features

1. Frontend components go in frontend/src/lib/components/
2. API endpoints go in backend/hfstudio/server.py
3. TTS models will go in backend/hfstudio/models/

🐛 Troubleshooting

Port Already in Use

# Change frontend port
cd frontend
npm run dev -- --port 11112

# Change backend port
cd backend
python -m hfstudio.cli --port 11112

Missing Dependencies

# Frontend
cd frontend && npm install

# Backend
cd backend && pip install -r requirements.txt

CORS Issues

Make sure both servers are running and check the CORS configuration in backend/hfstudio/server.py