social-dl 0.9.0 → 0.9.2

package/index.d.ts

@@ -1,5 +1,5 @@
 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 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;
@@ -17,6 +17,7 @@ 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>;

package/package.json

@@ -1,11 +1,13 @@
 {
   "name": "social-dl",
-  "version": "0.9.0",
-  "license": "SEE LICENSE IN LICENSE ⚉",
+  "version": "0.9.2",
+  "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" },
+  "bin": {
+    "social-dl": "./bin/cli.js"
+  },
   "exports": {
     ".": "./src/index.js",
     "./facebook": "./src/platforms/facebook.js",
@@ -22,9 +24,27 @@
     "test": "node tests/test.js",
     "dev": "node src/index.js"
   },
-  "keywords": ["youtube downloader", "tiktok downloader", "facebook downloader", "instagram downloader", "twitter downloader", "pinterest downloader", "capcut downloader", "youtube mp3", "youtube to mp3", "reels downloader", "no api downloader", "direct cdn", "social-dl", "ytmp4", "ytmp3"],
+  "optionalDependencies": {
+    "yt-dlp-exec": "^1.2.0"
+  },
+  "keywords": [
+    "youtube downloader",
+    "tiktok downloader",
+    "facebook downloader",
+    "instagram downloader",
+    "twitter downloader",
+    "pinterest downloader",
+    "capcut downloader",
+    "youtube mp3",
+    "youtube to mp3",
+    "reels downloader",
+    "no api downloader",
+    "direct cdn",
+    "social-dl",
+    "ytmp4",
+    "ytmp3"
+  ],
   "author": "@plogme",
-  "license": "SEE LICENSE IN LICENSE",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/crysnovax/social-dl.git"

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';
@@ -39,8 +39,10 @@ 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 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 { 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) {
+  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]);
+  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) { return normalizeFallback(await ytdlpInfo(url), url); }
+
+async function facebookFallbackDownload(url, dest) {
+  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]);
+    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) {
+  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); }
+    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/' });
+  const result = await facebookDl(url);
+  if (result.fallback) return facebookFallbackDownload(url, dest);
+  return saveResult(result, dest, quality, FB_HEADERS);
 }

package/src/platforms/instagram.js

@@ -1,25 +1,59 @@
+import { mkdir, rename, stat, unlink } from 'node:fs/promises';
+import { join } from 'node:path';
 import { fetchWithRetry } from '../utils/fetcher.js';
 import { saveResult, sortFormats } from '../utils/media.js';
+import { 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];
 
+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) {
+  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);
+  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); }
+}
 
-/** 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) {
+  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 formats = [];
   let item;
   if (response.ok) {
@@ -34,7 +68,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: IG_HEADERS });
     const html = await response.text();
     if (response.url.includes('/accounts/login')) throw new PrivateError();
     formats = fromHtml(html);
@@ -44,5 +78,22 @@ 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) {
+  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; }
+  }
+}
+
 /** 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') {
+  const result = await instagramDl(url);
+  if (result.fallback) return instagramFallbackDownload(cleanInstagramUrl(url), dest);
+  return saveResult(result, dest, quality, IG_HEADERS);
+}

package/src/platforms/tiktok.js

@@ -1,3 +1,7 @@
+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';
@@ -5,29 +9,129 @@ import { extractJson, getPath, unescapeJson } from '../utils/parser.js';
 import { NotFoundError, PrivateError, UnsupportedError } from '../errors.js';
 import { CREATOR } from '../constants.js';
 
-const UA = 'Mozilla/5.0 (iPhone; CPU iPhone OS 16_6 like Mac OS X) AppleWebKit/605.1.15 Version/16.6 Mobile/15E148 Safari/604.1';
+const 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
+  };
+}
+
+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) {
+  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];
+  const id = resolved.match(/\/video\/(\d+)/)?.[1] || resolved.match(/\/v\/(\d+)/)?.[1] || new URL(resolved).pathname.split('/').filter(Boolean).pop();
   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) {
+    if (!(error instanceof PrivateError) && !/PRIVATE|LOGIN|404|TIKTOK|NOT_FOUND/i.test(error?.message || '')) throw error;
+    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') {
+  const result = await tiktokDl(url);
+  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/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) {
+  try { return fromYtDlp(await ytDlpInfo(id), 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,14 +57,20 @@ 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;
 }
 
@@ -45,18 +78,32 @@ export async function player(id) {
 export async function youtubeDl(url) {
   const id = videoId(url);
   if (!id) throw new UnsupportedError('Invalid YouTube URL.');
-  const data = await player(id);
-  if (!data.streamingData) throw new NotFoundError('PRIVATE_OR_AGE_RESTRICTED');
+  let data;
+  try { data = await player(id); }
+  catch (error) {
+    if (!fallbackAllowed(error)) throw error;
+    return ytDlpFallback(url, id, error);
+  }
+  if (!data.streamingData) return ytDlpFallback(url, id, new NotFoundError('PRIVATE_OR_AGE_RESTRICTED'));
   const all = [...(data.streamingData.formats || []), ...(data.streamingData.adaptiveFormats || [])];
-  const formats = sortFormats(all.filter(item => item.url && /^video\/mp4/.test(item.mimeType || '')).map(item => ({ tag: qualityOf(item, 'video'), quality: qualityOf(item, 'video'), type: 'mp4', hasAudio: !item.mimeType?.includes('video-only'), url: item.url, bitrate: item.bitrate, height: item.height })));
+  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') {
+  const result = await youtubeDl(url);
+  if (result.fallback) {
+    const { writeFile } = await import('node:fs/promises');
+    const output = await ytDlpDownload(result.id, 'mp4');
+    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) {
   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') {
+  const result = await youtubeMp3Dl(url);
+  if (result.fallback) {
+    const { writeFile } = await import('node:fs/promises');
+    const output = await ytDlpDownload(result.id, 'mp3');
+    await writeFile(dest, output.buffer);
+    return dest;
+  }
+  return saveResult(result, dest, quality, { ...YOUTUBE_MEDIA_HEADERS, fallbackHeaders: IOS_MEDIA_HEADERS });
+}

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,92 @@
+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';
+
+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',
+  '--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}`; }
+
+/** 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)]);
+  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) {
+  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)];
+  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 };