social-dl 0.9.2 → 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.2",
+  "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",
@@ -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,8 +1,8 @@
-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';
@@ -11,6 +11,7 @@ export const UA = 'Mozilla/5.0 (Linux; Android 15) AppleWebKit/537.36 Chrome/131
 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; }
@@ -25,8 +26,8 @@ function fallbackError(error) { return error instanceof PrivateError || error in
 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]);
+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);
@@ -35,13 +36,33 @@ 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) {
+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, url]);
+    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;
@@ -51,9 +72,10 @@ async function instagramFallbackDownload(url, dest) {
   } finally { await cleanup(temp); }
 }
 
-async function instagramTier1(url, id) {
+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: IG_HEADERS });
+  let response = await fetchWithRetry(`${base}?__a=1&__d=dis`, { headers: requestHeaders });
   let formats = [];
   let item;
   if (response.ok) {
@@ -68,7 +90,7 @@ async function instagramTier1(url, id) {
     } 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);
@@ -79,21 +101,22 @@ async function instagramTier1(url, id) {
 }
 
 /** 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); }
+  try { return await instagramTier1(cleanUrl, id, options); }
   catch (error) {
     if (!fallbackError(error)) throw error;
-    try { return await instagramFallbackInfo(cleanUrl, id); }
+    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') {
-  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 = {}) {
+  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

@@ -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 { 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';
@@ -62,6 +63,10 @@ function normalizeTikwm(data, originalUrl, id) {
     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);
@@ -69,10 +74,11 @@ async function tiktokFallback(url, id) {
 }
 
 /** Download metadata and direct CDN formats for a TikTok video. */
-export async function tiktokDl(url) {
+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 { /* 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}`;
   try {
@@ -90,8 +96,8 @@ export async function tiktokDl(url) {
     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);
+    try { return normalizeYtDlp(await ytDlpInfoUrl(url, options), url, id); }
+    catch { return tiktokFallback(url, id); }
   }
 }
 
@@ -126,8 +132,13 @@ export async function tiktokDownload(url, format = 'mp4') {
 }
 
 /** 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');
     await writeFile(dest, output.buffer);

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;