CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Development Commands

### Quick Start (Recommended)
```bash
./run_dev.sh
```
This single script starts both frontend (port 11111) and backend (port 11110) with auto-browser opening.

### Manual Development Setup

**Frontend (Svelte):**
```bash
cd frontend
npm install
npm run dev          # Development server on :11111
npm run build        # Production build
npm run check        # Type checking
```

**Backend (FastAPI):**
```bash
cd backend
pip install -r requirements.txt
python -m hfstudio.cli --dev  # Development server on :11110
# OR
pip install -e .
hfstudio --dev
```

### Port Configuration
- Frontend: 11111 (configured in `vite.config.js`)
- Backend: 7860 (configured in `cli.py`)
- CORS is configured for these specific ports in `server.py`

## Architecture Overview

### Frontend Structure (SvelteKit + TailwindCSS)
- **Single Page App**: Main interface in `src/routes/+page.svelte`
- **Layout**: Global layout with sidebar in `src/routes/+layout.svelte`
- **Design System**: HuggingFace brand colors (`#FFD21E`, `#FF9D00`) used throughout
- **State Management**: Local component state with reactive variables
- **Audio Handling**: Custom HTML5 audio element with manual progress tracking

### Key UI Components
- **Three-panel layout**: Sidebar (56 units) + Main content + Settings panel (80 units)
- **Fixed bottom button**: Generate button positioned absolutely at page bottom
- **Mini audio player**: Compact controls in generated audio card
- **Full audio player**: Expanded controls with ElevenLabs-style design
- **Custom pause icon**: CSS-only filled bars instead of outline

### Backend Structure (FastAPI)
- **Main server**: `server.py` with CORS configured for development ports
- **CLI interface**: `cli.py` with typer for command-line control
- **Pydantic models**: TTSRequest, TTSResponse, Voice, Model
- **Current implementation**: Mock TTS generation using placeholder audio

### API Endpoints
```
GET  /                     - Health check
GET  /api/status          - Mode and availability info
GET  /api/voices          - Available voice list
GET  /api/models          - Available model list  
POST /api/tts/generate    - Generate speech from text
```

## Design Patterns & Conventions

### Frontend Patterns
- **HF Brand Integration**: Uses official logo (`/assets/hf-logo.png`) and gradient colors
- **Responsive Controls**: All sliders use custom `.slider-hf` class with HF colors
- **Audio State Management**: Manual synchronization between UI state and HTML5 audio element
- **Progressive Enhancement**: Settings always visible, no hidden toggles

### Backend Patterns
- **Development Mode**: Auto-reload enabled with `--dev` flag
- **Mock Implementation**: Currently returns `/samples/harvard.wav` for testing
- **CORS Configuration**: Explicitly configured for development ports

### Styling Conventions
- **TailwindCSS**: Primary styling framework
- **Custom CSS**: Limited to audio sliders and pause icon in `app.css`
- **Color Scheme**: Light theme with HF amber/orange accents
- **Typography**: System fonts with careful spacing

## Key Implementation Details

### Audio System
The app uses a hidden HTML5 `<audio>` element controlled by custom UI:
- Real audio playback through bound `audioElement`
- Manual progress tracking via `timeupdate` events  
- Auto-play when generation completes
- Custom pause icon using CSS pseudo-elements

### Voice & Model Data
```javascript
// Current models (in +page.svelte)
const models = [
  { id: 'chatterbox', name: 'Chatterbox', badge: 'recommended' },
  { id: 'kokoro', name: 'Kokoro', badge: 'faster but lower quality' }
];

// Current voices with descriptions
const voices = [
  { id: 'novia', name: 'Novia', description: 'Warm, conversational voice' },
  // ... etc
];
```

### Configuration Files
- **Frontend env**: `.env` with `PUBLIC_API_URL=http://localhost:11110`
- **Vite config**: Custom port (11111) and host settings
- **TailwindCSS**: Custom colors and slider styling
- **Backend requirements**: FastAPI, numpy, soundfile for audio processing

### Static Assets
- **Logo**: HuggingFace logo at `/assets/hf-logo.png` 
- **Sample audio**: Harvard sample at `/samples/harvard.wav` for testing
- **Favicon**: Uses HF logo

## Development Workflow

### Making UI Changes
1. Edit components in `frontend/src/routes/+page.svelte`
2. Layout changes go in `frontend/src/routes/+layout.svelte`  
3. Global styles in `frontend/src/app.css`
4. Hot reload shows changes instantly

### Adding API Features  
1. Add Pydantic models in `server.py`
2. Create new endpoints following existing patterns
3. Update CORS origins if needed
4. Test at `http://localhost:11110/docs`

### Troubleshooting
- **Port conflicts**: Change ports in `vite.config.js` and `cli.py`
- **CORS issues**: Update `allow_origins` in `server.py`
- **Audio not playing**: Check audio file exists at `/samples/harvard.wav`
- **Dependencies**: Run `npm install` in frontend, `pip install -r requirements.txt` in backend