extract-youtube 1.0.421 → 1.0.423

package/README.md

@@ -1,757 +1,849 @@
-<p align="center">
-    <img width="300px" src="https://i.imgur.com/dwg2IYg.png" />
-</p>
-
-<!-- template-git-repo:badges:start -->
-<p align="center">
-    <a href="https://qwksearch.com/api"><img src="https://img.shields.io/badge/Docs-blue?logo=ReadTheDocs&logoColor=white" alt="Documentation" /></a>
-    <br />
-    <a href="https://github.com/OpenSourceAGI/qwksearch-research-agent/stargazers"><img src="https://img.shields.io/github/stars/OpenSourceAGI/qwksearch-research-agent" alt="GitHub Stars" /></a>
-    <a href="https://www.npmjs.com/package/extract-youtube"><img src="https://img.shields.io/npm/dm/extract-youtube.svg" alt="NPM Monthly Downloads" /></a>
-    <a href="https://www.npmjs.com/package/extract-youtube"><img src="https://img.shields.io/npm/v/extract-youtube.svg" alt="npm version" /></a>
-    <a href="https://www.npmjs.com/package/extract-youtube"><img src="https://img.shields.io/npm/dt/extract-youtube.svg" alt="NPM Total Downloads" /></a>
-    <a href="https://www.npmjs.com/package/extract-youtube"><img src="https://img.shields.io/npm/types/extract-youtube" alt="TypeScript types" /></a>
-    <a href="https://packagephobia.com/result?p=extract-youtube"><img src="https://packagephobia.com/badge?p=extract-youtube" alt="Install size" /></a>
-    <br />
-    <a href="https://github.com/OpenSourceAGI/qwksearch-research-agent/issues"><img src="https://img.shields.io/github/issues/OpenSourceAGI/qwksearch-research-agent?logo=github" alt="GitHub Issues" /></a>
-    <a href="https://github.com/OpenSourceAGI/qwksearch-research-agent/pulls"><img src="https://img.shields.io/github/issues-pr/OpenSourceAGI/qwksearch-research-agent?logo=github&label=PRs" alt="Open Pull Requests" /></a>
-    <a href="https://github.com/OpenSourceAGI/qwksearch-research-agent/pulls?q=is%3Apr+is%3Aclosed"><img src="https://img.shields.io/github/issues-pr-closed/OpenSourceAGI/qwksearch-research-agent?logo=github&label=PRs%20merged&color=8957e5" alt="Merged Pull Requests" /></a>
-    <a href="https://github.com/OpenSourceAGI/qwksearch-research-agent/discussions"><img src="https://img.shields.io/github/discussions/OpenSourceAGI/qwksearch-research-agent" alt="GitHub Discussions" /></a>
-    <a href="https://github.com/OpenSourceAGI/qwksearch-research-agent/commits/master/"><img src="https://img.shields.io/github/last-commit/OpenSourceAGI/qwksearch-research-agent.svg" alt="GitHub last commit" /></a>
-    <br />
-    <a href="https://stackblitz.com/github/OpenSourceAGI/qwksearch-research-agent/tree/master/packages/extract-youtube"><img height="20px" src="https://developer.stackblitz.com/img/open_in_stackblitz.svg" alt="Open in StackBlitz" /></a>
-    <img src="https://img.shields.io/badge/Bun-14151A?logo=bun&logoColor=white" alt="Bun" /> <img src="https://img.shields.io/badge/TypeScript-3178C6?logo=typescript&logoColor=white" alt="TypeScript" /> <img src="https://img.shields.io/badge/React-20232A?logo=react&logoColor=white" alt="React" /> <img src="https://img.shields.io/badge/Vite-646CFF?logo=vite&logoColor=white" alt="Vite" /> <img src="https://img.shields.io/badge/Jest-C21325?logo=jest&logoColor=white" alt="Jest" />
-</p>
-<!-- template-git-repo:badges:end -->
-
-# Extract YouTube Transcript 
-.
-⚡ **No API keys, no headless browsers, no dependencies. Only the fastest, most optimized YouTube transcript extractor.**
-
-A production-ready TypeScript port of the popular Python [`extract-youtube`](https://github.com/dbeley/youtube_extract) (100k+ monthly PyPI downloads), optimized for serverless environments and edge computing. No API keys, no headless browsers, no dependencies bloat.
-
-## Why This Package?
-
-### 🚀 **Superior to Other NPM Alternatives**
-
-- 
-- ✅ **Proven algorithm** - Direct port of Python's `extract-youtube` (100k+ monthly PyPI downloads)
-- ✅ **Serverless-first** - Works flawlessly in AWS Lambda, Vercel, Cloudflare Workers, Next.js Edge
-- ✅ **70% smaller** - ~7KB gzipped vs 20-30KB+ for alternatives
-- ✅ **Zero native deps** - Pure TypeScript, no puppeteer or heavy scraping libraries
-- ✅ **Better DX** - Full TypeScript, comprehensive error handling, tree-shakeable
-- ✅ **Battle-tested** - Same extraction logic trusted by 100k+ monthly users
-
-### 📊 **Package Comparison**
-
-| Feature                       | **extract-youtube** (this) | youtube-transcript (npm) | extract-youtube (Python) |
-| ----------------------------- | -------------------------------- | ------------------------ | ------------------------------- |
-| **Language**            | TypeScript/Node.js               | JavaScript/Node.js       | Python                          |
-| **Bundle Size**         | **~7KB gzipped**           | ~20-30KB+                | N/A                             |
-| **Serverless Ready**    | ✅ Yes                           | ⚠️ Limited             | ❌ No                           |
-| **Edge Compatible**     | ✅ Yes                           | ❌ No                    | ❌ No                           |
-| **Native Deps**         | ✅ None                          | ⚠️ Some                | ✅ None                         |
-| **Type Safety**         | ✅ Full TypeScript               | ⚠️ Partial             | ❌ No                           |
-| **Auto-generated Subs** | ✅ Yes                           | ✅ Yes                   | ✅ Yes                          |
-| **Translation**         | ✅ Yes                           | ⚠️ Limited             | ✅ Yes                          |
-| **Proxy Support**       | ✅ Advanced                      | ⚠️ Basic               | ✅ Yes                          |
-| **Error Handling**      | ✅ Comprehensive                 | ⚠️ Basic               | ✅ Good                         |
-| **CLI Tool**            | ✅ Yes                           | ❌ No                    | ✅ Yes                          |
-| **Format Output**       | ✅ 6 formats                     | ⚠️ 1-2 formats         | ✅ 5 formats                    |
-| **Monthly Downloads**   | Growing                          | ~50k                     | ~400k (PyPI)                    |
-| **Code Quality**        | ⭐⭐⭐⭐⭐                       | ⭐⭐⭐                   | ⭐⭐⭐⭐⭐                      |
-
-### 🎯 **Why Choose This Over Python?**
-
-**Top packages for YouTube transcripts are `youtube-transcript` (JS/NPM) and `extract-youtube` (Python).** This package combines the best of both:
-
-1. **Same reliability as Python** - Direct port of the proven Python implementation
-2. **Better for modern stacks** - Works natively in Node.js, Next.js, React Server Components
-3. **Serverless-first** - Perfect for AWS Lambda, Vercel Functions, Cloudflare Workers
-4. **Faster cold starts** - No Python runtime overhead
-5. **Modern tooling** - NPM ecosystem, TypeScript, tree-shaking, ESM/CJS
-
-### ⚡ **Optimized for Production**
-
-- **Bundle optimized with Vite + Terser** - Aggressive minification and tree-shaking
-- **Dual ESM/CJS builds** - Works everywhere (Node.js, bundlers, edge runtimes)
-- **Zero external HTTP clients** - Uses native `grab-url` (polyfilled in browsers)
-- **Efficient parsing** - Fast XML parsing with minimal memory footprint
-
-## 🎯 Quick Facts
-
-```
-Bundle Size:    7KB gzipped    (vs 20-30KB for alternatives)
-Cold Start:     ~50ms          (vs 150-500ms for alternatives)
-Memory:         ~30MB          (vs 45-80MB for alternatives)
-Dependencies:   4 minimal      (vs 10-50+ for alternatives)
-Serverless:     ✅ Optimized   (vs ⚠️ Limited support)
-TypeScript:     ✅ Full        (vs ⚠️ Partial/None)
-```
-
-## Installation
-
-```bash
-npm install extract-youtube
-```
-
-**Or try it instantly with npx:**
-
-```bash
-npx extract-youtube dQw4w9WgXcQ
-```
-
-## Quick Start
-
-```typescript
-import { YouTubeTranscriptApi } from 'extract-youtube';
-
-const api = new YouTubeTranscriptApi();
-const transcript = await api.fetch('dQw4w9WgXcQ');
-
-for (const snippet of transcript) {
-  console.log(`${snippet.start}s: ${snippet.text}`);
-}
-```
-
-## Basic Usage
-
-```typescript
-// Fetch with language preference
-const transcript = await api.fetch('video_id', {
-  languages: ['de', 'en']  // Try German first, then English
-});
-
-// List available transcripts
-const transcriptList = await api.list('video_id');
-for (const t of transcriptList) {
-  console.log(`${t.language} (${t.languageCode})`);
-}
-
-// Find and translate
-const transcript = transcriptList.findTranscript(['en']);
-const translated = transcript.translate('de');
-const fetched = await translated.fetch();
-```
-
-## Formatters
-
-```typescript
-import { SRTFormatter, WebVTTFormatter, JSONFormatter, ArticleFormatter } from 'extract-youtube';
-
-const transcript = await api.fetch('video_id');
-
-// SRT format
-const srt = new SRTFormatter().formatTranscript(transcript);
-
-// WebVTT format
-const webvtt = new WebVTTFormatter().formatTranscript(transcript);
-
-// JSON format
-const json = new JSONFormatter().formatTranscript(transcript, { indent: 2 });
-
-// Article format with character-to-timestamp mappings
-const article = new ArticleFormatter().formatTranscript(transcript);
-console.log(article);
-// Output:
-// {
-//   "text": "Full transcript text...",
-//   "timestamps": "10,15,20  100,200,300",  // speeds and positions
-//   "wordCount": 1234,
-//   "charCount": 5678
-// }
-```
-
-## Proxy Support
-
-```typescript
-import { WebshareProxyConfig } from 'extract-youtube';
-
-const api = new YouTubeTranscriptApi({
-  proxyConfig: new WebshareProxyConfig({
-    proxyUsername: 'your-username',
-    proxyPassword: 'your-password'
-  })
-});
-```
-
-See [docs/proxy.md](./docs/proxy.md) for the full guide: generic vs. Webshare
-proxies, the CLI flags, why `proxyConfig` does nothing on Cloudflare
-Workers/edge (and what to use there instead), and caching in front of the
-fetcher so a proxy request is only spent on a video you don't already have.
-
-## Error Handling
-
-```typescript
-import { TranscriptsDisabled, NoTranscriptFound } from 'extract-youtube';
-
-try {
-  const transcript = await api.fetch('video_id');
-} catch (error) {
-  if (error instanceof TranscriptsDisabled) {
-    console.error('Subtitles are disabled');
-  } else if (error instanceof NoTranscriptFound) {
-    console.error('No transcript found');
-  }
-}
-```
-
-## CLI Usage
-
-After installing globally or using npx, you can use the `extract-youtube` command:
-
-```bash
-# Install globally
-npm install -g extract-youtube
-
-# Or use with npx
-npx extract-youtube <video-id> [options]
-```
-
-### CLI Examples
-
-```bash
-# Extract transcript in JSON format (default)
-extract-youtube jNQXAC9IVRw
-
-# Extract transcript in SRT format
-extract-youtube jNQXAC9IVRw -f srt
-
-# Extract transcript with specific languages
-extract-youtube jNQXAC9IVRw -l en,de
-
-# Extract transcript with proxy
-extract-youtube jNQXAC9IVRw --proxy http://proxy.example.com:8080
-
-# Extract transcript with Webshare proxy
-extract-youtube jNQXAC9IVRw --webshare-user myuser --webshare-pass mypass
-
-# Extract as plain text with preserved formatting
-extract-youtube jNQXAC9IVRw -f text -p
-
-# Show help
-extract-youtube --help
-```
-
-### CLI Options
-
-- `-h, --help` - Show help message
-- `-v, --version` - Show version number
-- `-l, --languages <codes>` - Comma-separated language codes (e.g., en,de,fr)
-- `-f, --format <type>` - Output format: json, text, srt, webvtt, pretty, article (default: json)
-- `-p, --preserve-formatting` - Preserve text formatting (line breaks, etc.)
-- `--proxy <url>` - HTTP/HTTPS proxy URL
-- `--webshare-user <username>` - Webshare proxy username
-- `--webshare-pass <password>` - Webshare proxy password
-
-## React Components (Floating Player + Transcript Modal)
-
-`extract-youtube/react` is the package's UI half — two self-contained
-components, both ported from the video player used in production on
-[debate-ai.com](https://debate-ai.com), with everything app-specific
-stripped out. Neither depends on a design system, a state library, or a CSS
-framework: they inject their own minimal scoped styles and drop into any
-React app.
-
-- **`<FloatingYouTubePlayer />`** — a floating, draggable, resizable player
-  that keeps playing while the user moves around your app. Mount it once;
-  drive it from anywhere with `youtubePlayer.play({ videoId })`.
-- **`<YouTubeTranscriptModal />`** — a popout modal with the video on the
-  left and a transcript panel on the right that scrolls and highlights in
-  sync with playback; click any line to seek.
-
-### Why it's a separate entry point
-
-`extract-youtube` (the main entry) fetches captions server-side with no
-browser dependency at all — that's the whole point of the package.
-`extract-youtube/react` is a second, independent entry point that only
-exports UI: it never imports the transcript-fetching code, and the main
-entry never imports React. Import only the one you need and the other never
-ends up in your bundle. React, ReactDOM, and `lucide-react` (used for the
-icons) are peer dependencies — install them yourself if you don't already
-have them:
-
-```bash
-npm install extract-youtube react react-dom lucide-react
-```
-
-### The floating player
-
-Mount it once, near the root of your app. It renders through a portal into
-`document.body`, so nothing in the tree around it can clip it, hide it, or
-remount the playing video on a route change. It renders nothing at all until
-something asks it to play.
-
-```tsx
-// app/layout.tsx (or wherever your app root lives)
-import { FloatingYouTubePlayer } from 'extract-youtube/react';
-
-export default function RootLayout({ children }) {
-  return (
-    <>
-      {children}
-      <FloatingYouTubePlayer transcriptUrl="/api/transcript" />
-    </>
-  );
-}
-```
-
-Then play something from anywhere — a grid, a search result, a keyboard
-shortcut. No context provider, no prop drilling:
-
-```tsx
-import { youtubePlayer, usePlayerState, thumbnailUrl } from 'extract-youtube/react';
-
-function VideoCard({ videoId, title }: { videoId: string; title: string }) {
-  const { activeVideo } = usePlayerState();
-
-  return (
-    <button onClick={() => youtubePlayer.play({ videoId, title })}>
-      <img src={thumbnailUrl(videoId)} alt="" />
-      {title} {activeVideo?.videoId === videoId && '(playing)'}
-    </button>
-  );
-}
-```
-
-What you get, without wiring any of it up yourself:
-
-| | |
-| --- | --- |
-| **Drag & resize** | Drag by the title bar, resize from either side edge or a bottom corner, clamped to the viewport. Mouse and touch. |
-| **Minimize** | Collapses to the title bar. The iframe is hidden with CSS, never unmounted, so playback isn't interrupted. |
-| **Picture-in-picture** | Pops the video into an always-on-top OS window via the Document Picture-in-Picture API, where the browser supports it. The node is *moved*, not cloned, so playback continues. |
-| **Queue** | `addToQueue` / `setQueue` / `playNext`, with an "Up next" strip under the video. |
-| **Synced captions** | Optional subtitles panel above the video — caption cues are regrouped into whole sentences (no timestamps), the spoken one highlights and auto-scrolls, and clicking a sentence seeks. Needs `transcriptUrl` or `fetchTranscript` (see below). |
-| **Resume** | Remembers what was playing, and how far into it, across a reload — plus a per-video position for the last 50 videos, for 24 hours. `storageKey={null}` turns it off. |
-| **Error recovery** | Reads the IFrame API's error codes, explains them ("this video is private", "the owner doesn't allow embedding"), and offers Retry or Watch on YouTube from the same spot. |
-| **Theming** | Colours are CSS custom properties on `.eytp-root` and follow `prefers-color-scheme` by default. Override them to match your app. |
-
-#### Custom controls belong to your app, not the package
-
-The built-in control strip only holds buttons that mean the same thing for
-any YouTube video: play/pause, skip, captions, picture-in-picture, minimize,
-close. Anything specific to *your* product — a bookmark, a share menu, a
-speed control framed for your users — is yours to render, through
-`extraControls`:
-
-```tsx
-import { Gauge } from 'lucide-react';
-import { FloatingYouTubePlayer } from 'extract-youtube/react';
-
-<FloatingYouTubePlayer
-  transcriptUrl="/api/transcript"
-  extraControls={({ playbackRate, player }) => (
-    <button
-      // The player's own control classes, so custom buttons match the built-ins.
-      className={`eytp-btn${playbackRate !== 1 ? ' eytp-btn-active' : ''}`}
-      onClick={() => player.setPlaybackRate(playbackRate !== 1 ? 1 : 0.65)}
-      title="Slow it down"
-    >
-      <Gauge size={13} />
-    </button>
-  )}
-/>
-```
-
-debate-ai.com uses exactly this seam for its "slow the debate spread down"
-button — its own label, icon and rate, sitting in the same strip. The
-package stays generic: it exposes `player.setPlaybackRate()` and reports the
-current `playbackRate`, and the host decides what the button says and does.
-`renderTitle` is the same idea for the title bar, if you want badges or
-links instead of a plain video title.
-
-#### The imperative API
-
-Everything the player can do is on `youtubePlayer`, importable anywhere:
-
-```ts
-import { youtubePlayer, usePlayerState, getPlayerState } from 'extract-youtube/react';
-
-youtubePlayer.play({ videoId, title, meta });  // meta is yours; passed back untouched
-youtubePlayer.play({ videoId }, { startSeconds: 120 });
-youtubePlayer.togglePlay();
-youtubePlayer.seekTo(90);
-youtubePlayer.setPlaybackRate(1.5);
-youtubePlayer.addToQueue({ videoId, title });
-youtubePlayer.setQueue(videos);                // e.g. "play all" over a grid
-youtubePlayer.playNext();
-youtubePlayer.getCurrentTime();                // seconds
-youtubePlayer.close();
-
-usePlayerState();   // in a component: { activeVideo, isPlaying, isMinimized, playbackRate, queue, startTime }
-getPlayerState();   // the same, outside React
-```
-
-#### Floating player props
-
-| Prop | Type | Description |
-| --- | --- | --- |
-| `transcriptUrl` | `string` | Your captions endpoint (see below). Enables the subtitles button. |
-| `fetchTranscript` | `(videoId: string) => Promise<{ snippets, error? }>` | Custom caption loader, instead of `transcriptUrl`. |
-| `extraControls` | `ReactNode \| (ctx: PlayerControlContext) => ReactNode` | Your own buttons, rendered in the control strip. |
-| `renderTitle` | `(ctx: PlayerControlContext) => ReactNode` | Custom title-bar content. Defaults to the video title. |
-| `showSubtitles` | `boolean` | Force the captions button on or off. By default it appears only for videos that turned out to have a transcript — every video played is checked, and one without captions gets no button and no error. |
-| `showPictureInPicture` | `boolean` | Show the PiP button where supported. Default `true`. |
-| `storageKey` | `string \| null` | localStorage key for resume-after-reload. `null` disables persistence entirely. |
-| `className` | `string` | Extra class on the player root, for host-side positioning or theming. |
-| `onClose` | `() => void` | Called when the user closes the player. |
-| `minWidth` / `maxWidth` | `number` | Resize bounds in px. Default 256 / 800. |
-
-### Setup: video captions still have to be fetched server-side
-
-Neither component talks to YouTube's caption endpoints directly — browsers
-can't (no CORS, and it would leak this package's whole fetching strategy
-client-side for no benefit). Instead, you expose one small backend endpoint
-that calls this package's `YouTubeTranscriptApi`, and point the components
-at it with `transcriptUrl`.
-
-**1. Add a backend endpoint** (any framework works — this is a Next.js
-route handler, following the same pattern as the Vercel Edge example
-above):
-
-```typescript
-// app/api/transcript/route.ts
-import { NextRequest, NextResponse } from 'next/server';
-import { YouTubeTranscriptApi, extractVideoId } from 'extract-youtube';
-
-const api = new YouTubeTranscriptApi();
-
-export async function GET(req: NextRequest) {
-  const raw = req.nextUrl.searchParams.get('videoId');
-  const videoId = raw ? extractVideoId(raw) : null;
-  if (!videoId) {
-    return NextResponse.json({ error: 'Missing videoId' }, { status: 400 });
-  }
-
-  try {
-    const transcript = await api.fetchTranscript(videoId, { languages: ['en'] });
-    return NextResponse.json({ videoId, snippets: transcript.toRawData() });
-  } catch (error) {
-    // 200 + an `error` field, not a 4xx/5xx — "no captions for this video"
-    // isn't a server failure, and the components check this field either way.
-    return NextResponse.json({
-      videoId,
-      snippets: [],
-      error: error instanceof Error ? error.message : 'Failed to fetch transcript',
-    });
-  }
-}
-```
-
-**2. Point the components at it** with `transcriptUrl="/api/transcript"`.
-The `videoId` query param is appended for you, and one request is shared
-per video across every component asking for it.
-
-`extractVideoId` (exported from the main entry, since it runs fine in Node)
-accepts any of the URL shapes YouTube uses — watch, youtu.be, embed, shorts,
-live — so you can pass what a user pastes in straight through.
-
-### Transcript modal
-
-```tsx
-import { YouTubeTranscriptModal } from 'extract-youtube/react';
-import { extractVideoId } from 'extract-youtube';
-
-function VideoCard({ url, title }: { url: string; title: string }) {
-  const videoId = extractVideoId(url);
-  if (!videoId) return null;
-
-  return <YouTubeTranscriptModal videoId={videoId} title={title} transcriptUrl="/api/transcript" />;
-}
-```
-
-| Prop | Type | Description |
-| --- | --- | --- |
-| `videoId` | `string` | **Required.** The YouTube video ID (not a full URL — run it through `extractVideoId` first if needed). |
-| `title` | `string` | Shown in the modal header and as the iframe's accessible title. |
-| `transcriptUrl` | `string` | URL of your backend endpoint (see above). Fetched with `fetch()` when the modal opens. The `videoId` query param is appended automatically if not already present. |
-| `fetchTranscript` | `(videoId: string) => Promise<{ snippets, error? }>` | Use instead of `transcriptUrl` if you want to load the transcript some other way (e.g. from a React Query cache). |
-| `snippets` | `TranscriptSnippet[]` | Pass transcript data directly to skip fetching entirely — e.g. if you already loaded it server-side. |
-| `trigger` | `ReactNode` | Custom element that opens the modal on click. Defaults to a small captions-icon button. |
-| `onOpenChange` | `(open: boolean) => void` | Called whenever the modal opens or closes. |
-
-### Demo: a video library, a floating player, synced subtitles
-
-The `demo/` folder is a small standalone app — an Express server for the
-transcript endpoint plus a Vite/React page — that puts the whole thing
-together: a **grid of saved favorite videos** to pick from, the floating
-player they open in, a queue, and per-card transcripts.
-
-```bash
-cd packages/extract-youtube
-npm run build          # builds dist/ (main lib + dist/react), which the demo depends on
-npm run demo           # installs the demo's own deps and starts it
-```
-
-`npm run demo` runs `cd demo && npm install && npm run dev`, which starts
-both the Express transcript API (port 8787) and the Vite dev server
-(port 5173, proxying `/api` to 8787) together. Open
-**http://localhost:5173** and click any video in the grid: it opens in the
-floating player, which you can drag, resize, minimize or pop out while you
-keep browsing. Star videos to favorite them, queue more up, hit **Play all**
-to run the grid as a playlist, or turn on the captions button to follow a
-synced transcript.
-
-Run the two halves separately if you'd rather:
-
-```bash
-cd packages/extract-youtube/demo
-npm install
-npm run server   # Express API on :8787
-npm run dev      # in another terminal — Vite dev server on :5173
-```
-
-See `demo/README.md` for what each file does — including
-`demo/src/SpeedButton.jsx`, the worked example of an app-supplied custom
-control.
-
-## Features
-
-### Core Functionality
-
-- ✅ Retrieve transcripts for any YouTube video (no API key needed)
-- ✅ Support for manually created and auto-generated subtitles
-- ✅ Translate transcripts to 100+ languages
-- ✅ Multiple output formats (JSON, Text, SRT, WebVTT, Pretty Print, Article)
-- ✅ Language preference fallback system
-- ✅ Timed segments with start/duration timestamps
-
-### Developer Experience
-
-- ✅ **Full TypeScript support** with comprehensive type definitions
-- ✅ **Tree-shakeable** - Only bundle what you use
-- ✅ **ESM + CJS** - Works with all module systems
-- ✅ **Zero configuration** - Works out of the box
-- ✅ Comprehensive JSDoc documentation
-- ✅ Intuitive error messages with troubleshooting guidance
-
-### Advanced Features
-
-- ✅ **Proxy support** (Generic HTTP/HTTPS & Webshare residential proxies)
-- ✅ **Rate limit handling** with rotating IP pools
-- ✅ **Serverless-optimized** - No file system dependencies
-- ✅ **Edge runtime compatible** - Runs on Cloudflare Workers, Vercel Edge
-- ✅ Command-line interface (CLI) for quick extraction
-
-### Production Ready
-
-- ✅ Battle-tested algorithm from Python package (100k+ monthly downloads)
-- ✅ Comprehensive error handling with typed exceptions
-- ✅ Automatic retry logic for network failures
-- ✅ Small bundle size (~7KB gzipped)
-- ✅ No native dependencies or binaries
-
-## Serverless & Edge Deployment
-
-This package is optimized for serverless and edge computing environments:
-
-### AWS Lambda
-
-```typescript
-import { YouTubeTranscriptApi } from 'extract-youtube';
-
-export const handler = async (event) => {
-  const api = new YouTubeTranscriptApi();
-  const transcript = await api.fetch(event.videoId);
-
-  return {
-    statusCode: 200,
-    body: JSON.stringify(transcript.toRawData())
-  };
-};
-```
-
-### Vercel Edge Functions
-
-```typescript
-import { YouTubeTranscriptApi } from 'extract-youtube';
-
-export const config = { runtime: 'edge' };
-
-export default async function handler(req: Request) {
-  const { searchParams } = new URL(req.url);
-  const videoId = searchParams.get('videoId');
-
-  const api = new YouTubeTranscriptApi();
-  const transcript = await api.fetch(videoId);
-
-  return new Response(JSON.stringify(transcript.toRawData()), {
-    headers: { 'content-type': 'application/json' }
-  });
-}
-```
-
-### Cloudflare Workers
-
-```typescript
-import { YouTubeTranscriptApi } from 'extract-youtube';
-
-export default {
-  async fetch(request: Request) {
-    const url = new URL(request.url);
-    const videoId = url.searchParams.get('videoId');
-
-    const api = new YouTubeTranscriptApi();
-    const transcript = await api.fetch(videoId);
-
-    return new Response(JSON.stringify(transcript.toRawData()), {
-      headers: { 'content-type': 'application/json' }
-    });
-  }
-};
-```
-
-### Next.js Server Actions / API Routes
-
-```typescript
-'use server';
-
-import { YouTubeTranscriptApi } from 'extract-youtube';
-
-export async function getTranscript(videoId: string) {
-  const api = new YouTubeTranscriptApi();
-  return await api.fetch(videoId);
-}
-```
-
-### Why It Works Great in Serverless
-
-- ✅ **Fast cold starts** - Minimal initialization overhead
-- ✅ **No file system** - Pure in-memory operations
-- ✅ **Small bundle** - Fits well within size limits
-- ✅ **No native deps** - No compilation needed
-- ✅ **Stateless** - Perfect for serverless architecture
-
-## Testing
-
-```bash
-npm test
-```
-
-## Performance Benchmarks
-
-### Bundle Size Comparison
-
-```
-extract-youtube (this):     ~7KB gzipped   ✅
-youtube-transcript:         ~25KB gzipped  ❌
-ytdl-core:                  ~300KB+        ❌❌
-puppeteer-based solutions:  ~200MB+        ❌❌❌
-```
-
-### Cold Start Times (AWS Lambda)
-
-```
-extract-youtube:    ~50ms   ✅
-youtube-transcript: ~150ms  ⚠️
-Python package:     ~500ms  ❌
-```
-
-### Memory Usage
-
-```
-extract-youtube:    ~30MB   ✅
-youtube-transcript: ~45MB   ⚠️
-Python package:     ~80MB   ❌
-```
-
-
-## Reliability
-
-This package uses the same proven algorithm as the Python `extract-youtube`:
-
-- ✅ **100k+ monthly downloads** on PyPI (Python version)
-- ✅ **Battle-tested** across thousands of production deployments
-- ✅ **Maintained** - Regular updates to handle YouTube API changes
-- ✅ **Comprehensive error handling** - Clear error messages for all failure modes
-
-**Unlike scraping-based alternatives**, this package:
-
-- Fetches transcripts directly from YouTube's caption endpoints
-- Doesn't rely on brittle HTML parsing
-- Handles both manual and auto-generated captions
-- Works with age-restricted videos (with authentication)
-
-## Common Use Cases
-
-### 1. AI/ML Applications
-
-```typescript
-// Extract transcripts for training data, analysis, or AI processing
-const transcript = await api.fetch('video_id');
-const text = transcript.snippets.map(s => s.text).join(' ');
-// Feed to GPT, LLM, or ML model
-```
-
-### 2. Accessibility Tools
-
-```typescript
-// Generate subtitles in multiple formats
-const transcript = await api.fetch('video_id');
-const srt = new SRTFormatter().formatTranscript(transcript);
-const webvtt = new WebVTTFormatter().formatTranscript(transcript);
-```
-
-### 3. Content Analysis
-
-```typescript
-// Analyze video content programmatically
-const transcript = await api.fetch('video_id');
-for (const snippet of transcript) {
-  if (snippet.text.includes('keyword')) {
-    console.log(`Found at ${snippet.start}s: ${snippet.text}`);
-  }
-}
-```
-
-### 4. Translation Services
-
-```typescript
-// Translate videos to multiple languages
-const list = await api.list('video_id');
-const transcript = list.findTranscript(['en']);
-const german = await transcript.translate('de').fetch();
-const spanish = await transcript.translate('es').fetch();
-```
-
-## Troubleshooting
-
-### Rate Limiting / IP Blocks
-
-If you're getting blocked by YouTube:
-
-```typescript
-import { YouTubeTranscriptApi, WebshareProxyConfig } from 'extract-youtube';
-
-const api = new YouTubeTranscriptApi({
-  proxyConfig: new WebshareProxyConfig({
-    proxyUsername: 'your-username',
-    proxyPassword: 'your-password',
-    // Rotate through 30M+ residential IPs
-  })
-});
-```
-
-### No Transcript Found
-
-```typescript
-try {
-  const transcript = await api.fetch('video_id', {
-    languages: ['en', 'de', 'es'] // Fallback languages
-  });
-} catch (error) {
-  if (error instanceof NoTranscriptFound) {
-    // Handle case where no transcript exists
-    console.log('Available:', error.availableTranscripts);
-  }
-}
-```
-
-## License
-
-MIT
-
-## Contributing
-
-Contributions are welcome! Please feel free to submit a Pull Request.
+<p align="center">
+    <img width="300px" src="https://i.imgur.com/dwg2IYg.png" />
+</p>
+
+<!-- template-git-repo:badges:start -->
+<p align="center">
+    <a href="https://qwksearch.com/api"><img src="https://img.shields.io/badge/Docs-blue?logo=ReadTheDocs&logoColor=white" alt="Documentation" /></a>
+    <br />
+    <a href="https://github.com/OpenSourceAGI/qwksearch-research-agent/stargazers"><img src="https://img.shields.io/github/stars/OpenSourceAGI/qwksearch-research-agent" alt="GitHub Stars" /></a>
+    <a href="https://www.npmjs.com/package/extract-youtube"><img src="https://img.shields.io/npm/dm/extract-youtube.svg" alt="NPM Monthly Downloads" /></a>
+    <a href="https://www.npmjs.com/package/extract-youtube"><img src="https://img.shields.io/npm/v/extract-youtube.svg" alt="npm version" /></a>
+    <a href="https://www.npmjs.com/package/extract-youtube"><img src="https://img.shields.io/npm/dt/extract-youtube.svg" alt="NPM Total Downloads" /></a>
+    <a href="https://www.npmjs.com/package/extract-youtube"><img src="https://img.shields.io/npm/types/extract-youtube" alt="TypeScript types" /></a>
+    <a href="https://packagephobia.com/result?p=extract-youtube"><img src="https://packagephobia.com/badge?p=extract-youtube" alt="Install size" /></a>
+    <br />
+    <a href="https://github.com/OpenSourceAGI/qwksearch-research-agent/issues"><img src="https://img.shields.io/github/issues/OpenSourceAGI/qwksearch-research-agent?logo=github" alt="GitHub Issues" /></a>
+    <a href="https://github.com/OpenSourceAGI/qwksearch-research-agent/pulls"><img src="https://img.shields.io/github/issues-pr/OpenSourceAGI/qwksearch-research-agent?logo=github&label=PRs" alt="Open Pull Requests" /></a>
+    <a href="https://github.com/OpenSourceAGI/qwksearch-research-agent/pulls?q=is%3Apr+is%3Aclosed"><img src="https://img.shields.io/github/issues-pr-closed/OpenSourceAGI/qwksearch-research-agent?logo=github&label=PRs%20merged&color=8957e5" alt="Merged Pull Requests" /></a>
+    <a href="https://github.com/OpenSourceAGI/qwksearch-research-agent/discussions"><img src="https://img.shields.io/github/discussions/OpenSourceAGI/qwksearch-research-agent" alt="GitHub Discussions" /></a>
+    <a href="https://github.com/OpenSourceAGI/qwksearch-research-agent/commits/master/"><img src="https://img.shields.io/github/last-commit/OpenSourceAGI/qwksearch-research-agent.svg" alt="GitHub last commit" /></a>
+    <br />
+    <a href="https://stackblitz.com/github/OpenSourceAGI/qwksearch-research-agent/tree/master/packages/extract-youtube"><img height="20px" src="https://developer.stackblitz.com/img/open_in_stackblitz.svg" alt="Open in StackBlitz" /></a>
+    <img src="https://img.shields.io/badge/Bun-14151A?logo=bun&logoColor=white" alt="Bun" /> <img src="https://img.shields.io/badge/TypeScript-3178C6?logo=typescript&logoColor=white" alt="TypeScript" /> <img src="https://img.shields.io/badge/React-20232A?logo=react&logoColor=white" alt="React" /> <img src="https://img.shields.io/badge/Vite-646CFF?logo=vite&logoColor=white" alt="Vite" /> <img src="https://img.shields.io/badge/Jest-C21325?logo=jest&logoColor=white" alt="Jest" />
+</p>
+<!-- template-git-repo:badges:end -->
+
+# Extract YouTube Transcript 
+.
+
+**[Live demo at youtube.js.org](https://youtube.js.org)** · [Storybook](https://youtube.js.org/storybook/)
+
+⚡ **No API keys, no headless browsers, no dependencies. Only the fastest, most optimized YouTube transcript extractor.**
+
+A production-ready TypeScript port of the popular Python [`extract-youtube`](https://github.com/dbeley/youtube_extract) (100k+ monthly PyPI downloads), optimized for serverless environments and edge computing. No API keys, no headless browsers, no dependencies bloat.
+
+## Why This Package?
+
+### 🚀 **Superior to Other NPM Alternatives**
+
+- 
+- ✅ **Proven algorithm** - Direct port of Python's `extract-youtube` (100k+ monthly PyPI downloads)
+- ✅ **Serverless-first** - Works flawlessly in AWS Lambda, Vercel, Cloudflare Workers, Next.js Edge
+- ✅ **70% smaller** - ~7KB gzipped vs 20-30KB+ for alternatives
+- ✅ **Zero native deps** - Pure TypeScript, no puppeteer or heavy scraping libraries
+- ✅ **Better DX** - Full TypeScript, comprehensive error handling, tree-shakeable
+- ✅ **Battle-tested** - Same extraction logic trusted by 100k+ monthly users
+
+### 📊 **Package Comparison**
+
+| Feature                       | **extract-youtube** (this) | youtube-transcript (npm) | extract-youtube (Python) |
+| ----------------------------- | -------------------------------- | ------------------------ | ------------------------------- |
+| **Language**            | TypeScript/Node.js               | JavaScript/Node.js       | Python                          |
+| **Bundle Size**         | **~7KB gzipped**           | ~20-30KB+                | N/A                             |
+| **Serverless Ready**    | ✅ Yes                           | ⚠️ Limited             | ❌ No                           |
+| **Edge Compatible**     | ✅ Yes                           | ❌ No                    | ❌ No                           |
+| **Native Deps**         | ✅ None                          | ⚠️ Some                | ✅ None                         |
+| **Type Safety**         | ✅ Full TypeScript               | ⚠️ Partial             | ❌ No                           |
+| **Auto-generated Subs** | ✅ Yes                           | ✅ Yes                   | ✅ Yes                          |
+| **Translation**         | ✅ Yes                           | ⚠️ Limited             | ✅ Yes                          |
+| **Proxy Support**       | ✅ Advanced                      | ⚠️ Basic               | ✅ Yes                          |
+| **Error Handling**      | ✅ Comprehensive                 | ⚠️ Basic               | ✅ Good                         |
+| **CLI Tool**            | ✅ Yes                           | ❌ No                    | ✅ Yes                          |
+| **Format Output**       | ✅ 6 formats                     | ⚠️ 1-2 formats         | ✅ 5 formats                    |
+| **Monthly Downloads**   | Growing                          | ~50k                     | ~400k (PyPI)                    |
+| **Code Quality**        | ⭐⭐⭐⭐⭐                       | ⭐⭐⭐                   | ⭐⭐⭐⭐⭐                      |
+
+### 🎯 **Why Choose This Over Python?**
+
+**Top packages for YouTube transcripts are `youtube-transcript` (JS/NPM) and `extract-youtube` (Python).** This package combines the best of both:
+
+1. **Same reliability as Python** - Direct port of the proven Python implementation
+2. **Better for modern stacks** - Works natively in Node.js, Next.js, React Server Components
+3. **Serverless-first** - Perfect for AWS Lambda, Vercel Functions, Cloudflare Workers
+4. **Faster cold starts** - No Python runtime overhead
+5. **Modern tooling** - NPM ecosystem, TypeScript, tree-shaking, ESM/CJS
+
+### ⚡ **Optimized for Production**
+
+- **Bundle optimized with Vite + Terser** - Aggressive minification and tree-shaking
+- **Dual ESM/CJS builds** - Works everywhere (Node.js, bundlers, edge runtimes)
+- **Zero external HTTP clients** - Uses native `grab-url` (polyfilled in browsers)
+- **Efficient parsing** - Fast XML parsing with minimal memory footprint
+
+## 🎯 Quick Facts
+
+```
+Bundle Size:    7KB gzipped    (vs 20-30KB for alternatives)
+Cold Start:     ~50ms          (vs 150-500ms for alternatives)
+Memory:         ~30MB          (vs 45-80MB for alternatives)
+Dependencies:   4 minimal      (vs 10-50+ for alternatives)
+Serverless:     ✅ Optimized   (vs ⚠️ Limited support)
+TypeScript:     ✅ Full        (vs ⚠️ Partial/None)
+```
+
+## Installation
+
+```bash
+npm install extract-youtube
+```
+
+**Or try it instantly with npx:**
+
+```bash
+npx extract-youtube dQw4w9WgXcQ
+```
+
+## Quick Start
+
+```typescript
+import { YouTubeTranscriptApi } from 'extract-youtube';
+
+const api = new YouTubeTranscriptApi();
+const transcript = await api.fetch('dQw4w9WgXcQ');
+
+for (const snippet of transcript) {
+  console.log(`${snippet.start}s: ${snippet.text}`);
+}
+```
+
+## Basic Usage
+
+```typescript
+// Fetch with language preference
+const transcript = await api.fetch('video_id', {
+  languages: ['de', 'en']  // Try German first, then English
+});
+
+// List available transcripts
+const transcriptList = await api.list('video_id');
+for (const t of transcriptList) {
+  console.log(`${t.language} (${t.languageCode})`);
+}
+
+// Find and translate
+const transcript = transcriptList.findTranscript(['en']);
+const translated = transcript.translate('de');
+const fetched = await translated.fetch();
+```
+
+## Formatters
+
+```typescript
+import { SRTFormatter, WebVTTFormatter, JSONFormatter, ArticleFormatter } from 'extract-youtube';
+
+const transcript = await api.fetch('video_id');
+
+// SRT format
+const srt = new SRTFormatter().formatTranscript(transcript);
+
+// WebVTT format
+const webvtt = new WebVTTFormatter().formatTranscript(transcript);
+
+// JSON format
+const json = new JSONFormatter().formatTranscript(transcript, { indent: 2 });
+
+// Article format with character-to-timestamp mappings
+const article = new ArticleFormatter().formatTranscript(transcript);
+console.log(article);
+// Output:
+// {
+//   "text": "Full transcript text...",
+//   "timestamps": "10,15,20  100,200,300",  // speeds and positions
+//   "wordCount": 1234,
+//   "charCount": 5678
+// }
+```
+
+## Proxy Support
+
+```typescript
+import { WebshareProxyConfig } from 'extract-youtube';
+
+const api = new YouTubeTranscriptApi({
+  proxyConfig: new WebshareProxyConfig({
+    proxyUsername: 'your-username',
+    proxyPassword: 'your-password'
+  })
+});
+```
+
+See [docs/proxy.md](./docs/proxy.md) for the full guide: generic vs. Webshare
+proxies, the CLI flags, why `proxyConfig` does nothing on Cloudflare
+Workers/edge (and what to use there instead), and caching in front of the
+fetcher so a proxy request is only spent on a video you don't already have.
+
+## Error Handling
+
+```typescript
+import { TranscriptsDisabled, NoTranscriptFound } from 'extract-youtube';
+
+try {
+  const transcript = await api.fetch('video_id');
+} catch (error) {
+  if (error instanceof TranscriptsDisabled) {
+    console.error('Subtitles are disabled');
+  } else if (error instanceof NoTranscriptFound) {
+    console.error('No transcript found');
+  }
+}
+```
+
+## CLI Usage
+
+After installing globally or using npx, you can use the `extract-youtube` command:
+
+```bash
+# Install globally
+npm install -g extract-youtube
+
+# Or use with npx
+npx extract-youtube <video-id> [options]
+```
+
+### CLI Examples
+
+```bash
+# Extract transcript in JSON format (default)
+extract-youtube jNQXAC9IVRw
+
+# Extract transcript in SRT format
+extract-youtube jNQXAC9IVRw -f srt
+
+# Extract transcript with specific languages
+extract-youtube jNQXAC9IVRw -l en,de
+
+# Extract transcript with proxy
+extract-youtube jNQXAC9IVRw --proxy http://proxy.example.com:8080
+
+# Extract transcript with Webshare proxy
+extract-youtube jNQXAC9IVRw --webshare-user myuser --webshare-pass mypass
+
+# Extract as plain text with preserved formatting
+extract-youtube jNQXAC9IVRw -f text -p
+
+# Show help
+extract-youtube --help
+```
+
+### CLI Options
+
+- `-h, --help` - Show help message
+- `-v, --version` - Show version number
+- `-l, --languages <codes>` - Comma-separated language codes (e.g., en,de,fr)
+- `-f, --format <type>` - Output format: json, text, srt, webvtt, pretty, article (default: json)
+- `-p, --preserve-formatting` - Preserve text formatting (line breaks, etc.)
+- `--proxy <url>` - HTTP/HTTPS proxy URL
+- `--webshare-user <username>` - Webshare proxy username
+- `--webshare-pass <password>` - Webshare proxy password
+
+## React Components (Floating Player + Transcript Modal)
+
+`extract-youtube/react` is the package's UI half — two self-contained
+components, both ported from the video player used in production on
+[debate-ai.com](https://debate-ai.com), with everything app-specific
+stripped out. Neither depends on a design system, a state library, or a CSS
+framework: they inject their own minimal scoped styles and drop into any
+React app.
+
+- **`<FloatingYouTubePlayer />`** — a floating, draggable, resizable player
+  that keeps playing while the user moves around your app. Mount it once;
+  drive it from anywhere with `youtubePlayer.play({ videoId })`.
+- **`<YouTubeTranscriptModal />`** — a popout modal with the video on the
+  left and a transcript panel on the right that scrolls and highlights in
+  sync with playback; click any line to seek.
+
+### Why it's a separate entry point
+
+`extract-youtube` (the main entry) fetches captions server-side with no
+browser dependency at all — that's the whole point of the package.
+`extract-youtube/react` is a second, independent entry point that only
+exports UI: it never imports the transcript-fetching code, and the main
+entry never imports React. Import only the one you need and the other never
+ends up in your bundle. React, ReactDOM, and `lucide-react` (used for the
+icons) are peer dependencies — install them yourself if you don't already
+have them:
+
+```bash
+npm install extract-youtube react react-dom lucide-react
+```
+
+### The floating player
+
+Mount it once, near the root of your app. It renders through a portal into
+`document.body`, so nothing in the tree around it can clip it, hide it, or
+remount the playing video on a route change. It renders nothing at all until
+something asks it to play.
+
+```tsx
+// app/layout.tsx (or wherever your app root lives)
+import { FloatingYouTubePlayer } from 'extract-youtube/react';
+
+export default function RootLayout({ children }) {
+  return (
+    <>
+      {children}
+      <FloatingYouTubePlayer transcriptUrl="/api/transcript" />
+    </>
+  );
+}
+```
+
+Then play something from anywhere — a grid, a search result, a keyboard
+shortcut. No context provider, no prop drilling:
+
+```tsx
+import { youtubePlayer, usePlayerState, thumbnailUrl } from 'extract-youtube/react';
+
+function VideoCard({ videoId, title }: { videoId: string; title: string }) {
+  const { activeVideo } = usePlayerState();
+
+  return (
+    <button onClick={() => youtubePlayer.play({ videoId, title })}>
+      <img src={thumbnailUrl(videoId)} alt="" />
+      {title} {activeVideo?.videoId === videoId && '(playing)'}
+    </button>
+  );
+}
+```
+
+What you get, without wiring any of it up yourself:
+
+| | |
+| --- | --- |
+| **Drag & resize** | Drag by the title bar, resize from either side edge or a bottom corner, clamped to the viewport. Mouse and touch. |
+| **Minimize** | Collapses to the title bar. The iframe is hidden with CSS, never unmounted, so playback isn't interrupted. |
+| **Picture-in-picture** | Pops the video into an always-on-top OS window via the Document Picture-in-Picture API, where the browser supports it. The node is *moved*, not cloned, so playback continues. |
+| **Queue** | `addToQueue` / `setQueue` / `playNext`, with an "Up next" strip under the video. |
+| **Synced captions** | Optional subtitles panel above the video — caption cues are regrouped into whole sentences (no timestamps), the spoken one highlights and auto-scrolls, and clicking a sentence seeks. Needs `transcriptUrl` or `fetchTranscript` (see below). |
+| **Resume** | Remembers what was playing, and how far into it, across a reload — plus a per-video position for the last 50 videos, for 24 hours. `storageKey={null}` turns it off. |
+| **Error recovery** | Reads the IFrame API's error codes, explains them ("this video is private", "the owner doesn't allow embedding"), and offers Retry or Watch on YouTube from the same spot. |
+| **Theming** | Colours are CSS custom properties on `.eytp-root` and follow `prefers-color-scheme` by default. Override them to match your app. |
+
+#### Custom controls belong to your app, not the package
+
+The built-in control strip only holds buttons that mean the same thing for
+any YouTube video: play/pause, skip, captions, picture-in-picture, minimize,
+close. Anything specific to *your* product — a bookmark, a share menu, a
+speed control framed for your users — is yours to render, through
+`extraControls`:
+
+```tsx
+import { Gauge } from 'lucide-react';
+import { FloatingYouTubePlayer } from 'extract-youtube/react';
+
+<FloatingYouTubePlayer
+  transcriptUrl="/api/transcript"
+  extraControls={({ playbackRate, player }) => (
+    <button
+      // The player's own control classes, so custom buttons match the built-ins.
+      className={`eytp-btn${playbackRate !== 1 ? ' eytp-btn-active' : ''}`}
+      onClick={() => player.setPlaybackRate(playbackRate !== 1 ? 1 : 0.65)}
+      title="Slow it down"
+    >
+      <Gauge size={13} />
+    </button>
+  )}
+/>
+```
+
+debate-ai.com uses exactly this seam for its "slow the debate spread down"
+button — its own label, icon and rate, sitting in the same strip. The
+package stays generic: it exposes `player.setPlaybackRate()` and reports the
+current `playbackRate`, and the host decides what the button says and does.
+`renderTitle` is the same idea for the title bar, if you want badges or
+links instead of a plain video title.
+
+#### The imperative API
+
+Everything the player can do is on `youtubePlayer`, importable anywhere:
+
+```ts
+import { youtubePlayer, usePlayerState, getPlayerState } from 'extract-youtube/react';
+
+youtubePlayer.play({ videoId, title, meta });  // meta is yours; passed back untouched
+youtubePlayer.play({ videoId }, { startSeconds: 120 });
+youtubePlayer.togglePlay();
+youtubePlayer.seekTo(90);
+youtubePlayer.setPlaybackRate(1.5);
+youtubePlayer.addToQueue({ videoId, title });
+youtubePlayer.setQueue(videos);                // e.g. "play all" over a grid
+youtubePlayer.playNext();
+youtubePlayer.getCurrentTime();                // seconds
+youtubePlayer.close();
+
+usePlayerState();   // in a component: { activeVideo, isPlaying, isMinimized, playbackRate, queue, startTime }
+getPlayerState();   // the same, outside React
+```
+
+#### Floating player props
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `transcriptUrl` | `string` | Your captions endpoint (see below). Enables the subtitles button. |
+| `fetchTranscript` | `(videoId: string) => Promise<{ snippets, error? }>` | Custom caption loader, instead of `transcriptUrl`. |
+| `extraControls` | `ReactNode \| (ctx: PlayerControlContext) => ReactNode` | Your own buttons, rendered in the control strip. |
+| `renderTitle` | `(ctx: PlayerControlContext) => ReactNode` | Custom title-bar content. Defaults to the video title. |
+| `showSubtitles` | `boolean` | Force the captions button on or off. By default it appears only for videos that turned out to have a transcript — every video played is checked, and one without captions gets no button and no error. |
+| `showPictureInPicture` | `boolean` | Show the PiP button where supported. Default `true`. |
+| `storageKey` | `string \| null` | localStorage key for resume-after-reload. `null` disables persistence entirely. |
+| `className` | `string` | Extra class on the player root, for host-side positioning or theming. |
+| `onClose` | `() => void` | Called when the user closes the player. |
+| `minWidth` / `maxWidth` | `number` | Resize bounds in px. Default 256 / 800. |
+
+### Setup: video captions still have to be fetched server-side
+
+Neither component talks to YouTube's caption endpoints directly — browsers
+can't (no CORS, and it would leak this package's whole fetching strategy
+client-side for no benefit). Instead, you expose one small backend endpoint
+that calls this package's `YouTubeTranscriptApi`, and point the components
+at it with `transcriptUrl`.
+
+**1. Add a backend endpoint** (any framework works — this is a Next.js
+route handler, following the same pattern as the Vercel Edge example
+above):
+
+```typescript
+// app/api/transcript/route.ts
+import { NextRequest, NextResponse } from 'next/server';
+import { YouTubeTranscriptApi, extractVideoId } from 'extract-youtube';
+
+const api = new YouTubeTranscriptApi();
+
+export async function GET(req: NextRequest) {
+  const raw = req.nextUrl.searchParams.get('videoId');
+  const videoId = raw ? extractVideoId(raw) : null;
+  if (!videoId) {
+    return NextResponse.json({ error: 'Missing videoId' }, { status: 400 });
+  }
+
+  try {
+    const transcript = await api.fetchTranscript(videoId, { languages: ['en'] });
+    return NextResponse.json({ videoId, snippets: transcript.toRawData() });
+  } catch (error) {
+    // 200 + an `error` field, not a 4xx/5xx — "no captions for this video"
+    // isn't a server failure, and the components check this field either way.
+    return NextResponse.json({
+      videoId,
+      snippets: [],
+      error: error instanceof Error ? error.message : 'Failed to fetch transcript',
+    });
+  }
+}
+```
+
+**2. Point the components at it** with `transcriptUrl="/api/transcript"`.
+The `videoId` query param is appended for you, and one request is shared
+per video across every component asking for it.
+
+`extractVideoId` (exported from the main entry, since it runs fine in Node)
+accepts any of the URL shapes YouTube uses — watch, youtu.be, embed, shorts,
+live — so you can pass what a user pastes in straight through.
+
+### Transcript modal
+
+```tsx
+import { YouTubeTranscriptModal } from 'extract-youtube/react';
+import { extractVideoId } from 'extract-youtube';
+
+function VideoCard({ url, title }: { url: string; title: string }) {
+  const videoId = extractVideoId(url);
+  if (!videoId) return null;
+
+  return <YouTubeTranscriptModal videoId={videoId} title={title} transcriptUrl="/api/transcript" />;
+}
+```
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `videoId` | `string` | **Required.** The YouTube video ID (not a full URL — run it through `extractVideoId` first if needed). |
+| `title` | `string` | Shown in the modal header and as the iframe's accessible title. |
+| `transcriptUrl` | `string` | URL of your backend endpoint (see above). Fetched with `fetch()` when the modal opens. The `videoId` query param is appended automatically if not already present. |
+| `fetchTranscript` | `(videoId: string) => Promise<{ snippets, error? }>` | Use instead of `transcriptUrl` if you want to load the transcript some other way (e.g. from a React Query cache). |
+| `snippets` | `TranscriptSnippet[]` | Pass transcript data directly to skip fetching entirely — e.g. if you already loaded it server-side. |
+| `trigger` | `ReactNode` | Custom element that opens the modal on click. Defaults to a small captions-icon button. |
+| `onOpenChange` | `(open: boolean) => void` | Called whenever the modal opens or closes. |
+
+## Video Library: Grid, List and Admin
+
+Ported from the video library on [debate-ai.com](https://debate-ai.com) (its
+`debate-videos` grid package and its admin API routes), with everything
+debate-specific generalised into **custom fields** you declare yourself.
+
+| Entry point | What you get |
+| --- | --- |
+| `extract-youtube/library` | Storage (in-memory or Cloudflare D1), one framework-agnostic HTTP handler with public and admin routes, a typed client, stacked playlists, grouping, YouTube Data API resync and auto-fill. No React, no Node built-ins: it runs on Workers. |
+| `extract-youtube/react` | `<VideoGrid />`, `<VideoList />`, `<VideoCard />`, `<StackedVideoCard />`, `<StackNav />`, `useVideoLibrary()`, and the admin screens `<VideoLibraryAdmin />`, `<VideoEditDialog />`, `<CustomFieldInput />` and `<VideoAvailabilityPanel />`. |
+
+### Serve the library (Cloudflare Worker + D1)
+
+```ts
+import { bearerTokenAuth, createD1LibraryStore, createVideoLibraryHandler, type CustomFieldDef } from 'extract-youtube/library';
+
+const fields: CustomFieldDef[] = [
+  { key: 'speaker', label: 'Speaker', type: 'text', searchable: true, showOnCard: true, showInList: true },
+  { key: 'level', label: 'Level', type: 'select', options: ['Beginner', 'Advanced'] },
+];
+
+export default {
+  async fetch(request: Request, env: { DB: D1Database; ADMIN_TOKEN: string; YOUTUBE_API_KEY?: string }) {
+    const store = createD1LibraryStore(env.DB);
+    await store.ensureSchema();
+    const library = createVideoLibraryHandler({
+      store,
+      authorize: bearerTokenAuth(env.ADMIN_TOKEN), // omit it and every admin route answers 403
+      customFields: fields,
+      youtubeApiKey: env.YOUTUBE_API_KEY, // optional: resync + richer auto-fill
+    });
+    return (await library.handle(request)) ?? new Response('Not found', { status: 404 });
+  },
+};
+```
+
+Routes live under `/api/library`: public `GET /videos` (search, filter,
+sort, page), `/videos/:id`, `/stacks`, `/categories`, `/fields`, `/session`;
+admin `POST/PATCH/DELETE /videos`, `/autofill`, `/resync`, `/availability`,
+`/import`, `/stacks/recompute` and `/exclusions`. The same handler mounts in
+Next.js, vinext, Hono, Bun or Deno, since it only takes a `Request`. Use
+`createMemoryLibraryStore()` for tests and demos, or implement
+`VideoLibraryStore` for any other database.
+
+### Show it
+
+```tsx
+import { createLibraryClient } from 'extract-youtube/library';
+import { FloatingYouTubePlayer, VideoGrid, VideoList, useVideoLibrary } from 'extract-youtube/react';
+
+const client = createLibraryClient({ baseUrl: '/api/library' });
+
+function Library() {
+  const { videos, stacks } = useVideoLibrary(client, { sort: 'views', availability: 'available' });
+  return (
+    <>
+      <VideoGrid videos={videos} stacks={stacks} customFields={fields} transcriptUrl="/api/transcript" />
+      <VideoList videos={videos} stacks={stacks} customFields={fields} groupBy={['year', 'channel']} />
+      <FloatingYouTubePlayer transcriptUrl="/api/transcript" />
+    </>
+  );
+}
+```
+
+- **Cards** show title, channel, date, views, category, "Top pick" and your
+  custom fields as badges, with opt-in favorite, hide, queue, transcript and
+  YouTube actions.
+- **Stacked playlists**: videos whose descriptions link each other ("Part 2:
+  https://youtu.be/…") fold into one card with `<` / `>` arrows.
+- **The list** is a table with sortable, resizable columns, one column per
+  custom field, and `groupBy` for a tree by year, channel, category or any
+  custom field, collapsible level by level.
+- Styles are scoped (`eytg-` classes) and injected once, follow dark mode,
+  and theme through `--eytg-*` CSS variables.
+
+### Curate it
+
+```tsx
+import { VideoAvailabilityPanel, VideoLibraryAdmin } from 'extract-youtube/react';
+
+const admin = createLibraryClient({ baseUrl: '/api/library', headers: () => ({ authorization: `Bearer ${token}` }) });
+
+<VideoLibraryAdmin client={admin} />      // search, sort, page, add, auto-fill, edit, feature, delete, resync
+<VideoAvailabilityPanel client={admin} /> // videos YouTube no longer plays
+```
+
+Edits send only the fields that changed and mark the row `adminEdited`, so
+bulk imports leave it alone. Deletes record an exclusion, so imports don't
+bring the video back. Auto-fill reads the YouTube Data API (or oEmbed with no
+key) and then your own `suggest` hook, and never overwrites what the admin
+typed.
+
+Full guides: [video grid and list](../../apps/extract-youtube-docs/content/docs/react/video-grid.mdx),
+[library admin API](../../apps/extract-youtube-docs/content/docs/admin/library-api.mdx),
+[custom fields](../../apps/extract-youtube-docs/content/docs/admin/custom-fields.mdx) and
+[admin components](../../apps/extract-youtube-docs/content/docs/admin/admin-components.mdx).
+
+## Live Demo and Storybook
+
+**Live demo: [youtube.js.org](https://youtube.js.org)** · Storybook: [youtube.js.org/storybook](https://youtube.js.org/storybook/)
+
+[`apps/extract-youtube-demo`](../../apps/extract-youtube-demo) runs all of
+this on one Cloudflare Worker: the library grid and list, the admin screens,
+the floating player with captions from `/api/transcript`, the library API at
+`/api/library`, and a Storybook with a story for every component at
+`/storybook/`.
+
+```bash
+bun install                           # from the monorepo root
+cd apps/extract-youtube-demo
+bun run dev                           # app + Worker on one port
+bun run storybook                     # Storybook on :6006
+bun run build && bunx wrangler deploy # app, Worker and Storybook in one deploy
+```
+
+With no secrets set it runs as a sandbox (an in-memory library anyone can
+edit, reset per Worker isolate). Set `ADMIN_TOKEN` to require a token, bind a
+D1 database as `DB` to persist, and set `YOUTUBE_API_KEY` for resync. The
+docs site is [`apps/extract-youtube-docs`](../../apps/extract-youtube-docs),
+built from template-fumadocs and also deployed to Workers.
+
+The demo's `src/SpeedButton.tsx` is the worked example of an app-supplied
+custom control, passed in through `<FloatingYouTubePlayer extraControls />`.
+
+## Features
+
+### Core Functionality
+
+- ✅ Retrieve transcripts for any YouTube video (no API key needed)
+- ✅ Support for manually created and auto-generated subtitles
+- ✅ Translate transcripts to 100+ languages
+- ✅ Multiple output formats (JSON, Text, SRT, WebVTT, Pretty Print, Article)
+- ✅ Language preference fallback system
+- ✅ Timed segments with start/duration timestamps
+
+### Developer Experience
+
+- ✅ **Full TypeScript support** with comprehensive type definitions
+- ✅ **Tree-shakeable** - Only bundle what you use
+- ✅ **ESM + CJS** - Works with all module systems
+- ✅ **Zero configuration** - Works out of the box
+- ✅ Comprehensive JSDoc documentation
+- ✅ Intuitive error messages with troubleshooting guidance
+
+### Advanced Features
+
+- ✅ **Proxy support** (Generic HTTP/HTTPS & Webshare residential proxies)
+- ✅ **Rate limit handling** with rotating IP pools
+- ✅ **Serverless-optimized** - No file system dependencies
+- ✅ **Edge runtime compatible** - Runs on Cloudflare Workers, Vercel Edge
+- ✅ Command-line interface (CLI) for quick extraction
+
+### Production Ready
+
+- ✅ Battle-tested algorithm from Python package (100k+ monthly downloads)
+- ✅ Comprehensive error handling with typed exceptions
+- ✅ Automatic retry logic for network failures
+- ✅ Small bundle size (~7KB gzipped)
+- ✅ No native dependencies or binaries
+
+## Serverless & Edge Deployment
+
+This package is optimized for serverless and edge computing environments:
+
+### AWS Lambda
+
+```typescript
+import { YouTubeTranscriptApi } from 'extract-youtube';
+
+export const handler = async (event) => {
+  const api = new YouTubeTranscriptApi();
+  const transcript = await api.fetch(event.videoId);
+
+  return {
+    statusCode: 200,
+    body: JSON.stringify(transcript.toRawData())
+  };
+};
+```
+
+### Vercel Edge Functions
+
+```typescript
+import { YouTubeTranscriptApi } from 'extract-youtube';
+
+export const config = { runtime: 'edge' };
+
+export default async function handler(req: Request) {
+  const { searchParams } = new URL(req.url);
+  const videoId = searchParams.get('videoId');
+
+  const api = new YouTubeTranscriptApi();
+  const transcript = await api.fetch(videoId);
+
+  return new Response(JSON.stringify(transcript.toRawData()), {
+    headers: { 'content-type': 'application/json' }
+  });
+}
+```
+
+### Cloudflare Workers
+
+```typescript
+import { YouTubeTranscriptApi } from 'extract-youtube';
+
+export default {
+  async fetch(request: Request) {
+    const url = new URL(request.url);
+    const videoId = url.searchParams.get('videoId');
+
+    const api = new YouTubeTranscriptApi();
+    const transcript = await api.fetch(videoId);
+
+    return new Response(JSON.stringify(transcript.toRawData()), {
+      headers: { 'content-type': 'application/json' }
+    });
+  }
+};
+```
+
+### Next.js Server Actions / API Routes
+
+```typescript
+'use server';
+
+import { YouTubeTranscriptApi } from 'extract-youtube';
+
+export async function getTranscript(videoId: string) {
+  const api = new YouTubeTranscriptApi();
+  return await api.fetch(videoId);
+}
+```
+
+### Why It Works Great in Serverless
+
+- ✅ **Fast cold starts** - Minimal initialization overhead
+- ✅ **No file system** - Pure in-memory operations
+- ✅ **Small bundle** - Fits well within size limits
+- ✅ **No native deps** - No compilation needed
+- ✅ **Stateless** - Perfect for serverless architecture
+
+## Testing
+
+```bash
+npm test
+```
+
+## Performance Benchmarks
+
+### Bundle Size Comparison
+
+```
+extract-youtube (this):     ~7KB gzipped   ✅
+youtube-transcript:         ~25KB gzipped  ❌
+ytdl-core:                  ~300KB+        ❌❌
+puppeteer-based solutions:  ~200MB+        ❌❌❌
+```
+
+### Cold Start Times (AWS Lambda)
+
+```
+extract-youtube:    ~50ms   ✅
+youtube-transcript: ~150ms  ⚠️
+Python package:     ~500ms  ❌
+```
+
+### Memory Usage
+
+```
+extract-youtube:    ~30MB   ✅
+youtube-transcript: ~45MB   ⚠️
+Python package:     ~80MB   ❌
+```
+
+
+## Reliability
+
+This package uses the same proven algorithm as the Python `extract-youtube`:
+
+- ✅ **100k+ monthly downloads** on PyPI (Python version)
+- ✅ **Battle-tested** across thousands of production deployments
+- ✅ **Maintained** - Regular updates to handle YouTube API changes
+- ✅ **Comprehensive error handling** - Clear error messages for all failure modes
+
+**Unlike scraping-based alternatives**, this package:
+
+- Fetches transcripts directly from YouTube's caption endpoints
+- Doesn't rely on brittle HTML parsing
+- Handles both manual and auto-generated captions
+- Works with age-restricted videos (with authentication)
+
+## Common Use Cases
+
+### 1. AI/ML Applications
+
+```typescript
+// Extract transcripts for training data, analysis, or AI processing
+const transcript = await api.fetch('video_id');
+const text = transcript.snippets.map(s => s.text).join(' ');
+// Feed to GPT, LLM, or ML model
+```
+
+### 2. Accessibility Tools
+
+```typescript
+// Generate subtitles in multiple formats
+const transcript = await api.fetch('video_id');
+const srt = new SRTFormatter().formatTranscript(transcript);
+const webvtt = new WebVTTFormatter().formatTranscript(transcript);
+```
+
+### 3. Content Analysis
+
+```typescript
+// Analyze video content programmatically
+const transcript = await api.fetch('video_id');
+for (const snippet of transcript) {
+  if (snippet.text.includes('keyword')) {
+    console.log(`Found at ${snippet.start}s: ${snippet.text}`);
+  }
+}
+```
+
+### 4. Translation Services
+
+```typescript
+// Translate videos to multiple languages
+const list = await api.list('video_id');
+const transcript = list.findTranscript(['en']);
+const german = await transcript.translate('de').fetch();
+const spanish = await transcript.translate('es').fetch();
+```
+
+## Troubleshooting
+
+### Rate Limiting / IP Blocks
+
+If you're getting blocked by YouTube:
+
+```typescript
+import { YouTubeTranscriptApi, WebshareProxyConfig } from 'extract-youtube';
+
+const api = new YouTubeTranscriptApi({
+  proxyConfig: new WebshareProxyConfig({
+    proxyUsername: 'your-username',
+    proxyPassword: 'your-password',
+    // Rotate through 30M+ residential IPs
+  })
+});
+```
+
+### No Transcript Found
+
+```typescript
+try {
+  const transcript = await api.fetch('video_id', {
+    languages: ['en', 'de', 'es'] // Fallback languages
+  });
+} catch (error) {
+  if (error instanceof NoTranscriptFound) {
+    // Handle case where no transcript exists
+    console.log('Available:', error.availableTranscripts);
+  }
+}
+```
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.