social-dl 0.9.2 → 0.9.6

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.2",
+  "version": "0.9.6",
   "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",
@@ -25,7 +25,7 @@
     "dev": "node src/index.js"
   },
   "optionalDependencies": {
-    "yt-dlp-exec": "^1.2.0"
+    "yt-dlp-exec": "^1.0.2"
   },
   "keywords": [
     "youtube downloader",
@@ -57,10 +57,8 @@
     "node": ">=18.0.0"
   },
   "files": [
-    "src/",
     "bin/",
-    "index.d.ts",
-    "README.md",
-    "LICENSE"
+    "src/",
+    "README.md"
   ]
 }

package/src/index.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,7 +39,11 @@ 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';
-  if (detectPlatform(url) === 'youtube') return opts.audioOnly ? youtubeMp3Save(url, dest, quality) : youtubeSave(url, dest, quality);
+  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);
   const headers = detectPlatform(url) === 'youtube' ? { ...YOUTUBE_MEDIA_HEADERS, fallbackHeaders: IOS_MEDIA_HEADERS } : {};
   return saveResult(result, dest, quality, headers, opts.noWatermark === true);

package/src/platforms/facebook.js

@@ -2,7 +2,7 @@ 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 { runYtDlp } from '../utils/ytdlp.js';
+import { cookieArgs, runYtDlp } from '../utils/ytdlp.js';
 import { NotFoundError, PrivateError, UnsupportedError } from '../errors.js';
 import { CREATOR } from '../constants.js';
 
@@ -38,8 +38,8 @@ 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) {
-  const { stdout } = await runYtDlp(['--dump-json', '--no-download', '--no-playlist', '--skip-download', '--no-warnings', '--remote-components', 'ejs:github', '--js-runtimes', 'node', '--user-agent', UA, url]);
+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);
@@ -48,14 +48,14 @@ 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) { return normalizeFallback(await ytdlpInfo(url), url); }
+async function facebookFallbackInfo(url, options) { return normalizeFallback(await ytdlpInfo(url, options), url); }
 
-async function facebookFallbackDownload(url, dest) {
+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<=720]+ba[ext=m4a]/b[ext=mp4]/best', '--merge-output-format', 'mp4', '-o', temp, url]);
+    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;
@@ -82,19 +82,19 @@ async function facebookTier1(url) {
 }
 
 /** Download metadata for a Facebook video or reel. */
-export async function facebookDl(url) {
+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); }
+    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') {
-  const result = await facebookDl(url);
-  if (result.fallback) return facebookFallbackDownload(url, dest);
+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,59 +1,87 @@
-import { mkdir, rename, stat, unlink } from 'node:fs/promises';
+import { mkdir, readFile, rename, stat, unlink } from 'node:fs/promises';
 import { join } from 'node:path';
-import { fetchWithRetry } from '../utils/fetcher.js';
+import { fetchWithRetry, downloadTo } from '../utils/fetcher.js';
 import { saveResult, sortFormats } from '../utils/media.js';
-import { runYtDlp } from '../utils/ytdlp.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';
 
 export const UA = 'Mozilla/5.0 (Linux; Android 15) AppleWebKit/537.36 Chrome/131 Mobile Safari/537.36';
 export const TMP_DIR = 'cache/temp';
+export const IG_APP_ID = '936619743392459';
 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];
+const codeOf = url => new URL(url).pathname.match(/\/(?:reel|reels|p|tv)\/([A-Za-z0-9_-]+)/i)?.[1];
 
 export function isInstagramUrl(value) {
-  try { return /instagram\.com\/(?:reel|p|tv)\//i.test(new URL(value).href); } catch { return false; }
+  try {
+    const parsed = new URL(String(value).trim());
+    const host = parsed.hostname.toLowerCase().replace(/^www\./, '');
+    return (parsed.protocol === 'http:' || parsed.protocol === 'https:') && host.endsWith('instagram.com') && /\/(?:reel|reels|p|tv)\//i.test(parsed.pathname);
+  } catch { return false; }
 }
 export function cleanInstagramUrl(value) { const parsed = new URL(value); return `${parsed.origin}${parsed.pathname.endsWith('/') ? parsed.pathname : `${parsed.pathname}/`}`; }
+async function cookieText(options = {}) { const path = options.cookies || options.cookiesPath; if (!path) return ''; try { return await readFile(path, 'utf8'); } catch { return ''; } }
+function cookieHeader(text) {
+  if (!text) return '';
+  if (!text.includes('\t')) return text.match(/(?:^|\n)Cookie:\s*(.+)/i)?.[1]?.trim() || text.trim();
+  return text.split(/\r?\n/).filter(line => line && !line.startsWith('#')).map(line => line.split('\t')).filter(parts => parts.length >= 7 && parts[5] && parts[6]).map(parts => `${parts[5]}=${parts[6]}`).join('; ');
+}
+async function headersFor(options = {}) { const cookie = cookieHeader(await cookieText(options)); return cookie ? { ...IG_HEADERS, Cookie: cookie } : IG_HEADERS; }
 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 })));
+  const find = key => { const match = html.match(new RegExp(`"${key}"\\s*:\\s*"([^"]+)"`)); return match && unescapeJson(match[1]); };
+  const urls = [...html.matchAll(/"url"\s*:\s*"(https:[^\"]+)"/g)].map(match => unescapeJson(match[1])).filter(url => /(?:scontent|cdninstagram)/i.test(url) && /\.mp4(?:[?&]|$)/i.test(url));
+  return sortFormats([find('video_url') || urls[0], ...urls].filter(Boolean).map((url, index) => ({ tag: index ? 'SD' : 'HD', quality: index ? '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) {
-  const { stdout } = await runYtDlp(['--dump-json', '--no-download', '--no-playlist', '--skip-download', '--no-warnings', '--user-agent', UA, '--add-header', 'Referer:https://www.instagram.com/', '-f', 'best', 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 instagramFallbackInfo(url, id) { return normalizeFallback(await ytdlpInfo(url), url, id); }
-async function instagramFallbackDownload(url, dest) {
-  await mkdir(TMP_DIR, { recursive: true });
-  const base = `ig-${Date.now()}-${Math.random().toString(36).slice(2)}`;
-  const temp = outputFile(base);
+
+async function runInstagramYtDlp(url, options = {}) {
+  const dir = join(process.cwd(), TMP_DIR);
+  await mkdir(dir, { recursive: true });
+  const tmp = join(dir, `ig-${Date.now()}-${Math.random().toString(36).slice(2, 8)}.mp4`);
+  const cookie = await cookieText(options);
+  const cookies = cookie ? cookieArgs({ cookiesPath: options.cookies || options.cookiesPath }) : [];
+  const common = ['--no-playlist', '--remote-components', 'ejs:github', '--js-runtimes', 'node', '--no-warnings', '--user-agent', UA, '--add-header', 'Referer:https://www.instagram.com/'];
+  const attempts = [
+    [...common, '-f', 'best', '-o', tmp, ...cookies, url],
+    [...common, '-f', 'bv*[ext=mp4]+ba[ext=m4a]/b[ext=mp4]/best', '--merge-output-format', 'mp4', '-o', tmp, ...cookies, url]
+  ];
   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, 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); }
+    for (const args of attempts) {
+      try { await runYtDlp(args); } catch { /* retry with progressive video plus audio */ }
+      if (await validFile(tmp)) return await readFile(tmp);
+      await unlink(tmp).catch(() => {});
+    }
+    return null;
+  } finally { await unlink(tmp).catch(() => {}); }
+}
+
+async function getDirect(id, options = {}) {
+  const cookie = cookieHeader(await cookieText(options));
+  const headers = cookie ? { 'User-Agent': UA, 'X-IG-App-ID': IG_APP_ID, Accept: '*/*', Cookie: cookie } : { 'User-Agent': UA, 'X-IG-App-ID': IG_APP_ID, Accept: '*/*' };
+  for (const pageUrl of [`https://www.instagram.com/reel/${id}/`, `https://www.instagram.com/p/${id}/`, `https://www.instagram.com/tv/${id}/`]) {
+    try {
+      const response = await fetch(pageUrl, { headers, redirect: 'follow' });
+      if (!response.ok) continue;
+      const html = await response.text();
+      const match = html.match(/"video_url"\s*:\s*"(https:[^"]+)"/) || html.match(/"video_versions"\s*:\s*\[.*?\{"url"\s*:\s*"(https:[^"]+)"/s);
+      if (!match) continue;
+      const mediaUrl = unescapeJson(match[1]).replace(/\\u0026/g, '&').replace(/\\/g, '');
+      const media = await fetch(mediaUrl, { headers: { 'User-Agent': UA, Referer: 'https://www.instagram.com/' }, redirect: 'follow' });
+      if (!media.ok) continue;
+      const buffer = Buffer.from(await media.arrayBuffer());
+      if (buffer.length > 4096) return buffer;
+    } catch { /* try the next direct Instagram page */ }
+  }
+  return null;
 }
 
-async function instagramTier1(url, id) {
-  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: IG_HEADERS });
+async function instagramTier1(url, id, options = {}) {
+  const requestHeaders = await headersFor(options);
+  const type = url.match(/\/(reel|reels|p|tv)\//i)?.[1] || 'p';
+  const base = `https://www.instagram.com/${type}/${id}/`;
+  let response = await fetchWithRetry(`${base}?__a=1&__d=dis`, { headers: requestHeaders });
   let formats = [];
   let item;
   if (response.ok) {
@@ -62,13 +90,13 @@ async function instagramTier1(url, id) {
       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?.video_versions || []).map(video => ({ tag: index ? `${index + 1}` : 'HD', quality: `${video.height || 720}p`, type: 'mp4', url: video.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(`${base}embed/`, { headers: IG_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);
@@ -78,22 +106,24 @@ async function instagramTier1(url, id) {
   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) {
+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); }
-  catch (error) {
-    if (!fallbackError(error)) throw error;
-    try { return await instagramFallbackInfo(cleanUrl, id); }
-    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; }
-  }
+  try { return await instagramTier1(cleanUrl, id, options); }
+  catch (error) { if (!fallbackError(error)) throw error; return { creator: CREATOR, platform: 'instagram', id, originalUrl: cleanUrl, formats: [], fallback: true }; }
 }
 
-/** Save an Instagram video or image. */
-export async function instagramSave(url, dest = './ig.mp4', quality = 'best') {
-  const result = await instagramDl(url);
-  if (result.fallback) return instagramFallbackDownload(cleanInstagramUrl(url), dest);
-  return saveResult(result, dest, quality, IG_HEADERS);
+export async function instagramSave(url, dest = './ig.mp4', quality = 'best', options = {}) {
+  if (!isInstagramUrl(url)) throw new UnsupportedError('Invalid Instagram URL.');
+  const cleanUrl = cleanInstagramUrl(url);
+  const id = codeOf(cleanUrl);
+  const ytDlpBuffer = await runInstagramYtDlp(cleanUrl, options);
+  if (ytDlpBuffer) { const { writeFile } = await import('node:fs/promises'); await writeFile(dest, ytDlpBuffer); return dest; }
+  const directBuffer = await getDirect(id, options);
+  if (directBuffer) { const { writeFile } = await import('node:fs/promises'); await writeFile(dest, directBuffer); return dest; }
+  try {
+    const result = await instagramTier1(cleanUrl, id, options);
+    return saveResult(result, dest, quality, await headersFor(options));
+  } catch { throw new NotFoundError('NOT_FOUND: Instagram empty media - use --cookies ~/cookies.txt'); }
 }

package/src/platforms/tiktok.js

@@ -8,6 +8,7 @@ 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 { cookieArgs, runYtDlp, ytDlpDownloadUrl, ytDlpInfoUrl } from '../utils/ytdlp.js';
 
 const execFileAsync = promisify(execFile);
 const UA = 'Mozilla/5.0 (Linux; Android 15) AppleWebKit/537.36 Chrome/131 Mobile Safari/537.36';
@@ -15,64 +16,80 @@ 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; }
+  try {
+    const parsed = new URL(String(value).trim());
+    const host = parsed.hostname.toLowerCase().replace(/^www\./, '');
+    return (parsed.protocol === 'http:' || parsed.protocol === 'https:') && (host === 'tiktok.com' || host.endsWith('.tiktok.com'));
+  } catch { return false; }
 }
 
 export function validMediaBuffer(buffer) { return Buffer.isBuffer(buffer) && buffer.length > 4096; }
 
-async function tikwmApi(url) {
+async function resolveTikTokUrl(url) {
+  try {
+    const response = await fetch(url, { method: 'HEAD', redirect: 'follow', headers: { 'User-Agent': UA } });
+    return response.url || url;
+  } catch { return url; }
+}
+
+async function tikwmApi(inputUrl) {
+  const url = await resolveTikTokUrl(inputUrl);
   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()
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded', 'User-Agent': UA, Accept: '*/*', Referer: 'https://www.tikwm.com/', Origin: 'https://www.tikwm.com' },
+    body: new URLSearchParams({ url, hd: '1', full_data: '1' }).toString()
   });
-  if (!response.ok) throw new Error(`TIKWM_HTTP_${response.status}`);
-  const json = await response.json();
+  let json = response.ok ? await response.json() : null;
+  if (!json?.data) {
+    const retry = await fetchWithRetry(TIKWM_API, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/x-www-form-urlencoded', 'User-Agent': UA, Accept: '*/*', Referer: 'https://www.tikwm.com/' },
+      body: new URLSearchParams({ url, hd: '0' }).toString()
+    });
+    if (!retry.ok) throw new Error(`TIKWM_HTTP_${response.status || retry.status}`);
+    json = await retry.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;
+  const headersList = [
+    { Referer: 'https://www.tiktok.com/', Origin: 'https://www.tiktok.com' },
+    { Referer: 'https://www.tikwm.com/', Origin: 'https://www.tikwm.com' },
+    { Referer: 'https://m.tiktok.com/' }
+  ];
+  let lastError;
+  for (const extra of headersList) {
+    try {
+      const response = await fetchWithRetry(url, { headers: { 'User-Agent': UA, Accept: '*/*', ...extra } }, 0);
+      if (!response.ok) { lastError = new Error(`TIKTOK_MEDIA_HTTP_${response.status}`); continue; }
+      const buffer = Buffer.from(await response.arrayBuffer());
+      if (validMediaBuffer(buffer)) return buffer;
+      lastError = new Error('TIKTOK_MEDIA_TOO_SMALL');
+    } catch (error) { lastError = error; }
+  }
+  throw lastError || new Error('TIKTOK_MEDIA_FAILED');
 }
 
 function normalizeTikwm(data, originalUrl, id) {
   const author = data.author || {};
-  const video = data.hdplay || data.play;
+  const video = data.hdplay || data.play || data.wmplay;
   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
-  };
+  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 };
 }
-
-async function tiktokFallback(url, id) {
-  const data = await tikwmApi(url);
-  return normalizeTikwm(data, url, id);
+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' };
 }
 
-/** Download metadata and direct CDN formats for a TikTok video. */
-export async function tiktokDl(url) {
+async function tiktokFallback(url, id) { return normalizeTikwm(await tikwmApi(url), url, id); }
+
+export async function tiktokDl(url, options = {}) {
   if (!isTikTokUrl(url)) throw new UnsupportedError('Invalid TikTok URL.');
-  const resolved = await resolveShortUrl(url);
-  const id = resolved.match(/\/video\/(\d+)/)?.[1] || resolved.match(/\/v\/(\d+)/)?.[1] || new URL(resolved).pathname.split('/').filter(Boolean).pop();
+  let resolved = url;
+  try { resolved = await resolveShortUrl(url); } catch { resolved = await resolveTikTokUrl(url); }
+  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}`;
   try {
@@ -83,36 +100,38 @@ export async function tiktokDl(url) {
     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 }
-    ]);
+    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) {
-    if (!(error instanceof PrivateError) && !/PRIVATE|LOGIN|404|TIKTOK|NOT_FOUND/i.test(error?.message || '')) throw error;
-    return tiktokFallback(url, id);
+  } catch {
+    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') {
+export async function tiktokDownload(url, format = 'mp4', options = {}) {
   const normalizedFormat = String(format).toLowerCase();
   if (!['mp3', 'mp4'].includes(normalizedFormat)) throw new UnsupportedError('Invalid TikTok format.');
-  const result = await tiktokDl(url);
+  const result = await tiktokDl(url, options);
+  if (result.fallbackMethod === 'yt-dlp') return ytDlpDownloadUrl(url, 'mp4', options);
   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' };
+    if (normalizedFormat === 'mp4') {
+      try { return { buffer: await getMedia(wanted.url), mimetype: 'video/mp4', extension: 'mp4' }; }
+      catch { return ytDlpDownloadUrl(url, 'mp4', options); }
+    }
   }
   const data = await tikwmApi(url);
-  if (normalizedFormat === 'mp4') return { buffer: await getMedia(data.hdplay || data.play), mimetype: 'video/mp4', extension: 'mp4' };
+  if (normalizedFormat === 'mp4') {
+    try { return { buffer: await getMedia(data.hdplay || data.play || data.wmplay), mimetype: 'video/mp4', extension: 'mp4' }; }
+    catch { return ytDlpDownloadUrl(url, 'mp4', options); }
+  }
   if (data.music) return { buffer: await getMedia(data.music), mimetype: 'audio/mpeg', extension: 'mp3' };
-  const video = await getMedia(data.hdplay || data.play);
+  const video = await getMedia(data.hdplay || data.play || data.wmplay);
   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`;
+  const input = `${base}.mp4`, output = `${base}.mp3`;
   await mkdir(dir, { recursive: true });
   try {
     await writeFile(input, video);
@@ -120,16 +139,18 @@ export async function tiktokDownload(url, format = 'mp4') {
     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)]);
-  }
+  } finally { await Promise.allSettled([unlink(input), unlink(output)]); }
 }
 
-/** Save a TikTok video to disk. */
-export async function tiktokSave(url, dest = './tt.mp4', quality = 'best') {
-  const result = await tiktokDl(url);
+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');
+    const output = await tiktokDownload(url, dest.toLowerCase().endsWith('.mp3') ? 'mp3' : 'mp4', options);
     await writeFile(dest, output.buffer);
     return dest;
   }

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

@@ -33,8 +33,8 @@ function fromYtDlp(data, url, id) {
   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) {
-  try { return fromYtDlp(await ytDlpInfo(id), url, id); }
+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})`); }
 }
 
@@ -75,16 +75,16 @@ export async function player(id) {
 }
 
 /** 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.');
   let data;
   try { data = await player(id); }
   catch (error) {
     if (!fallbackAllowed(error)) throw error;
-    return ytDlpFallback(url, id, error);
+    return ytDlpFallback(url, id, error, options);
   }
-  if (!data.streamingData) return ytDlpFallback(url, id, new NotFoundError('PRIVATE_OR_AGE_RESTRICTED'));
+  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 }))).sort((a, b) => Number(b.hasAudio) - Number(a.hasAudio));
   if (!formats.length) throw new NotFoundError('NO_PLAYABLE_MP4');
@@ -95,11 +95,11 @@ export async function youtubeDl(url) {
 }
 
 /** Save a YouTube video to disk. */
-export async function youtubeSave(url, dest = './yt.mp4', quality = 'best') {
-  const result = await youtubeDl(url);
+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');
+    const output = await ytDlpDownload(result.id, 'mp4', options);
     await writeFile(dest, output.buffer);
     return dest;
   }

package/src/platforms/ytmp3.js

@@ -5,7 +5,7 @@ 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.');
   let data;
@@ -38,11 +38,11 @@ export async function youtubeMp3Dl(url) {
 }
 
 /** Save the best YouTube audio stream to disk. */
-export async function youtubeMp3Save(url, dest = './audio.m4a', quality = 'best') {
-  const result = await youtubeMp3Dl(url);
+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');
+    const output = await ytDlpDownload(result.id, 'mp3', options);
     await writeFile(dest, output.buffer);
     return dest;
   }

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/ytdlp.js

@@ -2,9 +2,8 @@ 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 UA = 'Mozilla/5.0 (Linux; Android 15) AppleWebKit/537.36 Chrome/131 Mobile Safari/537.36';
 const BASE_ARGS = [
   '--no-playlist', '--no-warnings', '--newline', '--no-part', '--no-continue',
   '--retries', '3', '--fragment-retries', '3', '--file-access-retries', '3',
@@ -40,10 +39,19 @@ export async function runYtDlp(args) {
 }
 
 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) {
-  const { stdout } = await runYtDlp(['--dump-json', '--no-download', '--no-playlist', '--skip-download', '--no-warnings', '--remote-components', 'ejs:github', '--js-runtimes', 'node', '--user-agent', UA, ytDlpUrl(id)]);
+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);
@@ -63,15 +71,18 @@ async function cleanup(base, dir) {
 }
 
 /** Download a YouTube video or audio fallback into memory, then clean temp files. */
-export async function ytDlpDownload(id, format) {
+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, '-f', 'bestaudio[ext=m4a]/bestaudio', '-x', '--audio-format', 'mp3', '--audio-quality', '0', '-o', output, ytDlpUrl(id)]
-    : [...BASE_ARGS, '-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, ytDlpUrl(id)];
+    ? [...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);

package/index.d.ts

@@ -1,32 +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; client?: 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 tiktokDownload(url: string, format?: 'mp3' | 'mp4'): Promise<{ buffer: Buffer; mimetype: string; extension: 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;