social-dl 0.0.2 → 0.9.0

package/README.md

@@ -1,9 +1,166 @@
-# social-dl ⚉
+## SOCIAL MEDIA SCRAPPER ⚉
+> brought to you by CRYSNOVA_AI
 
-Direct social media video downloader - **no prexzy, no hitube, no 3rd party API**.
+# social-dl — The last downloader you'll ever need
 
-Downloads straight from `fbcdn.net`, `tiktokcdn`, etc. Won't go down when those APIs go down.
+Direct CDN social downloader for YouTube, TikTok, Facebook, Instagram, Twitter/X, Pinterest, and CapCut. **No API. No keys. No third-party downloader service.**
+
+[![npm](https://img.shields.io/npm/v/social-dl)](https://www.npmjs.com/package/social-dl) [![License](https://img.shields.io/badge/license-proprietary-red)](./LICENSE) [![Node](https://img.shields.io/badge/node-%3E%3D18-green)](https://nodejs.org/)
+
+![social-dl direct media downloader](https://cdn.crysnova.qzz.io/files/1790612783695-28bb146a-6d45-4d09-8255-def439edb896.jpeg)
+
+## Why social-dl?
+
+| Capability | social-dl | Proxy downloader API |
+|---|---:|---:|
+| Direct CDN extraction | Yes | No |
+| Depends on a third-party API staying online | No | Yes |
+| API key required | No | Often |
+| Open source | No — proprietary | Varies |
+
+## Install
 
-### Install
 ```bash
 npm install social-dl
+```
+
+## CLI
+
+```bash
+npx social-dl https://youtu.be/BJs3DBrMTSc
+npx social-dl https://youtu.be/BJs3DBrMTSc --mp3 -o audio.m4a
+npx social-dl https://facebook.com/share/r/xxx/ --json
+npx social-dl https://www.tiktok.com/@user/video/123 --no-watermark
+npx social-dl doctor
+```
+
+Use `--quality 720p`, `--json`, `--no-watermark`, and `-o output.mp4` as needed. YouTube may reject datacenter IPs; `doctor` reports this as `BOT_DETECTED`.
+
+## Library
+
+```js
+import { universalDl, universalSave, universalStream } from 'social-dl';
+
+const data = await universalDl('https://youtu.be/BJs3DBrMTSc');
+await universalSave('https://youtu.be/BJs3DBrMTSc', './video.mp4');
+```
+
+### Platform-specific library examples
+
+Every platform also exposes its own `xxxDl()` and `xxxSave()` functions. Each `Dl()` call returns normalized metadata and direct CDN formats; each `Save()` call downloads the selected format.
+
+#### Facebook
+
+```js
+import { facebookDl, facebookSave } from 'social-dl/facebook';
+
+const facebook = await facebookDl('https://www.facebook.com/reel/1234567890/');
+await facebookSave('https://www.facebook.com/reel/1234567890/', './facebook.mp4', 'HD');
+```
+
+#### YouTube video
+
+```js
+import { youtubeDl, youtubeSave } from 'social-dl/youtube';
+
+const youtube = await youtubeDl('https://youtu.be/BJs3DBrMTSc');
+await youtubeSave('https://youtu.be/BJs3DBrMTSc', './youtube.mp4', '720p');
+```
+
+#### YouTube audio
+
+```js
+import { youtubeMp3Dl, youtubeMp3Save } from 'social-dl/ytmp3';
+
+const audio = await youtubeMp3Dl('https://youtu.be/BJs3DBrMTSc');
+await youtubeMp3Save('https://youtu.be/BJs3DBrMTSc', './audio.m4a');
+```
+
+#### Instagram
+
+```js
+import { instagramDl, instagramSave } from 'social-dl/instagram';
+
+const instagram = await instagramDl('https://www.instagram.com/reel/CODE/');
+await instagramSave('https://www.instagram.com/reel/CODE/', './instagram.mp4');
+```
+
+#### TikTok
+
+```js
+import { tiktokDl, tiktokSave } from 'social-dl/tiktok';
+
+const tiktok = await tiktokDl('https://www.tiktok.com/@user/video/1234567890123456789');
+await tiktokSave('https://www.tiktok.com/@user/video/1234567890123456789', './tiktok.mp4', 'NOWM');
+```
+
+#### Twitter/X
+
+```js
+import { twitterDl, twitterSave } from 'social-dl/twitter';
+
+const tweet = await twitterDl('https://x.com/user/status/1851234567890');
+await twitterSave('https://x.com/user/status/1851234567890', './twitter.mp4');
+```
+
+#### Pinterest
+
+```js
+import { pinterestDl, pinterestSave } from 'social-dl/pinterest';
+
+const pin = await pinterestDl('https://www.pinterest.com/pin/1234567890/');
+await pinterestSave('https://www.pinterest.com/pin/1234567890/', './pinterest.mp4');
+```
+
+#### CapCut
+
+```js
+import { capcutDl, capcutSave } from 'social-dl/capcut';
+
+const template = await capcutDl('https://www.capcut.com/template-detail/1234567890');
+await capcutSave('https://www.capcut.com/template-detail/1234567890', './capcut.mp4');
+```
+
+### Express/Next.js streaming
+
+```js
+const { stream, contentType, filename } = await universalStream(url);
+res.setHeader('Content-Type', contentType);
+res.setHeader('Content-Disposition', `inline; filename="${filename}"`);
+Readable.fromWeb(stream).pipe(res);
+```
+
+## Platforms
+
+| Platform | Example |
+|---|---|
+| Facebook | `https://www.facebook.com/reel/1234567890/` |
+| YouTube | `https://youtu.be/BJs3DBrMTSc` |
+| Instagram | `https://www.instagram.com/reel/CODE/` |
+| TikTok | `https://www.tiktok.com/@user/video/123` |
+| Twitter/X | `https://x.com/user/status/123` |
+| Pinterest | `https://www.pinterest.com/pin/1234567890/` |
+| CapCut | `https://www.capcut.com/template-detail/1234567890` |
+| YouTube audio | Same YouTube URLs with `{ audioOnly: true }` or `--mp3` |
+
+## API reference
+
+- `universalDl(url, { audioOnly, quality })` — return normalized direct-CDN formats.
+- `universalSave(url, destination, { audioOnly, quality, noWatermark })` — save a selected format.
+- `universalStream(url, options)` — return a Web `ReadableStream` for piping.
+- `doctor({ log })` — test provider reachability, Node, and ffmpeg.
+- Every platform exports `xxxDl()` and `xxxSave()`.
+
+## Error handling
+
+Handle `BotDetectedError` for provider anti-automation blocks, `PrivateError` for login/private content, `NotFoundError` for missing media, and `UnsupportedError` for unsupported URLs.
+
+## Demo
+
+<!-- DEMO TODO FOR 1.0.0: After publishing 0.9.0, record terminal and replace with ![demo](./demo.gif) -->
+
+Demo video coming in 1.0.0 — npx becomes available after this 0.9.0 pre-launch.
+
+## License
+
+Proprietary license. See [LICENSE](./LICENSE).

package/bin/cli.js

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+import { createWriteStream } from 'node:fs';
+import { pipeline } from 'node:stream/promises';
+import { universalDl, universalSave } from '../src/index.js';
+import { doctor } from '../src/doctor.js';
+import { randomUserAgent } from '../src/utils/fetcher.js';
+
+const VERSION = '0.9.0';
+const HELP = `social-dl ${VERSION}\n\nUsage:\n  social-dl <url> [-o file] [--quality 720p]\n  social-dl <url> --mp3 -o audio.m4a\n  social-dl <url> --json\n  social-dl <url> --no-watermark\n  social-dl doctor [--json]\n\nOptions: --quality <label>  --mp3  --json  --no-watermark  -o, --output <file>  --help`;
+const color = (code, text) => process.stdout.isTTY ? `\x1b[${code}m${text}\x1b[0m` : text;
+
+function parse(argv) {
+  const opts = { _: [] };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--help' || arg === '-h') opts.help = true;
+    else if (arg === '--mp3') opts.audioOnly = true;
+    else if (arg === '--json') opts.json = true;
+    else if (arg === '--no-watermark') opts.noWatermark = true;
+    else if (arg === '--quality') opts.quality = argv[++i];
+    else if (arg === '-o' || arg === '--output') opts.output = argv[++i];
+    else opts._.push(arg);
+  }
+  return opts;
+}
+
+async function streamSave(info, output, quality, noWatermark) {
+  let formats = info.formats;
+  if (noWatermark) formats = formats.filter(item => item.isNoWatermark !== false);
+  const selected = quality ? formats.find(item => item.tag === quality || item.quality === quality) : formats[0];
+  const format = selected || formats[0];
+  if (!format) throw new Error('NO_FORMATS');
+  const response = await fetch(format.url, { headers: { 'User-Agent': randomUserAgent(), Referer: info.originalUrl } });
+  if (!response.ok || !response.body) throw new Error(`CDN_FETCH_FAILED_${response.status}`);
+  const total = Number(response.headers.get('content-length')) || 0;
+  let received = 0;
+  const reader = response.body.getReader();
+  const outputStream = createWriteStream(output);
+  const readable = new ReadableStream({ async pull(controller) { const { done, value } = await reader.read(); if (done) return controller.close(); received += value.byteLength; controller.enqueue(value); if (!process.stdout.isTTY) return; const mb = (received / 1048576).toFixed(1); const suffix = total ? ` / ${(total / 1048576).toFixed(1)} MB` : ' MB'; process.stdout.write(`\r${color(36, `Downloading ${mb}${suffix}`)}`); }, cancel() { reader.cancel(); } });
+  await pipeline(readable, outputStream);
+  if (process.stdout.isTTY) process.stdout.write('\n');
+  return output;
+}
+
+async function main() {
+  const opts = parse(process.argv.slice(2));
+  if (opts.help || opts._[0] === undefined) return console.log(HELP);
+  if (opts._[0] === 'doctor') return opts.json ? console.log(JSON.stringify(await doctor({ log: false }), null, 2)) : await doctor();
+  const url = opts._[0];
+  const info = await universalDl(url, { audioOnly: opts.audioOnly });
+  if (opts.json) return console.log(JSON.stringify(info, null, 2));
+  const output = opts.output || `${info.id}.${opts.audioOnly ? 'm4a' : (info.formats[0]?.type || 'mp4')}`;
+  await streamSave(info, output, opts.quality, opts.noWatermark);
+  console.log(`${color(32, 'Saved')} ${output}`);
+}
+
+main().catch(error => { console.error(color(31, `${error.code || error.name || 'ERROR'}: ${error.message}`)); process.exitCode = 1; });

package/index.d.ts

@@ -0,0 +1,31 @@
+export interface Format { tag: string; quality: string; type: string; url: string; hasAudio?: boolean; isAudioOnly?: boolean; isNoWatermark?: boolean; }
+export interface DlResult { creator?: string; platform: string; id: string; title?: string; author?: string; thumbnail?: string; originalUrl: string; isAudioOnly?: boolean; formats: Format[]; needsMux?: boolean; videoUrl?: string; audioUrl?: string; }
+export interface UniversalOptions { audioOnly?: boolean; quality?: string; noWatermark?: boolean; }
+export interface StreamResult { stream: ReadableStream<Uint8Array>; filename: string; info: DlResult; contentType: string; contentLength?: string | null; }
+export function detectPlatform(url: string): string;
+export function universalDl(url: string, opts?: UniversalOptions): Promise<DlResult>;
+export function universalSave(url: string, dest?: string, opts?: UniversalOptions): Promise<string>;
+export function universalStream(url: string, opts?: UniversalOptions): Promise<StreamResult>;
+export function doctor(options?: { log?: boolean }): Promise<any>;
+export function facebookDl(url: string): Promise<DlResult>;
+export function facebookSave(url: string, dest?: string, quality?: string): Promise<string>;
+export function youtubeDl(url: string): Promise<DlResult>;
+export function youtubeSave(url: string, dest?: string, quality?: string): Promise<string>;
+export function youtubeMp3Dl(url: string): Promise<DlResult>;
+export function youtubeMp3Save(url: string, dest?: string, quality?: string): Promise<string>;
+export function instagramDl(url: string): Promise<DlResult>;
+export function instagramSave(url: string, dest?: string, quality?: string): Promise<string>;
+export function tiktokDl(url: string): Promise<DlResult>;
+export function tiktokSave(url: string, dest?: string, quality?: string): Promise<string>;
+export function twitterDl(url: string): Promise<DlResult>;
+export function twitterSave(url: string, dest?: string, quality?: string): Promise<string>;
+export function pinterestDl(url: string): Promise<DlResult>;
+export function pinterestSave(url: string, dest?: string, quality?: string): Promise<string>;
+export function capcutDl(url: string): Promise<DlResult>;
+export function capcutSave(url: string, dest?: string, quality?: string): Promise<string>;
+export class SocialDlError extends Error { code: string; }
+export class BotDetectedError extends SocialDlError {}
+export class PrivateError extends SocialDlError {}
+export class NotFoundError extends SocialDlError {}
+export class UnsupportedError extends SocialDlError {}
+export const CREATOR: string;

package/package.json

@@ -1,35 +1,30 @@
 {
   "name": "social-dl",
-  "version": "0.0.2",
+  "version": "0.9.0",
   "license": "SEE LICENSE IN LICENSE ⚉",
-  "description": "Universal social media downloader - ⚉ direct from Facebook, TikTok, Instagram, Twitter/X without any 3rd party API like prexzy",
+  "description": "Direct CDN social downloader - YouTube, TikTok, Facebook, Instagram, Twitter, Pinterest, CapCut - No API, No keys, Never dies",
   "main": "src/index.js",
   "type": "module",
+  "bin": { "social-dl": "./bin/cli.js" },
   "exports": {
     ".": "./src/index.js",
-    "./facebook": "./src/platforms/facebook.js"
+    "./facebook": "./src/platforms/facebook.js",
+    "./youtube": "./src/platforms/youtube.js",
+    "./ytmp3": "./src/platforms/ytmp3.js",
+    "./instagram": "./src/platforms/instagram.js",
+    "./tiktok": "./src/platforms/tiktok.js",
+    "./twitter": "./src/platforms/twitter.js",
+    "./pinterest": "./src/platforms/pinterest.js",
+    "./capcut": "./src/platforms/capcut.js",
+    "./stream": "./src/stream.js"
   },
   "scripts": {
-    "test": "node test.js",
+    "test": "node tests/test.js",
     "dev": "node src/index.js"
   },
-  "keywords": [
-    "facebook",
-    "tiktok",
-    "instagram",
-    "twitter",
-    "downloader",
-    "social-media",
-    "video-downloader",
-    "fbdown",
-    "reels",
-    "scrapper",
-    "plogme",
-    "crysnovax",
-    "no-api"
-  ],
-  "author": "crysnovax",
-  "license": "MIT",
+  "keywords": ["youtube downloader", "tiktok downloader", "facebook downloader", "instagram downloader", "twitter downloader", "pinterest downloader", "capcut downloader", "youtube mp3", "youtube to mp3", "reels downloader", "no api downloader", "direct cdn", "social-dl", "ytmp4", "ytmp3"],
+  "author": "@plogme",
+  "license": "SEE LICENSE IN LICENSE",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/crysnovax/social-dl.git"
@@ -43,6 +38,9 @@
   },
   "files": [
     "src/",
-    "README.md"
+    "bin/",
+    "index.d.ts",
+    "README.md",
+    "LICENSE"
   ]
 }

package/src/constants.js

@@ -0,0 +1,2 @@
+/** Constant attribution included in social-dl metadata responses. */
+export const CREATOR = '@plogme';

package/src/doctor.js

@@ -0,0 +1,41 @@
+import { spawnSync } from 'node:child_process';
+import { fetchWithRetry } from './utils/fetcher.js';
+import { BotDetectedError } from './errors.js';
+import { player } from './platforms/youtube.js';
+
+const CHECKS = {
+  facebook: 'https://www.facebook.com/',
+  youtube: 'https://www.youtube.com/',
+  instagram: 'https://www.instagram.com/',
+  tiktok: 'https://www.tiktok.com/',
+  twitter: 'https://video.twimg.com/',
+  pinterest: 'https://v.pinimg.com/',
+  capcut: 'https://www.capcut.com/'
+};
+
+/** Check provider reachability and local runtime prerequisites. */
+export async function doctor({ log = true } = {}) {
+  const result = { node: { ok: Number(process.versions.node.split('.')[0]) >= 18, version: process.versions.node }, ffmpeg: { ok: spawnSync('ffmpeg', ['-version'], { stdio: 'ignore' }).status === 0 }, providers: {} };
+  for (const [name, url] of Object.entries(CHECKS)) {
+    const started = Date.now();
+    try {
+      const response = await fetchWithRetry(url, { signal: AbortSignal.timeout(5000), headers: { Accept: 'text/html' } }, 0);
+      result.providers[name] = { ok: response.ok || response.status < 500, status: response.status, ms: Date.now() - started };
+      if (name === 'youtube') {
+        try {
+          await player('BJs3DBrMTSc');
+        } catch (error) {
+          if (error instanceof BotDetectedError) result.providers[name] = { ...result.providers[name], ok: false, code: error.code, warning: 'YouTube is blocking Innertube requests from this network.' };
+        }
+      }
+    } catch (error) {
+      result.providers[name] = { ok: false, code: error instanceof BotDetectedError ? error.code : 'FETCH_FAILED', message: error.message, ms: Date.now() - started, warning: name === 'youtube' && error instanceof BotDetectedError ? 'YouTube may be blocking this datacenter IP.' : undefined };
+    }
+  }
+  if (log) {
+    console.log(`Node ${result.node.ok ? '✓' : '✗'} ${result.node.version}`);
+    console.log(`ffmpeg ${result.ffmpeg.ok ? '✓ available' : '✗ not found'}`);
+    for (const [name, item] of Object.entries(result.providers)) console.log(`${name.padEnd(10)} ${item.ok ? '✓' : '✗'}${item.status ? ` HTTP ${item.status}` : ` ${item.code}`}${item.warning ? ` — ${item.warning}` : ''}`);
+  }
+  return result;
+}

package/src/errors.js

@@ -0,0 +1,40 @@
+/** Base error for social-dl failures. */
+export class SocialDlError extends Error {
+  constructor(message, code = 'SOCIAL_DL_ERROR') {
+    super(message);
+    this.name = 'SocialDlError';
+    this.code = code;
+  }
+}
+
+/** Indicates that the source is private or requires authentication. */
+export class PrivateError extends SocialDlError {
+  constructor(message = 'The media is private or requires login.') {
+    super(message, 'PRIVATE_OR_LOGIN_REQUIRED');
+    this.name = 'PrivateError';
+  }
+}
+
+/** Indicates that no supported media was found. */
+export class NotFoundError extends SocialDlError {
+  constructor(message = 'No supported media was found.') {
+    super(message, 'NOT_FOUND');
+    this.name = 'NotFoundError';
+  }
+}
+
+/** Indicates that the URL is not supported. */
+export class UnsupportedError extends SocialDlError {
+  constructor(message = 'Unsupported URL.') {
+    super(message, 'UNSUPPORTED_URL');
+    this.name = 'UnsupportedError';
+  }
+}
+
+/** Indicates that a provider blocked an automated request. */
+export class BotDetectedError extends SocialDlError {
+  constructor(message = 'The provider blocked this automated request.') {
+    super(message, 'BOT_DETECTED');
+    this.name = 'BotDetectedError';
+  }
+}

package/src/index.js

@@ -0,0 +1,57 @@
+import { UnsupportedError } from './errors.js';
+import { facebookDl, facebookSave } from './platforms/facebook.js';
+import { youtubeDl, youtubeSave } from './platforms/youtube.js';
+import { youtubeMp3Dl, youtubeMp3Save } from './platforms/ytmp3.js';
+import { instagramDl, instagramSave } from './platforms/instagram.js';
+import { tiktokDl, tiktokSave } from './platforms/tiktok.js';
+import { twitterDl, twitterSave } from './platforms/twitter.js';
+import { pinterestDl, pinterestSave } from './platforms/pinterest.js';
+import { capcutDl, capcutSave } from './platforms/capcut.js';
+import { saveResult } from './utils/media.js';
+
+/** Identify the supported platform for a URL. */
+export function detectPlatform(value) {
+  const host = new URL(value).hostname.toLowerCase();
+  if (host.includes('facebook.com') || host === 'fb.watch') return 'facebook';
+  if (host.includes('youtube.com') || host === 'youtu.be') return 'youtube';
+  if (host.includes('instagram.com')) return 'instagram';
+  if (host.includes('tiktok.com')) return 'tiktok';
+  if (host === 'x.com' || host.endsWith('twitter.com') || host === 't.co') return 'twitter';
+  if (host.includes('pinterest.com') || host === 'pin.it') return 'pinterest';
+  if (host.includes('capcut.com')) return 'capcut';
+  throw new UnsupportedError();
+}
+
+/** Download metadata using the correct platform extractor. */
+export async function universalDl(url, opts = {}) {
+  switch (detectPlatform(url)) {
+    case 'facebook': return facebookDl(url);
+    case 'youtube': return opts.audioOnly ? youtubeMp3Dl(url) : youtubeDl(url);
+    case 'instagram': return instagramDl(url);
+    case 'tiktok': return tiktokDl(url);
+    case 'twitter': return twitterDl(url);
+    case 'pinterest': return pinterestDl(url);
+    case 'capcut': return capcutDl(url);
+    default: throw new UnsupportedError();
+  }
+}
+
+/** Save a selected format from the correct platform. */
+export async function universalSave(url, dest = './video.mp4', opts = {}) {
+  const quality = opts.quality || 'best';
+  const result = await universalDl(url, opts);
+  return saveResult(result, dest, quality, {}, opts.noWatermark === true);
+}
+
+export * from './errors.js';
+export * from './constants.js';
+export { universalStream } from './stream.js';
+export { doctor } from './doctor.js';
+export * from './platforms/facebook.js';
+export * from './platforms/youtube.js';
+export * from './platforms/ytmp3.js';
+export * from './platforms/instagram.js';
+export * from './platforms/tiktok.js';
+export * from './platforms/twitter.js';
+export * from './platforms/pinterest.js';
+export * from './platforms/capcut.js';

package/src/platforms/capcut.js

@@ -0,0 +1,28 @@
+import { fetchWithRetry } from '../utils/fetcher.js';
+import { resolveShortUrl } from '../utils/resolver.js';
+import { saveResult, sortFormats } from '../utils/media.js';
+import { unescapeJson } from '../utils/parser.js';
+import { NotFoundError, UnsupportedError } from '../errors.js';
+import { CREATOR } from '../constants.js';
+
+const findUrls = value => { const urls = []; const walk = item => { if (!item) return; if (typeof item === 'string' && /\.(?:mp4)(?:[?&]|$)/i.test(item)) urls.push(item); else if (Array.isArray(item)) item.forEach(walk); else if (typeof item === 'object') Object.values(item).forEach(walk); }; walk(value); return urls; };
+
+/** Download metadata and direct CapCut CDN formats. */
+export async function capcutDl(url) {
+  const resolved = await resolveShortUrl(url);
+  const id = resolved.match(/template-detail\/(\d+)/)?.[1] || resolved.match(/\/(\d{10,19})(?:\D|$)/)?.[1];
+  if (!id) throw new UnsupportedError('Invalid CapCut URL.');
+  let urls = [];
+  const api = await fetchWithRetry(`https://www.capcut.com/api/v1/query/template/detail?template_id=${id}&language=en&aid=0`, { headers: { Referer: 'https://www.capcut.com/' } });
+  if (api.ok) { try { urls = findUrls(await api.json()); } catch {} }
+  if (!urls.length) {
+    const html = await (await fetchWithRetry(`https://www.capcut.com/template-detail/${id}`, { headers: { Referer: 'https://www.capcut.com/' } })).text();
+    urls = ['video_url', 'download_url', 'play_url'].map(key => html.match(new RegExp(`"${key}":"([^"]+)"`))?.[1]).filter(Boolean).map(unescapeJson);
+  }
+  const formats = sortFormats([...new Set(urls)].map((item, index) => ({ tag: index ? 'SD' : 'HD', quality: index ? '720p' : '1080p', type: 'mp4', isNoWatermark: true, url: item })));
+  if (!formats.length) throw new NotFoundError();
+  return { creator: CREATOR, platform: 'capcut', id, title: `CapCut template ${id}`, originalUrl: resolved, formats };
+}
+
+/** Save a CapCut video to disk. */
+export async function capcutSave(url, dest = './video.mp4', quality = 'best') { return saveResult(await capcutDl(url), dest, quality); }

package/src/platforms/facebook.js

@@ -0,0 +1,42 @@
+import { fetchWithRetry, downloadTo } from '../utils/fetcher.js';
+import { sortFormats, saveResult } from '../utils/media.js';
+import { NotFoundError, PrivateError } from '../errors.js';
+import { CREATOR } from '../constants.js';
+
+const DESKTOP = 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 Chrome/120.0 Safari/537.36';
+const unescape = value => { try { return JSON.parse(`"${value}"`); } catch { return value.replace(/\\u0025/g, '%').replace(/\\u0026/g, '&').replace(/\\\//g, '/'); } };
+
+function extract(html) {
+  const find = name => { const match = html.match(new RegExp(`"${name}":"([^"]+)"`)); return match && unescape(match[1]); };
+  const hd = find('browser_native_hd_url') || find('playable_url_quality_hd');
+  const sd = find('browser_native_sd_url') || find('playable_url');
+  return sortFormats([
+    hd && { tag: 'HD', quality: '720p', type: 'mp4', url: hd },
+    sd && { tag: 'SD', quality: '360p', type: 'mp4', url: sd }
+  ]);
+}
+
+/** Download metadata for a Facebook video or reel. */
+export async function facebookDl(url) {
+  const resolved = await fetchWithRetry(url, { headers: { 'User-Agent': DESKTOP } });
+  const originalUrl = resolved.url || url;
+  const id = originalUrl.match(/reel\/(\d+)|videos\/(\d+)|[?&]v=(\d+)|\/(\d+)\/?$/)?.slice(1).find(Boolean) || originalUrl;
+  let html = await (await fetchWithRetry(originalUrl, { headers: { 'User-Agent': DESKTOP } })).text();
+  let formats = extract(html);
+  if (html.length < 5000 || formats.length === 0) {
+    await new Promise(resolve => setTimeout(resolve, 1000));
+    const basicUrl = originalUrl.replace(/www\.facebook\.com/i, 'mbasic.facebook.com');
+    html = await (await fetchWithRetry(basicUrl, { headers: { 'User-Agent': DESKTOP } })).text();
+    formats = extract(html);
+  }
+  if (!formats.length) {
+    if (/login|checkpoint|not found/i.test(html)) throw new PrivateError();
+    throw new NotFoundError('PRIVATE_OR_NOT_FOUND');
+  }
+  return { creator: CREATOR, platform: 'facebook', id, originalUrl, formats };
+}
+
+/** Save a Facebook video to disk. */
+export async function facebookSave(url, dest = './video.mp4', quality = 'best') {
+  return saveResult(await facebookDl(url), dest, quality, { 'User-Agent': DESKTOP, Referer: 'https://www.facebook.com/' });
+}

package/src/platforms/instagram.js

@@ -0,0 +1,48 @@
+import { fetchWithRetry } from '../utils/fetcher.js';
+import { saveResult, sortFormats } from '../utils/media.js';
+import { unescapeJson } from '../utils/parser.js';
+import { NotFoundError, PrivateError, UnsupportedError } from '../errors.js';
+import { CREATOR } from '../constants.js';
+
+const UAS = ['Mozilla/5.0 (iPhone; CPU iPhone OS 16_6 like Mac OS X) AppleWebKit/605.1.15', 'Mozilla/5.0 (Linux; Android 14; Pixel 8) AppleWebKit/537.36 Chrome/120 Mobile Safari/537.36'];
+const headers = () => ({ 'User-Agent': UAS[Math.floor(Math.random() * UAS.length)], 'X-IG-App-ID': '936619743392459', Accept: 'application/json' });
+const codeOf = url => new URL(url).pathname.match(/\/(?:p|reel|tv)\/([A-Za-z0-9_-]+)/)?.[1] || new URL(url).pathname.match(/share\/([A-Za-z0-9_-]+)/)?.[1];
+
+function fromHtml(html) {
+  const find = key => { const m = html.match(new RegExp(`"${key}":"([^"]+)"`)); return m && unescapeJson(m[1]); };
+  const urls = [...html.matchAll(/"url":"(https:[^\"]+)"/g)].map(m => unescapeJson(m[1])).filter(url => /(?:scontent|cdninstagram)/i.test(url) && /\.mp4(?:[?&]|$)/i.test(url));
+  return sortFormats([find('video_url') || urls[0], ...urls].filter(Boolean).map((url, i) => ({ tag: i ? 'SD' : 'HD', quality: i ? '480p' : '720p', type: 'mp4', url })));
+}
+
+/** Download metadata and direct formats for an Instagram post or reel. */
+export async function instagramDl(url) {
+  const id = codeOf(url);
+  if (!id) throw new UnsupportedError('Invalid Instagram URL.');
+  const base = `https://www.instagram.com/p/${id}/`;
+  let response = await fetchWithRetry(`${base}?__a=1&__d=dis`, { headers: headers() });
+  let formats = [];
+  let item;
+  if (response.ok) {
+    try {
+      const json = await response.json();
+      item = json.items?.[0] || json.data?.xdt_shortcode_media;
+      const media = item?.carousel_media || [item];
+      formats = sortFormats(media.flatMap((entry, index) => [
+        ...(entry?.video_versions || []).map(v => ({ tag: index ? `${index + 1}` : 'HD', quality: `${v.height || 720}p`, type: 'mp4', url: v.url })),
+        entry?.image_versions2?.candidates?.[0] && { tag: 'IMG', quality: `${entry.image_versions2.candidates[0].width || 1080}x${entry.image_versions2.candidates[0].height || 1080}`, type: 'jpg', url: entry.image_versions2.candidates[0].url }
+      ]));
+    } catch { /* use embed fallback */ }
+  }
+  if (!formats.length) {
+    response = await fetchWithRetry(`https://www.instagram.com/reel/${id}/embed/`, { headers: headers() });
+    const html = await response.text();
+    if (response.url.includes('/accounts/login')) throw new PrivateError();
+    formats = fromHtml(html);
+    if (!formats.length) { const image = html.match(/"display_url":"([^"]+)"/); if (image) formats.push({ tag: 'IMG', quality: '1080x1080', type: 'jpg', url: unescapeJson(image[1]) }); }
+  }
+  if (!formats.length) throw new NotFoundError('NOT_FOUND');
+  return { creator: CREATOR, platform: 'instagram', id, username: item?.user?.username, author: item?.user?.username, caption: item?.caption?.text, originalUrl: url, formats };
+}
+
+/** Save an Instagram video or image. */
+export async function instagramSave(url, dest = './ig.mp4', quality = 'best') { return saveResult(await instagramDl(url), dest, quality, { Referer: 'https://www.instagram.com/' }); }

package/src/platforms/pinterest.js

@@ -0,0 +1,30 @@
+import { fetchWithRetry } from '../utils/fetcher.js';
+import { resolveShortUrl } from '../utils/resolver.js';
+import { saveResult, sortFormats } from '../utils/media.js';
+import { extractJson } from '../utils/parser.js';
+import { NotFoundError, UnsupportedError } from '../errors.js';
+import { CREATOR } from '../constants.js';
+
+/** Download metadata and direct Pinterest video/image formats. */
+export async function pinterestDl(url) {
+  const resolved = await resolveShortUrl(url);
+  const id = resolved.match(/pin\/(\d+)/)?.[1];
+  if (!id) throw new UnsupportedError('Invalid Pinterest URL.');
+  const response = await fetchWithRetry(`https://www.pinterest.com/pin/${id}/`, { headers: { 'User-Agent': 'Mozilla/5.0 iPhone', 'X-Pinterest-PWS-Handler': 'www/[pin]' } });
+  const html = await response.text();
+  const json = extractJson(html, '__PWS_DATA__');
+  const pin = json?.props?.initialReduxState?.pins?.[id];
+  const list = pin?.videos?.video_list || {};
+  const formats = sortFormats(Object.values(list).filter(v => v?.url && /\.mp4(?:[?&]|$)/i.test(v.url)).map(v => ({ tag: v.width ? `${v.width}p` : 'HD', quality: v.width ? `${v.width}p` : 'HD', type: 'mp4', url: v.url, height: v.height })));
+  const image = pin?.images?.orig?.url;
+  if (image) formats.push({ tag: 'IMG', quality: 'orig', type: 'jpg', url: image });
+  if (!formats.length) {
+    const video = html.match(/"video_url":"([^"]+)"/)?.[1];
+    if (video) formats.push({ tag: 'HD', quality: '720p', type: 'mp4', url: JSON.parse(`"${video}"`) });
+  }
+  if (!formats.length) throw new NotFoundError();
+  return { creator: CREATOR, platform: 'pinterest', id, title: pin?.grid_title || pin?.title, originalUrl: resolved, formats };
+}
+
+/** Save a Pinterest video or image to disk. */
+export async function pinterestSave(url, dest = './video.mp4', quality = 'best') { return saveResult(await pinterestDl(url), dest, quality); }

package/src/platforms/tiktok.js

@@ -0,0 +1,33 @@
+import { fetchWithRetry } from '../utils/fetcher.js';
+import { resolveShortUrl } from '../utils/resolver.js';
+import { saveResult, sortFormats } from '../utils/media.js';
+import { extractJson, getPath, unescapeJson } from '../utils/parser.js';
+import { NotFoundError, PrivateError, UnsupportedError } from '../errors.js';
+import { CREATOR } from '../constants.js';
+
+const UA = 'Mozilla/5.0 (iPhone; CPU iPhone OS 16_6 like Mac OS X) AppleWebKit/605.1.15 Version/16.6 Mobile/15E148 Safari/604.1';
+const clean = value => value && unescapeJson(value);
+
+/** Download metadata and direct CDN formats for a TikTok video. */
+export async function tiktokDl(url) {
+  const resolved = await resolveShortUrl(url);
+  const id = resolved.match(/\/video\/(\d+)/)?.[1] || resolved.match(/\/v\/(\d+)/)?.[1];
+  if (!id) throw new UnsupportedError('Invalid TikTok URL.');
+  const pageUrl = resolved.match(/\/video\//) ? resolved : `https://www.tiktok.com/@a/video/${id}`;
+  const response = await fetchWithRetry(pageUrl, { headers: { 'User-Agent': UA, Accept: 'text/html' } });
+  const html = await response.text();
+  const json = extractJson(html, '__UNIVERSAL_DATA_FOR_REHYDRATION__');
+  const video = getPath(json, '__DEFAULT_SCOPE__.webapp.video-detail.videoData.itemInfo.itemStruct.video');
+  const item = getPath(json, '__DEFAULT_SCOPE__.webapp.video-detail.videoData.itemInfo.itemStruct');
+  const play = clean(video?.playAddr) || clean(html.match(/"playAddr":"([^"]+)"/)?.[1]);
+  const download = clean(video?.downloadAddr) || clean(html.match(/"downloadAddr":"([^"]+)"/)?.[1]);
+  const formats = sortFormats([
+    download && { tag: 'NOWM', quality: '720p', type: 'mp4', isNoWatermark: true, url: download },
+    play && { tag: 'WM', quality: '720p', type: 'mp4', isNoWatermark: false, url: play }
+  ]);
+  if (!formats.length) { if (/user-posts|login/i.test(html)) throw new PrivateError('PRIVATE_OR_NOT_FOUND'); throw new NotFoundError('PRIVATE_OR_NOT_FOUND'); }
+  return { creator: CREATOR, platform: 'tiktok', id, username: item?.author?.uniqueId ? `@${item.author.uniqueId}` : undefined, author: item?.author?.nickname, title: item?.desc, originalUrl: resolved, formats };
+}
+
+/** Save a TikTok video to disk. */
+export async function tiktokSave(url, dest = './tt.mp4', quality = 'best') { return saveResult(await tiktokDl(url), dest, quality, { Referer: 'https://www.tiktok.com/' }); }

package/src/platforms/twitter.js

@@ -0,0 +1,27 @@
+import { fetchWithRetry } from '../utils/fetcher.js';
+import { saveResult, sortFormats } from '../utils/media.js';
+import { unescapeJson } from '../utils/parser.js';
+import { NotFoundError, UnsupportedError } from '../errors.js';
+import { CREATOR } from '../constants.js';
+
+const idOf = url => new URL(url).pathname.match(/status\/(\d+)/)?.[1];
+
+/** Download metadata and direct MP4 variants for an X/Twitter post. */
+export async function twitterDl(url) {
+  const id = idOf(url);
+  if (!id) throw new UnsupportedError('Invalid Twitter URL.');
+  const response = await fetchWithRetry(`https://cdn.syndication.twimg.com/tweet-result?id=${id}&lang=en&features=tfw_timeline_list%3D%7B%7D`, { headers: { 'User-Agent': 'Mozilla/5.0' } });
+  const json = response.ok ? await response.json() : {};
+  const media = json.mediaDetails?.flatMap(item => item.video_info?.variants || []) || [];
+  let formats = sortFormats(media.filter(v => v.content_type === 'video/mp4' && v.url).map(v => ({ tag: `${Math.round((v.bitrate || 0) / 1000) || 0}kbps`, quality: `${Math.round((v.bitrate || 0) / 1000) || 0}kbps`, type: 'mp4', url: v.url, bitrate: v.bitrate })));
+  if (!formats.length) {
+    const html = await (await fetchWithRetry(`https://x.com/i/status/${id}`, { headers: { 'User-Agent': 'Mozilla/5.0' } })).text();
+    const urls = [...html.matchAll(/https:[^" ]*video\.twimg\.com[^" ]+\.mp4[^" ]*/g)].map(m => unescapeJson(m[0]));
+    formats = urls.map((item, index) => ({ tag: index ? '480p' : '720p', quality: index ? '480p' : '720p', type: 'mp4', url: item }));
+  }
+  if (!formats.length) throw new NotFoundError();
+  return { creator: CREATOR, platform: 'twitter', id, author: json.user?.screen_name ? `@${json.user.screen_name}` : undefined, title: json.text, originalUrl: url, formats };
+}
+
+/** Save a Twitter/X video to disk. */
+export async function twitterSave(url, dest = './video.mp4', quality = 'best') { return saveResult(await twitterDl(url), dest, quality); }

package/src/platforms/youtube.js

@@ -0,0 +1,62 @@
+import { fetchWithRetry, getVisitorData } from '../utils/fetcher.js';
+import { saveResult, sortFormats, qualityOf } from '../utils/media.js';
+import { NotFoundError, UnsupportedError } from '../errors.js';
+import { CREATOR } from '../constants.js';
+
+const KEY = 'AIzaSyA8eiZmM1FaDVjRy-df2KTyQ_vz_yYM39w';
+const ENDPOINT = `https://www.youtube.com/youtubei/v1/player?key=${KEY}`;
+const CLIENTS = [
+  { name: 'ANDROID', version: '20.10.38', ua: 'com.google.android.youtube/20.10.38 (Linux; U; Android 14) gzip' },
+  { name: 'IOS', version: '19.45.4', deviceModel: 'iPhone15,2', ua: 'com.google.ios.youtube/19.45.4 (iPhone15,2; U; CPU iOS 17_5_1 like Mac OS X)' },
+  { name: 'ANDROID_MUSIC', version: '6.51', ua: 'com.google.android.apps.youtube.music/6.51 (Linux; U; Android 14) gzip' }
+];
+
+/** Extract an 11-character YouTube video id. */
+export function videoId(url) { return new URL(url).toString().match(/(?:youtu\.be\/|[?&]v=|shorts\/)([A-Za-z0-9_-]{11})/)?.[1]; }
+
+/** Send one direct Innertube player request for a specific client profile. */
+export async function innertubeRequest(id, client, visitorData) {
+  const context = { client: { clientName: client.name, clientVersion: client.version, ...(client.deviceModel ? { deviceModel: client.deviceModel } : {}), hl: 'en', gl: 'US' }, ...(visitorData ? { visitorData } : {}) };
+  const response = await fetchWithRetry(ENDPOINT, { method: 'POST', headers: { 'Content-Type': 'application/json', 'User-Agent': client.ua, ...(visitorData ? { 'X-Goog-Visitor-Id': visitorData } : {}), Origin: 'https://www.youtube.com', Referer: 'https://www.youtube.com/' }, body: JSON.stringify({ context, videoId: id, contentCheckOk: true, racyCheckOk: true }) });
+  if (!response.ok) throw new Error(`YOUTUBE_HTTP_${response.status}`);
+  return response.json();
+}
+
+/** Try each supported YouTube client until streaming data is returned. */
+export async function player(id) {
+  const visitorData = await getVisitorData();
+  let data = null;
+  let lastError;
+  for (const client of CLIENTS) {
+    try {
+      data = await innertubeRequest(id, client, visitorData);
+      if (data?.streamingData?.formats || data?.streamingData?.adaptiveFormats) return data;
+      if (data?.playabilityStatus?.status === 'ERROR' && JSON.stringify(data).includes('403')) continue;
+      lastError = new Error(data?.playabilityStatus?.reason || 'UNAVAILABLE');
+    } catch (error) {
+      lastError = error;
+    }
+  }
+  if (!data?.streamingData) throw lastError || new Error(data?.playabilityStatus?.reason || 'UNAVAILABLE');
+  return data;
+}
+
+/** Download metadata and direct formats for a YouTube video. */
+export async function youtubeDl(url) {
+  const id = videoId(url);
+  if (!id) throw new UnsupportedError('Invalid YouTube URL.');
+  const data = await player(id);
+  if (!data.streamingData) throw new NotFoundError('PRIVATE_OR_AGE_RESTRICTED');
+  const all = [...(data.streamingData.formats || []), ...(data.streamingData.adaptiveFormats || [])];
+  const formats = sortFormats(all.filter(item => item.url && /^video\/mp4/.test(item.mimeType || '')).map(item => ({ tag: qualityOf(item, 'video'), quality: qualityOf(item, 'video'), type: 'mp4', hasAudio: !item.mimeType?.includes('video-only'), url: item.url, bitrate: item.bitrate, height: item.height })));
+  if (!formats.length) throw new NotFoundError('NO_PLAYABLE_MP4');
+  const best = formats[0];
+  const audio = all.find(item => item.url && String(item.itag) === '140' && item.mimeType?.startsWith('audio/')) || all.find(item => item.url && item.mimeType?.startsWith('audio/'));
+  const mux = best.height >= 1080 && best.hasAudio === false && audio;
+  return { creator: CREATOR, platform: 'youtube', id, title: data.videoDetails?.title, thumbnail: `https://i.ytimg.com/vi/${id}/maxresdefault.jpg`, originalUrl: url, formats, ...(mux ? { needsMux: true, videoUrl: best.url, audioUrl: audio.url } : {}) };
+}
+
+/** Save a YouTube video to disk. */
+export async function youtubeSave(url, dest = './yt.mp4', quality = 'best') { return saveResult(await youtubeDl(url), dest, quality); }
+
+export { CLIENTS };

package/src/platforms/ytmp3.js

@@ -0,0 +1,22 @@
+import { player, videoId } from './youtube.js';
+import { saveResult, sortFormats } from '../utils/media.js';
+import { NotFoundError, UnsupportedError } from '../errors.js';
+import { CREATOR } from '../constants.js';
+
+/** Download audio-only metadata from YouTube (m4a/opus, not transcoded MP3). */
+export async function youtubeMp3Dl(url) {
+  const id = videoId(url);
+  if (!id) throw new UnsupportedError('Invalid YouTube URL.');
+  const data = await player(id);
+  const source = data.streamingData?.adaptiveFormats || [];
+  const formats = sortFormats(source.filter(item => item.url && item.mimeType?.startsWith('audio/')).map(item => {
+    const type = item.mimeType.includes('webm') ? 'opus' : 'm4a';
+    const kbps = Math.round((item.bitrate || 0) / 1000);
+    return { tag: type === 'opus' ? `OPUS_${kbps}` : `MP3_${kbps}`, quality: `${kbps}kbps`, type, hasAudio: true, isAudioOnly: true, url: item.url, bitrate: item.bitrate };
+  }));
+  if (!formats.length) throw new NotFoundError('PRIVATE_OR_AGE_RESTRICTED');
+  return { creator: CREATOR, platform: 'youtube', id, title: data.videoDetails?.title, thumbnail: `https://i.ytimg.com/vi/${id}/maxresdefault.jpg`, isAudioOnly: true, originalUrl: url, formats };
+}
+
+/** Save the best YouTube audio stream to disk. */
+export async function youtubeMp3Save(url, dest = './audio.m4a', quality = 'best') { return saveResult(await youtubeMp3Dl(url), dest, quality); }

package/src/stream.js

@@ -0,0 +1,13 @@
+import { randomUserAgent } from './utils/fetcher.js';
+import { universalDl } from './index.js';
+
+/** Resolve a direct CDN stream and its normalized metadata. */
+export async function universalStream(url, opts = {}) {
+  const info = await universalDl(url, opts);
+  const best = opts.quality ? info.formats.find(item => item.tag === opts.quality || item.quality === opts.quality) || info.formats[0] : info.formats[0];
+  if (!best) throw new Error('NO_FORMATS');
+  const response = await fetch(best.url, { headers: { 'User-Agent': randomUserAgent(), Referer: info.originalUrl } });
+  if (!response.ok || !response.body) throw new Error('CDN_FETCH_FAILED');
+  const filename = `${info.id}.${best.type}`.replace(/[^a-z0-9._-]/gi, '_');
+  return { stream: response.body, filename, info, contentType: best.type === 'mp4' ? 'video/mp4' : best.type === 'jpg' ? 'image/jpeg' : 'audio/mp4', contentLength: response.headers.get('content-length') };
+}

package/src/utils/fetcher.js

@@ -0,0 +1,65 @@
+import { BotDetectedError } from '../errors.js';
+
+const USER_AGENTS = [
+  'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 Chrome/120.0 Safari/537.36',
+  'Mozilla/5.0 (iPhone; CPU iPhone OS 16_6 like Mac OS X) AppleWebKit/605.1.15 Version/16.6 Mobile/15E148 Safari/604.1',
+  'Mozilla/5.0 (Linux; Android 14; Pixel 8) AppleWebKit/537.36 Chrome/120.0 Mobile Safari/537.36'
+];
+
+/** Pick a browser-like user agent. */
+export function randomUserAgent() {
+  return USER_AGENTS[Math.floor(Math.random() * USER_AGENTS.length)];
+}
+
+/** Fetch a URL with redirect following and one retry for transient failures. */
+export async function fetchWithRetry(input, options = {}, retries = 1) {
+  let lastError;
+  for (let attempt = 0; attempt <= retries; attempt += 1) {
+    try {
+      const headers = { 'User-Agent': randomUserAgent(), ...(options.headers || {}) };
+      const response = await fetch(input, { ...options, headers, redirect: options.redirect || 'follow' });
+      if (response.status === 403) {
+        const body = await response.clone().text();
+        if (/automated|unusual traffic|sorry/i.test(body)) {
+          throw new BotDetectedError('The provider rejected this request as automated traffic.');
+        }
+      }
+      if (!response.ok && attempt < retries && (response.status >= 500 || response.status === 429)) continue;
+      return response;
+    } catch (error) {
+      lastError = error;
+      if (attempt < retries) await new Promise(resolve => setTimeout(resolve, 250));
+    }
+  }
+  throw lastError;
+}
+
+/** Read YouTube's visitor-data token for Innertube requests. */
+export async function getVisitorData() {
+  try {
+    const response = await fetch('https://www.youtube.com/', { headers: { 'User-Agent': 'Mozilla/5.0' } });
+    const html = await response.text();
+    return html.match(/"VISITOR_DATA":"([^"]+)"/)?.[1]
+      || html.match(/ytcfg\.set.*?"VISITOR_DATA":"([^"]+)"/)?.[1]
+      || null;
+  } catch {
+    return null;
+  }
+}
+
+/** Fetch and return text, rejecting non-success responses. */
+export async function fetchText(input, options = {}) {
+  const response = await fetchWithRetry(input, options);
+  if (!response.ok) throw new Error(`HTTP_${response.status}`);
+  return response.text();
+}
+
+/** Fetch a direct media URL and write it to disk. */
+export async function downloadTo(url, dest, options = {}) {
+  const response = await fetchWithRetry(url, options);
+  if (!response.ok) throw new Error(`DOWNLOAD_HTTP_${response.status}`);
+  const { writeFile } = await import('node:fs/promises');
+  const data = Buffer.from(await response.arrayBuffer());
+  await writeFile(dest, data);
+  return dest;
+}

package/src/utils/media.js

@@ -0,0 +1,29 @@
+import { downloadTo } from './fetcher.js';
+import { saveMuxed } from './mux.js';
+
+/** Sort formats by resolution, bitrate, then audio preference. */
+export function sortFormats(formats) {
+  return formats.filter(format => format?.url).sort((a, b) => {
+    const score = item => (parseInt(item.quality, 10) || 0) * 100000 + (item.bitrate || 0) + (item.hasAudio ? 100 : 0);
+    return score(b) - score(a);
+  });
+}
+
+/** Select a format by requested quality and save it. */
+export async function saveResult(result, dest, quality = 'best', headers = {}, noWatermark = false) {
+  if (result.needsMux && quality === 'best') {
+    const muxed = await saveMuxed(result, dest, headers);
+    if (muxed) return muxed;
+    console.warn('Install ffmpeg to auto-mux 1080p; saving the best direct video stream instead.');
+  }
+  let formats = result.formats || [];
+  if (noWatermark) formats = formats.filter(item => item.isNoWatermark !== false);
+  const wanted = quality === 'best' ? formats[0] : formats.find(item => item.tag === quality || item.quality === quality) || formats[0];
+  if (!wanted) throw new Error('NO_FORMATS');
+  return downloadTo(wanted.url, dest, { headers });
+}
+
+/** Parse a quality label from a media object. */
+export function qualityOf(item, fallback = 'unknown') {
+  return item.qualityLabel || (item.height ? `${item.height}p` : fallback);
+}

package/src/utils/mux.js

@@ -0,0 +1,31 @@
+import { spawnSync, execFile } from 'node:child_process';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { unlink } from 'node:fs/promises';
+import { downloadTo } from './fetcher.js';
+
+/** Return whether ffmpeg is available on PATH. */
+export function hasFfmpeg() {
+  return spawnSync('ffmpeg', ['-version'], { stdio: 'ignore' }).status === 0;
+}
+
+function runFfmpeg(args) {
+  return new Promise((resolve, reject) => execFile('ffmpeg', args, { windowsHide: true }, (error, _stdout, stderr) => error ? reject(new Error(stderr || error.message)) : resolve()));
+}
+
+/** Download separate audio/video streams and mux them into one MP4 when possible. */
+export async function saveMuxed(result, dest, headers = {}) {
+  if (!result.needsMux || !result.videoUrl || !result.audioUrl) return null;
+  if (!hasFfmpeg()) return false;
+  const base = join(tmpdir(), `social-dl-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+  const videoPath = `${base}.video.mp4`;
+  const audioPath = `${base}.audio.m4a`;
+  try {
+    await downloadTo(result.videoUrl, videoPath, { headers });
+    await downloadTo(result.audioUrl, audioPath, { headers });
+    await runFfmpeg(['-y', '-i', videoPath, '-i', audioPath, '-c', 'copy', dest]);
+    return dest;
+  } finally {
+    await Promise.allSettled([unlink(videoPath), unlink(audioPath)]);
+  }
+}

package/src/utils/parser.js

@@ -0,0 +1,18 @@
+/** Decode a JSON-escaped string found inside HTML. */
+export function unescapeJson(value) {
+  if (value == null) return value;
+  try { return JSON.parse(`"${value}"`); } catch { return value.replace(/\\u002F/g, '/').replace(/\\\\/g, '\\').replace(/\\"/g, '"'); }
+}
+
+/** Extract a JSON script element by id. */
+export function extractJson(html, id) {
+  const escapedId = id.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const match = html.match(new RegExp(`<script[^>]+id=["']${escapedId}["'][^>]*>([\\s\\S]*?)</script>`, 'i'));
+  if (!match) return null;
+  try { return JSON.parse(match[1]); } catch { return null; }
+}
+
+/** Return a JSON object nested at a dotted path. */
+export function getPath(value, path) {
+  return path.split('.').reduce((current, key) => current?.[key], value);
+}

package/src/utils/resolver.js

@@ -0,0 +1,12 @@
+import { fetchWithRetry } from './fetcher.js';
+
+/** Resolve a short social URL and return its final URL. */
+export async function resolveShortUrl(url) {
+  const input = new URL(url);
+  const host = input.hostname.toLowerCase();
+  const shortHosts = ['vm.tiktok.com', 'pin.it', 't.co', 'fb.watch'];
+  const isCapcutShort = host.endsWith('capcut.com') && input.pathname.startsWith('/t/');
+  if (!shortHosts.includes(host) && !isCapcutShort) return url;
+  const response = await fetchWithRetry(url, { method: 'GET', redirect: 'follow' });
+  return response.url || url;
+}