Ithildin - YouTube Transcript Downloader

A full-stack web application that extracts and exports YouTube video transcripts as professionally formatted PDFs with real-time progress tracking. Named after the seeing stone from Tolkien's legendarium, Ithildin reveals the hidden text within videos.

👨‍💻 Developer

Peyton Nowlin
📧 Peytonn98@Gmail.com
🌐 nowlinautomation.com

---

📋 Overview

This application provides a seamless way to download YouTube video transcripts and convert them into polished PDF documents. Built with modern web technologies, it features a responsive UI with real-time WebSocket updates, async background processing, and an intuitive user experience.

Key Features

• ⚡ Real-Time Updates: WebSocket-powered progress tracking for instant feedback
• 🚀 Async Processing: Non-blocking background tasks with FastAPI
• 📄 PDF Generation: Clean, professional PDF output with optional timestamps
• 🎨 Modern UI: Responsive Vue.js interface with dark theme and animations
• 🔌 RESTful API: Well-structured API endpoints for easy integration
• 📱 Mobile-Friendly: Fully responsive design for all devices

---

🛠️ Tech Stack

Backend

• FastAPI - High-performance async Python web framework
• Uvicorn - Lightning-fast ASGI server
• WebSockets - Real-time bidirectional communication
• Pydantic - Data validation and settings management

Frontend

• Vue.js 3 - Progressive JavaScript framework
• Vanilla CSS - Custom styling with modern CSS features
• WebSocket API - Real-time progress updates

Libraries

• youtube-transcript-api - YouTube transcript extraction
• FPDF - PDF document generation

---

🏗️ Architecture

Ithildin/
├── api/
│   ├── main.py              # FastAPI app & WebSocket manager
│   └── routes.py            # API route handlers
├── models/
│   └── transcript_model.py  # Business logic & PDF generation
├── frontend/
│   ├── index.html           # Vue.js SPA
│   ├── app.js               # Application logic
│   └── styles.css           # UI styling
├── downloads/               # Generated PDF storage
├── requirements.txt         # Python dependencies
└── run.py                   # Application entry point

Design Patterns

• MVC Architecture: Separation of concerns with models, routes, and views
• WebSocket Manager: Singleton pattern for connection management
• Async/Await: Non-blocking I/O operations throughout
• REST API: Standardized HTTP methods and status codes

---

🚀 Getting Started

Prerequisites

• Python 3.8 or higher
• pip (Python package manager)

Installation

1. Clone the repository

   git clone https://github.com/PeytonNowlin/Ithildin.git
   cd Ithildin

2. Install dependencies

   pip install -r requirements.txt

3. Run the application

   python run.py

   Or use uvicorn directly:

   uvicorn api.main:app --reload

4. Access the application

   Navigate to http://localhost:8000 in your browser

---

📖 Usage

1. Enter YouTube URL - Paste any valid YouTube video link
2. Configure Options - Choose whether to include timestamps
3. Download - Click the download button and watch real-time progress
4. Save PDF - Download the generated PDF transcript

Supported URL Formats

• https://www.youtube.com/watch?v={video_id}
• https://youtu.be/{video_id}
• https://www.youtube.com/embed/{video_id}

---

🔌 API Reference

Endpoints

Method	Endpoint	Description
GET	/	Serve frontend application
POST	/api/transcript/download	Initiate transcript download
GET	/api/transcript/download/{filename}	Download generated PDF
GET	/api/transcript/status/{file_id}	Check download status
WS	/ws/progress	WebSocket for progress updates

Example Request

import requests

response = requests.post('http://localhost:8000/api/transcript/download', json={
    'url': 'https://www.youtube.com/watch?v=dQw4w9WgXcQ',
    'include_timestamps': True
})

---

💡 Technical Highlights

• WebSocket Integration: Custom ConnectionManager class for efficient real-time updates
• Async Background Tasks: Non-blocking PDF generation using FastAPI's background tasks
• Error Handling: Comprehensive exception handling with user-friendly error messages
• CORS Support: Configured for cross-origin requests
• Responsive Design: CSS Grid and Flexbox for adaptive layouts
• Clean Code: Modular structure with separation of concerns

---

📦 Dependencies

youtube-transcript-api>=0.6.2
fpdf>=1.7.2
fastapi>=0.104.0
uvicorn[standard]>=0.24.0
websockets>=12.0
pydantic>=2.5.0

---

🎨 UI/UX Features

• Animated orb with pulsing glow effects
• Starfield background animation
• Real-time progress bar with percentage
• Smooth transitions and hover effects
• Status indicators for WebSocket connection
• Responsive mobile-first design

---

🔮 Future Enhancements

• Support for multiple languages
• Batch download functionality
• User authentication and history
• Cloud storage integration
• Advanced PDF formatting options
• Export to additional formats (TXT, JSON, SRT)

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

🤝 Connect

For questions, collaborations, or opportunities:

• Email: Peytonn98@Gmail.com
• Website: nowlinautomation.com
• GitHub: @PeytonNowlin

---

Built with ⚡ FastAPI + 💚 Vue.js

Version 3.0