# CLAUDE.md

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

## Project Overview

mvmaker is a FastAPI-based video synchronization tool that creates AI-generated music videos by:
1. Downloading TikTok videos
2. Extracting and transcribing audio
3. Generating songs via Suno API
4. Synchronizing the original video to the new audio using word-level alignment

## Common Development Commands

### Backend Setup and Running
```bash
cd backend
pip install -r requirements.txt
uvicorn app:app --reload --host 0.0.0.0 --port 8000
```

### Environment Variables
Create a `.env` file in the backend directory with:
```
REPLICATE_API_TOKEN=<your_replicate_token>
SUNO_TOKEN=<your_suno_bearer_token>
WHISPER_MODEL=villesau/whisper-timestamped:c5b122b7e513b1b5a6ef849891c538869b77cc932cbd0f8203e11d3b357553b8
```

### Docker
```bash
cd backend
docker build -t mvmaker .
docker run -p 8000:8000 --env-file .env mvmaker
```

## Architecture Overview

### Core Components

1. **app.py** - Main FastAPI application
   - `/api/full` - One-click endpoint that orchestrates the entire pipeline
   - `/api/status/{jid}` - Check job status
   - Frontend static file serving from `frontend/`

2. **vidmaker.py** - Video synchronization engine
   - `build_combined_sync()` - Aligns transcripts using difflib SequenceMatcher
   - `retime_video()` - Applies temporal remapping with smooth interpolation
   - Uses MoviePy for video processing

3. **tiktok_utils.py** - Media handling
   - `download_tiktok()` - Uses yt-dlp for video download
   - `extract_audio()` - FFmpeg extraction to 16kHz mono PCM WAV
   - `transcribe_with_replicate()` - Whisper API for word-level transcription

4. **suno_utils.py** - AI music generation
   - `audio_to_suno_song()` - Complete upload→generate→download flow
   - Handles both staging and production Suno API endpoints
   - Robust retry logic with exponential backoff

### Data Flow

1. User submits TikTok URL + prompt → Creates job with UUID
2. Downloads video → `storage/{job_id}/*.mp4`
3. Extracts audio → `audio.wav`
4. Generates song via Suno → `suno.wav`
5. Transcribes both audios → `video.json`, `song.json`
6. Builds sync anchors → `combined.json`
7. Renders synced video → `output.mp4`

### Key Algorithms

- **Word Alignment**: Uses longest common subsequence matching on normalized text
- **Temporal Remapping**: Smooth monotonic interpolation with configurable window
- **Anchor Filtering**: Rejects matches with duration ratios outside 0.3-3.0 range

## Important Notes

- The codebase is actively migrating from individual endpoints to the unified `/api/full` flow
- Storage is currently local filesystem under `backend/storage/`
- The frontend is a simple HTML interface served from `frontend/index.html`
- Error handling includes detailed logging to `storage/{job_id}/log.txt`