🌈 Refract AI

Convert YouTube videos into multi-platform content in 30 seconds.

Refract AI takes any YouTube video and instantly generates:

• 📝 SEO-optimized blog posts (1500-2000 words)
• 🐦 Viral Twitter threads (8-12 engaging tweets)
• 💼 LinkedIn articles (800-1200 words with hashtags)
• 🖼️ Custom thumbnails (1280x720 YouTube-optimized)

---

🚀 Quick Start

Prerequisites

• Python 3.10+
• Node.js 18+
• Google Gemini API key (Get one free)

Backend Setup

cd backend

# Create virtual environment
python -m venv .venv

# Activate (Windows)
.\.venv\Scripts\activate
# Activate (macOS/Linux)
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Configure environment
cp .env.example .env
# Edit .env and add your GEMINI_API_KEY

# Start server
uvicorn main:app --reload --port 8000

Frontend Setup

cd frontend

# Install dependencies
npm install

# Configure environment (optional)
cp .env.example .env

# Start development server
npm run dev

Open http://localhost:5173 in your browser.

---

⚙️ Environment Variables

Backend (backend/.env)

Variable	Description	Required	Default
GEMINI_API_KEY	Google Gemini API key	✅ Yes	-
ENVIRONMENT	development or production	No	development
CORS_ORIGINS	Allowed CORS origins (comma-separated)	No	http://localhost:5173
LOG_LEVEL	Logging level	No	INFO

Frontend (frontend/.env)

Variable	Description	Required	Default
VITE_API_URL	Backend API URL	No	http://localhost:8000

---

🎯 Features

Content Generation

• Smart transcript extraction from any YouTube video
• Trend-aware content using real-time DuckDuckGo search
• Multiple output formats optimized for each platform
• AI-powered thumbnails with gradient backgrounds

User Experience

• 🎨 Beautiful dark mode UI with prism gradient accents
• ⚡ Real-time progress tracking with stage indicators
• 📋 One-click copy for all content types
• 📥 Download blog posts as Markdown files
• 🖼️ Download thumbnails as PNG files

Technical

• 🔒 Secure API with rate limiting
• 📱 Fully responsive (mobile, tablet, desktop)
• ♿ WCAG 2.1 accessible
• 🚀 Performance optimized with React.lazy and memoization

---

🏗️ Tech Stack

Backend

• FastAPI - Modern Python web framework
• Google Gemini AI - Content generation (1.5 Pro model)
• youtube-transcript-api - Transcript extraction
• DuckDuckGo Search - Trend research
• Pillow - Thumbnail generation
• Pydantic - Data validation

Frontend

• React 18 - UI library
• TypeScript - Type safety
• Vite - Build tool
• Tailwind CSS - Styling
• Framer Motion - Animations
• Zustand - State management
• React Router - Navigation
• React Markdown - Blog rendering

---

📁 Project Structure

refract-ai/
├── backend/
│   ├── app/
│   │   ├── api/
│   │   │   └── routes.py      # API endpoints
│   │   ├── core/
│   │   │   └── config.py      # Settings
│   │   ├── models/
│   │   │   └── schemas.py     # Pydantic models
│   │   └── services/
│   │       ├── ai_service.py       # Gemini integration
│   │       ├── youtube_service.py  # Transcript extraction
│   │       ├── search_service.py   # Trend research
│   │       └── thumbnail_service.py # Image generation
│   ├── main.py
│   ├── requirements.txt
│   └── .env.example
├── frontend/
│   ├── src/
│   │   ├── components/        # Reusable UI components
│   │   ├── pages/            # Route pages
│   │   ├── services/         # API client
│   │   ├── store/            # Zustand state
│   │   ├── hooks/            # Custom hooks
│   │   └── types/            # TypeScript types
│   ├── package.json
│   └── .env.example
└── README.md

---

🔌 API Reference

POST /api/refract

Generate multi-platform content from a YouTube video.

Request:

{
  "youtube_url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
}

Response:

{
  "video_info": {
    "video_id": "dQw4w9WgXcQ",
    "title": "Video Title",
    "channel_name": "Channel Name",
    "transcript": "...",
    "thumbnail_url": "..."
  },
  "blog_post": "# Blog Title\n\n...",
  "twitter_thread": ["Tweet 1...", "Tweet 2...", ...],
  "linkedin_article": "Professional intro...\n\n#hashtags",
  "thumbnail_url": "data:image/png;base64,...",
  "generation_time": 12.5,
  "trends_used": ["trend1", "trend2"],
  "created_at": "2024-01-15T10:30:00Z"
}

GET /api/health

Health check endpoint.

GET /api/test-gemini

Test Gemini API connectivity.

---

🧪 Testing

Test Complete Flow

1. Start both backend and frontend servers
2. Navigate to http://localhost:5173
3. Paste a YouTube URL (e.g., https://www.youtube.com/watch?v=dQw4w9WgXcQ)
4. Click "Refract" and wait for processing
5. Switch between tabs to view Blog, Twitter, LinkedIn, and Thumbnail
6. Test copy buttons and download functionality

Test Error Handling

• Try an invalid URL → Should show validation error
• Try a video without subtitles → Should show API error
• Try while offline → Should show network error

---

📝 License

MIT License - see LICENSE for details.

---

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing-feature)
5. Open a Pull Request

---

🙏 Acknowledgments

• Google Gemini for AI capabilities
• Lucide for beautiful icons
• Built with ❤️ for the hackathon

---

Transform one video into a content empire 🌈