Skip to content

TESTING_GUIDE.md

Latest commit

 

History

History
333 lines (248 loc) · 6.35 KB

TESTING_GUIDE.md

File metadata and controls

333 lines (248 loc) · 6.35 KB

Testing Guide - Quick Start

Prerequisites

Before testing, ensure you have:

  1. FFmpeg installed

    ffmpeg -version

  2. OpenRouter API key with credits

Setup (First Time Only)

Option 1: Automated Setup

./setup.sh

Then add your OpenRouter API key to backend/.env:

cd backend
nano .env  # or use your preferred editor
# Add: OPENROUTER_API_KEY=your_key_here

Option 2: Manual Setup

Backend:

cd backend
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
# Edit .env and add your OPENROUTER_API_KEY

Remotion:

cd remotion-renderer
npm install

Frontend:

cd frontend
npm install
cp .env.local.example .env.local

Running the System

You need 3 terminals:

Terminal 1: Backend

cd backend
source venv/bin/activate
python -m uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

Expected output:

INFO:     Started server process
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8000

Terminal 2: Frontend

cd frontend
npm run dev

Expected output:

  ▲ Next.js 14.x.x
  - Local:        http://localhost:3000
  - Ready in X.Xs

Terminal 3: Watch Logs (Optional)

# Watch backend logs
tail -f backend/*.log

# Or watch temp directory
watch -n 1 "ls -lh backend/temp"

Testing

1. Access the Test UI

Open your browser and go to:

http://localhost:3000

Click "Start Testing" to go to the test page.

2. Upload a Test Video

Where to get test videos:

  • Record a short video on your phone (10-30 seconds recommended)
  • Download from: https://www.pexels.com/videos/ (free, no attribution required)
  • Use any MP4, MOV, or WebM file you have

Recommended test video specs:

  • Duration: 10-30 seconds
  • Resolution: 1080p or lower
  • Size: < 50MB

3. Choose Instructions

The test page has quick examples, or try these:

Simple test:

Cut the video to 5 seconds and add text "Hello World" in the center

Medium complexity:

Cut to 10 seconds, add exciting text "AMAZING!" with a slide animation, and apply an energetic emotion effect

Complex test:

Trim the video to 15 seconds, add bold text "Epic Moment" at the bottom with fade animation, apply high saturation color grading, add a zoom effect, and use an energetic emotion

4. Submit and Watch Progress

  1. Click "Start Editing"
  2. You'll be redirected to the results page
  3. Watch real-time progress updates
  4. Download when complete!

Expected Processing Times

Based on video length and complexity:

Operations Expected Time
1-3 ops 10-15 seconds
4-7 ops 20-30 seconds
8+ ops 30-60 seconds

Troubleshooting

Backend Issues

Error: "OPENROUTER_API_KEY environment variable is required"

  • Make sure you added your API key to backend/.env
  • Restart the backend after adding the key

Error: "FFmpeg not found"

# Install FFmpeg
# macOS:
brew install ffmpeg

# Ubuntu/Debian:
sudo apt-get install ffmpeg

Error: "Module not found"

cd backend
source venv/bin/activate
pip install -r requirements.txt

Frontend Issues

Error: "Failed to fetch"

  • Make sure backend is running on port 8000
  • Check frontend/.env.local has correct API URL

Connection refused errors

  • Backend might not be running
  • Check firewall settings

Remotion Issues

Error: "npx: command not found"

Remotion rendering fails

cd remotion-renderer
npm install

What to Watch For

Success Indicators ✅

  1. Backend logs show:

    • "Processing job..."
    • "Planner node complete"
    • "FFmpeg operations complete"
    • "Remotion operations complete"
    • "Job completed successfully"

  2. Frontend shows:

    • Progress bar moving
    • Status updates every second
    • Final video player appears
    • Download button works

Common Issues ❌

  1. Job stuck at "Processing"

    • Check backend logs for errors
    • Verify FFmpeg is installed
    • Check OpenRouter API key and credits

  2. "Planning failed" error

    • OpenRouter API issue
    • Check your API key
    • Verify you have credits

  3. "FFmpeg cut error"

    • Video format might not be supported
    • Try converting to MP4 first

  4. "Remotion render failed"

    • Check if Node.js is installed
    • Verify remotion-renderer/node_modules exists
    • Check disk space

Testing Checklist

  • Backend starts without errors
  • Frontend loads at localhost:3000
  • Can upload a video file
  • Job is created successfully
  • Progress updates in real-time
  • Final video downloads
  • Final video plays correctly

Advanced Testing

Test with Multiple Videos

# Use the /editor page instead of /test
http://localhost:3000/editor

Upload 2-3 videos and try:

Cut all videos to 5 seconds each, add text to each clip, then combine them with smooth transitions

Test with Style Context

Create a file my_style.md:

# My Video Style

## Text
- Large bold text
- Bottom center position

## Colors
- High saturation
- Warm tones

## Mood
- Energetic and upbeat

Upload this on the /editor page along with your videos.

Monitor Performance

In Terminal 3:

# Watch processing
cd backend
watch -n 1 "ls -lh temp/ | tail -20"

# Monitor CPU usage
htop  # or top on macOS

API Testing (Optional)

Test the API directly with curl:

# Health check
curl http://localhost:8000/health

# Upload video
curl -X POST http://localhost:8000/api/upload/video \
  -F "file=@/path/to/your/video.mp4"

# Create job
curl -X POST http://localhost:8000/api/jobs/create \
  -H "Content-Type: application/json" \
  -d '{
    "video_ids": ["your-video-id"],
    "instructions": "Cut to 10 seconds"
  }'

# Check job status
curl http://localhost:8000/api/jobs/{job-id}

Need Help?

  1. Check backend terminal for error messages
  2. Check browser console (F12) for frontend errors
  3. Review the logs in backend/ directory
  4. Open an issue on GitHub with:
    • Error messages
    • Steps to reproduce
    • System info (OS, Python version, Node version)

Happy testing! 🎬