YouTube Summarizer API & Web Application

A comprehensive AI-powered API ecosystem and web application that automatically extracts, transcribes, and summarizes YouTube videos. Features enterprise-grade developer tools, SDKs, agent framework integrations, and autonomous operations.

🚀 What's New: Advanced API Ecosystem

Developer API Platform

• 🔌 MCP Server: Model Context Protocol integration for AI development tools
• 📦 Native SDKs: Python and JavaScript/TypeScript SDKs with full async support
• 🤖 Agent Frameworks: LangChain, CrewAI, and AutoGen integrations
• 🔄 Webhooks: Real-time event notifications with HMAC authentication
• 🤖 Autonomous Operations: Self-managing system with intelligent automation
• 🔑 API Authentication: Enterprise-grade API key management and rate limiting
• 📊 OpenAPI 3.0: Comprehensive API documentation and client generation

🎯 Features

Core Features

• Dual Transcript Options ✅ UPGRADED: Choose between YouTube captions, AI Whisper transcription, or compare both
  • YouTube Captions: Fast extraction (~3s) with standard quality
  • Faster-Whisper AI ⚡ NEW: 20-32x speed improvement with large-v3-turbo model
    • Performance: 2.3x faster than realtime processing (3.6 min video in 94 seconds)
    • Quality: Perfect transcription accuracy (1.000 quality score, 0.962 confidence)
    • Technology: CTranslate2 optimization engine with GPU acceleration
    • Intelligence: Voice Activity Detection, int8 quantization, native MP3 support
  • Smart Comparison: Side-by-side analysis with quality metrics and recommendations
  • Processing Time Estimates: Real-time speed ratios and performance metrics
  • Quality Scoring: Advanced confidence levels and improvement analysis
• Video Transcript Extraction: Automatically fetch transcripts from YouTube videos
• AI-Powered Summarization: Generate concise summaries using multiple AI models
• Multi-Model Support: Choose between OpenAI GPT, Anthropic Claude, or DeepSeek
• Key Points Extraction: Identify and highlight main topics and insights
• Chapter Generation: Automatically create timestamped chapters
• Export Options: Save summaries as Markdown, PDF, HTML, JSON, or plain text ✅
• Template System: Customizable export templates with Jinja2 support ✅
• Bulk Export: Export multiple summaries as organized ZIP archives ✅
• Caching System: Reduce API calls with intelligent caching
• Rate Limiting: Built-in protection against API overuse

Authentication & Security ✅

• Flexible Authentication: Configurable auth system for development and production
  • Development Mode: No authentication required by default - perfect for testing
  • Production Mode: Automatic JWT-based authentication with user sessions
  • Environment Controls: VITE_FORCE_AUTH_MODE, VITE_AUTH_DISABLED for fine control
• User Registration & Login: Secure email/password authentication with JWT tokens
• Email Verification: Required email verification for new accounts
• Password Reset: Secure password recovery via email
• Session Management: JWT access tokens with refresh token rotation
• Protected Routes: User-specific summaries and history (when auth enabled)
• API Key Management: Generate and manage personal API keys
• Security Features: bcrypt password hashing, token expiration, CORS protection

Summary Management & History ✅

• Persistent Job History: Comprehensive history system that discovers all processed jobs from storage
  • High-Density Views: See 12+ jobs in grid view, 15+ jobs in list view
  • Smart Discovery: Automatically indexes existing files from video_storage/ directories
  • Rich Metadata: File status, processing times, word counts, storage usage
  • Enhanced Detail Modal: Tabbed interface with transcript viewer, files, and metadata
  • Search & Filtering: Real-time search with status, date, and tag filtering
• History Tracking: View all your processed summaries with search and filtering
• Favorites: Star important summaries for quick access
• Tags & Notes: Organize summaries with custom tags and personal notes
• Sharing: Generate shareable links for public summaries
• Bulk Operations: Select and manage multiple summaries at once

Batch Processing ✅

• Multiple URL Processing: Process up to 100 YouTube videos in a single batch
• File Upload Support: Upload .txt or .csv files with YouTube URLs
• Sequential Processing: Smart queue management to control API costs
• Real-time Progress: WebSocket-powered live progress updates
• Individual Item Tracking: See status, errors, and processing time per video
• Retry Failed Items: Automatically retry videos that failed processing
• Batch Export: Download all summaries as a organized ZIP archive
• Cost Tracking: Monitor API usage costs in real-time ($0.0025/1k tokens)

Real-time Updates ✅

• WebSocket Progress Tracking: Live updates for all processing stages
• Granular Progress: Detailed percentage and sub-task progress
• Time Estimation: Intelligent time remaining based on historical data
• Connection Recovery: Automatic reconnection with message queuing
• Job Cancellation: Cancel any processing job with immediate termination
• Visual Progress UI: Beautiful progress component with stage indicators
• Heartbeat Monitoring: Connection health checks and status indicators
• Offline Recovery: Queued updates delivered when reconnected

Enhanced Export System (NEW) ✅

• Professional Document Generation: Business-grade markdown with AI intelligence
• Executive Summaries: C-suite ready summaries with ROI analysis and strategic insights
• Timestamped Navigation: Clickable [HH:MM:SS] YouTube links for easy video navigation
• 6 Domain-Specific Templates: Optimized for Educational, Business, Technical, Content Creation, Research, and General content
• AI-Powered Recommendations: Intelligent content analysis suggests best template for your video
• Custom Template Creation: Build and manage your own AI prompt templates with A/B testing
• Quality Scoring: Automated quality assessment for generated exports
• Template Analytics: Usage statistics and performance metrics for template optimization

🏗️ Architecture

[Web Interface] → [Authentication Layer] → [FastAPI Backend]
                         ↓                        ↓
[User Management] ← [JWT Auth] → [Dual Transcript Service] ← [YouTube API]
                         ↓              ↓           ↓
[AI Service] ← [Summary Generation] ← [YouTube Captions] | [Whisper AI]
                         ↓              ↓           ↓
[Database] → [User Summaries] → [Quality Comparison] → [Export Service]

Enhanced Transcript Extraction (v5.1) ✅

• 9-Tier Fallback Chain: Guaranteed transcript extraction with multiple methods
  • YouTube Transcript API (primary)
  • Auto-generated captions
  • Whisper AI transcription
  • PyTubeFix, YT-DLP, Playwright fallbacks
  • External tools and web services
• Audio Retention System: Save audio files for re-transcription
  • MP3 format (192kbps) for storage efficiency
  • Metadata tracking (duration, quality, download date)
  • Re-transcription without re-downloading
• Dual Transcript Architecture:
  • TranscriptSelector Component: Choose between YouTube captions, Whisper AI, or both
  • DualTranscriptService: Orchestrates parallel extraction and quality comparison
  • WhisperTranscriptService: High-quality AI transcription with chunking support
  • Quality Comparison Engine: Analyzes differences and provides recommendations
  • Real-time Progress: WebSocket updates for long-running Whisper jobs

🚀 Quick Start

Prerequisites

• Python 3.11+
• YouTube API Key (optional but recommended)
• At least one AI service API key (OpenAI, Anthropic, or DeepSeek)

🎯 Quick Testing (No Authentication Required)

For immediate testing and development with our flexible authentication system:

# Easy server management with restart scripts
./scripts/restart-backend.sh     # Starts backend on port 8000
./scripts/restart-frontend.sh    # Starts frontend on port 3002
./scripts/restart-both.sh        # Starts both servers

# Visit main app (no login required by default)
open http://localhost:3002/

Development Mode Features:

• 🔓 No authentication required by default - perfect for development
• 🛡️ Admin mode indicators show you're in development mode
• 🔄 Server restart scripts handle backend changes seamlessly
• 🌐 Full functionality available without login barriers

Production Authentication:

# Enable authentication for production-like testing
VITE_FORCE_AUTH_MODE=true npm run dev

Installation

1. Clone the repository

git clone https://eniasgit.zeabur.app/demo/youtube-summarizer.git
cd youtube-summarizer

2. Set up virtual environment

python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies

# Backend dependencies
cd backend
pip install -r requirements.txt

# Frontend dependencies (if applicable)
cd ../frontend
npm install

4. Configure environment

cp .env.example .env
# Edit .env with your API keys and configuration

5. Initialize database

cd backend
python3 -m alembic upgrade head  # Apply existing migrations

6. Run the application

# Recommended: Use restart scripts for easy development
./scripts/restart-backend.sh     # Backend on http://localhost:8000
./scripts/restart-frontend.sh    # Frontend on http://localhost:3002

# Or run manually
cd backend && python3 main.py    # Backend 
cd frontend && npm run dev        # Frontend

# Full stack restart after major changes
./scripts/restart-both.sh

📁 Project Structure

youtube-summarizer/
├── scripts/              # Development tools ✅ NEW
│   ├── restart-backend.sh    # Backend restart script
│   ├── restart-frontend.sh   # Frontend restart script
│   └── restart-both.sh       # Full stack restart
├── logs/                 # Server logs (auto-created)
├── backend/
│   ├── api/              # API endpoints
│   │   ├── auth.py       # Authentication endpoints
│   │   ├── history.py    # Job history API ✅ NEW
│   │   ├── pipeline.py   # Pipeline management
│   │   ├── export.py     # Export functionality
│   │   └── videos.py     # Video operations
│   ├── services/         # Business logic
│   │   ├── job_history_service.py  # History management ✅ NEW
│   │   ├── auth_service.py      # JWT authentication
│   │   ├── email_service.py     # Email notifications
│   │   ├── youtube_service.py   # YouTube integration
│   │   └── ai_service.py        # AI summarization
│   ├── models/           # Database models
│   │   ├── job_history.py    # Job history models ✅ NEW
│   │   ├── user.py       # User & auth models
│   │   ├── summary.py    # Summary models
│   │   ├── batch_job.py  # Batch processing models
│   │   └── video.py      # Video models
│   ├── core/             # Core utilities
│   │   ├── config.py     # Configuration
│   │   ├── database.py   # Database setup
│   │   └── exceptions.py # Custom exceptions
│   ├── alembic/          # Database migrations
│   ├── tests/            # Test suite
│   │   ├── unit/         # Unit tests
│   │   └── integration/  # Integration tests
│   ├── main.py           # Application entry point
│   └── requirements.txt  # Python dependencies
├── frontend/             # React frontend
│   ├── src/              # Source code
│   │   ├── components/   # React components
│   │   │   ├── history/      # History components ✅ NEW
│   │   │   ├── auth/         # Auth components
│   │   │   └── forms/        # Form components  
│   │   ├── pages/        # Page components
│   │   │   ├── MainPage.tsx      # Unified main page ✅ NEW
│   │   │   ├── HistoryPage.tsx   # Job history page ✅ NEW
│   │   │   └── auth/         # Auth pages
│   │   ├── config/       # Configuration ✅ NEW
│   │   │   └── app.config.ts # App & auth config ✅ NEW
│   │   ├── api/          # API clients
│   │   │   └── historyAPI.ts # History API client ✅ NEW
│   │   └── hooks/        # React hooks
│   ├── public/           # Static assets
│   ├── .env.example      # Environment variables ✅ NEW
│   └── package.json      # Node dependencies
├── docs/                 # Documentation
│   ├── stories/          # BMad story files
│   └── architecture.md  # System design
└── README.md            # This file

🔧 Configuration

Essential Environment Variables

Variable	Description	Required
Authentication
JWT_SECRET_KEY	Secret key for JWT tokens	Production
JWT_ALGORITHM	JWT algorithm (default: HS256)	No
ACCESS_TOKEN_EXPIRE_MINUTES	Access token expiry (default: 15)	No
REFRESH_TOKEN_EXPIRE_DAYS	Refresh token expiry (default: 7)	No
Frontend Authentication ✅ NEW
VITE_FORCE_AUTH_MODE	Enable auth in development (true)	No
VITE_AUTH_REQUIRED	Force authentication requirement	No
VITE_AUTH_DISABLED	Disable auth even in production	No
VITE_SHOW_AUTH_UI	Show login/register buttons	No
Email Service
SMTP_HOST	SMTP server host	For production
SMTP_PORT	SMTP server port	For production
SMTP_USER	SMTP username	For production
SMTP_PASSWORD	SMTP password	For production
SMTP_FROM_EMAIL	Sender email address	For production
AI Services
YOUTUBE_API_KEY	YouTube Data API v3 key	Optional*
OPENAI_API_KEY	OpenAI API key	One of these
ANTHROPIC_API_KEY	Anthropic Claude API key	is required
DEEPSEEK_API_KEY	DeepSeek API key	for AI
Database
DATABASE_URL	Database connection string	Yes
Application
SECRET_KEY	Application secret key	Yes
ENVIRONMENT	dev/staging/production	Yes
APP_NAME	Application name (default: YouTube Summarizer)	No

*YouTube API key improves metadata fetching but transcript extraction works without it.

🧪 Testing

Run the test suite:

cd backend

# Run all tests
python3 -m pytest tests/ -v

# Run unit tests only
python3 -m pytest tests/unit/ -v

# Run integration tests
python3 -m pytest tests/integration/ -v

# With coverage report
python3 -m pytest tests/ --cov=backend --cov-report=html

📝 API Documentation

Once running, visit:

• Interactive API docs: http://localhost:8000/docs
• Alternative docs: http://localhost:8000/redoc

Authentication Endpoints

• POST /api/auth/register - Register a new user
• POST /api/auth/login - Login and receive JWT tokens
• POST /api/auth/refresh - Refresh access token
• POST /api/auth/logout - Logout and revoke tokens
• GET /api/auth/me - Get current user info
• POST /api/auth/verify-email - Verify email address
• POST /api/auth/reset-password - Request password reset
• POST /api/auth/reset-password/confirm - Confirm password reset

Core Endpoints

• POST /api/pipeline/process - Submit a YouTube URL for summarization
• GET /api/pipeline/status/{job_id} - Get processing status
• GET /api/pipeline/result/{job_id} - Retrieve summary result
• GET /api/summaries - List user's summaries (requires auth)
• POST /api/export/{id} - Export summary in different formats
• POST /api/export/bulk - Export multiple summaries as ZIP

Batch Processing Endpoints

• POST /api/batch/create - Create new batch processing job
• GET /api/batch/{job_id} - Get batch job status and progress
• GET /api/batch/ - List all batch jobs for user
• POST /api/batch/{job_id}/cancel - Cancel running batch job
• POST /api/batch/{job_id}/retry - Retry failed items in batch
• GET /api/batch/{job_id}/download - Download batch results as ZIP
• DELETE /api/batch/{job_id} - Delete batch job and results

🔧 Developer API Ecosystem

🔌 MCP Server Integration

The YouTube Summarizer includes a FastMCP server providing Model Context Protocol tools:

# Use with Claude Code or other MCP-compatible tools
mcp_tools = [
    "extract_transcript",      # Extract video transcripts
    "generate_summary",        # Create AI summaries
    "batch_process",          # Process multiple videos
    "search_summaries",       # Search processed content
    "analyze_video"          # Deep video analysis
]

# MCP Resources for monitoring
mcp_resources = [
    "yt-summarizer://video-metadata/{video_id}",
    "yt-summarizer://processing-queue",
    "yt-summarizer://analytics"
]

📦 Native SDKs

Python SDK

from youtube_summarizer import YouTubeSummarizerClient

async with YouTubeSummarizerClient(api_key="your-api-key") as client:
    # Extract transcript
    transcript = await client.extract_transcript("https://youtube.com/watch?v=...")
    
    # Generate summary
    summary = await client.generate_summary(
        video_url="https://youtube.com/watch?v=...",
        summary_type="comprehensive"
    )
    
    # Batch processing
    batch = await client.batch_process(["url1", "url2", "url3"])

JavaScript/TypeScript SDK

import { YouTubeSummarizerClient } from '@youtube-summarizer/sdk';

const client = new YouTubeSummarizerClient({ apiKey: 'your-api-key' });

// Extract transcript with progress tracking
const transcript = await client.extractTranscript('https://youtube.com/watch?v=...', {
  onProgress: (progress) => console.log(`Progress: ${progress.percentage}%`)
});

// Generate summary with streaming
const summary = await client.generateSummary({
  videoUrl: 'https://youtube.com/watch?v=...',
  stream: true,
  onChunk: (chunk) => process.stdout.write(chunk)
});

🤖 Agent Framework Integration

LangChain Tools

from backend.integrations.langchain_tools import get_youtube_langchain_tools
from langchain.agents import create_react_agent

tools = get_youtube_langchain_tools()
agent = create_react_agent(llm=your_llm, tools=tools)

result = await agent.invoke({
    "input": "Summarize this YouTube video: https://youtube.com/watch?v=..."
})

Multi-Framework Support

from backend.integrations.agent_framework import create_youtube_agent_orchestrator

orchestrator = create_youtube_agent_orchestrator()

# Works with LangChain, CrewAI, AutoGen
result = await orchestrator.process_video(
    "https://youtube.com/watch?v=...",
    framework=FrameworkType.LANGCHAIN
)

🔄 Webhooks & Autonomous Operations

Webhook Events

// Register webhook endpoint
POST /api/autonomous/webhooks/my-app
{
  "url": "https://myapp.com/webhooks",
  "events": [
    "transcription.completed",
    "summarization.completed",
    "batch.completed",
    "error.occurred"
  ],
  "security_type": "hmac_sha256"
}

// Webhook payload example
{
  "event": "transcription.completed",
  "timestamp": "2024-01-20T10:30:00Z",
  "data": {
    "video_id": "abc123",
    "transcript": "...",
    "quality_score": 0.92,
    "processing_time": 45.2
  }
}

Autonomous Rules

# Configure autonomous operations
POST /api/autonomous/automation/rules
{
  "name": "Auto-Process Queue",
  "trigger": "queue_based",
  "action": "batch_process",
  "parameters": {
    "queue_threshold": 10,
    "batch_size": 5
  }
}

🔑 API Authentication

# Generate API key
POST /api/auth/api-keys
Authorization: Bearer {jwt-token}

# Use API key in requests
curl -H "X-API-Key: your-api-key" \
  https://api.yoursummarizer.com/v1/extract

📊 Rate Limiting

• Free Tier: 100 requests/hour, 1000 requests/day
• Pro Tier: 1000 requests/hour, 10000 requests/day
• Enterprise: Unlimited with custom limits

🌐 API Endpoints

Developer API v1

• POST /api/v1/extract - Extract transcript with options
• POST /api/v1/summarize - Generate summary
• POST /api/v1/batch - Batch processing
• GET /api/v1/status/{job_id} - Check job status
• POST /api/v1/search - Search processed content
• POST /api/v1/analyze - Deep video analysis
• GET /api/v1/webhooks - Manage webhooks
• POST /api/v1/automation - Configure automation

🚢 Deployment

Docker

docker build -t youtube-summarizer .
docker run -p 8082:8082 --env-file .env youtube-summarizer

Production Considerations

1. Database: Use PostgreSQL instead of SQLite for production
2. Security:
   • Configure proper CORS settings
   • Set up SSL/TLS certificates
   • Use strong JWT secret keys
   • Enable HTTPS-only cookies
3. Email Service: Configure production SMTP server (SendGrid, AWS SES, etc.)
4. Rate Limiting: Configure per-user rate limits
5. Monitoring:
   • Set up application monitoring (Sentry, New Relic)
   • Configure structured logging
   • Monitor JWT token usage
6. Scaling:
   • Use Redis for session storage and caching
   • Implement horizontal scaling with load balancer
   • Use CDN for static assets

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

📄 License

This project is part of the Personal AI Assistant ecosystem.

🔗 Related Projects

• Personal AI Assistant
• YouTube Automation Service
• PDF Translator

📞 Support

For issues and questions, please create an issue in the repository.