# MVMaker - AI Music Video Generator

MVMaker creates AI-generated music videos by synchronizing TikTok videos with new audio generated by Suno AI.

## Features

- Downloads TikTok videos
- Extracts and transcribes audio using Whisper
- Generates new music using Suno AI v4.5 (preserves vocals)
- Synchronizes video to new audio using word-level alignment
- Creates professional music videos with perfect lip sync

## Setup

### Backend

```bash
cd backend
pip install -r requirements.txt
```

Create a `.env` file:
```
REPLICATE_API_TOKEN=your_replicate_token
SUNO_TOKEN=your_suno_bearer_token
WHISPER_MODEL=villesau/whisper-timestamped:c5b122b7e513b1b5a6ef849891c538869b77cc932cbd0f8203e11d3b357553b8
```

### Running

```bash
cd backend
uvicorn app:app --reload --host 0.0.0.0 --port 8000
```

Visit http://localhost:8000

## API Endpoints

- `POST /api/full/v2` - Main endpoint for video generation
  - `url`: TikTok URL
  - `prompt`: Music style (e.g., "drum and bass", "smooth jazz")

- `GET /api/status/{job_id}` - Check job status
- `GET /api/debug/{job_id}` - Debug interface

## How It Works

1. **Download** - Fetches TikTok video
2. **Extract** - Pulls audio from video
3. **Transcribe** - Uses Whisper to get word-level timestamps
4. **Generate** - Creates new music with Suno AI (preserves vocals)
5. **Sync** - Aligns video to new audio using transcript matching
6. **Export** - Outputs synced music video

## Tech Stack

- **Backend**: FastAPI, Python
- **Video**: MoviePy, FFmpeg
- **AI**: Suno API, Replicate (Whisper)
- **Frontend**: Vanilla HTML/JS

## File Structure

```
mvmaker/
├── backend/
│   ├── app.py              # Main FastAPI application
│   ├── vidmaker.py         # Video synchronization engine
│   ├── tiktok_utils.py     # TikTok download & transcription
│   ├── suno_*.py           # Suno AI integration
│   └── storage/            # Job storage
├── frontend/
│   ├── index.html          # Main UI
│   └── debug.html          # Debug interface
└── docs/                   # Documentation
```

## Notes

- Suno generates 2 clips per request; we use the first one
- Transcription is done twice: original audio + generated song
- Sync works by matching words between transcripts
- Videos are retimed to match new audio while preserving lip sync