anime-qize/CLAUDE.md

CLAUDE.md

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

Project Overview

Anime Quiz Video Generator - A full-stack web application that generates "Guess the Anime Opening" videos for YouTube Shorts and TikTok. Combines a Python FastAPI backend for video processing with a Vue 3 frontend.

Commands

Docker (primary development method)

docker-compose up --build    # Build and start all services
docker-compose up            # Start existing containers
docker-compose down          # Stop containers

Frontend (from /frontend directory)

npm run dev      # Start Vite dev server (port 5173)
npm run build    # Build for production
npm run preview  # Preview production build

Backend (from /backend directory)

uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

Architecture

Backend (FastAPI + MoviePy)

• backend/app/main.py - FastAPI application with REST endpoints
• backend/app/video_generator.py - Core VideoGenerator class handling all video composition
• backend/app/models.py - Pydantic models (VideoMode, Difficulty, QuizItem, GenerateRequest)
• backend/app/config.py - Settings via Pydantic BaseSettings with QUIZ_ env prefix

Video generation runs in ThreadPoolExecutor (max_workers=1) to avoid blocking the async event loop.

Frontend (Vue 3 + Vite)

• frontend/src/App.vue - Single component handling all UI, form state, and API calls
• Uses Vue 3 Composition API (ref, reactive, computed)
• Vite proxies /api, /videos, /download to backend at http://backend:8000

Media Organization

media/
├── audio/        # MP3 anime openings
├── backgrounds/  # MP4 looping videos (5-10 sec recommended)
└── posters/      # Anime poster images (JPG/PNG/WebP)

output/videos/    # Generated MP4 files

Video Generation Flow

1. Frontend POSTs to /generate with quiz configuration
2. VideoGenerator.generate() creates scenes in sequence:
   • Question scene: background + countdown timer + difficulty badge + audio track
   • Answer scene: anime title + poster image with fade-in
3. For "full" mode, adds final CTA screen
4. Concatenates all scenes → writes MP4 (H.264/AAC)
5. Returns video URL for download

Video dimensions:

• shorts: 1080x1920 (9:16) for TikTok/Shorts
• full: 1920x1080 (16:9) for YouTube

API Endpoints

Method	Endpoint	Purpose
GET	/health	Health check with FFmpeg status
GET	/content	List available audio, backgrounds, posters
POST	/generate	Generate video (returns video URL)
GET	/download/{filename}	Download generated video
DELETE	/videos/{filename}	Delete video
GET	/videos-list	List generated videos

Environment Variables

QUIZ_MEDIA_PATH=/app/media
QUIZ_OUTPUT_PATH=/app/output/videos
VITE_API_URL=http://backend:8000