# YT2AI - YouTube Subtitle Extraction & AI Summarization Bookmarklet

[![Build Status](https://github.com/yt2ai/yt2ai-bookmarklet/workflows/Build%20and%20Test%20YT2AI%20Bookmarklet/badge.svg)](https://github.com/yt2ai/yt2ai-bookmarklet/actions)
[![Coverage Status](https://codecov.io/gh/yt2ai/yt2ai-bookmarklet/branch/main/graph/badge.svg)](https://codecov.io/gh/yt2ai/yt2ai-bookmarklet)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

> **One-click YouTube subtitle extraction for AI-powered educational content analysis on Android Chrome**

## Overview

YT2AI is a lightweight, mobile-optimized bookmarklet that extracts YouTube auto-generated subtitles and prepares them for AI analysis. Designed specifically for Android Chrome users who want to quickly evaluate educational YouTube content without watching entire videos.

### Key Benefits
- ⚡ **2-3 minute evaluation** instead of 10-20 minutes of uncertain viewing
- 📱 **Mobile-first design** optimized for Android Chrome
- 🧠 **AI-ready output** formatted for Claude.ai integration
- 🚫 **Zero installation** required - works as a simple bookmark
- 🔒 **Privacy-focused** - no data storage or tracking
- 🎯 **85% technical success rate** for subtitle extraction

## Quick Start

### Installation (30 seconds)

1. **Copy the bookmarklet code:**
   ```javascript
   javascript:(function(){/* Minified code here - get from releases */})();
   ```

2. **Create bookmark in Chrome:**
   - Open Chrome on Android
   - Tap the ⭐ (bookmark) icon in address bar
   - Edit the bookmark
   - Replace URL with the copied javascript code
   - Name it "YT2AI Extractor"
   - Save

3. **Use on any YouTube video:**
   - Navigate to a YouTube video page
   - Tap your "YT2AI Extractor" bookmark
   - Wait for extraction (5-30 seconds)
   - Content is copied to clipboard and Claude.ai opens

### Usage Workflow

```
YouTube Video → Tap Bookmarklet → Subtitle Extraction → Claude.ai Analysis
    (1s)            (5-30s)              (Auto)
```

## Features

### 🎯 Core Functionality
- **Automatic video detection** from YouTube URLs (watch, shorts, embed)
- **Subtitle extraction** via downloadyoutubesubtitles.com API
- **Claude.ai integration** with automatic tab opening
- **Clipboard fallback** for manual paste scenarios
- **CAPTCHA handling** with user guidance

### 📱 Mobile Optimization
- **44px touch targets** for WCAG AA compliance
- **Portrait-optimized UI** with mobile breakpoints
- **Touch gesture support** (touchend events)
- **Network-aware timeouts** for mobile connections
- **Memory-efficient** (<10MB usage)

### 🛠️ Developer Experience
- **Comprehensive debugging** in development mode
- **Performance monitoring** with memory tracking
- **Error reporting** with stack trace capture
- **Mobile environment detection**
- **Zero build dependencies** in production

## Technical Specifications

### Browser Requirements
- **Android Chrome 90+** (primary target)
- **Mobile viewport** optimized experience
- **JavaScript ES6+** feature support
- **Clipboard API** for copy functionality

### Architecture
- **Vanilla JavaScript** - no external dependencies
- **Single-file distribution** - 8.7KB minified
- **Mobile-first responsive design**
- **CSP-compliant code structure**
- **YouTube-safe CSS** (yt2ai- prefixed)

### Performance Targets
- **Initialization:** <100ms
- **Subtitle extraction:** <60s normal conditions
- **Memory usage:** <10MB peak
- **Bundle size:** <10KB compressed

## Installation Guide

### For End Users

#### Method 1: Direct Installation (Recommended)
1. **Get the latest bookmarklet:**
   - Visit the [Releases page](https://github.com/yt2ai/yt2ai-bookmarklet/releases)
   - Copy the code from `bookmarklet.min.js`

2. **Install in Chrome Mobile:**
   - Open Chrome on your Android device
   - Go to any webpage
   - Tap the star (⭐) icon in the address bar
   - Tap "Edit" on the bookmark
   - Replace the URL field with the copied javascript code
   - Change the name to "YT2AI Extractor"
   - Tap "Save"

3. **Test the installation:**
   - Go to any YouTube video
   - Tap your new bookmark
   - You should see a "YT2AI Ready!" message

#### Method 2: QR Code Installation
1. Scan the QR code below to open the installation page
2. Follow the mobile-optimized installation wizard
3. The bookmarklet will be automatically configured

### For Developers

#### Development Setup
```bash
# Clone repository
git clone https://github.com/yt2ai/yt2ai-bookmarklet.git
cd yt2ai-bookmarklet

# Install dependencies
npm install

# Run development build
npm run build:dev

# Run tests
npm test

# Start development with file watching
npm run build:watch
```

#### Build Commands
```bash
npm run build          # Production build
npm run build:dev      # Development build with debugging
npm run test           # Run unit tests
npm run lint           # Code linting
npm run format         # Code formatting
npm run verify         # Full verification pipeline
```

## Usage Instructions

### Basic Usage
1. **Navigate to YouTube video** - Any video with auto-generated subtitles
2. **Tap bookmarklet** - Use your saved "YT2AI Extractor" bookmark
3. **Wait for processing** - Usually 5-30 seconds depending on video length
4. **Get results** - Claude.ai opens with formatted subtitle content

### Supported Video Types
- ✅ **Standard YouTube videos** (`youtube.com/watch?v=`)
- ✅ **YouTube Shorts** (`youtube.com/shorts/`)
- ✅ **Embedded videos** (`youtube.com/embed/`)
- ❌ **Playlists** (navigate to specific video first)
- ❌ **Live streams** (subtitles not available)

### What Gets Extracted
- **Auto-generated English subtitles** (when available)
- **Video metadata** (title, duration, video ID)
- **Formatted for AI analysis** with structured prompts
- **Mobile-optimized output** for easy reading

## Troubleshooting

### Common Issues

#### "No subtitles found"
- **Cause:** Video doesn't have auto-generated English subtitles
- **Solution:** Try a different video or check if subtitles exist manually

#### "CAPTCHA required"
- **Cause:** Subtitle API requires verification
- **Solution:** Follow the mobile-friendly CAPTCHA guidance popup

#### "Please navigate to a video"
- **Cause:** Not on a valid YouTube video page
- **Solution:** Make sure you're on youtube.com/watch?v=... or similar

#### Bookmarklet doesn't work
- **Check installation:** Ensure javascript: prefix is included
- **Check browser:** Must be Chrome 90+ on Android
- **Check network:** Ensure internet connection is stable

### Debug Mode
Add `?debug=true` to any YouTube URL to enable detailed logging:
```
https://www.youtube.com/watch?v=VIDEO_ID&debug=true
```

## Mobile Considerations

### Android Chrome Optimization
- **Touch-first interactions** with 44px minimum targets
- **Portrait orientation** optimized layouts
- **Mobile network timeouts** (30s vs 15s desktop)
- **Memory management** for resource-constrained devices
- **Gesture-friendly UI** with swipe and tap support

### Network Handling
- **Adaptive timeouts** based on connection quality
- **Retry logic** for mobile network instability
- **Progress indicators** for longer operations
- **Offline graceful degradation**

### Battery Optimization
- **Minimal CPU usage** with efficient JavaScript
- **Quick execution** to minimize active processing time
- **Automatic cleanup** to free memory resources
- **No background processes** or persistent connections

## Security & Privacy

### Privacy Principles
- **No data collection** - bookmarklet is stateless
- **No user tracking** - no analytics or telemetry
- **Local processing only** - no data sent to YT2AI servers
- **YouTube data only** - accesses only public subtitle data

### Security Features
- **Input validation** for all user data
- **XSS protection** through proper escaping
- **CSP compliance** with YouTube's security policies
- **No external dependencies** in production builds

### Third-Party Services
- **downloadyoutubesubtitles.com** - For subtitle extraction only
- **Claude.ai** - User's own subscription for AI analysis
- **No tracking services** - Google Analytics, Facebook Pixel, etc.

## Development

### Architecture Overview
```
src/
├── core/                    # Future: Core extraction logic
├── ui/                      # Future: UI components
├── utils/                   # Future: Utility functions
└── bookmarklet.js          # Main entry point (current)

build/
├── webpack.config.js       # Build configuration
└── README.md              # Build system documentation

tests/
├── unit/                  # Unit tests
├── integration/           # Integration tests
└── manual/               # Manual testing protocols
```

### Contributing Guidelines
1. **Fork the repository** and create a feature branch
2. **Follow coding standards** - ESLint and Prettier configurations
3. **Add tests** for new functionality (80% coverage target)
4. **Test on real devices** - Android Chrome compatibility
5. **Update documentation** for user-facing changes

### Code Standards
- **Vanilla JavaScript ES6+** - no frameworks or libraries
- **Mobile-first development** - touch and gesture optimized
- **Comprehensive error handling** - all async operations wrapped
- **Performance monitoring** - development mode metrics
- **Accessibility compliance** - WCAG AA standards

## API Integration

### Subtitle Extraction API
- **Service:** downloadyoutubesubtitles.com
- **Method:** GET requests with video ID
- **Format:** JSON response with subtitle text
- **Rate limiting:** Client-side throttling implemented
- **Error handling:** Comprehensive retry logic

### Claude.ai Integration
- **Method:** Browser tab automation
- **Fallback:** Clipboard copy for manual paste
- **Format:** Structured prompts for consistent analysis
- **Privacy:** Uses user's existing Claude.ai subscription

## Browser Compatibility

### Supported Browsers
- ✅ **Chrome 90+ (Android)** - Primary target, fully tested
- ✅ **Chrome 90+ (Desktop)** - Secondary support for development
- ❌ **Firefox Mobile** - Not supported (different bookmarklet handling)
- ❌ **Safari Mobile** - Not supported (iOS restrictions)
- ❌ **Samsung Internet** - Not tested

### Feature Detection
- **Clipboard API** - Graceful fallback to document.execCommand
- **Performance API** - Development-only, safe degradation
- **Network Information** - Progressive enhancement only
- **Touch Events** - Mobile-optimized with click fallbacks

## Performance

### Bundle Analysis
- **Production size:** 8.7KB minified
- **Development size:** 13.6KB with debugging
- **Compression ratio:** 36% size reduction
- **Load time:** <100ms on mobile networks

### Runtime Performance
- **Initialization:** <100ms target
- **Memory usage:** <10MB peak, <5MB typical
- **CPU usage:** Minimal, <1% during extraction
- **Network requests:** 1-2 per extraction cycle

### Mobile Optimization
- **Code splitting:** Single file for bookmarklet constraints
- **Tree shaking:** Unused code eliminated in production
- **Minification:** Terser with mobile-optimized settings
- **Polyfills:** Only for required ES6+ features

## Roadmap

### Version 1.1 (Next Release)
- **RPA automation** for Claude.ai form filling
- **Enhanced error recovery** with automatic retries
- **Performance optimizations** for slower devices
- **Extended browser support** testing

### Version 1.2 (Future)
- **Multiple AI providers** support (GPT, Gemini)
- **Subtitle language options** beyond English
- **Batch processing** for playlist support
- **Custom prompt templates** for different use cases

### Long-term Vision
- **Progressive Web App** version for enhanced mobile experience
- **Browser extension** for advanced features
- **API service** for developers and integrations
- **Analytics dashboard** for usage insights (opt-in)

## Support

### Getting Help
- **GitHub Issues** - Bug reports and feature requests
- **Discussions** - Community support and questions
- **Wiki** - Extended documentation and guides
- **Email Support** - For private or urgent issues

### Community Resources
- **Developer Guide** - Extended technical documentation
- **Mobile Testing Guide** - Device-specific testing procedures
- **Integration Examples** - Sample implementations
- **Video Tutorials** - Step-by-step usage guides

## License

MIT License - see [LICENSE](LICENSE) file for details.

## Acknowledgments

- **downloadyoutubesubtitles.com** - Reliable subtitle extraction API
- **Claude.ai** - AI analysis capabilities
- **Android Chrome team** - Excellent mobile browser platform
- **Open source community** - Testing and feedback

---

**Made with ❤️ for mobile educational content consumption**

For more information, visit our [documentation site](https://yt2ai.github.io/yt2ai-bookmarklet/) or check the [developer guide](docs/DEVELOPER.md).