umedia 0.3.0 → 0.4.1

package/README.md

@@ -8,7 +8,7 @@
 
 No hosted API. No API keys. No rate limits. **No server bill.**
 
-YouTube · TikTok · Pinterest · SoundCloud · Dailymotion · Vimeo · Streamable · Twitch · Bluesky · Instagram · Reddit · X · Facebook · iTunes · 1800+ sites (via the optional yt-dlp tier)
+YouTube · TikTok · Pinterest · SoundCloud · Dailymotion · Vimeo · Streamable · Twitch · Bluesky · Instagram · Reddit · X · Facebook · Threads · Snapchat · Rumble · Tumblr · iTunes · 1800+ sites (via the optional yt-dlp tier)
 
 [![npm version](https://img.shields.io/npm/v/umedia?color=67e8f9&label=npm)](https://www.npmjs.com/package/umedia)
 [![node](https://img.shields.io/badge/node-%E2%89%A5%2018-brightgreen)](https://nodejs.org)
@@ -83,10 +83,14 @@ trailers, social posts with official embeds. `previewKind: "none"` beats a fake
 | **Streamable** | — | ✅ | ✅ | direct mp4 renditions |
 | **Twitch** | — | ✅ | ✅ | clips = direct CloudFront mp4s; VODs/livestreams via the yt-dlp tier |
 | **Bluesky** | — | ✅ | ✅ | public AppView API — full-size images + video playlists |
-| **Instagram** | — | ✅ best-effort | ✅ | public embeds (gated on some networks — the yt-dlp tier is the reliable path) |
-| **Reddit** | — | ✅ best-effort | ✅ | public JSON across reddit edges (datacenter IPs often 403 — typed honest error) |
-| **X** | — | ✅ best-effort | ✅ | public syndication (media login-gated on some networks — typed honest error) |
-| **Facebook · Threads · Snapchat · Rumble · Tumblr** | — | ✅ best-effort | ✅ best-effort | official Open Graph media on their share pages; often login-gated on datacenter IPs |
+| **Instagram** | — | ✅ | ✅ | oEmbed→mobile info API: photos, videos, full carousels |
+| **Reddit** | — | ✅ | ✅ | posts + galleries + video with its audio sidecar (DC IPs may 403 — typed honest error) |
+| **X** | — | ✅ | ✅ | syndication token + guest GraphQL: photos/videos/gifs at real bitrates |
+| **Facebook** | — | ✅ | ✅ | reels/watch/videos/shares/fb.watch via the web player JSON |
+| **Threads** | — | ✅ | ✅ | post SSR state + og media (Meta gates some networks — typed honest error) |
+| **Snapchat** | — | ✅ | ✅ | spotlight videos (direct sc-cdn mp4) + public stories/highlights — ALL snaps in order |
+| **Rumble** | — | ✅ best-effort | ✅ best-effort | embed API direct mp4s (site blocks datacenter IPs) |
+| **Tumblr** | — | ✅ | ✅ | mobile API: video/audio/photo posts + reblog trails, all in order |
 | **iTunes** | ✅ | — | ✅ previews | real 30s clips, rock solid |
 | **1800+ sites** | — | ✅ | ✅ | optional tier: `pip install yt-dlp` — labeled `source: "ytdlp"` |
 

package/lib/download.js

@@ -1,5 +1,5 @@
 import { createWriteStream } from "node:fs";
-import { mkdir, stat } from "node:fs/promises";
+import { mkdir, stat, rename } from "node:fs/promises";
 import { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
 import path from "node:path";
@@ -42,6 +42,7 @@ async function downloadHls(url, dest, onProgress) {
   let manifest = await getText(url);
   let base = url;
   let pickedHeight = null;
+  let fmp4 = false;
 
   if (manifest.includes("#EXT-X-STREAM-INF")) {
     const lines = manifest.split(/\r?\n/);
@@ -65,14 +66,21 @@ async function downloadHls(url, dest, onProgress) {
     manifest = await getText(base);
   }
   if (manifest.includes("#EXT-X-MAP")) {
-    throw new UMediaError(Codes.QUALITY_UNAVAILABLE,
-      "fMP4 HLS stream — single-file muxing needs the yt-dlp tier: downloadWithYtdlp()");
+    // fMP4: init segment + media fragments concat to a valid fragmented MP4
+    fmp4 = true;
   }
+  const mapUri = /#EXT-X-MAP:URI="([^"]+)"/.exec(manifest)?.[1] || null;
   const segs = manifest.split(/\r?\n/).filter((l) => l && !l.startsWith("#")).map((l) => new URL(l, base).href);
   if (!segs.length) throw new UMediaError(Codes.PROVIDER_ERROR, "HLS media playlist has no segments");
 
   await mkdir(path.dirname(dest), { recursive: true });
   const ws = createWriteStream(dest);
+  if (fmp4 && mapUri) {
+    const initRes = await fetch(new URL(mapUri, base).href, { headers: { "user-agent": UA }, redirect: "follow" });
+    if (!initRes.ok) throw new UMediaError(Codes.PROVIDER_ERROR, `HTTP ${initRes.status} fetching fMP4 init segment`);
+    const initBuf = Buffer.from(await initRes.arrayBuffer());
+    await new Promise((r, j) => ws.write(initBuf, (e) => (e ? j(e) : r())));
+  }
   let done = 0;
   for (const seg of segs) {
     const res = await fetch(seg, { headers: { "user-agent": UA }, redirect: "follow" });
@@ -84,7 +92,7 @@ async function downloadHls(url, dest, onProgress) {
   }
   await new Promise((r) => ws.end(r));
   const st = await stat(dest);
-  return { size: st.size, height: pickedHeight };
+  return { size: st.size, height: pickedHeight, ext: fmp4 ? "mp4" : "ts" };
 }
 
 /**
@@ -146,15 +154,22 @@ export async function download({ url, quality = "best", type = "video", dir = ".
       if (!selectedQuality) { selectedQuality = pick.selectedQuality; fallback = pick.fallback; }
 
       const isHls = /\.m3u8$/i.test(chosenUrl.split(/[?#]/)[0]);
-      const ext = isHls ? "ts" : ((chosenUrl.split("?")[0].match(/\.(mp4|webm|m4a|mp3|jpg|jpeg|png|gif|webp)$/) || [])[1]
+      let ext = isHls ? "ts" : ((chosenUrl.split("?")[0].match(/\.(mp4|webm|m4a|mp3|jpg|jpeg|png|gif|webp)$/) || [])[1]
         || (item.type === "image" ? "jpg" : item.type === "audio" ? "m4a" : "mp4"));
       const base = cleanName(resolved.title);
-      const name = `${String(item.index + 1).padStart(3, "0")} - ${base.toLowerCase().endsWith(`.${ext}`) ? base.slice(0, -(ext.length + 1)) : base}.${ext}`;
-      const dest = path.join(dir, name);
-      let size, hlsHeight = null;
+      let name = `${String(item.index + 1).padStart(3, "0")} - ${base.toLowerCase().endsWith(`.${ext}`) ? base.slice(0, -(ext.length + 1)) : base}.${ext}`;
+      let dest = path.join(dir, name);
+      let size, hlsHeight = null, hlsExt = null;
       if (isHls) {
-        ({ size, height: hlsHeight } = await downloadHls(chosenUrl, dest, onProgress));
+        ({ size, height: hlsHeight, ext: hlsExt } = await downloadHls(chosenUrl, dest, onProgress));
         if (hlsHeight) selectedQuality = `${hlsHeight}p`; // the REAL rendition downloaded
+        if (hlsExt && hlsExt !== ext) {
+          // fMP4 concat produces a real .mp4 — rename so the file never lies about its container
+          ext = hlsExt;
+          name = name.replace(/\.ts$/, `.${ext}`);
+          dest = path.join(dir, name);
+          await rename(`${dest.replace(new RegExp(`\\.${ext}$`), ".ts")}`, dest).catch(() => {});
+        }
       } else {
         size = await fetchToFile(chosenUrl, dest, onProgress);
       }

package/lib/providers/facebook.js

@@ -0,0 +1,126 @@
+import { fetchText, hostMatches } from "../util.js";
+import { Codes, UMediaError } from "../errors.js";
+
+/**
+ * Facebook — the platform's own player JSON embedded in the page (the exact
+ * fields Facebook's web player reads: browser_native_hd/sd_url,
+ * playable_url_quality_hd/playable_url). Reels, watch, videos, shares, fb.watch.
+ * Reference: yt-dlp facebook extractor + cobalt facebook service.
+ */
+export const name = "facebook";
+
+const HEADERS = {
+  accept: "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,*/*;q=0.8",
+  "accept-language": "en-US,en;q=0.5",
+  "sec-fetch-mode": "navigate",
+  "sec-fetch-site": "none",
+};
+
+export function canHandle(url) {
+  try {
+    return hostMatches(new URL(String(url)).hostname, ["facebook.com", "fb.watch", "fb.com"]);
+  } catch { return false; }
+}
+
+export function videoId(url) {
+  const u = String(url);
+  return (u.match(/\/(?:reel|videos|watch)\/(?:\?v=)?(\d+)/) || u.match(/[?&]v=(\d+)/) || u.match(/\/share\/[^/]+\/([\w-]+)/) || [])[1] || null;
+}
+
+function pickJsonStr(html, key) {
+  const m = html.match(new RegExp(`"${key}":("(?:[^"\\\\]|\\\\.)*")`));
+  if (!m) return null;
+  try { return JSON.parse(m[1]); } catch { return null; }
+}
+
+async function resolveShort(url, ctx) {
+  // fb.watch / facebook.com/share short links -> canonical page (Location or Link header)
+  const res = await fetch(url, { headers: HEADERS, redirect: "follow" }).catch(() => null);
+  if (!res) return url;
+  return res.url || url;
+}
+
+export async function resolve(url, ctx = {}) {
+  const attempt = { provider: name, status: "skipped" };
+  ctx.attempts?.push(attempt);
+  const t0 = Date.now();
+
+  let target = String(url);
+  if (/fb\.watch\//i.test(target) || /facebook\.com\/share\//i.test(target)) {
+    try { target = await resolveShort(target, ctx); } catch { /* use original */ }
+  }
+  // normalize watch/video.php/reel forms onto a fetchable page
+  const id = videoId(target) || videoId(url);
+  if (/\/watch\/?\?/i.test(target) && id) target = `https://www.facebook.com/watch/?v=${id}`;
+  if (/video\.php/i.test(target) && id) target = `https://www.facebook.com/video.php?v=${id}`;
+  if (/\/reel\//i.test(target) && id) target = `https://www.facebook.com/reel/${id}`;
+
+  let html;
+  try {
+    const r = await fetchText(target, { headers: HEADERS }, 20_000);
+    html = r.text;
+  } catch (e) {
+    attempt.status = "failed";
+    attempt.error = e.message;
+    throw new UMediaError(Codes.PROVIDER_UNAVAILABLE, `Facebook page not retrievable. ${e.message}`, { attempts: [attempt] });
+  }
+
+  const hd = pickJsonStr(html, "browser_native_hd_url") || pickJsonStr(html, "playable_url_quality_hd");
+  const sd = pickJsonStr(html, "browser_native_sd_url") || pickJsonStr(html, "playable_url");
+
+  const media = [];
+  const variants = [];
+  for (const [u, q] of [[hd, "hd"], [sd, "sd"]]) {
+    if (u && /^https?:/.test(u)) variants.push({ url: u, quality: q, height: null, width: null, hasAudio: true, hasVideo: true, mimeType: "video/mp4" });
+  }
+  if (variants.length) {
+    media.push({
+      type: "video", index: 0, url: variants[0].url,
+      thumbnail: pickJsonStr(html, "playable_url_thumbnail") || null,
+      mimeType: "video/mp4", width: null, height: null, duration: null, size: null,
+      quality: variants[0].quality, hasAudio: true, hasVideo: true, source: name, variants,
+    });
+  } else {
+    // og fallback (public photos / gated networks)
+    const og = (html.match(/property="og:(?:video|image)"[^>]+content="([^"]+)"/) || html.match(/content="([^"]+)"[^>]+property="og:(?:video|image)"/) || [])[1];
+    const isVideo = /property="og:video"/.test(html);
+    if (og && /^https?:/.test(og.replace(/&/g, "&"))) {
+      media.push({
+        type: isVideo ? "video" : "image", index: 0, url: og.replace(/&/g, "&"), thumbnail: og,
+        mimeType: isVideo ? "video/mp4" : "image/jpeg", width: null, height: null,
+        duration: null, size: null, quality: null,
+        hasAudio: isVideo, hasVideo: isVideo, source: name, variants: [],
+      });
+    }
+  }
+
+  if (!media.length) {
+    attempt.status = "failed";
+    attempt.error = "no player JSON or og media in the page (login-gated, private, or removed)";
+    throw new UMediaError(Codes.MEDIA_NOT_FOUND,
+      `Facebook exposes no media for this URL (${attempt.error}) — public videos work from most networks; the yt-dlp tier covers gated ones.`, { attempts: [attempt] });
+  }
+
+  const title = (html.match(/"title":"((?:[^"\\]|\\.)*)"/) || html.match(/<title[^>]*>([^<]*)/i) || [])[1] || null;
+  attempt.status = "success";
+  attempt.latencyMs = Date.now() - t0;
+  return {
+    result: {
+      sourceUrl: url,
+      platform: name,
+      title: title ? title.replace(/\\u0025/g, "%").slice(0, 200) : null,
+      author: null,
+      thumbnail: media[0].thumbnail,
+      itemCount: media.length,
+      counts: { images: media.filter((m) => m.type === "image").length, videos: media.filter((m) => m.type === "video").length, audios: 0, other: 0 },
+      truncated: false,
+      media,
+      streamUrlsAvailable: true,
+    },
+    engine: { attempts: ctx.attempts || [attempt], finalProvider: name, totalLatencyMs: Date.now() - t0 },
+  };
+}
+
+export async function search() {
+  return [];
+}

package/lib/providers/instagram.js

@@ -1,67 +1,189 @@
-import { fetchText, hostMatches } from "../util.js";
+import { fetchJson, fetchText, hostMatches } from "../util.js";
 import { Codes, UMediaError } from "../errors.js";
 
-/** Instagram — public embed page parse. Best-effort: IG gates aggressively; failures are typed. */
+/**
+ * Instagram — the proven logged-out chain (yt-dlp instagram + cobalt instagram):
+ *  1. i.instagram.com oEmbed -> numeric media_id
+ *  2. i.instagram.com mobile media info API -> ALL carousel items, best video/photo
+ *  3. the /embed/captioned/ page's embedded contextJSON
+ *  4. official og: meta on the share page
+ */
 export const name = "instagram";
 
+const MOBILE_HEADERS = {
+  "x-ig-app-locale": "en_US",
+  "x-ig-device-locale": "en_US",
+  "x-ig-mapped-locale": "en_US",
+  "user-agent": "Instagram 275.0.0.27.98 Android (33/13; 280dpi; 720x1423; Xiaomi; Redmi 7; onclite; qcom; en_US; 458229237)",
+  "accept-language": "en-US",
+  "x-fb-http-engine": "Liger",
+  "x-fb-client-ip": "True",
+  "x-fb-server-cluster": "True",
+};
+
+const EMBED_HEADERS = {
+  accept: "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8",
+  "accept-language": "en-GB,en;q=0.9",
+  "sec-fetch-dest": "document",
+  "sec-fetch-mode": "navigate",
+  "sec-fetch-site": "none",
+  "upgrade-insecure-requests": "1",
+  "user-agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0 Safari/537.36",
+};
+
 export function canHandle(url) {
   try {
-    return hostMatches(new URL(String(url)).hostname, ["instagram.com", "instagr.am"]) && /\/(p|reel|tv)\//i.test(String(url));
+    return hostMatches(new URL(String(url)).hostname, ["instagram.com", "instagr.am"]) && /\/(p|reel|tv)\/[\w-]+/i.test(String(url));
   } catch { return false; }
 }
 
+export function shortcode(url) {
+  const m = String(url).match(/\/(?:p|reel|tv)\/([\w-]+)/);
+  return m ? m[1] : null;
+}
+
+function pushMobileItem(item, media) {
+  const isVideo = Array.isArray(item.video_versions) && item.video_versions.length > 0;
+  const img = item.image_versions2?.candidates?.[0]?.url || null;
+  if (isVideo) {
+    const best = item.video_versions.reduce((a, b) => (a.width * a.height < b.width * b.height ? b : a), item.video_versions[0]);
+    media.push({
+      type: "video", index: media.length, url: best.url, thumbnail: img,
+      mimeType: "video/mp4", width: best.width ?? null, height: best.height ?? null,
+      duration: item.video_duration ? Math.round(item.video_duration) : null, size: null,
+      quality: best.height ? `${best.height}p` : null,
+      hasAudio: true, hasVideo: true, source: name,
+      variants: item.video_versions.map((v) => ({
+        height: v.height ?? null, width: v.width ?? null, url: v.url,
+        hasAudio: true, hasVideo: true, quality: v.height ? `${v.height}p` : null, mimeType: "video/mp4",
+      })),
+    });
+  } else if (img) {
+    media.push({
+      type: "image", index: media.length, url: img, thumbnail: img,
+      mimeType: "image/jpeg", width: item.original_width ?? null, height: item.original_height ?? null,
+      duration: null, size: null, quality: "original",
+      hasAudio: false, hasVideo: false, source: name,
+      variants: (item.image_versions2?.candidates || []).map((c) => ({
+        height: c.height ?? null, width: c.width ?? null, url: c.url,
+        hasAudio: false, hasVideo: false, quality: c.height ? `${c.height}p` : null, mimeType: "image/jpeg",
+      })),
+    });
+  }
+}
+
 export async function resolve(url, ctx = {}) {
   const attempt = { provider: name, status: "skipped" };
   ctx.attempts?.push(attempt);
   const t0 = Date.now();
-  const clean = String(url).split("?")[0].replace(/\/$/, "");
+  const sc = shortcode(url);
+  if (!sc) {
+    attempt.status = "failed";
+    throw new UMediaError(Codes.INVALID_URL, "Not an Instagram post URL (expected instagram.com/p|reel|tv/{code})", { attempts: [attempt] });
+  }
+
+  const media = [];
+  let title = null;
+  let author = null;
+
+  // 1+2) oEmbed -> mobile media info (the complete path: carousels included)
   try {
-    const { status, text } = await fetchText(`${clean}/embed/captioned/`, {}, 15_000);
-    if (status !== 200) throw new UMediaError(Codes.PROVIDER_ERROR, `Instagram embed returned HTTP ${status}`);
-    const media = [];
-    // video first (reels), then display images
-    for (const m of text.matchAll(/"video_url":"(https:[^"]+?)"/g)) {
-      const u = m[1].replace(/\\u0026/g, "&").replace(/\\\//g, "/");
-      media.push({
-        type: "video", index: media.length, url: u, thumbnail: null, mimeType: "video/mp4",
-        width: null, height: null, duration: null, size: null, quality: null,
-        hasAudio: true, hasVideo: true, source: name, variants: [],
-      });
-      break; // first video per embed page
+    const o = await fetchJson(`https://i.instagram.com/api/v1/oembed/?url=${encodeURIComponent(`https://www.instagram.com/p/${sc}/`)}`,
+      { headers: MOBILE_HEADERS }, 15_000);
+    if (o?.media_id) {
+      author = o.author_name || null;
+      title = o.title || null;
+      const info = await fetchJson(`https://i.instagram.com/api/v1/media/${o.media_id}/info/`,
+        { headers: MOBILE_HEADERS }, 15_000);
+      const item = info?.items?.[0];
+      if (item) {
+        if (Array.isArray(item.carousel_media) && item.carousel_media.length) {
+          // ALL slides, in post order — never truncate
+          item.carousel_media.forEach((c) => pushMobileItem(c, media));
+        } else {
+          pushMobileItem(item, media);
+        }
+        title = title || item.caption?.text?.slice(0, 200) || null;
+      }
     }
-    if (!media.length) {
-      for (const m of text.matchAll(/"display_url":"(https:[^"]+?)"/g)) {
-        const u = m[1].replace(/\\u0026/g, "&").replace(/\\\//g, "/");
-        if (!media.some((x) => x.url === u)) media.push({
-          type: "image", index: media.length, url: u, thumbnail: u, mimeType: "image/jpeg",
-          width: null, height: null, duration: null, size: null, quality: null,
-          hasAudio: false, hasVideo: false, source: name, variants: [],
-        });
+  } catch (e) {
+    attempt.note = `mobile: ${String(e.message).slice(0, 60)}`;
+  }
+
+  // 3) embed page's embedded contextJSON
+  if (!media.length) {
+    try {
+      const r = await fetchText(`https://www.instagram.com/p/${sc}/embed/captioned/`, { headers: EMBED_HEADERS }, 18_000);
+      const init = r.text.match(/"init",\[\],\[(.*?)\]\],/);
+      if (init) {
+        const arr = JSON.parse(`[${init[1]}]`);
+        const ctxJson = arr.map((x) => x?.contextJSON).find(Boolean);
+        if (ctxJson) {
+          const d = JSON.parse(ctxJson);
+          const m = d?.media || d;
+          const isVideo = Boolean(m.video_url);
+          const u = m.video_url || m.display_url;
+          if (u) media.push({
+            type: isVideo ? "video" : "image", index: 0, url: u, thumbnail: m.display_url || u,
+            mimeType: isVideo ? "video/mp4" : "image/jpeg", width: null, height: null,
+            duration: null, size: null, quality: null,
+            hasAudio: isVideo, hasVideo: isVideo, source: name, variants: [],
+          });
+          title = title || m.caption?.text?.slice(0, 200) || null;
+          author = author || m.owner?.username || null;
+        }
       }
+    } catch (e) {
+      attempt.note = `${attempt.note ? attempt.note + " · " : ""}embed: ${String(e.message).slice(0, 60)}`;
     }
-    if (!media.length) {
-      throw new UMediaError(Codes.MEDIA_NOT_FOUND, "No media exposed in the public embed (post may be private)");
+  }
+
+  // 4) og: meta (official share tags)
+  if (!media.length) {
+    try {
+      const r = await fetchText(`https://www.instagram.com/p/${sc}/`, { headers: EMBED_HEADERS }, 18_000);
+      const ogv = (r.text.match(/property="og:video"[^>]+content="([^"]+)"/) || r.text.match(/content="([^"]+)"[^>]+property="og:video"/) || [])[1];
+      const ogi = (r.text.match(/property="og:image"[^>]+content="([^"]+)"/) || r.text.match(/content="([^"]+)"[^>]+property="og:image"/) || [])[1];
+      const u = ogv || ogi;
+      if (u) media.push({
+        type: ogv ? "video" : "image", index: 0, url: u.replace(/&amp;/g, "&"), thumbnail: (ogi || u).replace(/&amp;/g, "&"),
+        mimeType: ogv ? "video/mp4" : "image/jpeg", width: null, height: null,
+        duration: null, size: null, quality: null,
+        hasAudio: Boolean(ogv), hasVideo: Boolean(ogv), source: name, variants: [],
+      });
+    } catch (e) {
+      attempt.note = `${attempt.note ? attempt.note + " · " : ""}og: ${String(e.message).slice(0, 60)}`;
     }
-    attempt.status = "success";
-    attempt.latencyMs = Date.now() - t0;
-    return {
-      result: {
-        sourceUrl: url, platform: "instagram", title: null, author: null,
-        thumbnail: media[0].thumbnail, itemCount: media.length,
-        counts: {
-          images: media.filter((m) => m.type === "image").length,
-          videos: media.filter((m) => m.type === "video").length, audios: 0, other: 0,
-        },
-        truncated: false, media,
-      },
-      engine: { attempts: ctx.attempts || [attempt], finalProvider: name, totalLatencyMs: Date.now() - t0 },
-    };
-  } catch (e) {
+  }
+
+  if (!media.length) {
     attempt.status = "failed";
-    attempt.error = e.message;
-    if (e instanceof UMediaError) throw e;
-    throw new UMediaError(Codes.PROVIDER_UNAVAILABLE, `Instagram unavailable: ${e.message}`, { attempts: [attempt] });
+    attempt.error = attempt.note || "no media exposed (private, removed, or login-gated)";
+    throw new UMediaError(Codes.MEDIA_NOT_FOUND,
+      `Instagram exposes no media for this URL (${attempt.error}) — the yt-dlp tier covers gated posts with cookies.`, { attempts: [attempt] });
   }
+
+  attempt.status = "success";
+  attempt.latencyMs = Date.now() - t0;
+  return {
+    result: {
+      sourceUrl: url,
+      platform: name,
+      title: title || null,
+      author: author || null,
+      thumbnail: media[0].thumbnail,
+      itemCount: media.length,
+      counts: {
+        images: media.filter((m) => m.type === "image").length,
+        videos: media.filter((m) => m.type === "video").length,
+        audios: 0, other: 0,
+      },
+      truncated: false,
+      media,
+      streamUrlsAvailable: true,
+    },
+    engine: { attempts: ctx.attempts || [attempt], finalProvider: name, totalLatencyMs: Date.now() - t0 },
+  };
 }
 
 export async function search() {

package/lib/providers/reddit.js

@@ -14,7 +14,15 @@ export async function resolve(url, ctx = {}) {
   const attempt = { provider: name, status: "skipped" };
   ctx.attempts?.push(attempt);
   const t0 = Date.now();
-  const base = String(url).split("?")[0].replace(/\/$/, "");
+  let base = String(url).split("?")[0].replace(/\/$/, "");
+
+  // short links: /video/{id} and /r/{sub}/s/{shareId} redirect to the full permalink
+  if (/reddit\.com\/video\/[\w-]+/i.test(base) || /\/s\/[\w-]+/i.test(base)) {
+    try {
+      const res = await fetch(base, { headers: { "user-agent": UA + " umedia-sdk" }, redirect: "follow" });
+      if (res.url && /comments\//.test(res.url)) base = res.url.split("?")[0].replace(/\/$/, "");
+    } catch { /* keep original */ }
+  }
 
   // Reddit edge-gates datacenter IPs per-host — try the alternate public edges, honestly.
   async function fetchRedditJson() {
@@ -45,11 +53,29 @@ export async function resolve(url, ctx = {}) {
     });
 
     const rv = post.secure_media?.reddit_video || post.media?.reddit_video;
-    if (rv) add("video", rv.fallback_url, {
-      width: rv.width, height: rv.height, duration: rv.duration,
-      quality: rv.height ? `${rv.height}p` : null, mimeType: "video/mp4",
-      thumbnail: post.preview?.images?.[0]?.source?.url?.replace(/&/g, "&") ?? null,
-    });
+    if (rv) {
+      add("video", rv.fallback_url, {
+        width: rv.width, height: rv.height, duration: rv.duration,
+        quality: rv.height ? `${rv.height}p` : null, mimeType: "video/mp4",
+        thumbnail: post.preview?.images?.[0]?.source?.url?.replace(/&/g, "&") ?? null,
+      });
+      // reddit serves audio as a SIDE CAR file — fetch it too so downloads are complete
+      const vidUrl = rv.fallback_url.split("?")[0];
+      const audioCandidates = [
+        vidUrl.includes(".mp4") ? `${vidUrl.split("_")[0]}_audio.mp4` : null,
+        vidUrl.replace(/DASH[^/]*\.mp4/, "DASH_audio"),
+        `${vidUrl.split("_")[0]}_AUDIO_128.mp4`,
+      ].filter(Boolean);
+      for (const au of audioCandidates) {
+        try {
+          const head = await fetch(au, { method: "HEAD", headers: { "user-agent": UA + " umedia-sdk" }, redirect: "follow" });
+          if (head.ok && Number(head.headers.get("content-length") || 1) > 0) {
+            add("audio", au, { mimeType: "audio/mp4", quality: "audio" });
+            break;
+          }
+        } catch { /* try the next candidate */ }
+      }
+    }
 
     if (post.gallery_data?.items && post.media_metadata) {
       for (const it of post.gallery_data.items) {

package/lib/providers/rumble.js

@@ -0,0 +1,110 @@
+import { fetchJson, hostMatches } from "../util.js";
+import { Codes, UMediaError } from "../errors.js";
+
+/**
+ * Rumble — the public embed JSON (rumble.com/embedJS/u3/?request=video&ver=2&v={id}),
+ * the same route Rumble's own embed player calls: direct mp4 renditions with real
+ * w/h/bitrate + HLS + audio. Reference: yt-dlp rumble extractor.
+ */
+export const name = "rumble";
+
+export function canHandle(url) {
+  try {
+    return hostMatches(new URL(String(url)).hostname, ["rumble.com"]);
+  } catch { return false; }
+}
+
+export function videoId(url) {
+  const u = String(url);
+  // /embed/{id} | /v{id}-{slug}.html | /v{id} | /{id}.html (embed ids)
+  const m = u.match(/\/embed\/(?:[\w-]+\.)?([\w-]+)/) || u.match(/\/(v[\w]+)[-.]/) || u.match(/\/(v[\w]+)\/?$/) || u.match(/\/([\w]+)\.html/);
+  return m ? m[1] : null;
+}
+
+export async function resolve(url, ctx = {}) {
+  const attempt = { provider: name, status: "skipped" };
+  ctx.attempts?.push(attempt);
+  const t0 = Date.now();
+
+  const id = videoId(url);
+  if (!id) {
+    attempt.status = "failed";
+    throw new UMediaError(Codes.INVALID_URL, "Not a Rumble video URL", { attempts: [attempt] });
+  }
+
+  let v;
+  try {
+    v = await fetchJson(`https://rumble.com/embedJS/u3/?request=video&ver=2&v=${encodeURIComponent(id)}`, {}, 15_000);
+  } catch (e) {
+    attempt.status = "failed";
+    attempt.error = e.message;
+    throw new UMediaError(Codes.PROVIDER_UNAVAILABLE, `Rumble embed API unavailable. ${e.message}`, { attempts: [attempt] });
+  }
+  if (v?.sys?.msg || !v?.ua) {
+    attempt.status = "failed";
+    attempt.error = v?.sys?.msg || "video not found";
+    throw new UMediaError(Codes.MEDIA_NOT_FOUND, `Rumble: ${attempt.error}`, { attempts: [attempt] });
+  }
+
+  // ua = { mp4: {...height-keyed or list}, hls: [...], audio: [...], timeline: [...] }
+  const variants = [];
+  const addList = (type, list, heightKeyed) => {
+    const entries = heightKeyed ? Object.entries(list).map(([h, info]) => [h, info]) : (list || []).map((info) => [info?.meta?.h, info]);
+    for (const [h, info] of entries) {
+      if (!info?.url) continue;
+      if (type === "tar" || type === "timeline") continue;
+      const isHls = type === "hls" || /\.m3u8/.test(info.url);
+      variants.push({
+        height: parseInt(h ?? info?.meta?.h, 10) || info?.meta?.h || null,
+        width: info?.meta?.w ?? null,
+        url: info.url,
+        hasAudio: type !== "audio", hasVideo: type !== "audio",
+        quality: h ? `${h}p` : (type === "audio" ? "audio" : type),
+        mimeType: type === "audio" ? "audio/mpeg" : isHls ? "application/x-mpegURL" : "video/mp4",
+        bitrate: info?.meta?.bitrate ?? null,
+      });
+    }
+  };
+  for (const [type, formatInfo] of Object.entries(v.ua || {})) {
+    if (type === "tar") continue;
+    addList(type, formatInfo, !Array.isArray(formatInfo));
+  }
+
+  const progressive = variants.filter((x) => /mp4/.test(x.mimeType || "") || (!/m3u8|mpegurl/i.test(x.url + (x.mimeType || "")) && x.hasVideo));
+  const chosen = progressive.sort((a, b) => (b.height || 0) - (a.height || 0))[0] || variants[0];
+  if (!chosen) {
+    attempt.status = "failed";
+    throw new UMediaError(Codes.MEDIA_NOT_FOUND, "Rumble: no downloadable renditions", { attempts: [attempt] });
+  }
+
+  attempt.status = "success";
+  attempt.latencyMs = Date.now() - t0;
+  return {
+    result: {
+      sourceUrl: url,
+      platform: name,
+      title: v.title || null,
+      author: v.author?.name || null,
+      thumbnail: Array.isArray(v.t) ? v.t[v.t.length - 1]?.i : v.t?.i || null,
+      itemCount: 1,
+      counts: { images: 0, videos: 1, audios: 0, other: 0 },
+      truncated: false,
+      media: [{
+        type: chosen.hasVideo ? "video" : "audio", index: 0, url: chosen.url,
+        thumbnail: Array.isArray(v.t) ? v.t[v.t.length - 1]?.i : null,
+        mimeType: chosen.mimeType,
+        width: chosen.width ?? null, height: chosen.height ?? null,
+        duration: v.duration ?? null, size: null,
+        quality: chosen.quality,
+        hasAudio: true, hasVideo: chosen.hasVideo !== false, source: name,
+        variants: variants.filter((x) => x.url),
+      }],
+      streamUrlsAvailable: true,
+    },
+    engine: { attempts: ctx.attempts || [attempt], finalProvider: name, totalLatencyMs: Date.now() - t0 },
+  };
+}
+
+export async function search() {
+  return [];
+}