extract-youtube 1.0.459 → 1.0.461

package/README.md

@@ -571,6 +571,71 @@ Full guides: [video grid and list](./site/content/docs/react/video-grid.mdx),
 [custom fields](./site/content/docs/admin/custom-fields.mdx) and
 [admin components](./site/content/docs/admin/admin-components.mdx).
 
+## Media Download: Audio, Video, Subtitles (`extract-youtube/download`)
+
+For what captions can't give you — a video with **no transcript at all** — the
+`extract-youtube/download` entry downloads the media itself, built on
+[`cloud-ytdl`](https://github.com/cloudkuimages/cloud-ytdl) (YouTube's Android
+InnerTube client, with signature/cipher decoding handled internally). Pull the
+audio, then hand it to a speech-to-text model.
+
+It is **Node-only** (undici streams, and `ffmpeg` for MP3), so it is its own
+entry point and `cloud-ytdl` is an *optional* peer — a transcript-only install
+never pulls it in, and the other entries stay Worker-safe.
+
+```bash
+npm install extract-youtube cloud-ytdl   # plus ffmpeg on PATH for MP3
+```
+
+```ts
+import { createMediaExtractor } from 'extract-youtube/download';
+import { createWriteStream } from 'node:fs';
+
+const media = createMediaExtractor({ cookies: process.env.YOUTUBE_COOKIES });
+
+const info = await media.getInfo('dQw4w9WgXcQ');   // title, length, every stream, caption languages
+const audio = await media.downloadAudio('dQw4w9WgXcQ', {
+  container: 'mp3',     // or 'm4a' / 'webm' — YouTube's own stream, untouched, no ffmpeg
+  bitrateKbps: 48,      // speech needs no more; ~21 MB an hour
+  mono: true,
+  sampleRate: 16000,
+});
+audio.stream.pipe(createWriteStream(audio.filename));
+
+await media.downloadVideo(id, { quality: 'highest' });   // or 'highestvideo', or an itag
+await media.getSubtitles(id, { lang: 'en', format: 'srt' });
+await media.getPlaylist('https://www.youtube.com/playlist?list=PL…');
+await media.getPost('https://www.youtube.com/post/Ugkx…');
+```
+
+### Run it as a cloud service
+
+A Cloudflare Worker can't run `cloud-ytdl` or ffmpeg, so deploy the media API on
+any Node host and call it over HTTP. `createMediaHandler` is a fetch-style
+`(Request) => Response`; `serveMediaApi` wraps it in `node:http`:
+
+```bash
+MEDIA_API_KEY=… YOUTUBE_COOKIES=… npx extract-youtube serve-media --port 8787
+curl -H "Authorization: Bearer $MEDIA_API_KEY" \
+  "http://localhost:8787/audio?v=dQw4w9WgXcQ&format=mp3&bitrate=48&mono=1&rate=16000" -o round.mp3
+```
+
+| Route | Query | Answers |
+| --- | --- | --- |
+| `GET …/info` | `v` | video info and stream list (JSON) |
+| `GET …/audio` | `v`, `format` (`mp3`/`m4a`/`webm`), `bitrate`, `mono`, `rate` | the audio file |
+| `GET …/video` | `v`, `quality` | the video file |
+| `GET …/subtitles` | `v`, `lang`, `format` (`srt`/`xml`) | the captions |
+| `GET …/playlist` | `url` | playlist JSON |
+| `GET …/post` | `url` | community post JSON |
+
+Routes match on the last path segment, so the handler mounts under any prefix.
+Always set `MEDIA_API_KEY` (or `apiKey`) on a public host — an open download
+proxy is bandwidth anyone can spend. Treat cookie strings as passwords. Use it
+within YouTube's Terms of Service.
+
+From the CLI: `extract-youtube audio <id> [--format mp3|m4a|webm] [--bitrate 64] [--mono] [-o file]`.
+
 ## Live Demo and Storybook
 
 **Docs: [youtube.js.org](https://youtube.js.org)** · Live demo: [youtube.js.org/demo](https://youtube.js.org/demo) · Storybook: [youtube.js.org/storybook](https://youtube.js.org/storybook/)

package/dist/cli.js

@@ -2010,7 +2010,7 @@ var package_exports = /* @__PURE__ */ require_rolldown_runtime.__exportAll({
 var init_package = require_rolldown_runtime.__esmMin((() => {
 	name = "extract-youtube";
 	version = "1.0.414";
-	description = "Fast, no-browser serverless-optimized YouTube transcript extractor, with a video library admin API (D1 or in-memory) and React UI: a floating YouTube player, a synced-transcript modal, video grid/list components and library admin screens";
+	description = "Fast, no-browser serverless-optimized YouTube transcript extractor, with optional cloud-ytdl audio/video download (MP3 via ffmpeg) and a media HTTP API, with a video library admin API (D1 or in-memory) and React UI: a floating YouTube player, a synced-transcript modal, video grid/list components and library admin screens";
 	main$1 = "dist/index.cjs";
 	module$1 = "dist/index.mjs";
 	types = "dist/index.d.ts";
@@ -2029,19 +2029,25 @@ var init_package = require_rolldown_runtime.__esmMin((() => {
 			"types": "./dist/library/index.d.ts",
 			"import": "./dist/library/index.mjs",
 			"require": "./dist/library/index.cjs"
+		},
+		"./download": {
+			"types": "./dist/download/index.d.ts",
+			"import": "./dist/download/index.mjs",
+			"require": "./dist/download/index.cjs"
 		}
 	};
 	bin = { "extract-youtube": "dist/cli.js" };
 	files = ["dist", "src"];
 	scripts = {
 		"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:library && npm run build:types",
+		"build": "npm run clean && npm run build:lib && npm run build:cli && npm run build:react && npm run build:library && npm run build:download && npm run build:types",
 		"build:types": "tsc --emitDeclarationOnly --declaration --declarationMap",
 		"build:lib": "vite build",
 		"build:cli": "BUILD_CLI=true vite build",
 		"build:react": "BUILD_REACT=true vite build",
 		"build:library": "BUILD_LIBRARY=true vite build",
-		"build:bundle": "npm run build:lib && npm run build:cli && npm run build:react && npm run build:library",
+		"build:download": "BUILD_DOWNLOAD=true vite build",
+		"build:bundle": "npm run build:lib && npm run build:cli && npm run build:react && npm run build:library && npm run build:download",
 		"build:legacy": "tsc",
 		"ship": "npm run build && npx standard-version --release-as patch; npm publish",
 		"test": "jest",
@@ -2079,6 +2085,9 @@ var init_package = require_rolldown_runtime.__esmMin((() => {
 		"video-grid",
 		"admin",
 		"cloudflare-d1",
+		"youtube-downloader",
+		"mp3",
+		"audio-extraction",
 		"storybook"
 	];
 	license = "rights.institute/PROSPER";
@@ -2095,11 +2104,13 @@ var init_package = require_rolldown_runtime.__esmMin((() => {
 		"youtube-transcript-api": "^3.0.6"
 	};
 	peerDependencies = {
+		"cloud-ytdl": ">=1.0.5-next",
 		"react": ">=18",
 		"react-dom": ">=18",
 		"lucide-react": "^0.300.0 || ^1.0.0"
 	};
 	peerDependenciesMeta = {
+		"cloud-ytdl": { "optional": true },
 		"react": { "optional": true },
 		"react-dom": { "optional": true },
 		"lucide-react": { "optional": true }
@@ -2109,6 +2120,7 @@ var init_package = require_rolldown_runtime.__esmMin((() => {
 		"@types/node": "^26.5.0",
 		"@types/react": "^19.2.18",
 		"@types/react-dom": "^19.2.7",
+		"cloud-ytdl": "^1.0.5-next",
 		"jest": "^30.5.1",
 		"lucide-react": "^1.43.0",
 		"react": "^19.2.8",
@@ -2137,6 +2149,7 @@ var init_package = require_rolldown_runtime.__esmMin((() => {
 		license,
 		repository,
 		dependencies,
+		"//peerDependencies": "cloud-ytdl backs only the Node-only extract-youtube/download entry (audio/video download, MP3 via ffmpeg); optional so a transcript-only install stays dependency-light and Worker-safe.",
 		peerDependencies,
 		peerDependenciesMeta,
 		devDependencies,
@@ -2226,13 +2239,57 @@ EXAMPLES:
 
   # Extract speech speed encoding with joined text and timestamps
   extract-youtube jNQXAC9IVRw -f speeds
+
+MEDIA (needs the optional peer: npm install cloud-ytdl; MP3 also needs ffmpeg):
+  extract-youtube audio <video-id> [--format mp3|m4a|webm] [--bitrate 64] [--mono] [-o file]
+  extract-youtube serve-media [--port 8787]   # HTTP API; set MEDIA_API_KEY to require a key
+  Cookies for restricted videos: YOUTUBE_COOKIES env var. Proxy: --proxy <url>.
 `);
 }
 function showVersion() {
 	const pkg = (init_package(), require_rolldown_runtime.__toCommonJS(package_exports).default);
 	console.log(`extract-youtube v${pkg.version}`);
 }
+/** `audio` and `serve-media`: the cloud-ytdl backed `extract-youtube/download` entry. */
+async function runMediaCommand(command, args) {
+	const { createMediaExtractor, serveMediaApi } = await Promise.resolve().then(() => require("./download-B1w1a7Bx.js"));
+	const flag = (name) => {
+		const i = args.indexOf(name);
+		return i >= 0 ? args[i + 1] : void 0;
+	};
+	const shared = {
+		cookies: process.env.YOUTUBE_COOKIES,
+		proxy: flag("--proxy")
+	};
+	if (command === "serve-media") {
+		const port = Number(flag("--port") ?? process.env.PORT ?? 8787);
+		await serveMediaApi({
+			...shared,
+			port,
+			apiKey: process.env.MEDIA_API_KEY
+		});
+		console.error(`extract-youtube media API listening on :${port}${process.env.MEDIA_API_KEY ? "" : " (no MEDIA_API_KEY: open to anyone)"}`);
+		return;
+	}
+	const videoId = args.find((a, i) => !a.startsWith("-") && !args[i - 1]?.startsWith("-"));
+	if (!videoId) throw new Error("Usage: extract-youtube audio <video-id> [--format mp3|m4a|webm] [-o file]");
+	const download = await createMediaExtractor(shared).downloadAudio(videoId, {
+		container: flag("--format") ?? "mp3",
+		bitrateKbps: flag("--bitrate") ? Number(flag("--bitrate")) : void 0,
+		mono: args.includes("--mono")
+	});
+	const file = flag("-o") ?? flag("--output") ?? download.filename;
+	const fs = await import("node:fs");
+	const { pipeline } = await import("node:stream/promises");
+	await pipeline(download.stream, fs.createWriteStream(file));
+	console.error(`Saved ${download.info.title} to ${file}`);
+}
 async function main() {
+	const [command, ...rest] = process.argv.slice(2);
+	if (command === "audio" || command === "serve-media") {
+		await runMediaCommand(command, rest);
+		return;
+	}
 	const options = parseArgs();
 	if (options.help) {
 		showHelp();
@@ -2295,7 +2352,10 @@ async function main() {
 		process.exit(1);
 	}
 }
-main();
+main().catch((error) => {
+	console.error(`Error: ${error instanceof Error ? error.message : String(error)}`);
+	process.exit(1);
+});
 //#endregion
 
 //# sourceMappingURL=cli.js.map