social-dl 0.9.1 → 0.9.5

package/README.md

@@ -31,10 +31,12 @@ 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 https://www.instagram.com/reel/CODE/ --cookies ~/cookies.txt -o instagram.mp4
+npx social-dl https://www.tiktok.com/@user/video/123 --cookies-from-browser chrome -o tiktok.mp4
 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`.
+Use `--quality 720p`, `--json`, `--no-watermark`, and `-o output.mp4` as needed. For login-required Instagram or TikTok posts, pass an exported cookie file with `--cookies path/to/cookies.txt` or use `--cookies-from-browser chrome`, `firefox`, `edge`, or `brave`. YouTube may reject datacenter IPs; `doctor` reports this as `BOT_DETECTED`.
 
 ## Library
 
@@ -81,8 +83,8 @@ await youtubeMp3Save('https://youtu.be/BJs3DBrMTSc', './audio.m4a');
 ```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');
+const instagram = await instagramDl('https://www.instagram.com/reel/CODE/', { cookiesPath: './cookies.txt' });
+await instagramSave('https://www.instagram.com/reel/CODE/', './instagram.mp4', 'best', { cookiesPath: './cookies.txt' });
 ```
 
 #### TikTok
@@ -90,8 +92,8 @@ await instagramSave('https://www.instagram.com/reel/CODE/', './instagram.mp4');
 ```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');
+const tiktok = await tiktokDl('https://www.tiktok.com/@user/video/1234567890123456789', { cookiesFromBrowser: 'chrome' });
+await tiktokSave('https://www.tiktok.com/@user/video/1234567890123456789', './tiktok.mp4', 'NOWM', { cookiesFromBrowser: 'chrome' });
 ```
 
 #### Twitter/X
@@ -145,8 +147,8 @@ Readable.fromWeb(stream).pipe(res);
 
 ## API reference
 
-- `universalDl(url, { audioOnly, quality })` — return normalized direct-CDN formats.
-- `universalSave(url, destination, { audioOnly, quality, noWatermark })` — save a selected format.
+- `universalDl(url, { audioOnly, quality, cookiesPath, cookiesFromBrowser })` — return normalized direct-CDN formats.
+- `universalSave(url, destination, { audioOnly, quality, noWatermark, cookiesPath, cookiesFromBrowser })` — 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()`.

package/bin/cli.js

@@ -4,8 +4,11 @@ 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';
+import { createRequire } from 'node:module';
+import { mkdir } from 'node:fs/promises';
 
-const VERSION = '0.9.0';
+const require = createRequire(import.meta.url);
+const VERSION = require('../package.json').version;
 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;
 
@@ -18,6 +21,8 @@ function parse(argv) {
     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 === '--cookies') opts.cookiesPath = argv[++i];
+    else if (arg === '--cookies-from-browser') opts.cookiesFromBrowser = argv[++i];
     else if (arg === '-o' || arg === '--output') opts.output = argv[++i];
     else opts._.push(arg);
   }
@@ -43,14 +48,17 @@ async function streamSave(info, output, quality, noWatermark) {
 }
 
 async function main() {
-  const opts = parse(process.argv.slice(2));
+  const argv = process.argv.slice(2);
+  if (argv.includes('--version') || argv.includes('-v')) return console.log(VERSION);
+  await mkdir('cache/cookies', { recursive: true });
+  const opts = parse(argv);
   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 });
+  const info = await universalDl(url, opts);
   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);
+  await universalSave(url, output, opts);
   console.log(`${color(32, 'Saved')} ${output}`);
 }
 

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "social-dl",
-  "version": "0.9.1",
+  "version": "0.9.5",
   "license": "SEE LICENSE IN LICENSE",
   "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"
+    "social-dl": "bin/cli.js"
   },
   "exports": {
     ".": "./src/index.js",
@@ -24,6 +24,9 @@
     "test": "node tests/test.js",
     "dev": "node src/index.js"
   },
+  "optionalDependencies": {
+    "yt-dlp-exec": "^1.0.2"
+  },
   "keywords": [
     "youtube downloader",
     "tiktok downloader",
@@ -54,10 +57,8 @@
     "node": ">=18.0.0"
   },
   "files": [
-    "src/",
     "bin/",
-    "index.d.ts",
-    "README.md",
-    "LICENSE"
+    "src/",
+    "README.md"
   ]
 }

package/src/index.js

@@ -1,6 +1,6 @@
 import { UnsupportedError } from './errors.js';
 import { facebookDl, facebookSave } from './platforms/facebook.js';
-import { youtubeDl, youtubeSave } from './platforms/youtube.js';
+import { IOS_MEDIA_HEADERS, YOUTUBE_MEDIA_HEADERS, 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';
@@ -25,10 +25,10 @@ export function detectPlatform(value) {
 /** 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 'facebook': return facebookDl(url, opts);
+    case 'youtube': return opts.audioOnly ? youtubeMp3Dl(url, opts) : youtubeDl(url, opts);
+    case 'instagram': return instagramDl(url, opts);
+    case 'tiktok': return tiktokDl(url, opts);
     case 'twitter': return twitterDl(url);
     case 'pinterest': return pinterestDl(url);
     case 'capcut': return capcutDl(url);
@@ -39,8 +39,14 @@ export async function universalDl(url, opts = {}) {
 /** Save a selected format from the correct platform. */
 export async function universalSave(url, dest = './video.mp4', opts = {}) {
   const quality = opts.quality || 'best';
+  const platform = detectPlatform(url);
+  if (platform === 'youtube') return opts.audioOnly ? youtubeMp3Save(url, dest, quality, opts) : youtubeSave(url, dest, quality, opts);
+  if (platform === 'facebook') return facebookSave(url, dest, quality, opts);
+  if (platform === 'instagram') return instagramSave(url, dest, quality, opts);
+  if (platform === 'tiktok') return tiktokSave(url, dest, quality, opts);
   const result = await universalDl(url, opts);
-  return saveResult(result, dest, quality, {}, opts.noWatermark === true);
+  const headers = detectPlatform(url) === 'youtube' ? { ...YOUTUBE_MEDIA_HEADERS, fallbackHeaders: IOS_MEDIA_HEADERS } : {};
+  return saveResult(result, dest, quality, headers, opts.noWatermark === true);
 }
 
 export * from './errors.js';

package/src/platforms/facebook.js

@@ -1,11 +1,27 @@
-import { fetchWithRetry, downloadTo } from '../utils/fetcher.js';
+import { mkdir, rename, stat, unlink } from 'node:fs/promises';
+import { join } from 'node:path';
+import { fetchWithRetry } from '../utils/fetcher.js';
 import { sortFormats, saveResult } from '../utils/media.js';
-import { NotFoundError, PrivateError } from '../errors.js';
+import { cookieArgs, runYtDlp } from '../utils/ytdlp.js';
+import { NotFoundError, PrivateError, UnsupportedError } 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';
+export const UA = 'Mozilla/5.0 (Linux; Android 15) AppleWebKit/537.36 Chrome/131 Mobile Safari/537.36';
+export const TMP_DIR = 'cache/temp';
+const FB_HEADERS = { 'User-Agent': UA, Accept: '*/*', 'Accept-Language': 'en-US,en;q=0.9', Referer: 'https://www.facebook.com/', Origin: 'https://www.facebook.com/' };
 const unescape = value => { try { return JSON.parse(`"${value}"`); } catch { return value.replace(/\\u0025/g, '%').replace(/\\u0026/g, '&').replace(/\\\//g, '/'); } };
 
+export function isFacebookUrl(value) {
+  try {
+    const parsed = new URL(value);
+    return /facebook\.com\/share\/r\//i.test(parsed.href)
+      || /fb\.watch/i.test(parsed.hostname)
+      || /facebook\.com\/reel\//i.test(parsed.href)
+      || /web\.facebook\.com\/reel\//i.test(parsed.href)
+      || /facebook\.com\/watch/i.test(parsed.href);
+  } catch { return false; }
+}
+
 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');
@@ -16,27 +32,69 @@ function extract(html) {
   ]);
 }
 
-/** Download metadata for a Facebook video or reel. */
-export async function facebookDl(url) {
-  const resolved = await fetchWithRetry(url, { headers: { 'User-Agent': DESKTOP } });
+function idOf(url) { return url.match(/reel\/(\d+)|videos\/(\d+)|[?&]v=(\d+)|\/(\d+)\/?/)?.slice(1).find(Boolean) || url; }
+function fallbackError(error) { return error instanceof PrivateError || error instanceof NotFoundError || /PRIVATE|NOT_FOUND|empty|404|403|login|checkpoint/i.test(error?.message || ''); }
+function outputFile(base) { return join(TMP_DIR, `${base}.mp4`); }
+async function validFile(file) { try { return (await stat(file)).isFile() && (await stat(file)).size > 4096; } catch { return false; } }
+async function cleanup(file) { await unlink(file).catch(() => {}); }
+
+async function ytdlpInfo(url, options = {}) {
+  const { stdout } = await runYtDlp(['--dump-json', '--no-download', '--no-playlist', '--skip-download', '--no-warnings', '--remote-components', 'ejs:github', '--js-runtimes', 'node', '--user-agent', UA, ...cookieArgs(options), url]);
+  const line = stdout.trim().split(/\r?\n/).find(Boolean);
+  if (!line) throw new Error('yt-dlp returned no Facebook video information.');
+  return JSON.parse(line);
+}
+function normalizeFallback(data, url) {
+  const direct = data.url || data.requested_formats?.find(item => item.url)?.url;
+  return { creator: CREATOR, platform: 'facebook', id: data.id || idOf(url), title: data.title, author: data.uploader || data.channel, originalUrl: url, formats: direct ? [{ tag: 'BEST', quality: `${data.height || 720}p`, type: 'mp4', url: direct, hasAudio: true }] : [], fallback: true };
+}
+async function facebookFallbackInfo(url, options) { return normalizeFallback(await ytdlpInfo(url, options), url); }
+
+async function facebookFallbackDownload(url, dest, options = {}) {
+  await mkdir(TMP_DIR, { recursive: true });
+  const base = `fb-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+  const temp = outputFile(base);
+  try {
+    await runYtDlp(['--no-playlist', '--remote-components', 'ejs:github', '--js-runtimes', 'node', '--no-warnings', '--user-agent', UA, '-f', 'bv*[ext=mp4][vcodec^=avc1][height<=1080]+ba[ext=m4a]/b[ext=mp4]/best', '--merge-output-format', 'mp4', '-o', temp, ...cookieArgs(options), url]);
+    if (!await validFile(temp)) throw new Error('Facebook yt-dlp output was empty or too small.');
+    await rename(temp, dest);
+    return dest;
+  } catch (error) {
+    if (/ENOENT|not found|spawn/i.test(error.message)) throw new Error('Facebook blocked. Run npm i yt-dlp-exec or pip install yt-dlp');
+    throw error;
+  } finally { await cleanup(temp); }
+}
+
+async function facebookTier1(url) {
+  const resolved = await fetchWithRetry(url, { headers: FB_HEADERS });
   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();
+  const id = idOf(originalUrl);
+  let html = await (await fetchWithRetry(originalUrl, { headers: FB_HEADERS })).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();
+    html = await (await fetchWithRetry(basicUrl, { headers: FB_HEADERS })).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');
-  }
+  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 };
 }
 
+/** Download metadata for a Facebook video or reel. */
+export async function facebookDl(url, options = {}) {
+  if (!isFacebookUrl(url)) throw new UnsupportedError('Invalid Facebook URL.');
+  try { return await facebookTier1(url); }
+  catch (error) {
+    if (!fallbackError(error)) throw error;
+    try { return await facebookFallbackInfo(url, options); }
+    catch (fallback) { if (/ENOENT|not found|spawn/i.test(fallback.message)) throw new Error('Facebook blocked. Run npm i yt-dlp-exec or pip install yt-dlp'); throw fallback; }
+  }
+}
+
 /** 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/' });
+export async function facebookSave(url, dest = './video.mp4', quality = 'best', options = {}) {
+  const result = await facebookDl(url, options);
+  if (result.fallback) return facebookFallbackDownload(url, dest, options);
+  return saveResult(result, dest, quality, FB_HEADERS);
 }

package/src/platforms/instagram.js

@@ -1,25 +1,81 @@
-import { fetchWithRetry } from '../utils/fetcher.js';
+import { mkdir, readFile, rename, stat, unlink } from 'node:fs/promises';
+import { join } from 'node:path';
+import { fetchWithRetry, downloadTo } from '../utils/fetcher.js';
 import { saveResult, sortFormats } from '../utils/media.js';
+import { cookieArgs, runYtDlp } from '../utils/ytdlp.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];
+export const UA = 'Mozilla/5.0 (Linux; Android 15) AppleWebKit/537.36 Chrome/131 Mobile Safari/537.36';
+export const TMP_DIR = 'cache/temp';
+const IG_HEADERS = { 'User-Agent': UA, Accept: '*/*', 'Accept-Language': 'en-US,en;q=0.9', Referer: 'https://www.instagram.com/', Origin: 'https://www.instagram.com/' };
+const codeOf = url => new URL(url).pathname.match(/\/(?:p|reel|tv)\/([A-Za-z0-9_-]+)/)?.[1];
+async function headersFor(options = {}) { return options.cookiesPath ? { ...IG_HEADERS, Cookie: await readFile(options.cookiesPath, 'utf8') } : IG_HEADERS; }
 
+export function isInstagramUrl(value) {
+  try { return /instagram\.com\/(?:reel|p|tv)\//i.test(new URL(value).href); } catch { return false; }
+}
+export function cleanInstagramUrl(value) { const parsed = new URL(value); return `${parsed.origin}${parsed.pathname.endsWith('/') ? parsed.pathname : `${parsed.pathname}/`}`; }
 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 })));
 }
+function fallbackError(error) { return error instanceof PrivateError || error instanceof NotFoundError || /PRIVATE|NOT_FOUND|LOGIN|404|403|empty|accounts\/login/i.test(error?.message || ''); }
+function outputFile(base) { return join(TMP_DIR, `${base}.mp4`); }
+async function validFile(file) { try { return (await stat(file)).isFile() && (await stat(file)).size > 4096; } catch { return false; } }
+async function cleanup(file) { await unlink(file).catch(() => {}); }
+async function ytdlpInfo(url, options = {}) {
+  const { stdout } = await runYtDlp(['--dump-json', '--no-download', '--no-playlist', '--skip-download', '--no-warnings', '--remote-components', 'ejs:github', '--js-runtimes', 'node', '--user-agent', UA, '--add-header', 'Referer:https://www.instagram.com/', '-f', 'best', ...cookieArgs(options), url]);
+  const line = stdout.trim().split(/\r?\n/).find(Boolean);
+  if (!line) throw new Error('yt-dlp returned no Instagram video information.');
+  return JSON.parse(line);
+}
+function normalizeFallback(data, url, id) {
+  const direct = data.url || data.requested_formats?.find(item => item.url)?.url;
+  return { creator: CREATOR, platform: 'instagram', id: data.id || id, username: data.uploader_id, author: data.uploader, caption: data.description, originalUrl: url, formats: direct ? [{ tag: 'BEST', quality: `${data.height || 720}p`, type: 'mp4', url: direct, hasAudio: true }] : [], fallback: true };
+}
+async function ddinstagramFallback(url, id, options = {}) {
+  const cookie = options.cookiesPath ? await readFile(options.cookiesPath, 'utf8') : '';
+  const headers = cookie ? { ...IG_HEADERS, Cookie: cookie } : IG_HEADERS;
+  const parse = html => {
+    const match = html.match(/"video_url":"(https:[^"]+)"/) || html.match(/video_versions.*?"url":"(https:[^"]+)"/s);
+    if (!match) return null;
+    try { return decodeURIComponent(unescapeJson(match[1])); } catch { return unescapeJson(match[1]); }
+  };
+  for (const endpoint of [`https://www.ddinstagram.com/reel/${id}/`, ...(cookie ? [`https://www.instagram.com/reel/${id}/`] : [])]) {
+    try {
+      const response = await fetchWithRetry(endpoint, { headers: endpoint.includes('instagram.com/reel') ? { ...headers, 'X-IG-App-ID': '936619743392459' } : headers });
+      const video = parse(await response.text());
+      if (video) return { creator: CREATOR, platform: 'instagram', id, originalUrl: url, formats: [{ tag: 'DDINSTAGRAM', quality: 'best', type: 'mp4', url: video, hasAudio: true }], fallback: true, fallbackMethod: 'ddinstagram' };
+    } catch { /* try the next endpoint */ }
+  }
+  throw new NotFoundError('DDINSTAGRAM_EMPTY_MEDIA');
+}
+async function instagramFallbackInfo(url, id, options = {}) {
+  try { return normalizeFallback(await ytdlpInfo(url, options), url, id); }
+  catch { return ddinstagramFallback(url, id, options); }
+}
+async function instagramFallbackDownload(url, dest, options = {}) {
+  await mkdir(TMP_DIR, { recursive: true });
+  const base = `ig-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+  const temp = outputFile(base);
+  try {
+    await runYtDlp(['--no-playlist', '--remote-components', 'ejs:github', '--js-runtimes', 'node', '--no-warnings', '--user-agent', UA, '--add-header', 'Referer:https://www.instagram.com/', '-f', 'best', '--merge-output-format', 'mp4', '-o', temp, ...cookieArgs(options), url]);
+    if (!await validFile(temp)) throw new Error('Instagram yt-dlp output was empty or too small.');
+    await rename(temp, dest);
+    return dest;
+  } catch (error) {
+    if (/ENOENT|not found|spawn/i.test(error.message)) throw new Error('Instagram blocked. Run npm i yt-dlp-exec or pip install yt-dlp');
+    throw error;
+  } finally { await cleanup(temp); }
+}
 
-/** 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() });
+async function instagramTier1(url, id, options = {}) {
+  const requestHeaders = await headersFor(options);
+  const base = `https://www.instagram.com/${url.match(/\/(reel|p|tv)\//i)?.[1] || 'p'}/${id}/`;
+  let response = await fetchWithRetry(`${base}?__a=1&__d=dis`, { headers: requestHeaders });
   let formats = [];
   let item;
   if (response.ok) {
@@ -34,7 +90,7 @@ export async function instagramDl(url) {
     } catch { /* use embed fallback */ }
   }
   if (!formats.length) {
-    response = await fetchWithRetry(`https://www.instagram.com/reel/${id}/embed/`, { headers: headers() });
+    response = await fetchWithRetry(`${base}embed/`, { headers: requestHeaders });
     const html = await response.text();
     if (response.url.includes('/accounts/login')) throw new PrivateError();
     formats = fromHtml(html);
@@ -44,5 +100,23 @@ export async function instagramDl(url) {
   return { creator: CREATOR, platform: 'instagram', id, username: item?.user?.username, author: item?.user?.username, caption: item?.caption?.text, originalUrl: url, formats };
 }
 
+/** Download metadata and direct formats for an Instagram post or reel. */
+export async function instagramDl(url, options = {}) {
+  if (!isInstagramUrl(url)) throw new UnsupportedError('Invalid Instagram URL.');
+  const cleanUrl = cleanInstagramUrl(url);
+  const id = codeOf(cleanUrl);
+  try { return await instagramTier1(cleanUrl, id, options); }
+  catch (error) {
+    if (!fallbackError(error)) throw error;
+    try { return await instagramFallbackInfo(cleanUrl, id, options); }
+    catch (fallback) { if (/ENOENT|not found|spawn/i.test(fallback.message)) throw new Error('Instagram blocked. Run npm i yt-dlp-exec or pip install yt-dlp'); throw fallback; }
+  }
+}
+
 /** 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/' }); }
+export async function instagramSave(url, dest = './ig.mp4', quality = 'best', options = {}) {
+  const result = await instagramDl(url, options);
+  if (result.fallback && result.fallbackMethod === 'ddinstagram') return downloadTo(result.formats[0].url, dest, { headers: await headersFor(options) });
+  if (result.fallback) return instagramFallbackDownload(cleanInstagramUrl(url), dest, options);
+  return saveResult(result, dest, quality, await headersFor(options));
+}

package/src/platforms/tiktok.js

@@ -1,33 +1,148 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { mkdir, readFile, unlink, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
 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';
+import { ytDlpDownloadUrl, ytDlpInfoUrl } from '../utils/ytdlp.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 execFileAsync = promisify(execFile);
+const UA = 'Mozilla/5.0 (Linux; Android 15) AppleWebKit/537.36 Chrome/131 Mobile Safari/537.36';
+export const TIKWM_API = 'https://www.tikwm.com/api/';
 const clean = value => value && unescapeJson(value);
 
+export function isTikTokUrl(value) {
+  try { return new URL(value).hostname.toLowerCase().includes('tiktok.com'); } catch { return false; }
+}
+
+export function validMediaBuffer(buffer) { return Buffer.isBuffer(buffer) && buffer.length > 4096; }
+
+async function tikwmApi(url) {
+  const response = await fetchWithRetry(TIKWM_API, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded; charset=UTF-8', 'User-Agent': UA, Referer: 'https://www.tikwm.com/' },
+    body: new URLSearchParams({ url, hd: '1' }).toString()
+  });
+  if (!response.ok) throw new Error(`TIKWM_HTTP_${response.status}`);
+  const json = await response.json();
+  if (json?.code !== 0 || !json.data) throw new NotFoundError('TIKTOK_PRIVATE_OR_NOT_FOUND');
+  return json.data;
+}
+
+async function getMedia(url) {
+  const response = await fetchWithRetry(url, { headers: { 'User-Agent': UA, Referer: 'https://www.tikwm.com/' } });
+  if (!response.ok) throw new Error(`TIKTOK_MEDIA_HTTP_${response.status}`);
+  const buffer = Buffer.from(await response.arrayBuffer());
+  if (!validMediaBuffer(buffer)) throw new Error('TIKTOK_MEDIA_TOO_SMALL');
+  return buffer;
+}
+
+function normalizeTikwm(data, originalUrl, id) {
+  const author = data.author || {};
+  const video = data.hdplay || data.play;
+  const formats = sortFormats([video && { tag: 'NOWM', quality: '720p', type: 'mp4', isNoWatermark: true, url: video }]);
+  return {
+    creator: CREATOR,
+    platform: 'tiktok',
+    id: String(data.id || id),
+    username: author.unique_id ? `@${author.unique_id}` : undefined,
+    author: author.nickname,
+    title: data.title,
+    views: data.play_count,
+    likes: data.digg_count,
+    comments: data.comment_count,
+    shares: data.share_count,
+    downloads: data.download_count,
+    originalUrl: data.share_url || originalUrl,
+    formats,
+    music: data.music,
+    fallback: true
+  };
+}
+function normalizeYtDlp(data, originalUrl, id) {
+  const direct = data.url || data.requested_formats?.find(item => item.url)?.url;
+  return { creator: CREATOR, platform: 'tiktok', id: data.id || id, author: data.uploader, title: data.title, originalUrl, formats: direct ? [{ tag: 'BEST', quality: `${data.height || 720}p`, type: 'mp4', url: direct, hasAudio: true }] : [], fallback: true, fallbackMethod: 'yt-dlp' };
+}
+
+async function tiktokFallback(url, id) {
+  const data = await tikwmApi(url);
+  return normalizeTikwm(data, url, id);
+}
+
 /** 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];
+export async function tiktokDl(url, options = {}) {
+  if (!isTikTokUrl(url)) throw new UnsupportedError('Invalid TikTok URL.');
+  let resolved = url;
+  try { resolved = await resolveShortUrl(url); } catch { /* preserve the original URL for fallback providers */ }
+  const id = resolved.match(/\/video\/(\d+)/)?.[1] || resolved.match(/\/v\/(\d+)/)?.[1] || new URL(resolved).pathname.split('/').filter(Boolean).pop() || url;
   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 };
+  try {
+    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) throw new PrivateError('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 };
+  } catch (error) {
+    try { return normalizeYtDlp(await ytDlpInfoUrl(url, options), url, id); }
+    catch { return tiktokFallback(url, id); }
+  }
+}
+
+/** Download TikTok MP4 or MP3 bytes using Tier 1 first, then TikWM. */
+export async function tiktokDownload(url, format = 'mp4') {
+  const normalizedFormat = String(format).toLowerCase();
+  if (!['mp3', 'mp4'].includes(normalizedFormat)) throw new UnsupportedError('Invalid TikTok format.');
+  const result = await tiktokDl(url);
+  if (!result.fallback) {
+    const wanted = result.formats[0];
+    if (!wanted) throw new NotFoundError('PRIVATE_OR_NOT_FOUND');
+    if (normalizedFormat === 'mp4') return { buffer: await getMedia(wanted.url), mimetype: 'video/mp4', extension: 'mp4' };
+  }
+  const data = await tikwmApi(url);
+  if (normalizedFormat === 'mp4') return { buffer: await getMedia(data.hdplay || data.play), mimetype: 'video/mp4', extension: 'mp4' };
+  if (data.music) return { buffer: await getMedia(data.music), mimetype: 'audio/mpeg', extension: 'mp3' };
+  const video = await getMedia(data.hdplay || data.play);
+  const dir = join(process.cwd(), 'cache', 'temp');
+  const base = join(dir, `tt-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`);
+  const input = `${base}.mp4`;
+  const output = `${base}.mp3`;
+  await mkdir(dir, { recursive: true });
+  try {
+    await writeFile(input, video);
+    await execFileAsync('ffmpeg', ['-y', '-i', input, '-vn', '-c:a', 'libmp3lame', '-q:a', '2', output], { maxBuffer: 32 * 1024 * 1024 });
+    const buffer = await readFile(output);
+    if (!validMediaBuffer(buffer)) throw new Error('TIKTOK_AUDIO_TOO_SMALL');
+    return { buffer, mimetype: 'audio/mpeg', extension: 'mp3' };
+  } finally {
+    await Promise.allSettled([unlink(input), unlink(output)]);
+  }
 }
 
 /** 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/' }); }
+export async function tiktokSave(url, dest = './tt.mp4', quality = 'best', options = {}) {
+  const result = await tiktokDl(url, options);
+  if (result.fallbackMethod === 'yt-dlp') {
+    const output = await ytDlpDownloadUrl(url, 'mp4', options);
+    await writeFile(dest, output.buffer);
+    return dest;
+  }
+  if (result.fallback) {
+    const output = await tiktokDownload(url, dest.toLowerCase().endsWith('.mp3') ? 'mp3' : 'mp4');
+    await writeFile(dest, output.buffer);
+    return dest;
+  }
+  return saveResult(result, dest, quality, { Referer: 'https://www.tiktok.com/' });
+}

package/src/platforms/twitter.js

@@ -5,12 +5,23 @@ import { NotFoundError, UnsupportedError } from '../errors.js';
 import { CREATOR } from '../constants.js';
 
 const idOf = url => new URL(url).pathname.match(/status\/(\d+)/)?.[1];
+async function fxtwitter(id, originalUrl) {
+  const response = await fetchWithRetry(`https://api.fxtwitter.com/status/${id}`, { headers: { 'User-Agent': 'Mozilla/5.0', Accept: 'application/json' } });
+  if (!response.ok) throw new Error(`FXTWITTER_HTTP_${response.status}`);
+  const json = await response.json();
+  const tweet = json.tweet || json;
+  const formats = sortFormats((tweet.media?.all || []).flatMap(item => item.videos || []).map(video => ({ tag: `${video.bitrate || 0}kbps`, quality: `${video.height || 720}p`, type: 'mp4', url: video.url, bitrate: video.bitrate })));
+  if (!formats.length) throw new NotFoundError('NO_X_VIDEO');
+  return { creator: CREATOR, platform: 'twitter', id, author: tweet.author?.screen_name ? `@${tweet.author.screen_name}` : undefined, title: tweet.text, originalUrl, formats, fallback: true };
+}
 
 /** 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' } });
+  let response;
+  try { 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' } }); }
+  catch { return fxtwitter(id, url); }
   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 })));
@@ -19,7 +30,9 @@ export async function twitterDl(url) {
     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();
+  if (!formats.length) {
+    try { return await fxtwitter(id, url); } catch { 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 };
 }
 

package/src/platforms/youtube.js

@@ -1,22 +1,49 @@
 import { fetchWithRetry, getVisitorData } from '../utils/fetcher.js';
 import { saveResult, sortFormats, qualityOf } from '../utils/media.js';
-import { NotFoundError, UnsupportedError } from '../errors.js';
+import { BotDetectedError, NotFoundError, UnsupportedError } from '../errors.js';
 import { CREATOR } from '../constants.js';
+import { fallbackInstallMessage, ytDlpDownload, ytDlpInfo } from '../utils/ytdlp.js';
 
 const KEY = 'AIzaSyA8eiZmM1FaDVjRy-df2KTyQ_vz_yYM39w';
+export const UA = 'Mozilla/5.0 (Linux; Android 15) AppleWebKit/537.36 Chrome/131 Mobile Safari/537.36';
+export const INNERTUBE_CONTEXT = { client: { clientName: 'WEB', clientVersion: '2.20260813.01.00', hl: 'es', gl: 'DO' } };
+export const INNERTUBE_URL = 'https://www.youtube.com/youtubei/v1/search?prettyPrint=false';
 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' }
+  { name: 'WEB', version: '2.20260813.01.00', ua: UA },
+  { name: 'IOS', version: '19.09.3', deviceModel: 'iPhone16,2', ua: 'com.google.ios.youtube/19.09.3 (iPhone16,2; U; iOS 17.2; en_US)' }
 ];
+export const YOUTUBE_MEDIA_HEADERS = {
+  'User-Agent': UA,
+  Accept: '*/*',
+  'Accept-Language': 'en-US,en;q=0.9',
+  Referer: 'https://www.youtube.com/',
+  Origin: 'https://www.youtube.com'
+};
+export const IOS_MEDIA_HEADERS = {
+  ...YOUTUBE_MEDIA_HEADERS,
+  'User-Agent': 'com.google.ios.youtube/19.09.3 (iPhone16,2; U17D201)'
+};
+function fallbackAllowed(error) { return error?.code === 'BOT_DETECTED' || /YOUTUBE_HTTP_4\d\d|403|automated|unusual traffic|NO_PLAYABLE|UNAVAILABLE/i.test(error?.message || ''); }
+function fromYtDlp(data, url, id) {
+  const streams = data.requested_formats || [];
+  const video = streams.find(item => item.vcodec && item.vcodec !== 'none' && item.url) || (data.vcodec && data.url ? data : null);
+  const audio = streams.find(item => item.acodec && item.acodec !== 'none' && item.url) || (data.acodec && data.url ? data : null);
+  const direct = video?.url || data.url;
+  const format = direct ? [{ tag: data.height ? `${data.height}p` : 'best', quality: data.height ? `${data.height}p` : 'best', type: 'mp4', hasAudio: Boolean(video?.acodec && video.acodec !== 'none') || Boolean(data.acodec && data.acodec !== 'none'), url: direct, height: data.height, bitrate: data.tbr }] : [];
+  return { creator: CREATOR, platform: 'youtube', id, client: 'YT-DLP', title: data.title, author: data.uploader || data.channel, thumbnail: data.thumbnail, originalUrl: url, formats: format, ...(video?.url && audio?.url && video.url !== audio.url ? { needsMux: true, videoUrl: video.url, audioUrl: audio.url } : {}), fallback: true };
+}
+async function ytDlpFallback(url, id, cause, options = {}) {
+  try { return fromYtDlp(await ytDlpInfo(id, options), url, id); }
+  catch (error) { throw new Error(`${fallbackInstallMessage()} (${cause?.message || error.message})`); }
+}
 
 /** 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 context = { ...INNERTUBE_CONTEXT, client: { ...INNERTUBE_CONTEXT.client, clientName: client.name, clientVersion: client.version, ...(client.deviceModel ? { deviceModel: client.deviceModel } : {}) }, ...(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();
@@ -30,33 +57,53 @@ export async function player(id) {
   for (const client of CLIENTS) {
     try {
       data = await innertubeRequest(id, client, visitorData);
-      if (data?.streamingData?.formats || data?.streamingData?.adaptiveFormats) return data;
+      if (data?.streamingData?.formats || data?.streamingData?.adaptiveFormats) {
+        data.__socialDlClient = client.name;
+        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');
+  if (!data?.streamingData) {
+    if (lastError?.code === 'BOT_DETECTED' || /403|automated|unusual traffic/i.test(lastError?.message || '')) throw new BotDetectedError();
+    throw lastError || new Error(data?.playabilityStatus?.reason || 'UNAVAILABLE');
+  }
   return data;
 }
 
 /** Download metadata and direct formats for a YouTube video. */
-export async function youtubeDl(url) {
+export async function youtubeDl(url, options = {}) {
   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');
+  let data;
+  try { data = await player(id); }
+  catch (error) {
+    if (!fallbackAllowed(error)) throw error;
+    return ytDlpFallback(url, id, error, options);
+  }
+  if (!data.streamingData) return ytDlpFallback(url, id, new NotFoundError('PRIVATE_OR_AGE_RESTRICTED'), options);
   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 })));
+  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 }))).sort((a, b) => Number(b.hasAudio) - Number(a.hasAudio));
   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 } : {}) };
+  return { creator: CREATOR, platform: 'youtube', id, client: data.__socialDlClient, 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 async function youtubeSave(url, dest = './yt.mp4', quality = 'best', options = {}) {
+  const result = await youtubeDl(url, options);
+  if (result.fallback) {
+    const { writeFile } = await import('node:fs/promises');
+    const output = await ytDlpDownload(result.id, 'mp4', options);
+    await writeFile(dest, output.buffer);
+    return dest;
+  }
+  return saveResult(result, dest, quality, { ...YOUTUBE_MEDIA_HEADERS, fallbackHeaders: IOS_MEDIA_HEADERS });
+}
 
 export { CLIENTS };

package/src/platforms/ytmp3.js

@@ -1,13 +1,24 @@
-import { player, videoId } from './youtube.js';
+import { IOS_MEDIA_HEADERS, player, videoId, YOUTUBE_MEDIA_HEADERS } from './youtube.js';
 import { saveResult, sortFormats } from '../utils/media.js';
 import { NotFoundError, UnsupportedError } from '../errors.js';
 import { CREATOR } from '../constants.js';
+import { fallbackInstallMessage, ytDlpDownload, ytDlpInfo } from '../utils/ytdlp.js';
 
 /** Download audio-only metadata from YouTube (m4a/opus, not transcoded MP3). */
-export async function youtubeMp3Dl(url) {
+export async function youtubeMp3Dl(url, options = {}) {
   const id = videoId(url);
   if (!id) throw new UnsupportedError('Invalid YouTube URL.');
-  const data = await player(id);
+  let data;
+  try { data = await player(id); }
+  catch (error) {
+    if (!error?.code && !/403|automated|unusual traffic|UNAVAILABLE/i.test(error?.message || '')) throw error;
+    try {
+      const fallback = await ytDlpInfo(id);
+      return { creator: CREATOR, platform: 'youtube', id, client: 'YT-DLP', title: fallback.title, author: fallback.uploader || fallback.channel, thumbnail: fallback.thumbnail, isAudioOnly: true, originalUrl: url, formats: [], fallback: true };
+    } catch (fallbackError) {
+      throw new Error(`${fallbackInstallMessage()} (${fallbackError.message})`);
+    }
+  }
   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';
@@ -15,8 +26,25 @@ export async function youtubeMp3Dl(url) {
     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 };
+  if (!formats.length) {
+    try {
+      const fallback = await ytDlpInfo(id);
+      return { creator: CREATOR, platform: 'youtube', id, client: 'YT-DLP', title: fallback.title, author: fallback.uploader || fallback.channel, thumbnail: fallback.thumbnail, isAudioOnly: true, originalUrl: url, formats: [], fallback: true };
+    } catch (fallbackError) {
+      throw new Error(`${fallbackInstallMessage()} (${fallbackError.message})`);
+    }
+  }
+  return { creator: CREATOR, platform: 'youtube', id, client: data.__socialDlClient, 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); }
+export async function youtubeMp3Save(url, dest = './audio.m4a', quality = 'best', options = {}) {
+  const result = await youtubeMp3Dl(url, options);
+  if (result.fallback) {
+    const { writeFile } = await import('node:fs/promises');
+    const output = await ytDlpDownload(result.id, 'mp3', options);
+    await writeFile(dest, output.buffer);
+    return dest;
+  }
+  return saveResult(result, dest, quality, { ...YOUTUBE_MEDIA_HEADERS, fallbackHeaders: IOS_MEDIA_HEADERS });
+}

package/src/utils/constants.js

@@ -0,0 +1,2 @@
+export const UA = 'Mozilla/5.0 (Linux; Android 15) AppleWebKit/537.36 Chrome/131 Mobile Safari/537.36';
+export const TMP = 'cache/temp';

package/src/utils/fetcher.js

@@ -1,9 +1,7 @@
 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'
+  'Mozilla/5.0 (Linux; Android 15) AppleWebKit/537.36 Chrome/131 Mobile Safari/537.36'
 ];
 
 /** Pick a browser-like user agent. */
@@ -16,7 +14,7 @@ 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 headers = { 'User-Agent': randomUserAgent(), Accept: '*/*', 'Accept-Language': 'en-US,en;q=0.9', ...(options.headers || {}) };
       const response = await fetch(input, { ...options, headers, redirect: options.redirect || 'follow' });
       if (response.status === 403) {
         const body = await response.clone().text();
@@ -56,8 +54,21 @@ export async function fetchText(input, options = {}) {
 
 /** 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 { fallbackHeaders, ...requestOptions } = options;
+  const attempts = [requestOptions.headers, fallbackHeaders].filter(Boolean);
+  let response;
+  let lastError;
+  for (let index = 0; index < Math.max(1, attempts.length); index += 1) {
+    try {
+      response = await fetchWithRetry(url, { ...requestOptions, headers: attempts[index] }, 0);
+      if (response.ok || response.status !== 403 || index === attempts.length - 1) break;
+    } catch (error) {
+      lastError = error;
+      if (index === attempts.length - 1) throw error;
+    }
+  }
+  if (lastError && !response) throw lastError;
+  if (!response?.ok) throw new Error(`DOWNLOAD_HTTP_${response?.status || 'FAILED'}`);
   const { writeFile } = await import('node:fs/promises');
   const data = Buffer.from(await response.arrayBuffer());
   await writeFile(dest, data);

package/src/utils/resolver.js

@@ -4,7 +4,7 @@ import { fetchWithRetry } from './fetcher.js';
 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 shortHosts = ['vm.tiktok.com', 'vt.tiktok.com', 'm.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' });

package/src/utils/ytdlp.js

@@ -0,0 +1,103 @@
+import { execFile } from 'node:child_process';
+import { mkdir, readFile, readdir, stat, unlink } from 'node:fs/promises';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+import { UA } from './constants.js';
+const execFileAsync = promisify(execFile);
+const BASE_ARGS = [
+  '--no-playlist', '--no-warnings', '--newline', '--no-part', '--no-continue',
+  '--retries', '3', '--fragment-retries', '3', '--file-access-retries', '3',
+  '--extractor-retries', '3', '--remote-components', 'ejs:github', '--js-runtimes', 'node',
+  '--user-agent', UA
+];
+
+/** Run a yt-dlp-compatible executable and return stdout/stderr. */
+export async function runYtDlp(args) {
+  const commands = [];
+  try {
+    const mod = await import('yt-dlp-exec');
+    const binary = mod.default?.default || mod.default || mod;
+    if (typeof binary === 'function') {
+      const result = await binary(args, { maxBuffer: 32 * 1024 * 1024, env: { ...process.env } });
+      return { stdout: String(result?.stdout || result || ''), stderr: String(result?.stderr || '') };
+    }
+  } catch {
+    // Optional dependency is intentionally allowed to be absent.
+  }
+  commands.push('yt-dlp', 'yt-dlp-exec');
+  let lastError;
+  for (const command of commands) {
+    try {
+      const result = await execFileAsync(command, args, { maxBuffer: 32 * 1024 * 1024, env: { ...process.env } });
+      return { stdout: String(result.stdout || ''), stderr: String(result.stderr || '') };
+    } catch (error) {
+      lastError = error;
+      if (!/ENOENT|not found|spawn/i.test(error?.code || error?.message || '')) throw error;
+    }
+  }
+  throw new Error(String(lastError?.stderr || lastError?.stdout || lastError?.message || 'yt-dlp is not installed').trim());
+}
+
+export function ytDlpUrl(id) { return `https://www.youtube.com/watch?v=${id}`; }
+export function cookieArgs(options = {}) {
+  const args = [];
+  if (options.cookiesPath) args.push('--cookies', options.cookiesPath);
+  if (options.cookiesFromBrowser) args.push('--cookies-from-browser', options.cookiesFromBrowser);
+  return args;
+}
+
+/** Get yt-dlp JSON metadata for a video. */
+export async function ytDlpInfo(id, options = {}) {
+  return ytDlpInfoUrl(ytDlpUrl(id), options);
+}
+export async function ytDlpInfoUrl(url, options = {}) {
+  const { stdout } = await runYtDlp(['--dump-json', '--no-download', '--no-playlist', '--skip-download', '--no-warnings', '--remote-components', 'ejs:github', '--js-runtimes', 'node', '--user-agent', UA, ...cookieArgs(options), url]);
+  const line = stdout.trim().split(/\r?\n/).find(Boolean);
+  if (!line) throw new Error('yt-dlp returned no video information.');
+  return JSON.parse(line);
+}
+
+function valid(file) {
+  return stat(file).then(info => info.isFile() && info.size > 4096).catch(() => false);
+}
+async function locate(base, dir) {
+  for (const name of await readdir(dir).catch(() => [])) {
+    if (name.startsWith(base) && await valid(join(dir, name))) return join(dir, name);
+  }
+  return null;
+}
+async function cleanup(base, dir) {
+  await Promise.all((await readdir(dir).catch(() => [])).filter(name => name.startsWith(base)).map(name => unlink(join(dir, name)).catch(() => {})));
+}
+
+/** Download a YouTube video or audio fallback into memory, then clean temp files. */
+export async function ytDlpDownload(id, format, options = {}) {
+  return ytDlpDownloadUrl(ytDlpUrl(id), format, options);
+}
+export async function ytDlpDownloadUrl(url, format, options = {}) {
+  if (!['mp3', 'mp4'].includes(format)) throw new Error('Invalid yt-dlp format.');
+  const dir = join(process.cwd(), 'cache', 'temp');
+  await mkdir(dir, { recursive: true });
+  const base = `yt-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+  const output = join(dir, `${base}.%(ext)s`);
+  const args = format === 'mp3'
+    ? [...BASE_ARGS, ...cookieArgs(options), '-f', 'bestaudio[ext=m4a]/bestaudio', '-x', '--audio-format', 'mp3', '--audio-quality', '0', '-o', output, url]
+    : [...BASE_ARGS, ...cookieArgs(options), '-f', 'bv*[ext=mp4][vcodec^=avc1][height<=720]+ba[ext=m4a][acodec^=mp4a]/b[ext=mp4][height<=720]', '--merge-output-format', 'mp4', '--remux-video', 'mp4', '-o', output, url];
+  let file;
+  try {
+    await runYtDlp(args);
+    file = await locate(base, dir);
+    if (!file) throw new Error(`yt-dlp did not produce a valid ${format.toUpperCase()} file.`);
+    const buffer = await readFile(file);
+    return format === 'mp3' ? { buffer, mimetype: 'audio/mpeg', extension: 'mp3' } : { buffer, mimetype: 'video/mp4', extension: 'mp4' };
+  } finally {
+    if (file) await unlink(file).catch(() => {});
+    await cleanup(base, dir);
+  }
+}
+
+export function fallbackInstallMessage() {
+  return 'YouTube blocked datacenter IP. Install fallback: npm i yt-dlp-exec or pip install yt-dlp --remote-components ejs:github';
+}
+
+export { BASE_ARGS, UA as YTDLP_USER_AGENT };

package/index.d.ts

@@ -1,31 +0,0 @@
-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;