@jnzlab/easy-ytdlp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 easy-ytdlp contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,110 @@
+# easy-ytdlp
+
+Interactive, user-friendly CLI wrapper around [yt-dlp](https://github.com/yt-dlp/yt-dlp). Answer a few plain-English questions — quality, format, destination — and the tool builds and runs the correct `yt-dlp` command for you.
+
+No Python install. No flag memorization. The `yt-dlp` binary is downloaded and cached automatically on first run.
+
+## Install
+
+```bash
+# one-shot (no install)
+npx @jnzlab/easy-ytdlp <url>
+
+# or install globally
+npm install -g @jnzlab/easy-ytdlp
+easy-ytdlp <url>
+```
+
+**Requirements:** Node.js 18+. For video merging, audio extraction, and embedding, install [ffmpeg](https://ffmpeg.org/) on your system.
+
+## Usage
+
+```bash
+easy-ytdlp                                 # prompts for URL
+easy-ytdlp https://youtu.be/dQw4w9WgXcQ    # start with a URL
+easy-ytdlp <url> --show-command            # preview the yt-dlp flags first
+easy-ytdlp update-binary                   # force-refresh the cached yt-dlp binary
+```
+
+### Example session
+
+```text
+┌  easy-ytdlp
+│
+◇  yt-dlp ready
+│
+◇  Fetching video info…
+│
+◇  Found
+│  Never Gonna Give You Up
+│  by Rick Astley · 3m 33s
+│
+◇  What do you want to download?
+│  Video (with audio)
+│
+◇  Video quality?
+│  Up to 1080p
+│
+◇  Container preference?
+│  mp4
+│
+◇  Download subtitles?
+│  No
+│
+◇  Destination folder
+│  /home/you/Downloads
+│
+◇  Filename style?
+│  Title only
+│
+◇  Extras (optional)
+│  Embed metadata
+│
+◇  Summary
+│  Mode: video
+│  Quality: 1080
+│  Container: mp4
+│  …
+│
+◇  Start download?
+│  Yes
+│
+│  Downloading |████████████████| 100% | 4.2MiB/s | ETA 0s
+│
+◇  Saved
+│  /home/you/Downloads/Never Gonna Give You Up.mp4
+│
+└  Finished
+```
+
+### Audio-only example
+
+```bash
+npx @jnzlab/easy-ytdlp "https://www.youtube.com/watch?v=…"
+# → choose "Audio only" → mp3 → Best → confirm
+```
+
+## What it covers
+
+Guided choices for:
+
+- Video (+ audio), audio-only, video-only, subtitles-only, thumbnail-only
+- Quality caps (`-S res:…`) and available resolutions from metadata
+- Containers, audio formats, subtitle languages / embed vs file
+- Playlist: this video, whole playlist, or index range
+- Output folder + plain-English filename templates
+- Embed thumbnail / metadata, SponsorBlock remove
+
+## Out of scope (v1)
+
+These need the raw `yt-dlp` CLI directly:
+
+- Login / cookies-based extraction
+- DRM content
+- Live streams from the start
+
+See the [yt-dlp authentication](https://github.com/yt-dlp/yt-dlp#authentication-options) and related docs, or the local reference copy in [`docs/yt-dlp-README.md`](docs/yt-dlp-README.md).
+
+## License
+
+MIT

package/bin/easy-ytdlp.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../dist/cli.js';

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+
+export {  }

package/dist/cli.js

@@ -0,0 +1,1217 @@
+// src/cli.ts
+import { Command } from "commander";
+import * as p3 from "@clack/prompts";
+
+// src/binary.ts
+import { createWriteStream } from "fs";
+import { access, chmod, mkdir, unlink } from "fs/promises";
+import { constants } from "fs";
+import { arch, platform } from "os";
+import { join } from "path";
+import { pipeline } from "stream/promises";
+import { request as httpsRequest } from "https";
+import { request as httpRequest } from "http";
+import envPaths from "env-paths";
+
+// src/yt-dlp-wrap.ts
+import YTDlpWrapImport from "yt-dlp-wrap";
+function resolveConstructor() {
+  const mod = YTDlpWrapImport;
+  if (typeof mod === "function") {
+    return mod;
+  }
+  if (mod && typeof mod.default === "function") {
+    return mod.default;
+  }
+  throw new Error(
+    "Failed to load yt-dlp-wrap: unexpected module shape. Try reinstalling dependencies."
+  );
+}
+var YTDlpWrap = resolveConstructor();
+
+// src/binary.ts
+var paths = envPaths("easy-ytdlp");
+var RELEASE_BASE = "https://github.com/yt-dlp/yt-dlp/releases/latest/download";
+function binaryName() {
+  return platform() === "win32" ? "yt-dlp.exe" : "yt-dlp";
+}
+function releaseAssetName(osPlatform = platform(), cpuArch = arch()) {
+  if (osPlatform === "win32") return "yt-dlp.exe";
+  if (osPlatform === "darwin") return "yt-dlp_macos";
+  if (osPlatform === "linux") {
+    if (cpuArch === "arm64" || cpuArch === "aarch64") {
+      return "yt-dlp_linux_aarch64";
+    }
+    return "yt-dlp_linux";
+  }
+  return "yt-dlp";
+}
+function getBinaryPath() {
+  return join(paths.cache, binaryName());
+}
+async function exists(filePath) {
+  try {
+    await access(filePath, constants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function formatUnknownError(err) {
+  if (err instanceof Error) return err.message || err.name;
+  if (typeof err === "string") return err;
+  if (err && typeof err === "object") {
+    const r = err;
+    if (typeof r.statusCode === "number") {
+      return `HTTP ${r.statusCode}${r.statusMessage ? ` ${r.statusMessage}` : ""}`;
+    }
+    if (typeof r.message === "string") return r.message;
+    if (typeof r.code === "string") return r.code;
+    try {
+      return JSON.stringify(err);
+    } catch {
+      return Object.prototype.toString.call(err);
+    }
+  }
+  return String(err);
+}
+function friendlyBinaryError(err) {
+  const msg = formatUnknownError(err);
+  return new Error(
+    [
+      "Failed to download or set up the yt-dlp binary.",
+      "",
+      `Details: ${msg}`,
+      "",
+      "Common fixes:",
+      "  \u2022 Check your network / proxy settings",
+      "  \u2022 Ensure the cache directory is writable:",
+      `      ${paths.cache}`,
+      "  \u2022 Retry with: easy-ytdlp update-binary"
+    ].join("\n")
+  );
+}
+function getOnce(url) {
+  return new Promise((resolve, reject) => {
+    const lib = url.startsWith("http:") ? httpRequest : httpsRequest;
+    const req = lib(
+      url,
+      {
+        headers: {
+          "User-Agent": "easy-ytdlp",
+          Accept: "*/*"
+        }
+      },
+      (res) => resolve(res)
+    );
+    req.on("error", reject);
+    req.end();
+  });
+}
+async function downloadReleaseAsset(asset, destPath) {
+  const startUrl = `${RELEASE_BASE}/${asset}`;
+  let url = startUrl;
+  let redirects = 0;
+  while (url) {
+    const res = await getOnce(url);
+    const status = res.statusCode ?? 0;
+    if (status >= 300 && status < 400 && res.headers.location) {
+      res.resume();
+      const next = res.headers.location;
+      url = next.startsWith("http") ? next : new URL(next, url).href;
+      redirects += 1;
+      if (redirects > 10) {
+        throw new Error(`Too many redirects downloading ${asset}`);
+      }
+      continue;
+    }
+    if (status !== 200) {
+      res.resume();
+      throw new Error(
+        `Download failed: HTTP ${status} ${res.statusMessage ?? ""} (${startUrl})`.trim()
+      );
+    }
+    await pipeline(res, createWriteStream(destPath));
+    return;
+  }
+  throw new Error(`Download failed: no URL for ${asset}`);
+}
+async function ensureBinary(options = {}) {
+  const { force = false, onStatus } = options;
+  const binPath = getBinaryPath();
+  await mkdir(paths.cache, { recursive: true });
+  if (!force && await exists(binPath)) {
+    return binPath;
+  }
+  if (force && await exists(binPath)) {
+    try {
+      await unlink(binPath);
+    } catch {
+    }
+  }
+  const asset = releaseAssetName();
+  onStatus?.(`Downloading ${asset} (one-time setup)\u2026`);
+  const tmpPath = `${binPath}.tmp`;
+  try {
+    if (await exists(tmpPath)) {
+      await unlink(tmpPath);
+    }
+    await downloadReleaseAsset(asset, tmpPath);
+    await chmod(tmpPath, 493);
+    const { rename } = await import("fs/promises");
+    await rename(tmpPath, binPath);
+  } catch (err) {
+    try {
+      await unlink(tmpPath);
+    } catch {
+    }
+    throw friendlyBinaryError(err);
+  }
+  onStatus?.(`yt-dlp binary ready at ${binPath}`);
+  return binPath;
+}
+async function updateBinary(onStatus) {
+  return ensureBinary({ force: true, onStatus });
+}
+async function createYtDlp(options = {}) {
+  const binPath = await ensureBinary(options);
+  return new YTDlpWrap(binPath);
+}
+
+// src/builder.ts
+var FILENAME_TEMPLATES = {
+  title: "%(title)s.%(ext)s",
+  "title-channel": "%(title)s [%(uploader)s].%(ext)s",
+  "title-date": "%(upload_date)s - %(title)s.%(ext)s"
+};
+function audioQualityValue(q) {
+  return q === "good" ? "5" : "0";
+}
+function videoQualityFlags(quality) {
+  if (!quality || quality === "best") {
+    return ["-f", "bv*+ba/b"];
+  }
+  if (typeof quality === "object" && "height" in quality) {
+    const h = quality.height;
+    return ["-f", `bv*[height=${h}]+ba/b`];
+  }
+  return ["-S", `res:${quality}`, "-f", "bv*+ba/b"];
+}
+function containerFlags(container) {
+  if (!container || container === "best") return [];
+  return ["--merge-output-format", container];
+}
+function buildFlags(answers) {
+  const flags = [];
+  switch (answers.mode) {
+    case "video":
+      flags.push(...videoQualityFlags(answers.videoQuality));
+      flags.push(...containerFlags(answers.container));
+      break;
+    case "video-only":
+      if (answers.videoQuality && answers.videoQuality !== "best" && typeof answers.videoQuality !== "object") {
+        flags.push("-S", `res:${answers.videoQuality}`, "-f", "bv");
+      } else if (typeof answers.videoQuality === "object" && answers.videoQuality?.height) {
+        flags.push("-f", `bv[height=${answers.videoQuality.height}]`);
+      } else {
+        flags.push("-f", "bv");
+      }
+      flags.push(...containerFlags(answers.container));
+      break;
+    case "audio":
+      flags.push(
+        "-x",
+        "--audio-format",
+        answers.audioFormat ?? "best",
+        "--audio-quality",
+        audioQualityValue(answers.audioQuality)
+      );
+      break;
+    case "subs-only":
+      flags.push("--skip-download", "--write-subs");
+      break;
+    case "thumbnail-only":
+      flags.push("--skip-download", "--write-thumbnail");
+      break;
+  }
+  if (answers.mode === "subs-only") {
+    const langs = answers.subtitles.languages.length > 0 ? answers.subtitles.languages.join(",") : "all";
+    flags.push("--sub-langs", langs);
+  } else if (answers.subtitles.mode !== "none" && answers.mode !== "thumbnail-only") {
+    const langs = answers.subtitles.languages.length > 0 ? answers.subtitles.languages.join(",") : "all";
+    flags.push("--sub-langs", langs);
+    if (answers.subtitles.mode === "write" || answers.subtitles.mode === "both") {
+      flags.push("--write-subs");
+    }
+    if (answers.subtitles.mode === "embed" || answers.subtitles.mode === "both") {
+      flags.push("--embed-subs");
+    }
+  }
+  switch (answers.playlist.kind) {
+    case "single":
+      flags.push("--no-playlist");
+      break;
+    case "all":
+      flags.push("--yes-playlist");
+      break;
+    case "range":
+      flags.push(
+        "--yes-playlist",
+        "-I",
+        `${answers.playlist.start}:${answers.playlist.stop}`
+      );
+      break;
+  }
+  flags.push("-P", answers.outputDir);
+  flags.push("-o", FILENAME_TEMPLATES[answers.filenamePreset]);
+  if (answers.embedThumbnail && answers.mode !== "thumbnail-only") {
+    flags.push("--embed-thumbnail");
+  }
+  if (answers.embedMetadata) {
+    flags.push("--embed-metadata");
+  }
+  if (answers.sponsorBlock) {
+    flags.push("--sponsorblock-remove", "default");
+  }
+  flags.push("--print", "after_move:filepath");
+  flags.push(answers.url);
+  return flags;
+}
+function formatCommand(flags) {
+  const quoted = flags.map(
+    (f) => /[\s"'\\]/.test(f) ? JSON.stringify(f) : f
+  );
+  const parts = ["yt-dlp"];
+  for (let i = 0; i < quoted.length; i++) {
+    const cur = quoted[i];
+    const next = quoted[i + 1];
+    if (cur.startsWith("-") && next && !next.startsWith("-") && !looksLikeUrl(next)) {
+      parts.push(`${cur} ${next}`);
+      i++;
+    } else {
+      parts.push(cur);
+    }
+  }
+  return parts.join("\n  ");
+}
+function looksLikeUrl(s) {
+  return /^https?:\/\//i.test(s) || s.startsWith('"http');
+}
+
+// src/downloader.ts
+import cliProgress from "cli-progress";
+
+// src/ffmpeg.ts
+import { access as access2 } from "fs/promises";
+import { constants as constants2 } from "fs";
+import { platform as platform2 } from "os";
+import { delimiter, join as join2 } from "path";
+async function isExecutable(filePath) {
+  try {
+    await access2(filePath, constants2.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function commandExists(name) {
+  const pathEnv = process.env.PATH ?? "";
+  const exts = platform2() === "win32" ? (process.env.PATHEXT ?? ".EXE;.CMD;.BAT").split(";") : [""];
+  for (const dir of pathEnv.split(delimiter)) {
+    for (const ext of exts) {
+      const candidate = join2(dir, name + ext.toLowerCase());
+      if (await isExecutable(candidate)) return true;
+      const candidate2 = join2(dir, name + ext);
+      if (candidate2 !== candidate && await isExecutable(candidate2)) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+async function checkFfmpeg() {
+  const ffmpeg = await commandExists("ffmpeg");
+  const ffprobe = await commandExists("ffprobe");
+  return { ffmpeg, ffprobe, ok: ffmpeg && ffprobe };
+}
+function ffmpegInstallHint() {
+  const os = platform2();
+  const lines = [
+    "ffmpeg (and ffprobe) are required for merging video+audio, extracting audio, and embedding subtitles/thumbnails.",
+    "",
+    "Install ffmpeg:"
+  ];
+  if (os === "darwin") {
+    lines.push("  brew install ffmpeg");
+  } else if (os === "win32") {
+    lines.push(
+      "  winget install ffmpeg",
+      "  # or: choco install ffmpeg",
+      "  # or download from https://ffmpeg.org/download.html"
+    );
+  } else {
+    lines.push(
+      "  # Fedora / RHEL:",
+      "  sudo dnf install ffmpeg",
+      "  # Debian / Ubuntu:",
+      "  sudo apt install ffmpeg",
+      "  # Arch:",
+      "  sudo pacman -S ffmpeg"
+    );
+  }
+  lines.push("", "Then re-run easy-ytdlp.");
+  return lines.join("\n");
+}
+function needsFfmpeg(mode, extras) {
+  if (mode === "video" || mode === "video-only") return true;
+  if (mode === "audio" || extras.extractAudio) return true;
+  if (extras.embedSubs || extras.embedThumbnail) return true;
+  return false;
+}
+
+// src/youtube-compat.ts
+import { accessSync, constants as constants3, readdirSync } from "fs";
+import { join as join3 } from "path";
+var MIN_RECOMMENDED_MAJOR = 22;
+function nodeMajor(version) {
+  const m = version.replace(/^v/, "").split(".")[0];
+  return Number(m) || 0;
+}
+function isExecutable2(filePath) {
+  try {
+    accessSync(filePath, constants3.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function resolveNodeForYtDlp() {
+  const currentMajor = nodeMajor(process.versions.node);
+  if (currentMajor >= MIN_RECOMMENDED_MAJOR) {
+    return { path: process.execPath, major: currentMajor };
+  }
+  const nvmDir = process.env.NVM_DIR;
+  if (nvmDir) {
+    const versionsRoot = join3(nvmDir, "versions", "node");
+    try {
+      const dirs = readdirSync(versionsRoot).filter((name) => /^v\d+\.\d+\.\d+$/.test(name)).sort((a, b) => {
+        const pa = a.slice(1).split(".").map(Number);
+        const pb = b.slice(1).split(".").map(Number);
+        for (let i = 0; i < 3; i++) {
+          const diff = (pb[i] ?? 0) - (pa[i] ?? 0);
+          if (diff !== 0) return diff;
+        }
+        return 0;
+      });
+      for (const dir of dirs) {
+        const major = nodeMajor(dir);
+        if (major < MIN_RECOMMENDED_MAJOR) continue;
+        const candidate = join3(versionsRoot, dir, "bin", "node");
+        if (isExecutable2(candidate)) {
+          return { path: candidate, major };
+        }
+      }
+    } catch {
+    }
+  }
+  return { path: process.execPath, major: currentMajor };
+}
+function youtubeCompatFlags() {
+  const { path } = resolveNodeForYtDlp();
+  return [
+    "--js-runtimes",
+    `node:${path}`,
+    // Fallback if the cached binary's bundled EJS scripts are missing/outdated
+    "--remote-components",
+    "ejs:github"
+  ];
+}
+
+// src/downloader.ts
+var LIVE_PROGRESS_RE = /\[download\]\s+([\d.]+)%(?:\s+of\s+(\S+))?(?:\s+at\s+(\S+))?\s+ETA\s+(\S+)/i;
+var POSTPROCESS_RE = /^\[(?<name>Merger|ExtractAudio|EmbedSubtitle|EmbedThumbnail|Metadata|ModifyChapters|SponsorBlock|VideoRemuxer|VideoConvertor|MoveFiles|ThumbnailsConvertor|SubtitlesConvertor)\]/i;
+function stripAnsi(text2) {
+  return text2.replace(/\u001b\[[0-9;]*[A-Za-z]/g, "");
+}
+function humanizeError(raw) {
+  const lower = raw.toLowerCase();
+  if (lower.includes("ffmpeg") || lower.includes("ffprobe") || lower.includes("postprocessing")) {
+    return [
+      "Download or post-processing failed because ffmpeg/ffprobe is missing or broken.",
+      "",
+      ffmpegInstallHint(),
+      "",
+      `yt-dlp said: ${raw.trim()}`
+    ].join("\n");
+  }
+  if (lower.includes("http error 403") || lower.includes("403: forbidden") || lower.includes("javascript runtime") || lower.includes("js challenge") || lower.includes("n challenge")) {
+    return [
+      "YouTube blocked the download (often HTTP 403) \u2014 usually because a JavaScript runtime is needed to solve YouTube challenges.",
+      "",
+      "easy-ytdlp now enables Node automatically. If this still fails:",
+      "  1. Update the yt-dlp binary:  easy-ytdlp update-binary",
+      "  2. Use Node 22+ (recommended by yt-dlp for the JS solver)",
+      "  3. Or install Deno: https://deno.land  (yt-dlp\u2019s preferred runtime)",
+      "",
+      "More detail: https://github.com/yt-dlp/yt-dlp/wiki/EJS",
+      "",
+      `yt-dlp said: ${raw.trim()}`
+    ].join("\n");
+  }
+  if (lower.includes("impersonat")) {
+    return [
+      "This site asked for browser impersonation, but the required library is not available in the standalone yt-dlp binary.",
+      "Try: easy-ytdlp update-binary",
+      "Or see: https://github.com/yt-dlp/yt-dlp#impersonation",
+      "",
+      `yt-dlp said: ${raw.trim()}`
+    ].join("\n");
+  }
+  if (lower.includes("private video") || lower.includes("this video is private")) {
+    return "This video is private. Login/cookies are out of scope for easy-ytdlp \u2014 see yt-dlp authentication docs if you need them.";
+  }
+  if (lower.includes("geo") || lower.includes("not available in your country") || lower.includes("blocked in your country")) {
+    return `This video appears geo-restricted or blocked in your region.
+
+yt-dlp said: ${raw.trim()}`;
+  }
+  if (lower.includes("unsupported url") || lower.includes("no suitable extractor") || lower.includes("unable to extract")) {
+    return `That URL is not supported or could not be parsed.
+
+yt-dlp said: ${raw.trim()}`;
+  }
+  if (lower.includes("video unavailable") || lower.includes("has been removed")) {
+    return `This video is unavailable.
+
+yt-dlp said: ${raw.trim()}`;
+  }
+  return raw.trim() || "Download failed for an unknown reason.";
+}
+async function fetchMetadata(ytDlp, url) {
+  try {
+    return await ytDlp.getVideoInfo([
+      ...youtubeCompatFlags(),
+      "--no-playlist",
+      url
+    ]);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    throw new Error(humanizeError(msg));
+  }
+}
+function parseProgressLine(line) {
+  const cleaned = stripAnsi(line).trim();
+  if (/\bin\b/i.test(cleaned) && !/\bETA\b/i.test(cleaned)) {
+    return null;
+  }
+  const m = cleaned.match(LIVE_PROGRESS_RE);
+  if (!m) return null;
+  const percent = parseFloat(m[1]);
+  if (!Number.isFinite(percent)) return null;
+  return {
+    percent,
+    totalSize: m[2],
+    currentSpeed: m[3],
+    eta: m[4]
+  };
+}
+function parsePostprocessLine(line) {
+  const cleaned = stripAnsi(line).trim();
+  const m = cleaned.match(POSTPROCESS_RE);
+  if (!m?.groups?.name) return null;
+  const labels = {
+    Merger: "Merging video + audio\u2026",
+    ExtractAudio: "Extracting audio\u2026",
+    EmbedSubtitle: "Embedding subtitles\u2026",
+    EmbedThumbnail: "Embedding thumbnail\u2026",
+    Metadata: "Embedding metadata\u2026",
+    ModifyChapters: "Removing sponsor segments\u2026",
+    SponsorBlock: "SponsorBlock\u2026",
+    VideoRemuxer: "Remuxing\u2026",
+    VideoConvertor: "Converting\u2026",
+    MoveFiles: "Moving file\u2026",
+    ThumbnailsConvertor: "Processing thumbnail\u2026",
+    SubtitlesConvertor: "Processing subtitles\u2026"
+  };
+  return labels[m.groups.name] ?? `${m.groups.name}\u2026`;
+}
+function progressFlags() {
+  return ["--newline", "--progress"];
+}
+async function runDownload(ytDlp, flags) {
+  const filepaths = [];
+  let lastError = "";
+  let part = 1;
+  console.log();
+  const bar = new cliProgress.SingleBar(
+    {
+      // Use custom tokens — built-in `{eta}` is seconds-remaining and hits 0 at 100%
+      format: "  {phase} |{bar}| {percentage}% | {dl_speed} | ETA {dl_eta}",
+      barCompleteChar: "\u2588",
+      barIncompleteChar: "\u2591",
+      hideCursor: true,
+      clearOnComplete: false,
+      // CRITICAL: must be false — YouTube DASH hits 100% per stream; stopping
+      // here froze the bar while audio/merge still ran for minutes.
+      stopOnComplete: false,
+      forceRedraw: true,
+      stream: process.stderr
+    },
+    cliProgress.Presets.shades_classic
+  );
+  let barStarted = false;
+  let lastPercent = 0;
+  let phase = "Downloading";
+  const ensureBar = () => {
+    if (!barStarted) {
+      bar.start(100, 0, {
+        phase,
+        dl_speed: "starting\u2026",
+        dl_eta: "\u2014"
+      });
+      barStarted = true;
+    }
+  };
+  const updateBar = (progress) => {
+    let percent = Math.min(100, Math.max(0, progress.percent));
+    if (!Number.isFinite(percent)) return;
+    if (percent + 5 < lastPercent) {
+      part += 1;
+      phase = `Downloading (${part})`;
+    }
+    lastPercent = percent;
+    ensureBar();
+    bar.update(percent, {
+      phase,
+      dl_speed: progress.currentSpeed ?? "N/A",
+      dl_eta: progress.eta && progress.eta !== "Unknown" ? progress.eta : "\u2014"
+    });
+  };
+  const setPhase = (label) => {
+    phase = label;
+    ensureBar();
+    bar.update(Math.min(99, Math.max(lastPercent, 1)), {
+      phase,
+      dl_speed: "\u2026",
+      dl_eta: "\u2014"
+    });
+  };
+  const handleLine = (raw) => {
+    const trimmed = stripAnsi(raw).trim();
+    if (!trimmed) return;
+    const progress = parseProgressLine(trimmed);
+    if (progress) {
+      updateBar(progress);
+      return;
+    }
+    const post = parsePostprocessLine(trimmed);
+    if (post) {
+      setPhase(post);
+      return;
+    }
+    if (/^\[download\]\s+Destination:/i.test(trimmed)) {
+      if (lastPercent >= 99) {
+        part += 1;
+        lastPercent = 0;
+        phase = `Downloading (${part})`;
+        ensureBar();
+        bar.update(0, {
+          phase,
+          dl_speed: "starting\u2026",
+          dl_eta: "\u2014"
+        });
+      }
+    }
+  };
+  const execFlags = [...youtubeCompatFlags(), ...progressFlags(), ...flags];
+  return new Promise((resolve, reject) => {
+    const emitter = ytDlp.exec(execFlags);
+    emitter.on("progress", (progress) => {
+      if (typeof progress.percent === "number" && Number.isFinite(progress.percent) && // Ignore wrap's parse of completion lines (often lack a real ETA string)
+      progress.eta) {
+        updateBar({
+          percent: progress.percent,
+          currentSpeed: progress.currentSpeed,
+          eta: progress.eta
+        });
+      }
+    });
+    ensureBar();
+    const proc = emitter.ytDlpProcess;
+    if (proc?.stderr) {
+      let errBuf = "";
+      proc.stderr.on("data", (chunk) => {
+        const text2 = chunk.toString();
+        if (/error|errno|traceback|ffmpeg/i.test(text2)) {
+          lastError += text2;
+        }
+        errBuf += text2;
+        const lines = errBuf.split(/\r|\n/);
+        errBuf = lines.pop() ?? "";
+        for (const line of lines) handleLine(line);
+      });
+    }
+    if (proc?.stdout) {
+      let buffer = "";
+      proc.stdout.on("data", (chunk) => {
+        buffer += chunk.toString();
+        const lines = buffer.split(/\r?\n/);
+        buffer = lines.pop() ?? "";
+        for (const line of lines) {
+          const trimmed = stripAnsi(line).trim();
+          if (!trimmed) continue;
+          handleLine(trimmed);
+          if (!trimmed.startsWith("[") && (trimmed.includes("/") || trimmed.includes("\\")) && !trimmed.toLowerCase().includes("error")) {
+            filepaths.push(trimmed);
+          }
+        }
+      });
+    }
+    emitter.on("error", (err) => {
+      if (barStarted) {
+        bar.stop();
+        console.error();
+      }
+      const combined = [err.message, lastError].filter(Boolean).join("\n");
+      reject(new Error(humanizeError(combined)));
+    });
+    emitter.on("close", (code) => {
+      if (barStarted) {
+        if (code === 0 || code === null) {
+          bar.update(100, {
+            phase: "Done",
+            dl_speed: "done",
+            dl_eta: "0s"
+          });
+        }
+        bar.stop();
+        console.error();
+      }
+      if (code !== 0 && code !== null) {
+        reject(
+          new Error(
+            humanizeError(lastError || `yt-dlp exited with code ${code}`)
+          )
+        );
+        return;
+      }
+      resolve({ filepaths });
+    });
+  });
+}
+
+// src/questions.ts
+import * as p2 from "@clack/prompts";
+import { homedir } from "os";
+import { join as join4 } from "path";
+
+// src/ui.ts
+import * as p from "@clack/prompts";
+function contentWidth(pad = 8) {
+  const cols = process.stdout.columns ?? 80;
+  return Math.max(40, cols - pad);
+}
+function wrapText(text2, width = contentWidth()) {
+  return text2.split(/\r?\n/).flatMap((line) => wrapLine(line, width)).join("\n");
+}
+function wrapLine(line, width) {
+  if (line.length <= width) return [line || " "];
+  const out = [];
+  let rest = line;
+  while (rest.length > width) {
+    let breakAt = rest.lastIndexOf(" ", width);
+    if (breakAt < Math.floor(width * 0.5)) breakAt = width;
+    out.push(rest.slice(0, breakAt).trimEnd());
+    rest = rest.slice(breakAt).trimStart();
+  }
+  if (rest.length) out.push(rest);
+  return out;
+}
+function showNote(body, title) {
+  p.note(wrapText(body, contentWidth(14)), title);
+}
+function showSaved(paths2) {
+  p.log.step("Saved");
+  const width = contentWidth(4);
+  for (const filePath of paths2) {
+    for (const line of wrapText(filePath, width).split("\n")) {
+      console.log(`  ${line}`);
+    }
+  }
+}
+function showCommand(command) {
+  p.log.step("yt-dlp command");
+  for (const line of wrapText(command, contentWidth(4)).split("\n")) {
+    console.log(`  ${line}`);
+  }
+}
+
+// src/questions.ts
+function isCancel2(value) {
+  return p2.isCancel(value);
+}
+function exitOnCancel(value) {
+  if (isCancel2(value)) {
+    p2.cancel("Cancelled.");
+    process.exit(0);
+  }
+}
+function looksLikeUrl2(input) {
+  try {
+    const u = new URL(input);
+    return u.protocol === "http:" || u.protocol === "https:";
+  } catch {
+    return false;
+  }
+}
+function formatDuration(seconds) {
+  if (seconds == null || Number.isNaN(seconds)) return "unknown duration";
+  const h = Math.floor(seconds / 3600);
+  const m = Math.floor(seconds % 3600 / 60);
+  const s = Math.floor(seconds % 60);
+  if (h > 0) return `${h}h ${m}m ${s}s`;
+  if (m > 0) return `${m}m ${s}s`;
+  return `${s}s`;
+}
+function availableResolutions(meta) {
+  const heights = /* @__PURE__ */ new Set();
+  for (const f of meta.formats ?? []) {
+    if (f.height && f.vcodec && f.vcodec !== "none") {
+      heights.add(f.height);
+    }
+  }
+  return [...heights].sort((a, b) => b - a);
+}
+function availableSubtitleLangs(meta) {
+  const langs = /* @__PURE__ */ new Set();
+  for (const key of Object.keys(meta.subtitles ?? {})) {
+    if (key && key !== "live_chat") langs.add(key);
+  }
+  if (langs.size === 0) {
+    for (const key of Object.keys(meta.automatic_captions ?? {})) {
+      if (key && key !== "live_chat") langs.add(key);
+    }
+  }
+  return [...langs].sort();
+}
+function isPlaylistUrl(url, meta) {
+  if (meta.playlist || meta._type === "playlist") return true;
+  try {
+    const u = new URL(url);
+    return u.searchParams.has("list");
+  } catch {
+    return false;
+  }
+}
+async function promptUrl(initial) {
+  if (initial && looksLikeUrl2(initial)) return initial;
+  const url = await p2.text({
+    message: "Paste the video URL",
+    placeholder: "https://www.youtube.com/watch?v=\u2026",
+    initialValue: initial ?? "",
+    validate: (v) => {
+      if (!v?.trim()) return "URL is required";
+      if (!looksLikeUrl2(v.trim())) return "That does not look like a valid http(s) URL";
+    }
+  });
+  exitOnCancel(url);
+  return String(url).trim();
+}
+async function askQuestions(url, meta) {
+  const title = meta.title ?? "Unknown title";
+  const uploader = meta.uploader ?? "Unknown uploader";
+  const duration = formatDuration(meta.duration);
+  showNote(`${title}
+by ${uploader} \xB7 ${duration}`, "Found");
+  const mode = await p2.select({
+    message: "What do you want to download?",
+    options: [
+      { value: "video", label: "Video (with audio)" },
+      { value: "audio", label: "Audio only" },
+      { value: "video-only", label: "Video only (no audio)" },
+      { value: "subs-only", label: "Subtitles only" },
+      { value: "thumbnail-only", label: "Thumbnail only" }
+    ]
+  });
+  exitOnCancel(mode);
+  let videoQuality;
+  let container;
+  let audioFormat;
+  let audioQuality;
+  if (mode === "video" || mode === "video-only") {
+    const resolutions = availableResolutions(meta);
+    const qualityOpts = [
+      { value: "best", label: "Best available" },
+      { value: "1080", label: "Up to 1080p" },
+      { value: "720", label: "Up to 720p" },
+      { value: "480", label: "Up to 480p" }
+    ];
+    if (resolutions.length > 0) {
+      qualityOpts.push({
+        value: "pick",
+        label: "Choose from available resolutions\u2026"
+      });
+    }
+    const q = await p2.select({
+      message: "Video quality?",
+      options: qualityOpts
+    });
+    exitOnCancel(q);
+    if (q === "pick") {
+      const picked = await p2.select({
+        message: "Available resolutions",
+        options: resolutions.map((h) => ({
+          value: String(h),
+          label: `${h}p`
+        }))
+      });
+      exitOnCancel(picked);
+      videoQuality = { height: Number(picked) };
+    } else if (q === "best") {
+      videoQuality = "best";
+    } else {
+      videoQuality = q;
+    }
+    const c = await p2.select({
+      message: "Container preference?",
+      options: [
+        { value: "best", label: "Best available" },
+        { value: "mp4", label: "mp4" },
+        { value: "mkv", label: "mkv" },
+        { value: "webm", label: "webm" }
+      ]
+    });
+    exitOnCancel(c);
+    container = c;
+  }
+  if (mode === "audio") {
+    const fmt = await p2.select({
+      message: "Audio format?",
+      options: [
+        { value: "mp3", label: "mp3" },
+        { value: "m4a", label: "m4a" },
+        { value: "opus", label: "opus" },
+        { value: "flac", label: "flac" },
+        { value: "wav", label: "wav" },
+        { value: "best", label: "Best (no convert)" }
+      ]
+    });
+    exitOnCancel(fmt);
+    audioFormat = fmt;
+    const aq = await p2.select({
+      message: "Audio quality?",
+      options: [
+        { value: "best", label: "Best" },
+        { value: "good", label: "Good (smaller file)" }
+      ]
+    });
+    exitOnCancel(aq);
+    audioQuality = aq;
+  }
+  let subMode = "none";
+  let subLangs = [];
+  if (mode === "subs-only") {
+    subMode = "write";
+    const langs = availableSubtitleLangs(meta);
+    if (langs.length === 0) {
+      p2.log.warn('No subtitle languages found in metadata \u2014 will request "all".');
+      subLangs = ["all"];
+    } else {
+      const picked = await p2.multiselect({
+        message: "Which subtitle languages?",
+        options: [
+          { value: "all", label: "All languages" },
+          ...langs.map((l) => ({ value: l, label: l }))
+        ],
+        required: true
+      });
+      exitOnCancel(picked);
+      const sel = picked;
+      subLangs = sel.includes("all") ? ["all"] : sel;
+    }
+  } else if (mode !== "thumbnail-only") {
+    const wantSubs = await p2.confirm({
+      message: "Download subtitles?",
+      initialValue: false
+    });
+    exitOnCancel(wantSubs);
+    if (wantSubs) {
+      const langs = availableSubtitleLangs(meta);
+      if (langs.length === 0) {
+        p2.log.warn('No subtitle languages found \u2014 will request "all".');
+        subLangs = ["all"];
+      } else {
+        const picked = await p2.multiselect({
+          message: "Which subtitle languages?",
+          options: [
+            { value: "all", label: "All languages" },
+            ...langs.map((l) => ({ value: l, label: l }))
+          ],
+          required: true
+        });
+        exitOnCancel(picked);
+        const sel = picked;
+        subLangs = sel.includes("all") ? ["all"] : sel;
+      }
+      const how = await p2.select({
+        message: "How should subtitles be saved?",
+        options: [
+          { value: "embed", label: "Embed in the video" },
+          { value: "write", label: "Separate .srt / subtitle file" },
+          { value: "both", label: "Both embed and separate file" }
+        ]
+      });
+      exitOnCancel(how);
+      subMode = how;
+    }
+  }
+  let playlist = { kind: "single" };
+  if (isPlaylistUrl(url, meta)) {
+    const pl = await p2.select({
+      message: "This URL is part of a playlist. What should we download?",
+      options: [
+        { value: "single", label: "Just this video" },
+        { value: "all", label: "Whole playlist" },
+        { value: "range", label: "A specific range" }
+      ]
+    });
+    exitOnCancel(pl);
+    if (pl === "single") {
+      playlist = { kind: "single" };
+    } else if (pl === "all") {
+      playlist = { kind: "all" };
+    } else {
+      const start = await p2.text({
+        message: "Playlist start index (1-based)",
+        initialValue: "1",
+        validate: (v) => {
+          const n = Number(v);
+          if (!Number.isInteger(n) || n < 1) return "Enter a positive integer";
+        }
+      });
+      exitOnCancel(start);
+      const stop = await p2.text({
+        message: "Playlist stop index (inclusive)",
+        initialValue: String(meta.playlist_count ?? 10),
+        validate: (v) => {
+          const n = Number(v);
+          if (!Number.isInteger(n) || n < 1) return "Enter a positive integer";
+        }
+      });
+      exitOnCancel(stop);
+      playlist = {
+        kind: "range",
+        start: Number(start),
+        stop: Number(stop)
+      };
+    }
+  }
+  const defaultDir = join4(homedir(), "Downloads");
+  const outDir = await p2.text({
+    message: "Destination folder",
+    initialValue: defaultDir,
+    validate: (v) => !v?.trim() ? "Folder is required" : void 0
+  });
+  exitOnCancel(outDir);
+  const filenamePreset = await p2.select({
+    message: "Filename style?",
+    options: [
+      { value: "title", label: "Title only" },
+      {
+        value: "title-channel",
+        label: "Title + Channel"
+      },
+      {
+        value: "title-date",
+        label: "Title + Upload Date"
+      }
+    ]
+  });
+  exitOnCancel(filenamePreset);
+  const extras = mode === "subs-only" || mode === "thumbnail-only" ? [] : await (async () => {
+    const e = await p2.multiselect({
+      message: "Extras (optional)",
+      options: [
+        {
+          value: "thumbnail",
+          label: "Embed thumbnail as cover art"
+        },
+        { value: "metadata", label: "Embed metadata" },
+        {
+          value: "sponsorblock",
+          label: "SponsorBlock: remove sponsor segments"
+        }
+      ],
+      required: false
+    });
+    exitOnCancel(e);
+    return e;
+  })();
+  const selectedMode = mode;
+  const selectedFilename = filenamePreset;
+  const summaryLines = [
+    `Mode: ${selectedMode}`,
+    videoQuality ? `Quality: ${typeof videoQuality === "object" ? `${videoQuality.height}p` : videoQuality}` : null,
+    container ? `Container: ${container}` : null,
+    audioFormat ? `Audio: ${audioFormat} (${audioQuality ?? "best"})` : null,
+    subMode !== "none" ? `Subtitles: ${subMode} [${subLangs.join(", ")}]` : "Subtitles: none",
+    `Playlist: ${playlist.kind}${playlist.kind === "range" ? ` ${playlist.start}:${playlist.stop}` : ""}`,
+    `Output: ${String(outDir).trim()}`,
+    `Filename: ${selectedFilename}`,
+    extras.length ? `Extras: ${extras.join(", ")}` : "Extras: none"
+  ].filter(Boolean).join("\n");
+  showNote(summaryLines, "Summary");
+  const showCmd = await p2.confirm({
+    message: "Show the yt-dlp command before downloading?",
+    initialValue: false
+  });
+  exitOnCancel(showCmd);
+  return {
+    url,
+    mode: selectedMode,
+    videoQuality,
+    container,
+    audioFormat,
+    audioQuality,
+    subtitles: {
+      mode: subMode,
+      languages: subLangs
+    },
+    playlist,
+    outputDir: String(outDir).trim(),
+    filenamePreset: selectedFilename,
+    embedThumbnail: extras.includes("thumbnail"),
+    embedMetadata: extras.includes("metadata"),
+    sponsorBlock: extras.includes("sponsorblock"),
+    showCommand: Boolean(showCmd)
+  };
+}
+
+// src/cli.ts
+async function runWizard(urlArg, opts = {}) {
+  p3.intro("easy-ytdlp");
+  const spinner2 = p3.spinner();
+  spinner2.start("Preparing yt-dlp binary\u2026");
+  let ytDlp;
+  try {
+    ytDlp = await createYtDlp({
+      onStatus: (msg) => {
+        spinner2.message(msg);
+      }
+    });
+    spinner2.stop("yt-dlp ready");
+  } catch (err) {
+    spinner2.stop("Binary setup failed");
+    p3.log.error(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+  }
+  const url = await promptUrl(urlArg);
+  spinner2.start("Fetching video info\u2026");
+  let meta;
+  try {
+    meta = await fetchMetadata(ytDlp, url);
+    spinner2.stop("Metadata loaded");
+  } catch (err) {
+    spinner2.stop("Could not fetch metadata");
+    p3.log.error(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+  }
+  const answers = await askQuestions(url, meta);
+  if (opts.showCommand) {
+    answers.showCommand = true;
+  }
+  const flags = buildFlags(answers);
+  const displayFlags = [
+    ...youtubeCompatFlags(),
+    ...progressFlags(),
+    ...flags
+  ];
+  if (answers.showCommand) {
+    showCommand(formatCommand(displayFlags));
+    const proceed = await p3.confirm({
+      message: "Run this command?",
+      initialValue: true
+    });
+    if (p3.isCancel(proceed) || !proceed) {
+      p3.cancel("Cancelled.");
+      process.exit(0);
+    }
+  } else {
+    const proceed = await p3.confirm({
+      message: "Start download?",
+      initialValue: true
+    });
+    if (p3.isCancel(proceed) || !proceed) {
+      p3.cancel("Cancelled.");
+      process.exit(0);
+    }
+  }
+  if (needsFfmpeg(answers.mode, {
+    embedSubs: answers.subtitles.mode === "embed" || answers.subtitles.mode === "both",
+    embedThumbnail: answers.embedThumbnail,
+    extractAudio: answers.mode === "audio"
+  })) {
+    const status = await checkFfmpeg();
+    if (!status.ok) {
+      p3.log.warn(
+        [
+          "ffmpeg/ffprobe not found on PATH.",
+          ffmpegInstallHint()
+        ].join("\n\n")
+      );
+      const cont = await p3.confirm({
+        message: "Continue anyway? (download may fail at merge/extract)",
+        initialValue: false
+      });
+      if (p3.isCancel(cont) || !cont) {
+        p3.cancel("Cancelled.");
+        process.exit(0);
+      }
+    }
+  }
+  p3.log.info("Starting download\u2026");
+  try {
+    const result = await runDownload(ytDlp, flags);
+    if (result.filepaths.length > 0) {
+      showSaved(result.filepaths);
+    } else {
+      p3.log.success("Done. (No filepath printed \u2014 check your output folder.)");
+      p3.log.info(`Output folder: ${answers.outputDir}`);
+    }
+    p3.outro("Finished");
+  } catch (err) {
+    p3.log.error(err instanceof Error ? err.message : String(err));
+    p3.outro("Failed");
+    process.exit(1);
+  }
+}
+async function runUpdateBinary() {
+  p3.intro("easy-ytdlp update-binary");
+  const spinner2 = p3.spinner();
+  spinner2.start("Refreshing yt-dlp binary\u2026");
+  try {
+    const path = await updateBinary((msg) => spinner2.message(msg));
+    spinner2.stop(`Updated: ${path}`);
+    p3.outro("Binary update complete");
+  } catch (err) {
+    spinner2.stop("Update failed");
+    p3.log.error(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+  }
+}
+var program = new Command();
+program.name("easy-ytdlp").description(
+  "Interactive, user-friendly wrapper around yt-dlp \u2014 no flag memorization required"
+).version("1.0.0").argument("[url]", "Video URL (prompted if omitted)").option(
+  "--show-command",
+  "Always show the generated yt-dlp command before running"
+).action(async (url, options) => {
+  await runWizard(url, { showCommand: options.showCommand });
+});
+program.command("update-binary").description("Force-refresh the cached yt-dlp binary").action(async () => {
+  await runUpdateBinary();
+});
+program.parseAsync(process.argv).catch((err) => {
+  console.error(err instanceof Error ? err.message : err);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@jnzlab/easy-ytdlp",
+  "version": "1.0.0",
+  "description": "A user-friendly interactive CLI wrapper for yt-dlp — no Python or flag memorization required",
+  "type": "module",
+  "main": "./dist/cli.js",
+  "types": "./dist/cli.d.ts",
+  "bin": {
+    "easy-ytdlp": "bin/easy-ytdlp.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsup src/cli.ts --format esm --dts --clean --outDir dist",
+    "dev": "tsx src/cli.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "yt-dlp",
+    "youtube",
+    "download",
+    "cli",
+    "video"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@clack/prompts": "^0.10.0",
+    "cli-progress": "^3.12.0",
+    "commander": "^13.1.0",
+    "env-paths": "^3.0.0",
+    "yt-dlp-wrap": "^2.3.12"
+  },
+  "devDependencies": {
+    "@types/cli-progress": "^3.11.6",
+    "@types/node": "^22.13.10",
+    "tsup": "^8.4.0",
+    "tsx": "^4.19.3",
+    "typescript": "^5.8.2",
+    "vitest": "^3.0.8"
+  }
+}