extract-youtube 1.0.256 → 1.0.257

package/README.md

@@ -27,6 +27,7 @@
     <a href="https://codespaces.new/vtempest/qwksearch-research-agent">
     <img src="https://github.com/codespaces/badge.svg" width="150" height="20" />
     </a>
+    <a href="https://codecov.io/gh/OpenSourceAGI/qwksearch-research-agent"><img src="https://codecov.io/gh/OpenSourceAGI/qwksearch-research-agent/graph/badge.svg?component=package-extract-youtube" alt="Coverage" /></a>
 </p>
 
 # Extract YouTube Transcript 
@@ -244,6 +245,142 @@ extract-youtube --help
 - `--webshare-user <username>` - Webshare proxy username
 - `--webshare-pass <password>` - Webshare proxy password
 
+## React Popout Modal (Video + Synced Subtitles)
+
+`extract-youtube/react` ships a self-contained popout modal component:
+click a trigger, and it opens a YouTube player next to a transcript panel
+that scrolls and highlights in sync with playback — click any line to seek
+the video there. It has no dependency on any particular design system (it
+injects its own minimal, scoped styles), so it drops into any React app.
+It was ported from the video transcript modal used in production on
+[debate-ai.com](https://debate-ai.com). The layout: player on the left,
+a "Transcript" panel on the right (stacks below the player on narrow
+screens) — see the `demo/` app below to try it live.
+
+### 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 modal's icons) are peer dependencies — install them yourself if
+you don't already have them:
+
+```bash
+npm install extract-youtube react react-dom lucide-react
+```
+
+### Setup: video captions still have to be fetched server-side
+
+The modal itself never 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 modal 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 modal checks this field either way.
+    return NextResponse.json({
+      videoId,
+      snippets: [],
+      error: error instanceof Error ? error.message : 'Failed to fetch transcript',
+    });
+  }
+}
+```
+
+**2. Render the modal**, pointing it at that endpoint:
+
+```tsx
+import { YouTubeTranscriptModal } from 'extract-youtube/react';
+import { extractVideoId } from 'extract-youtube';
+
+function VideoCard({ url, title }: { url: string; title: string }) {
+  const videoId = extractVideoId(url); // handles watch/youtu.be/embed/shorts/live URLs, or a bare ID
+  if (!videoId) return null;
+
+  return (
+    <YouTubeTranscriptModal
+      videoId={videoId}
+      title={title}
+      transcriptUrl="/api/transcript"
+    />
+  );
+}
+```
+
+That's the whole setup — one endpoint, one component. `extractVideoId`
+(exported from the main entry, since it runs fine in Node) also accepts
+any of the URL shapes YouTube uses, so you can pass what a user pastes in
+straight through.
+
+### Props
+
+| 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: video player + subtitle sidebar, for any video
+
+The `demo/` folder is a small standalone app — an Express server for the
+transcript endpoint plus a Vite/React page with a "paste any YouTube URL"
+input — that puts the whole flow together end to end.
+
+```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**, paste any YouTube URL (or leave the default),
+click **Load**, then **▶ Open video + subtitles** — the player opens with
+the transcript loading in the side panel, synced to playback.
+
+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/server.js` for the Express endpoint and `demo/src/App.jsx` for
+the page that wires the input box up to the modal.
+
 ## Features
 
 ### Core Functionality

package/dist/cli.d.ts

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+/**
+ * @fileoverview CLI for extracting YouTube transcripts
+ */
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;GAEG"}

package/dist/cli.js

@@ -1994,42 +1994,55 @@ var package_exports = /* @__PURE__ */ require_rolldown_runtime.__exportAll({
 	devDependencies: () => devDependencies,
 	engines: () => engines,
 	exports: () => exports$1,
+	files: () => files,
 	keywords: () => keywords,
 	license: () => license,
 	main: () => main$1,
 	module: () => module$1,
 	name: () => name,
+	peerDependencies: () => peerDependencies,
+	peerDependenciesMeta: () => peerDependenciesMeta,
 	repository: () => repository,
 	scripts: () => scripts,
 	types: () => types,
 	version: () => version
-}), name, version, description, main$1, module$1, types, exports$1, bin, scripts, keywords, license, repository, dependencies, devDependencies, engines, package_default;
+}), name, version, description, main$1, module$1, types, exports$1, bin, files, scripts, keywords, license, repository, dependencies, peerDependencies, peerDependenciesMeta, devDependencies, engines, package_default;
 var init_package = require_rolldown_runtime.__esmMin((() => {
 	name = "extract-youtube";
-	version = "1.0.253";
+	version = "1.0.256";
 	description = "Fast, no-browser serverless-optimized YouTube transcript extractor";
 	main$1 = "dist/index.cjs";
 	module$1 = "dist/index.mjs";
 	types = "dist/index.d.ts";
-	exports$1 = { ".": {
-		"import": "./dist/index.mjs",
-		"require": "./dist/index.cjs",
-		"types": "./dist/index.d.ts"
-	} };
+	exports$1 = {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.mjs",
+			"require": "./dist/index.cjs"
+		},
+		"./react": {
+			"types": "./dist/react/index.d.ts",
+			"import": "./dist/react/index.mjs",
+			"require": "./dist/react/index.cjs"
+		}
+	};
 	bin = "dist/cli.js";
+	files = ["dist", "src"];
 	scripts = {
-		"build": "npm run build:types && npm run build:lib && npm run build:cli",
+		"clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
+		"build": "npm run clean && npm run build:lib && npm run build:cli && npm run build:react && npm run build:types",
 		"build:types": "tsc --emitDeclarationOnly --declaration --declarationMap",
 		"build:lib": "vite build",
 		"build:cli": "BUILD_CLI=true vite build",
-		"build:bundle": "npm run build:lib && npm run build:cli",
+		"build:react": "BUILD_REACT=true vite build",
+		"build:bundle": "npm run build:lib && npm run build:cli && npm run build:react",
 		"build:legacy": "tsc",
-		"prepare": "npm run build",
-		"ship": "npx standard-version --release-as patch; npm publish",
+		"ship": "npm run build && npx standard-version --release-as patch; npm publish",
 		"test": "jest",
 		"test:coverage": "jest --coverage",
 		"test:speeds": "bun src/cli.ts dQw4w9WgXcQ -f speeds",
-		"lint": "eslint src --ext .ts"
+		"lint": "eslint src --ext .ts",
+		"demo": "cd demo && npm install && npm run dev"
 	};
 	keywords = [
 		"youtube",
@@ -2065,10 +2078,25 @@ var init_package = require_rolldown_runtime.__esmMin((() => {
 		"grab-url": "^1.6.19",
 		"youtube-transcript-api": "^3.0.6"
 	};
+	peerDependencies = {
+		"react": ">=18",
+		"react-dom": ">=18",
+		"lucide-react": "^0.300.0 || ^1.0.0"
+	};
+	peerDependenciesMeta = {
+		"react": { "optional": true },
+		"react-dom": { "optional": true },
+		"lucide-react": { "optional": true }
+	};
 	devDependencies = {
 		"@types/jest": "^29.5.14",
 		"@types/node": ">=22.12.0",
+		"@types/react": "^19.2.17",
+		"@types/react-dom": "^19.2.3",
 		"jest": "^29.5.0",
+		"lucide-react": "^1.17.0",
+		"react": "^19.2.7",
+		"react-dom": "^19.2.7",
 		"terser": "^5.46.0",
 		"ts-jest": "^29.1.0",
 		"typescript": "^5.0.0",
@@ -2084,12 +2112,16 @@ var init_package = require_rolldown_runtime.__esmMin((() => {
 		types,
 		exports: exports$1,
 		bin,
+		"//files": "Publish only what consumers resolve. Without this the tarball also carries test/, jest.config.js, tsconfig*.json and vite.config.ts. Matches extract-webpage and extract-pdf.",
+		files,
 		scripts,
 		keywords,
 		author: "",
 		license,
 		repository,
 		dependencies,
+		peerDependencies,
+		peerDependenciesMeta,
 		devDependencies,
 		engines
 	};