YouTube Transcript API

A powerful API to fetch YouTube video transcripts, built with Hono and youtubei.js.

Deployment Options:

🐳 Docker/Coolify (Self-hosted, recommended for most users)
☁️ Cloudflare Workers (Serverless edge deployment)

🚀 Quick Start

Option 1: Docker/Coolify Deployment (Recommended)

Perfect for self-hosting on your own infrastructure.

# Clone and install
git clone <your-repo-url>
cd youtube-transcript-api
npm install

# Development mode with hot reload
npm run dev

# Or run with Docker Compose
npm run docker:up

Deploy to Coolify: See COOLIFY_SETUP.md for step-by-step guide.

Option 2: Cloudflare Workers

Deploy to Cloudflare's edge network for global performance.

# Development
npm run cf:dev

# Deploy to Cloudflare
npm run cf:deploy

📋 Prerequisites

For Docker/Coolify:

Node.js v18 or later
Docker (optional for local testing)
Coolify instance or any Docker-compatible hosting

For Cloudflare Workers:

🔧 Installation

# Clone repository
git clone <your-repo-url>
cd youtube-transcript-api

# Install dependencies
npm install

💻 Development

Docker/Node.js Development

# Hot reload development server (port 3000)
npm run dev

# Build for production
npm run build

# Run production build
npm start

# Docker development
npm run docker:up      # Start with Docker Compose
npm run docker:logs    # View logs
npm run docker:down    # Stop containers

Cloudflare Workers Development

# Local development (port 8787)
npm run cf:dev

# Generate TypeScript types for bindings
npm run cf:typegen

🌐 API Endpoints

`GET /`

Fetches the transcript for a given YouTube video.

Query Parameters:

id (required): YouTube video ID or URL

Example Requests:

# Using video ID
curl "http://localhost:3000/?id=dQw4w9WgXcQ"

# Using full URL
curl "http://localhost:3000/?id=https://www.youtube.com/watch?v=dQw4w9WgXcQ"

# YouTube Shorts
curl "http://localhost:3000/?id=https://youtube.com/shorts/abc123"

Success Response (200 OK):

{
  "videoTitle": "Video Title Here",
  "transcript": [
    {
      "text": "Hello and welcome...",
      "offset": 0.5,
      "duration": 3.2
    },
    {
      "text": "In today's video...",
      "offset": 3.7,
      "duration": 2.8
    }
  ]
}

Error Responses:

Status	Description
`400`	Missing or invalid video ID/URL
`403`	Video is private or unavailable
`404`	No transcript available
`429`	Rate limit exceeded (5 req/min)
`451`	Region-locked video
`500`	Server error

`GET /health` (Docker/Coolify only)

Health check endpoint for monitoring.

Response:

{
  "status": "ok",
  "timestamp": "2024-11-12T10:30:00.000Z"
}

🚢 Deployment

Docker/Coolify Deployment

Quick Deploy:

Push to Git:

git add .
git commit -m "Deploy to Coolify"
git push

Configure in Coolify:
- Create new Application
- Connect your Git repository
- Build Pack: Dockerfile
- Port: 3000
- Health Check: /health
Deploy - Coolify handles the rest!

Detailed Guide: See COOLIFY_SETUP.md

Manual Docker Build:

# Build image
npm run docker:build

# Run container
npm run docker:run

# Or use Docker Compose
npm run docker:up

Cloudflare Workers Deployment

# Login to Cloudflare
wrangler login

# Deploy
npm run cf:deploy

After deployment, Cloudflare will provide your worker URL.

⚙️ Configuration

Environment Variables

Variable	Default	Description
`PORT`	`3000`	Server port (Docker/Node.js only)
`NODE_ENV`	`production`	Environment mode

Set in Docker Compose:

environment:
  - PORT=3000
  - NODE_ENV=production

Set in Coolify: Application → Environment Variables

Rate Limiting

Docker/Coolify:

5 requests per 60 seconds per IP
In-memory store (configure in server.ts)

Cloudflare Workers:

5 requests per 60 seconds per IP
Cloudflare Rate Limiter binding (configure in wrangler.toml)

📊 Deployment Comparison

Feature	Docker/Coolify	Cloudflare Workers
Infrastructure	Your server	Cloudflare Edge
Cold Start	~100-500ms	~0ms
Cost	Fixed server cost	Pay-as-you-go
Scalability	Manual	Auto-scale globally
Control	Full control	Cloudflare managed
Best For	Self-hosting, privacy	Global performance

🔒 Security Features

✅ Rate limiting per IP address
✅ Input validation for video IDs
✅ Non-root Docker user
✅ Comprehensive error handling
✅ Multi-stage Docker builds
✅ No sensitive data exposure

📚 Documentation

COOLIFY_SETUP.md - Quick Coolify deployment guide
DEPLOYMENT.md - Comprehensive deployment documentation
Dockerfile - Docker build configuration
docker-compose.yml - Docker Compose setup

🧪 Testing

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

# Fetch transcript
curl "http://localhost:3000/?id=Ks-_Mh1QhMc" | jq

# Test rate limiting (run 6 times quickly)
for i in {1..6}; do curl "http://localhost:3000/health"; done

🛠️ Available Scripts

Script	Description
`npm run dev`	Development server with hot reload (Node.js)
`npm run build`	Build TypeScript to JavaScript
`npm start`	Start production server (Node.js)
`npm run docker:build`	Build Docker image
`npm run docker:run`	Run Docker container
`npm run docker:up`	Start with Docker Compose
`npm run docker:down`	Stop Docker Compose
`npm run docker:logs`	View Docker logs
`npm run cf:dev`	Cloudflare Workers dev server
`npm run cf:deploy`	Deploy to Cloudflare
`npm run cf:typegen`	Generate Cloudflare types

🐛 Troubleshooting

Port Already in Use

# Change port
PORT=3001 npm start

Docker Build Fails

# Clear cache and rebuild
docker system prune -a
docker build --no-cache -t youtube-transcript-api .

Rate Limiting Too Strict

Edit server.ts (Docker) or wrangler.toml (Cloudflare):

// server.ts
const RATE_LIMIT_MAX = 10; // Increase from 5

Transcript Not Available

Some videos don't have transcripts. Check:

Video is public
Captions/subtitles are enabled
Not a live stream or premiere
Not region-locked

🔄 Migration Guide

From Cloudflare Workers to Docker:

All features are preserved! The Docker version includes:

✅ Same API endpoints
✅ Equivalent rate limiting
✅ Same error handling
✅ Additional health check endpoint

From Docker to Cloudflare Workers:

The original Cloudflare Worker is still available:

Use index.ts instead of server.ts
Deploy with npm run cf:deploy
Configure in wrangler.toml

🤝 Support

We build tools to help you get the most out of YouTube videos:

YoutubeVideoTranscripts.com: Get transcripts of any YouTube video for free. Watch while reading, search within transcripts, and download for offline use.
YouTube Transcript Plus (Chrome Extension): Enhance YouTube with full transcript reading, AI chat with videos, and AI-generated chapter summaries.

📝 License

This project is open source and available under your chosen license.

🎯 Tech Stack

Framework: Hono - Ultrafast web framework
YouTube API: youtubei.js - YouTube API wrapper
Runtime: Node.js 20+ / Cloudflare Workers
Language: TypeScript
Container: Docker with multi-stage builds

Ready to deploy? Check out COOLIFY_SETUP.md for the quickest path to production!

Name		Name	Last commit message	Last commit date
.dockerignore		.dockerignore
.gitignore		.gitignore
COOLIFY_SETUP.md		COOLIFY_SETUP.md
DEPLOYMENT.md		DEPLOYMENT.md
Dockerfile		Dockerfile
README.md		README.md
docker-compose.yml		docker-compose.yml
index.ts		index.ts
package-lock.json		package-lock.json
package.json		package.json
server.ts		server.ts
tsconfig.json		tsconfig.json
tsconfig.server.json		tsconfig.server.json
wrangler.toml		wrangler.toml
yarn.lock		yarn.lock

Latest commit

History

Folders and files

Repository files navigation