umedia 0.1.2 → 0.2.1

package/lib/providers/youtube.js

@@ -0,0 +1,146 @@
+import { parseDuration, hostMatches } from "../util.js";
+import { Codes, UMediaError } from "../errors.js";
+
+/** YouTube via InnerTube (youtubei.js) — search + metadata always; stream URLs when the network allows. */
+export const name = "youtube";
+
+let _engine = null;
+async function engine() {
+  if (!_engine) {
+    const { Innertube } = await import("youtubei.js");
+    _engine = await Innertube.create({ retrieve_player: true });
+  }
+  return _engine;
+}
+
+export function canHandle(url) {
+  try {
+    return hostMatches(new URL(String(url)).hostname, ["youtube.com", "youtu.be", "youtube-nocookie.com"]);
+  } catch { return false; }
+}
+
+export function videoId(url) {
+  const u = new URL(String(url));
+  if (u.hostname.includes("youtu.be")) return u.pathname.slice(1).split("/")[0];
+  if (u.searchParams.get("v")) return u.searchParams.get("v");
+  const m = u.pathname.match(/\/(shorts|embed|live|v)\/([^/?#]+)/);
+  return m ? m[2] : null;
+}
+
+export async function search({ q, type = "video", limit = 12 }, ctx = {}) {
+  const attempt = { provider: name, status: "skipped" };
+  ctx.attempts?.push(attempt);
+  const t0 = Date.now();
+  try {
+    const e = await engine();
+    let query = q;
+    if (type === "movie") query = `${q} trailer`;
+    const res = await e.search(query, { type: "video" });
+    attempt.status = "success";
+    attempt.latencyMs = Date.now() - t0;
+    return (res.videos || []).slice(0, limit).map((v) => {
+      const id = v.id;
+      return {
+        id,
+        title: v.title?.text ?? String(v.title ?? ""),
+        author: v.author?.name ?? v.author ?? null,
+        pageUrl: `https://www.youtube.com/watch?v=${id}`,
+        thumbnail: v.thumbnails?.[v.thumbnails.length - 1]?.url ?? null,
+        duration: parseDuration(v.duration?.text) ?? v.duration?.seconds ?? null,
+        mediaType: type === "music" ? "music" : v.type === "short" ? "short_video" : "video",
+        source: name,
+        previewUrl: `https://www.youtube.com/embed/${id}`,
+        previewKind: type === "movie" ? "trailer" : "embed",
+      };
+    });
+  } catch (e) {
+    attempt.status = "failed";
+    attempt.error = e.message;
+    return [];
+  }
+}
+
+function fmtToVariant(f, url) {
+  return {
+    quality: f.quality_label || (f.height ? `${f.height}p` : f.quality || "unknown"),
+    width: f.width ?? null,
+    height: f.height ?? null,
+    url: url ?? null,
+    mimeType: (f.mime_type || "").split(";")[0] || null,
+    bitrateKbps: f.bitrate ? Math.round(f.bitrate / 1000) : null,
+    hasAudio: Boolean(f.has_audio),
+    hasVideo: Boolean(f.has_video),
+  };
+}
+
+export async function resolve(url, ctx = {}) {
+  const attempt = { provider: name, status: "skipped" };
+  ctx.attempts?.push(attempt);
+  const id = videoId(url);
+  if (!id) throw new UMediaError(Codes.INVALID_URL, `Not a recognizable YouTube URL: ${url}`);
+  const t0 = Date.now();
+  try {
+    const e = await engine();
+    const info = await e.getInfo(id);
+    attempt.status = "success";
+    attempt.latencyMs = Date.now() - t0;
+    const b = info.basic_info || {};
+    const all = [...(info.streaming_data?.formats || []), ...(info.streaming_data?.adaptive_formats || [])];
+
+    // stream URLs: present when the network isn't bot-gated; otherwise honest nulls
+    const variants = [];
+    for (const f of all) {
+      let u = null;
+      if (f.url) u = f.url;
+      else if (f.signature_cipher || f.cipher) {
+        try {
+          u = await f.decipher(e.session?.player);
+        } catch { u = null; }
+      }
+      variants.push(fmtToVariant(f, u));
+    }
+    const withUrls = variants.filter((v) => v.url);
+    const best = withUrls.sort((a, b2) => (b2.height || 0) - (a.height || 0))[0] || variants.sort((a, b2) => (b2.height || 0) - (a.height || 0))[0];
+
+    return {
+      result: {
+        sourceUrl: url,
+        platform: "youtube",
+        title: b.title ?? null,
+        author: b.author ?? null,
+        thumbnail: b.thumbnail?.[b.thumbnail.length - 1]?.url ?? null,
+        itemCount: 1,
+        counts: { images: 0, videos: 1, audios: 0, other: 0 },
+        truncated: false,
+        media: [{
+          type: "video",
+          index: 0,
+          url: best?.url ?? null,
+          thumbnail: b.thumbnail?.[b.thumbnail.length - 1]?.url ?? null,
+          mimeType: best?.mimeType ?? null,
+          width: best?.width ?? null,
+          height: best?.height ?? null,
+          duration: b.duration ?? null,
+          size: null,
+          quality: best?.quality ?? null,
+          hasAudio: best?.hasAudio ?? null,
+          hasVideo: best?.hasVideo ?? null,
+          source: name,
+          variants,
+        }],
+        streamUrlsAvailable: withUrls.length > 0,
+        streamAccess: withUrls.length > 0 ? "direct"
+          : "withheld — YouTube is bot-gating this network; install yt-dlp for hard networks",
+      },
+      engine: {
+        attempts: ctx.attempts || [attempt],
+        finalProvider: name,
+        totalLatencyMs: Date.now() - t0,
+      },
+    };
+  } catch (e) {
+    attempt.status = "failed";
+    attempt.error = e.message;
+    throw new UMediaError(e instanceof UMediaError ? e.code : Codes.PROVIDER_ERROR, `YouTube resolve failed: ${e.message}`, { attempts: [attempt] });
+  }
+}

package/lib/providers/ytdlp.js

@@ -0,0 +1,97 @@
+import { spawnSync } from "node:child_process";
+import { Codes, UMediaError } from "../errors.js";
+
+/**
+ * Optional yt-dlp power tier. If `yt-dlp` is on PATH (or UMedia_YTDLP points at it),
+ * it unlocks 1800+ sites and hard networks (PO tokens, cookies, muxing).
+ * Labeled honestly as source: "ytdlp" — never silently mixed with native results.
+ */
+export const name = "ytdlp";
+
+let _path;
+export function binary() {
+  if (_path !== undefined) return _path;
+  const probe = process.env.UMedia_YTDLP || "yt-dlp";
+  try {
+    const r = spawnSync(probe, ["--version"], { encoding: "utf8", timeout: 8000 });
+    _path = r.status === 0 ? probe : null;
+  } catch { _path = null; }
+  return _path;
+}
+
+export function canHandle() {
+  return Boolean(binary());
+}
+
+export function probe(url, extra = []) {
+  const bin = binary();
+  if (!bin) throw new UMediaError(Codes.PROVIDER_UNAVAILABLE, "yt-dlp not installed — `pip install yt-dlp` to enable the 1800+ sites tier");
+  const r = spawnSync(bin, ["--no-playlist", "-J", ...extra, url], {
+    encoding: "utf8", timeout: 120_000, maxBuffer: 64 * 1024 * 1024,
+  });
+  if (r.status !== 0) {
+    throw new UMediaError(Codes.PROVIDER_ERROR, `yt-dlp failed: ${(r.stderr || "").split("\n").slice(-2)[0] || "unknown error"}`);
+  }
+  return JSON.parse(r.stdout);
+}
+
+export async function resolve(url, ctx = {}) {
+  const attempt = { provider: name, status: "skipped" };
+  ctx.attempts?.push(attempt);
+  const t0 = Date.now();
+  try {
+    const info = probe(url);
+    attempt.status = "success";
+    attempt.latencyMs = Date.now() - t0;
+    const entries = info.entries || [info];
+    const media = entries.slice(0, 200).map((e, i) => ({
+      type: e._type === "image" ? "image" : (e.vcodec && e.vcodec !== "none") ? "video" : "audio",
+      index: i,
+      url: e.url || e.entries?.[0]?.url || null,
+      thumbnail: e.thumbnail ?? null,
+      mimeType: null,
+      width: e.width ?? null,
+      height: e.height ?? null,
+      duration: e.duration ?? null,
+      size: e.filesize ?? e.filesize_approx ?? null,
+      quality: e.height ? `${e.height}p` : null,
+      hasAudio: e.acodec && e.acodec !== "none",
+      hasVideo: e.vcodec && e.vcodec !== "none",
+      source: name,
+      variants: (e.formats || []).filter((f) => f.url).map((f) => ({
+        quality: f.format_note || (f.height ? `${f.height}p` : "unknown"),
+        width: f.width ?? null, height: f.height ?? null, url: f.url,
+        mimeType: (f.ext ? `video/${f.ext}` : null),
+        bitrateKbps: f.tbr ? Math.round(f.tbr) : null,
+        hasAudio: Boolean(f.acodec && f.acodec !== "none"),
+        hasVideo: Boolean(f.vcodec && f.vcodec !== "none"),
+      })),
+    }));
+    return {
+      result: {
+        sourceUrl: url,
+        platform: info.extractor_key?.toLowerCase() ?? "ytdlp",
+        title: info.title ?? null,
+        author: info.uploader ?? info.channel ?? null,
+        thumbnail: info.thumbnail ?? null,
+        itemCount: media.length,
+        counts: {
+          images: media.filter((m) => m.type === "image").length,
+          videos: media.filter((m) => m.type === "video").length,
+          audios: media.filter((m) => m.type === "audio").length, other: 0,
+        },
+        truncated: Boolean(info.entries && info.entries.length > 200),
+        media,
+      },
+      engine: { attempts: ctx.attempts || [attempt], finalProvider: name, totalLatencyMs: Date.now() - t0 },
+    };
+  } catch (e) {
+    attempt.status = "failed";
+    attempt.error = e.message;
+    throw e instanceof UMediaError ? e : new UMediaError(Codes.PROVIDER_ERROR, e.message, { attempts: [attempt] });
+  }
+}
+
+export async function search() {
+  return [];
+}

package/lib/quality.js

@@ -0,0 +1,49 @@
+/** Honest quality ladder — heights come from the real source, never invented. */
+export const LADDER = ["original", "best", "2160p", "1440p", "1080p", "720p", "480p", "360p", "240p", "144p", "audio"];
+
+export function heightOf(quality) {
+  const m = /^(\d+)p$/.exec(String(quality || ""));
+  return m ? Number(m[1]) : null;
+}
+
+export function labelOfHeight(h) {
+  return h ? `${h}p` : "unknown";
+}
+
+/**
+ * Pick the best format whose real height <= requested (fallback: closest available).
+ * @returns {{format: object|null, requestedQuality: string, selectedQuality: string|null, fallback: boolean}}
+ */
+export function pickFormat(formats, requestedQuality = "best") {
+  const req = String(requestedQuality || "best").toLowerCase();
+  const usable = (formats || []).filter((f) => f && (f.height || f.audioOnly));
+  if (!usable.length) return { format: null, requestedQuality: req, selectedQuality: null, fallback: false };
+
+  if (req === "audio") {
+    const audios = usable.filter((f) => f.audioOnly);
+    const format = audios[0] || null;
+    return { format, requestedQuality: req, selectedQuality: format ? "audio" : null, fallback: false };
+  }
+  const videos = usable.filter((f) => f.height);
+  if (!videos.length) {
+    return { format: null, requestedQuality: req, selectedQuality: null, fallback: false };
+  }
+  const sorted = [...videos].sort((a, b) => b.height - a.height);
+  if (req === "original" || req === "best") {
+    const format = sorted[0];
+    return { format, requestedQuality: req, selectedQuality: labelOfHeight(format.height), fallback: false };
+  }
+  const target = heightOf(req);
+  if (!target) {
+    const format = sorted[0];
+    return { format, requestedQuality: req, selectedQuality: labelOfHeight(format.height), fallback: true };
+  }
+  const atOrBelow = sorted.find((f) => f.height <= target);
+  const format = atOrBelow || sorted[sorted.length - 1];
+  return {
+    format,
+    requestedQuality: req,
+    selectedQuality: labelOfHeight(format.height),
+    fallback: format.height !== target,
+  };
+}

package/lib/registry.js

@@ -0,0 +1,123 @@
+import * as yt from "./providers/youtube.js";
+import * as tiktok from "./providers/tiktok.js";
+import * as reddit from "./providers/reddit.js";
+import * as xprov from "./providers/x.js";
+import * as ig from "./providers/instagram.js";
+import * as ytdlp from "./providers/ytdlp.js";
+import * as itunes from "./providers/itunes.js";
+import { Codes, UMediaError } from "./errors.js";
+
+const NATIVE = [yt, tiktok, reddit, xprov, ig];
+
+export function detectPlatform(url) {
+  for (const p of NATIVE) {
+    try { if (p.canHandle(url)) return p.name; } catch { /* bad URL — keep scanning */ }
+  }
+  return ytdlp.binary() ? "ytdlp" : "unknown";
+}
+
+const DIRECT_MEDIA = /\.(mp4|webm|m4a|mp3|aac|wav|jpg|jpeg|png|gif|webp|mov|mkv)(\?|#|$)/i;
+
+/** Resolve a URL: native adapter first, optional yt-dlp fallback. attempts[] is the honest trail. */
+export async function resolve(url) {
+  // direct media URL (an image/video/audio file) -> single-item result, no platform needed
+  const direct = String(url).split("#")[0].match(DIRECT_MEDIA);
+  if (direct) {
+    const ext = direct[1].toLowerCase();
+    const kind = ["mp4", "webm", "mov", "mkv"].includes(ext) ? "video"
+      : ["jpg", "jpeg", "png", "gif", "webp"].includes(ext) ? "image" : "audio";
+    return {
+      data: {
+        sourceUrl: url, platform: "direct",
+        title: String(url).split("/").pop() || "Direct media",
+        author: null, thumbnail: kind === "video" ? null : url,
+        itemCount: 1,
+        counts: { images: kind === "image" ? 1 : 0, videos: kind === "video" ? 1 : 0, audios: kind === "audio" ? 1 : 0, other: 0 },
+        truncated: false,
+        media: [{
+          type: kind, index: 0, url: String(url), thumbnail: null, mimeType: null,
+          width: null, height: null, duration: null, size: null, quality: "original",
+          hasAudio: kind !== "image", hasVideo: kind !== "audio", source: "direct", variants: [],
+        }],
+      },
+      engine: { attempts: [{ provider: "direct", status: "success" }], finalProvider: "direct", totalLatencyMs: 0 },
+    };
+  }
+
+  const ctx = { attempts: [] };
+  for (const p of NATIVE) {
+    if (!p.canHandle(url)) continue;
+    try {
+      const r = await p.resolve(url, ctx);
+      return { data: r.result, engine: r.engine };
+    } catch (e) {
+      if (e instanceof UMediaError && [Codes.MEDIA_NOT_FOUND, Codes.CONTENT_PRIVATE, Codes.SSRF_BLOCKED, Codes.INVALID_URL].includes(e.code)) {
+        // definitive outcome for this platform — don't mask it with fallbacks
+        e.attempts = ctx.attempts;
+        throw e;
+      }
+      // transient/provider failure → try the next layer
+      continue;
+    }
+  }
+  if (ytdlp.binary()) {
+    try {
+      const r = await ytdlp.resolve(url, ctx);
+      return { data: r.result, engine: r.engine };
+    } catch (e) {
+      e.attempts = ctx.attempts;
+      throw e;
+    }
+  }
+  const last = ctx.attempts[ctx.attempts.length - 1];
+  throw new UMediaError(
+    detectPlatform(url) === "unknown" ? Codes.INVALID_URL : Codes.PROVIDER_UNAVAILABLE,
+    `No provider could resolve this URL.${last?.error ? " Last error: " + last.error : ""}` +
+      (ytdlp.binary() ? "" : " Tip: install yt-dlp to unlock 1800+ sites and hard networks."),
+    { attempts: ctx.attempts },
+  );
+}
+
+/** Multi-source search. Music leads with iTunes 30s previews, then YouTube. */
+export async function search({ q, type = "video", limit = 12, adult = false } = {}) {
+  const ctx = { attempts: [] };
+  const out = [];
+  const plan = type === "music" ? [itunes, yt] : [yt];
+  for (const p of plan) {
+    if (out.length >= limit) break;
+    const items = await p.search({ q, type, limit: limit - out.length }, ctx);
+    out.push(...items);
+  }
+  return { items: out.slice(0, limit), attempts: ctx.attempts };
+}
+
+export function capabilities() {
+  return {
+    platforms: [
+      { platform: "youtube", search: true, resolve: true, download: "network-dependent (yt-dlp tier recommended)", notes: "search+metadata always; stream URLs depend on network/PO-token state" },
+      { platform: "tiktok", search: false, resolve: true, download: true, notes: "photo galleries + video posts" },
+      { platform: "instagram", search: false, resolve: true, download: true, notes: "public embed best-effort" },
+      { platform: "reddit", search: false, resolve: true, download: true, notes: "posts + galleries" },
+      { platform: "x", search: false, resolve: true, download: true, notes: "public posts via syndication" },
+      { platform: "itunes", search: true, resolve: false, download: "previews", notes: "real 30s clips" },
+      { platform: "ytdlp", search: false, resolve: Boolean(ytdlp.binary()), download: Boolean(ytdlp.binary()), notes: "optional tier: 1800+ sites — install yt-dlp" },
+    ],
+    qualityLadder: ["original", "best", "2160p", "1440p", "1080p", "720p", "480p", "360p", "240p", "144p", "audio"],
+  };
+}
+
+export function status() {
+  return {
+    overall: "operational",
+    runtime: { node: process.version, platform: process.platform },
+    providers: [
+      { name: "youtube", state: "operational", via: "youtubei.js" },
+      { name: "tiktok", state: "operational", via: "embed/v2" },
+      { name: "instagram", state: "degraded", via: "public embed (best-effort)" },
+      { name: "reddit", state: "operational", via: "public json" },
+      { name: "x", state: "degraded", via: "syndication (best-effort)" },
+      { name: "itunes", state: "operational", via: "search api" },
+      { name: "ytdlp", state: ytdlp.binary() ? "operational" : "unavailable", via: "external binary" },
+    ],
+  };
+}

package/lib/util.js

@@ -0,0 +1,93 @@
+import { UMediaError, Codes } from "./errors.js";
+
+export const UA =
+  "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0 Safari/537.36";
+
+export function rid() {
+  return "req_" + Math.random().toString(16).slice(2, 10) + Date.now().toString(16).slice(-8);
+}
+
+/** Hostname match: exact or dot-suffix (www-insensitive). */
+export function hostMatches(hostname, list) {
+  const h = String(hostname || "").toLowerCase().replace(/^www\./, "");
+  return list.some((d) => h === d || h.endsWith("." + d));
+}
+
+/** http(s) only, no private/loopback/link-local targets (SSRF hygiene). */
+export function validateUrl(raw) {
+  let u;
+  try {
+    u = new URL(String(raw || "").trim());
+  } catch {
+    throw new UMediaError(Codes.INVALID_URL, `Invalid URL: ${String(raw).slice(0, 120)}`);
+  }
+  if (!/^https?:$/.test(u.protocol)) {
+    throw new UMediaError(Codes.INVALID_URL, `Only http(s) URLs are supported — got ${u.protocol}`);
+  }
+  const host = u.hostname.toLowerCase();
+  if (
+    host === "localhost" || host.endsWith(".local") || host.endsWith(".internal") ||
+    /^127\./.test(host) || /^10\./.test(host) || /^192\.168\./.test(host) ||
+    /^172\.(1[6-9]|2\d|3[01])\./.test(host) || /^169\.254\./.test(host) ||
+    host === "0.0.0.0" || host === "::1" || host === "[::1]"
+  ) {
+    throw new UMediaError(Codes.SSRF_BLOCKED, `Refusing private/internal host: ${host}`);
+  }
+  return u;
+}
+
+export async function fetchJson(url, opts = {}, timeoutMs = 20_000) {
+  const ctl = new AbortController();
+  const t = setTimeout(() => ctl.abort(), timeoutMs);
+  try {
+    const res = await fetch(url, {
+      ...opts,
+      signal: ctl.signal,
+      headers: { "user-agent": UA, ...(opts.headers || {}) },
+    });
+    if (!res.ok) {
+      throw new UMediaError(
+        res.status === 429 ? Codes.RATE_LIMITED : res.status === 404 ? Codes.NOT_FOUND : Codes.PROVIDER_ERROR,
+        `HTTP ${res.status} from ${new URL(url).hostname}`,
+        { status: res.status },
+      );
+    }
+    return await res.json();
+  } catch (e) {
+    if (e instanceof UMediaError) throw e;
+    if (e.name === "AbortError") throw new UMediaError(Codes.TIMEOUT, `Timed out after ${timeoutMs}ms: ${new URL(url).hostname}`);
+    throw new UMediaError(Codes.PROVIDER_UNAVAILABLE, `Network error from ${new URL(url).hostname}: ${e.message}`);
+  } finally {
+    clearTimeout(t);
+  }
+}
+
+export async function fetchText(url, opts = {}, timeoutMs = 20_000) {
+  const ctl = new AbortController();
+  const t = setTimeout(() => ctl.abort(), timeoutMs);
+  try {
+    const res = await fetch(url, {
+      ...opts,
+      signal: ctl.signal,
+      headers: { "user-agent": UA, ...(opts.headers || {}) },
+    });
+    return { status: res.status, text: await res.text(), headers: res.headers };
+  } catch (e) {
+    if (e.name === "AbortError") throw new UMediaError(Codes.TIMEOUT, `Timed out after ${timeoutMs}ms: ${new URL(url).hostname}`);
+    throw new UMediaError(Codes.PROVIDER_UNAVAILABLE, `Network error from ${new URL(url).hostname}: ${e.message}`);
+  } finally {
+    clearTimeout(t);
+  }
+}
+
+export function parseDuration(text) {
+  if (text == null) return null;
+  if (typeof text === "number") return text;
+  const p = String(text).split(":").map(Number);
+  if (p.some(Number.isNaN)) return null;
+  return p.reduce((acc, n) => acc * 60 + n, 0);
+}
+
+export function cleanName(s) {
+  return String(s || "media").replace(/[\\/:*?"<>|]/g, "_").slice(0, 120).trim() || "media";
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "umedia",
-  "version": "0.1.2",
-  "description": "Official client for the Unified Media API — search, resolve and download media from YouTube, TikTok, Instagram, Reddit, X, iTunes and 1800+ sites through one REST API. Honest quality labels, multi-item galleries preserved, zero dependencies.",
+  "version": "0.2.1",
+  "description": "Standalone media engine — search, resolve and download media from YouTube, TikTok, Instagram, Reddit, X, iTunes (and 1800+ sites via the yt-dlp tier) entirely on your machine. No hosted API, no keys, no server bills. Honest quality labels, complete galleries, typed errors.",
   "type": "module",
   "main": "./index.js",
   "types": "./index.d.ts",
@@ -12,11 +12,12 @@
     }
   },
   "bin": {
-    "umedia": "bin/umedia.js"
+    "umedia": "./bin/umedia.js"
   },
   "files": [
     "index.js",
     "index.d.ts",
+    "lib/",
     "bin/",
     "README.md",
     "LICENSE"
@@ -27,18 +28,21 @@
   "scripts": {
     "test": "node --test test/"
   },
+  "dependencies": {
+    "fflate": "^0.8.2",
+    "youtubei.js": "^18.1.0"
+  },
   "keywords": [
     "media",
-    "api",
-    "sdk",
+    "downloader",
     "youtube",
     "tiktok",
     "instagram",
     "reddit",
-    "downloader",
     "search",
-    "resolve",
-    "rest"
+    "engine",
+    "ytdlp",
+    "cli"
   ],
   "license": "MIT",
   "repository": {