chatterbox-ui/OpenCode.md

OpenCode.md - Chatterbox UI Development Guide

Build & Run Commands

# Backend (FastAPI)
pip install -r backend/requirements.txt
uvicorn backend.app.main:app --reload --host 0.0.0.0 --port 8000

# Frontend
python frontend/start_dev_server.py  # Serves on port 8001

# Run backend tests
python backend/run_api_test.py

# Run frontend tests
npm test

# Run specific frontend test
npx jest frontend/tests/api.test.js

# Run Gradio interface
python gradio_app.py

# Run utility scripts
python cbx-audiobook.py --list-speakers  # List available speakers
python cbx-audiobook.py sample-audiobook.txt --speaker <speaker_id>  # Generate audiobook
python cbx-dialog-generate.py sample-dialog.md  # Generate dialog

Code Style Guidelines

Python

• Use type hints (from typing import Optional, List, Dict, etc.)
• Error handling: Use try/except with specific exceptions
• Async/await for I/O operations
• Docstrings for functions and classes
• PEP 8 naming: snake_case for functions/variables, PascalCase for classes

JavaScript

• ES6 modules with import/export
• Async/await for API calls
• JSDoc comments for functions
• Error handling: try/catch with detailed error messages
• Camel case for variables/functions (camelCase)

Import Structure

• When importing from scripts, use import import_helper first to fix Python path
• Backend modules use relative imports within the app package
• Services are in backend.app.services
• Models are in backend.app.models
• Configuration is in backend.app.config

Project Structure

• Backend: FastAPI with service-oriented architecture
• Frontend: Vanilla JS with modular design (api.js, app.js, config.js)
• Speaker data in YAML format with WAV samples
• Output directories: dialog_output/, single_output/, tts_outputs/

Common Issues

• Import errors: Make sure to use import import_helper in scripts
• Speaker samples must be WAV format in speaker_data/speaker_samples/
• TTS model requires GPU (CUDA) or Apple Silicon (MPS)