ytdwn 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Batikan Kutluer
+
+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,136 @@
+# YTDWN
+
+A fast and simple CLI tool to download audio from YouTube videos. Powered by [yt-dlp](https://github.com/yt-dlp/yt-dlp).
+
+## ✨ Features
+
+- 🎵 Download audio from YouTube in MP3 or other formats
+- ✂️ Clip specific sections of videos (e.g., `1:30-2:45`)
+- 📁 Set a default download folder
+- 🚀 Fast parallel downloads with concurrent fragments
+- 🎨 Beautiful progress bar and colored output
+- 📦 Auto-downloads yt-dlp binary if not present
+
+## 📋 Requirements
+
+- [Node.js](https://nodejs.org) >= 18.0.0 or [Bun](https://bun.sh) >= 1.0.0
+
+## 🚀 Installation
+
+### Using npm/npx
+
+```bash
+# Run directly without installing
+npx ytdwn prepare
+npx ytdwn https://www.youtube.com/watch?v=VIDEO_ID
+
+# Or install globally
+npm install -g ytdwn
+ytdwn prepare
+ytdwn https://www.youtube.com/watch?v=VIDEO_ID
+```
+
+### Using Bun
+
+```bash
+# Run directly without installing
+bunx ytdwn prepare
+bunx ytdwn https://www.youtube.com/watch?v=VIDEO_ID
+
+# Or install globally
+bun add -g ytdwn
+ytdwn prepare
+ytdwn https://www.youtube.com/watch?v=VIDEO_ID
+```
+
+### From Source
+
+```bash
+# Clone the repository
+git clone https://github.com/batikankutluer/ytdwn.git
+cd ytdwn
+
+# Install dependencies
+bun install
+
+# Run directly from source (no build needed)
+bun run index.ts prepare
+bun run index.ts https://www.youtube.com/watch?v=VIDEO_ID
+
+# Or build and use the compiled version
+bun run build
+node dist/index.js prepare
+```
+
+## 📖 Usage
+
+### Basic Download
+
+```bash
+# Download audio from a YouTube URL
+ytdwn https://www.youtube.com/watch?v=VIDEO_ID
+
+# Or use the short form
+ytdwn https://youtu.be/VIDEO_ID
+```
+
+### Options
+
+| Flag                    | Description                    | Example          |
+| ----------------------- | ------------------------------ | ---------------- |
+| `-f, --format <format>` | Audio format (default: mp3)    | `-f opus`        |
+| `-c, --clip <range>`    | Clip a specific time range     | `-c 01:30-02:45` |
+| `-q, --quiet`           | Minimal output (only filename) | `-q`             |
+| `-v, --version`         | Show version                   | `-v`             |
+| `-h, --help`            | Show help                      | `-h`             |
+
+### Examples
+
+```bash
+# Download as MP3 (default)
+ytdwn https://www.youtube.com/watch?v=VIDEO_ID
+
+# Download as OPUS format
+ytdwn https://www.youtube.com/watch?v=VIDEO_ID -f opus
+
+# Download only a portion (from 1:30 to 2:45)
+ytdwn https://www.youtube.com/watch?v=VIDEO_ID -c 1:30-2:45
+
+# Quiet mode - outputs only the filename
+ytdwn https://www.youtube.com/watch?v=VIDEO_ID -q
+```
+
+### Commands
+
+```bash
+# Download and prepare yt-dlp binary
+ytdwn prepare
+
+# Set default download folder
+ytdwn setDefaultFolder ~/Music/YouTube
+
+# View current download folder
+ytdwn setDefaultFolder
+
+# Reset to current directory
+ytdwn setDefaultFolder --reset
+```
+
+## ⚙️ Configuration
+
+Settings are stored in `~/.ytdwn.json`:
+
+- `downloadDir`: Default folder for downloaded files
+- `binaryPath`: Cached path to yt-dlp binary
+
+## 🛠️ Tech Stack
+
+- **Runtime**: [Node.js](https://nodejs.org) or [Bun](https://bun.sh)
+- **CLI Framework**: [Commander.js](https://github.com/tj/commander.js)
+- **Downloader**: [yt-dlp](https://github.com/yt-dlp/yt-dlp)
+- **Audio Processing**: [FFmpeg](https://ffmpeg.org)
+- **Styling**: [cfonts](https://github.com/dominikwilkowski/cfonts), [gradient-string](https://github.com/bokub/gradient-string), [picocolors](https://github.com/alexeyraspopov/picocolors)
+
+## 📄 License
+
+MIT - see [LICENSE](LICENSE) file for details

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,562 @@
+#!/usr/bin/env node
+
+// index.ts
+import { program } from "commander";
+
+// src/config.ts
+import { join } from "path";
+var APP_NAME = "ytdwn";
+var APP_TAGLINE = "YouTube to MP3 • Fast & Simple";
+var APP_VERSION = "1.0.0";
+var DEFAULT_FORMAT = "mp3";
+var DEFAULT_AUDIO_QUALITY = "0";
+var CONCURRENT_FRAGMENTS = "8";
+var BIN_DIR = join(process.cwd(), "bin");
+var getOutputTemplate = (downloadDir) => join(downloadDir, "%(title)s.%(ext)s");
+
+// src/binary.ts
+import { constants as fsConstants } from "fs";
+import { access, chmod, mkdir, writeFile as writeFile2 } from "fs/promises";
+import { platform } from "os";
+import { join as join3, dirname } from "path";
+import YTDlpWrap from "yt-dlp-wrap";
+
+// src/settings.ts
+import { readFile, writeFile } from "fs/promises";
+import { homedir } from "os";
+import { join as join2, resolve } from "path";
+var SETTINGS_PATH = join2(homedir(), ".ytdwn.json");
+async function load() {
+  try {
+    return JSON.parse(await readFile(SETTINGS_PATH, "utf-8"));
+  } catch {
+    return {};
+  }
+}
+var save = (settings) => writeFile(SETTINGS_PATH, JSON.stringify(settings, null, 2));
+async function getDownloadDir() {
+  const { downloadDir } = await load();
+  return downloadDir ?? process.cwd();
+}
+async function setDownloadDir(dir) {
+  const settings = await load();
+  await save({ ...settings, downloadDir: resolve(dir) });
+}
+async function resetDownloadDir() {
+  const { downloadDir, ...rest } = await load();
+  await save(rest);
+}
+async function getCachedBinaryPath() {
+  const { binaryPath } = await load();
+  return binaryPath ?? null;
+}
+async function setCachedBinaryPath(path) {
+  const settings = await load();
+  await save({ ...settings, binaryPath: path });
+}
+async function clearCachedBinaryPath() {
+  const { binaryPath, ...rest } = await load();
+  await save(rest);
+}
+
+// src/binary.ts
+var BINARY_NAMES = {
+  win32: ["yt-dlp.exe"],
+  darwin: {
+    arm64: ["yt-dlp_macos_arm64", "yt-dlp_macos_aarch64", "yt-dlp_macos"],
+    x64: ["yt-dlp_macos"]
+  },
+  linux: {
+    arm64: ["yt-dlp_linux_arm64", "yt-dlp_linux_aarch64", "yt-dlp"],
+    x64: ["yt-dlp_linux", "yt-dlp"]
+  }
+};
+var FALLBACK_BINARY = "yt-dlp";
+function getCandidateNames() {
+  const platformNames = BINARY_NAMES[process.platform];
+  if (!platformNames)
+    return [FALLBACK_BINARY];
+  if (Array.isArray(platformNames))
+    return platformNames;
+  const archNames = platformNames[process.arch];
+  return archNames ?? [FALLBACK_BINARY];
+}
+function getCandidatePaths() {
+  return getCandidateNames().map((name) => join3(BIN_DIR, name));
+}
+async function isExecutable(filePath) {
+  try {
+    await access(filePath, fsConstants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function downloadFile(url, targetPath) {
+  await mkdir(dirname(targetPath), { recursive: true });
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new Error(`Download failed: ${response.status} ${response.statusText}`);
+  }
+  await writeFile2(targetPath, Buffer.from(await response.arrayBuffer()));
+  if (platform() !== "win32") {
+    await chmod(targetPath, 493);
+  }
+}
+function pickAsset(release) {
+  const assets = release.assets ?? [];
+  const candidates = getCandidateNames();
+  const match = assets.find((a) => candidates.includes(a.name)) ?? assets.find((a) => a.name === FALLBACK_BINARY);
+  if (!match) {
+    throw new Error("Suitable yt-dlp binary not found for this platform.");
+  }
+  return match;
+}
+async function findBinary() {
+  const cached = await getCachedBinaryPath();
+  if (cached && await isExecutable(cached)) {
+    return cached;
+  }
+  for (const candidate of getCandidatePaths()) {
+    if (await isExecutable(candidate)) {
+      await setCachedBinaryPath(candidate);
+      return candidate;
+    }
+  }
+  if (cached)
+    await clearCachedBinaryPath();
+  return null;
+}
+async function requireBinary() {
+  const existing = await findBinary();
+  if (existing)
+    return existing;
+  throw new Error("yt-dlp binary not found. Run 'ytdwn prepare' first.");
+}
+async function downloadLatestBinary() {
+  const [release] = await YTDlpWrap.getGithubReleases(1, 1);
+  if (!release) {
+    throw new Error("Failed to fetch yt-dlp release from GitHub.");
+  }
+  const asset = pickAsset(release);
+  const binaryPath = join3(BIN_DIR, asset.name);
+  if (await isExecutable(binaryPath)) {
+    await setCachedBinaryPath(binaryPath);
+    return binaryPath;
+  }
+  await downloadFile(asset.browser_download_url, binaryPath);
+  await setCachedBinaryPath(binaryPath);
+  return binaryPath;
+}
+
+// src/download.ts
+import { mkdir as mkdir2 } from "fs/promises";
+import { spawn } from "child_process";
+import ffmpegInstaller from "@ffmpeg-installer/ffmpeg";
+
+// src/timestamp.ts
+var TIME_FORMAT_ERROR = "Invalid time format. Use MM:SS or HH:MM:SS (e.g. 0:02 or 01:23:45).";
+var RANGE_FORMAT_ERROR = "Range must be in 'start-end' format (e.g. 0:02-23:10).";
+var pad = (value) => value.padStart(2, "0");
+function normalizeTimeParts(parts) {
+  if (parts.length === 2) {
+    return ["0", parts[0] ?? "0", parts[1] ?? "0"];
+  }
+  return [parts[0] ?? "0", parts[1] ?? "0", parts[2] ?? "0"];
+}
+function parseTimestamp(raw) {
+  const parts = raw.split(":").map((p) => p.trim());
+  if (parts.length < 2 || parts.length > 3) {
+    throw new Error(TIME_FORMAT_ERROR);
+  }
+  const [h, m, s] = normalizeTimeParts(parts);
+  return `${pad(h)}:${pad(m)}:${pad(s)}`;
+}
+function parseClipRange(range) {
+  const parts = range.split("-").map((p) => p.trim());
+  if (parts.length !== 2 || !parts[0] || !parts[1]) {
+    throw new Error(RANGE_FORMAT_ERROR);
+  }
+  return `${parseTimestamp(parts[0])}-${parseTimestamp(parts[1])}`;
+}
+
+// src/colors.ts
+import pc from "picocolors";
+var c = {
+  success: (text) => pc.green(text),
+  error: (text) => pc.red(text),
+  warn: (text) => pc.yellow(text),
+  info: (text) => pc.cyan(text),
+  dim: (text) => pc.dim(text),
+  bold: (text) => pc.bold(text),
+  file: (text) => pc.bold(pc.white(text)),
+  size: (text) => pc.dim(text),
+  speed: (text) => pc.cyan(text),
+  bar: {
+    filled: (text) => pc.green(text),
+    empty: (text) => pc.dim(text),
+    percent: (text) => pc.bold(text)
+  },
+  sym: {
+    success: pc.green("✓"),
+    error: pc.red("✗"),
+    warn: pc.yellow("⚠"),
+    info: pc.cyan("ℹ"),
+    arrow: pc.dim("→")
+  }
+};
+
+// src/download.ts
+var SPINNER_FRAMES = [
+  "⠋",
+  "⠙",
+  "⠹",
+  "⠸",
+  "⠼",
+  "⠴",
+  "⠦",
+  "⠧",
+  "⠇",
+  "⠏"
+];
+var SPINNER_INTERVAL_MS = 80;
+var PROGRESS_BAR_WIDTH = 12;
+var LINE_CLEAR_WIDTH = 60;
+var REGEX = {
+  percent: /(\d+\.?\d*)%/,
+  total: /of\s+~?([\d.]+\s*\w+)/i,
+  speed: /at\s+([\d.]+\s*\w+\/s)/i,
+  size: /([\d.]+)\s*(\w+)/,
+  binaryUnits: /([KMG])iB/g,
+  destination: /\[(?:ExtractAudio|Merger)\].*?Destination:\s*(.+)$/m,
+  downloadDest: /\[download\]\s+Destination:\s*(.+)$/m,
+  fileSize: /~?([\d.]+\s*[KMG]i?B)/i
+};
+var PHASE_MESSAGES = new Map([
+  ["Extracting URL", "Extracting..."],
+  ["Downloading webpage", "Fetching info..."]
+]);
+var write = (text) => process.stdout.write(text);
+var clearLine = () => write(`\r${" ".repeat(LINE_CLEAR_WIDTH)}\r`);
+function createSpinner(initialMessage = "Getting ready...", quiet = false) {
+  let frame = 0;
+  let message = initialMessage;
+  let stopped = false;
+  if (quiet) {
+    return {
+      update: () => {},
+      stop: () => {}
+    };
+  }
+  const interval = setInterval(() => {
+    if (!stopped) {
+      const frameChar = SPINNER_FRAMES[frame++ % SPINNER_FRAMES.length] ?? "⠋";
+      write(`\r${c.info(frameChar)} ${c.dim(message)}`);
+    }
+  }, SPINNER_INTERVAL_MS);
+  return {
+    update: (msg) => {
+      message = msg;
+    },
+    stop: () => {
+      if (stopped)
+        return;
+      stopped = true;
+      clearInterval(interval);
+      clearLine();
+    }
+  };
+}
+function renderProgress({ percent, speed }, quiet = false) {
+  if (quiet)
+    return;
+  const filled = Math.round(percent / 100 * PROGRESS_BAR_WIDTH);
+  const bar = c.bar.filled("█".repeat(filled)) + c.bar.empty("░".repeat(PROGRESS_BAR_WIDTH - filled));
+  const speedText = speed ? ` ${c.speed(speed)}` : "";
+  write(`\r${c.bold("Downloading:")} ${bar} ${c.bar.percent(`${percent.toFixed(0)}%`)}${speedText}   `);
+}
+var normalizeUnit = (value) => value.replace(REGEX.binaryUnits, "$1B");
+function parseProgress(text) {
+  const percentMatch = text.match(REGEX.percent);
+  if (!percentMatch?.[1])
+    return null;
+  const percent = parseFloat(percentMatch[1]);
+  const total = text.match(REGEX.total)?.[1]?.trim();
+  const speed = text.match(REGEX.speed)?.[1];
+  let downloaded;
+  if (total) {
+    const [, size, unit] = total.match(REGEX.size) ?? [];
+    if (size && unit) {
+      downloaded = normalizeUnit(`${(percent / 100 * parseFloat(size)).toFixed(1)}${unit}`);
+    }
+  }
+  return {
+    percent,
+    downloaded,
+    total: total ? normalizeUnit(total) : undefined,
+    speed: speed ? normalizeUnit(speed) : undefined
+  };
+}
+function detectPhase(text) {
+  for (const [pattern, message] of PHASE_MESSAGES) {
+    if (text.includes(pattern))
+      return message;
+  }
+  return text.includes("Downloading") && !text.includes("%") ? "Preparing..." : null;
+}
+var isConvertingPhase = (text) => text.includes("ExtractAudio") || text.includes("Converting");
+function extractFileName(text) {
+  const match = text.match(REGEX.destination) || text.match(REGEX.downloadDest);
+  if (match?.[1]) {
+    const fullPath = match[1].trim();
+    return fullPath.split("/").pop() || null;
+  }
+  return null;
+}
+function extractFileSize(text) {
+  const match = text.match(REGEX.fileSize);
+  return match?.[1] || null;
+}
+function buildArgs(url, options, downloadDir) {
+  const baseArgs = [
+    url,
+    "-f",
+    "bestaudio/best",
+    "-x",
+    "--audio-format",
+    options.format,
+    "--audio-quality",
+    DEFAULT_AUDIO_QUALITY,
+    "-o",
+    getOutputTemplate(downloadDir),
+    "--no-playlist",
+    "--newline",
+    "--progress",
+    "--concurrent-fragments",
+    CONCURRENT_FRAGMENTS,
+    "--no-check-certificates",
+    "--prefer-free-formats"
+  ];
+  const conditionalArgs = [];
+  if (options.clip) {
+    conditionalArgs.push("--download-sections", `*${parseClipRange(options.clip)}`);
+  }
+  if (ffmpegInstaller?.path) {
+    conditionalArgs.push("--ffmpeg-location", ffmpegInstaller.path);
+  }
+  return [...baseArgs, ...conditionalArgs];
+}
+function createOutputHandler(spinner, state) {
+  return (data) => {
+    const text = data.toString();
+    const fileName = extractFileName(text);
+    if (fileName)
+      state.fileName = fileName;
+    const fileSize = extractFileSize(text);
+    if (fileSize)
+      state.fileSize = fileSize;
+    if (state.phase !== "converting" && isConvertingPhase(text)) {
+      state.phase = "converting";
+      spinner.stop();
+      clearLine();
+      if (!state.quiet) {
+        let frame = 0;
+        state.convertingInterval = setInterval(() => {
+          const frameChar = SPINNER_FRAMES[frame++ % SPINNER_FRAMES.length] ?? "⠋";
+          write(`\r${c.info(frameChar)} ${c.dim("Converting...")}`);
+        }, SPINNER_INTERVAL_MS);
+      }
+      return;
+    }
+    const progress = parseProgress(text);
+    if (progress && progress.percent > state.lastPercent) {
+      if (state.phase === "init") {
+        state.phase = "downloading";
+        spinner.stop();
+      }
+      state.lastPercent = progress.percent;
+      renderProgress(progress, state.quiet);
+      return;
+    }
+    if (state.phase === "init") {
+      const message = detectPhase(text);
+      if (message)
+        spinner.update(message);
+    }
+  };
+}
+function attachProcessHandlers(child, spinner, downloadDir, quiet) {
+  return new Promise((resolve2, reject) => {
+    const state = {
+      phase: "init",
+      lastPercent: 0,
+      fileName: null,
+      fileSize: null,
+      quiet,
+      convertingInterval: null
+    };
+    const handleOutput = createOutputHandler(spinner, state);
+    const cleanup = () => {
+      spinner.stop();
+      if (state.convertingInterval) {
+        clearInterval(state.convertingInterval);
+      }
+      if (!quiet)
+        clearLine();
+    };
+    child.stdout?.on("data", handleOutput);
+    child.stderr?.on("data", handleOutput);
+    child.on("close", (code) => {
+      cleanup();
+      if (code === 0) {
+        resolve2({
+          filePath: downloadDir,
+          fileName: state.fileName || "audio",
+          fileSize: state.fileSize || undefined
+        });
+      } else {
+        reject(new Error(`Download failed (code ${code})`));
+      }
+    });
+    child.on("error", (err) => {
+      cleanup();
+      reject(err);
+    });
+  });
+}
+async function downloadAudio(url, options) {
+  const [downloadDir, binaryPath] = await Promise.all([
+    getDownloadDir().then(async (dir) => {
+      await mkdir2(dir, { recursive: true });
+      return dir;
+    }),
+    requireBinary()
+  ]);
+  const quiet = options.quiet ?? false;
+  const spinner = createSpinner("Getting ready...", quiet);
+  const child = spawn(binaryPath, buildArgs(url, options, downloadDir));
+  return attachProcessHandlers(child, spinner, downloadDir, quiet);
+}
+
+// src/banner.ts
+import cfonts from "cfonts";
+import gradient from "gradient-string";
+var GRADIENT_COLORS = ["#ff6b6b", "#feca57", "#48dbfb", "#ff9ff3", "#54a0ff"];
+function showBanner() {
+  const result = cfonts.render(APP_NAME, {
+    font: "block",
+    align: "left",
+    colors: ["system"],
+    background: "transparent",
+    letterSpacing: 1,
+    lineHeight: 0,
+    space: false,
+    maxLength: 0,
+    rawMode: true
+  });
+  if (result && typeof result !== "boolean" && result.string) {
+    const gradientBanner = gradient(GRADIENT_COLORS)(result.string);
+    console.log(gradientBanner);
+  }
+  console.log(gradient(GRADIENT_COLORS)(`  ${APP_TAGLINE}
+
+`));
+}
+
+// index.ts
+var formatError = (err) => {
+  const msg = err instanceof Error ? err.message : String(err);
+  if (msg.includes("code 1") || msg.includes("Video unavailable")) {
+    return "Video not found or private";
+  }
+  if (msg.includes("code 2")) {
+    return "Invalid URL format";
+  }
+  if (msg.includes("age")) {
+    return "Age-restricted video (login required)";
+  }
+  if (msg.includes("network") || msg.includes("connect")) {
+    return "Connection error, try again";
+  }
+  return msg;
+};
+var exitWithError = (err) => {
+  console.error(`${c.sym.error} ${c.error("Error:")} ${formatError(err)}`);
+  process.exit(1);
+};
+var isUrl = (arg) => arg.startsWith("http://") || arg.startsWith("https://");
+async function handlePrepare() {
+  try {
+    if (await findBinary()) {
+      console.log(`${c.sym.success} ${c.success("Ready")}`);
+      return;
+    }
+    console.log(`${c.dim("Downloading yt-dlp...")}`);
+    await downloadLatestBinary();
+    console.log(`${c.sym.success} ${c.success("Ready")}`);
+  } catch (err) {
+    exitWithError(err);
+  }
+}
+async function handleSetFolder(folderPath, opts) {
+  try {
+    if (opts?.reset) {
+      await resetDownloadDir();
+      console.log(`${c.sym.success} ${c.success("Reset to current directory")}`);
+      return;
+    }
+    if (folderPath) {
+      await setDownloadDir(folderPath);
+      console.log(`${c.sym.success} ${c.info(folderPath)}`);
+    } else {
+      console.log(c.info(await getDownloadDir()));
+    }
+  } catch (err) {
+    exitWithError(err);
+  }
+}
+async function handleDownload(url, opts) {
+  try {
+    if (!opts.quiet) {
+      showBanner();
+      console.log(`${c.dim("URL:")} ${c.info(url)}
+`);
+    }
+    const result = await downloadAudio(url, {
+      format: opts.format,
+      clip: opts.clip,
+      quiet: opts.quiet
+    });
+    if (opts.quiet) {
+      console.log(result.fileName);
+    } else {
+      console.log();
+      console.log(`${c.sym.success} ${c.success("Process done!")}
+`);
+      const sizeInfo = result.fileSize ? ` ${c.size(`(${result.fileSize})`)}` : "";
+      console.log(`${c.file(result.fileName)}${sizeInfo}`);
+    }
+  } catch (err) {
+    exitWithError(err);
+  }
+}
+program.name(APP_NAME).usage("<url> [options]").description("Download audio from YouTube").version(APP_VERSION, "-v, --version").option("-f, --format <format>", "Audio format", DEFAULT_FORMAT).option("-c, --clip <range>", "Clip range (e.g. 1:30-2:45)").option("-q, --quiet", "Minimal output (only file name)").addHelpText("beforeAll", "").hook("preAction", (thisCommand) => {
+  if (thisCommand.args.includes("help") || process.argv.includes("--help") || process.argv.includes("-h")) {
+    showBanner();
+  }
+});
+program.command("prepare").description("Download yt-dlp binary").action(handlePrepare);
+program.command("setDefaultFolder [path]").description("Set or view default download folder").option("-r, --reset", "Reset to current directory").action(handleSetFolder);
+program.command("download <url>", { hidden: true }).description("Download audio from YouTube URL").option("-f, --format <format>", "Audio format", DEFAULT_FORMAT).option("-c, --clip <range>", "Clip range (e.g. 1:30-2:45)").option("-q, --quiet", "Minimal output").action(handleDownload);
+var firstArg = process.argv[2];
+if (firstArg && isUrl(firstArg)) {
+  process.argv.splice(2, 0, "download");
+}
+if (process.argv.length <= 2) {
+  showBanner();
+  program.help();
+}
+if (process.argv.includes("-v") || process.argv.includes("--version")) {
+  showBanner();
+}
+program.parse();

package/dist/src/banner.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Renders a stylish ASCII banner with gradient colors
+ */
+export declare function showBanner(): void;
+/**
+ * Renders a compact one-line banner
+ */
+export declare function showCompactBanner(): void;

package/dist/src/binary.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Finds an existing prepared binary. Uses cache for speed.
+ */
+export declare function findBinary(): Promise<string | null>;
+/**
+ * Ensures a prepared binary exists, throws if not.
+ */
+export declare function requireBinary(): Promise<string>;
+/**
+ * Downloads the latest yt-dlp binary from GitHub.
+ */
+export declare function downloadLatestBinary(): Promise<string>;

package/dist/src/colors.d.ts

@@ -0,0 +1,23 @@
+export declare const c: {
+    success: (text: string) => string;
+    error: (text: string) => string;
+    warn: (text: string) => string;
+    info: (text: string) => string;
+    dim: (text: string) => string;
+    bold: (text: string) => string;
+    file: (text: string) => string;
+    size: (text: string) => string;
+    speed: (text: string) => string;
+    bar: {
+        filled: (text: string) => string;
+        empty: (text: string) => string;
+        percent: (text: string) => string;
+    };
+    sym: {
+        success: string;
+        error: string;
+        warn: string;
+        info: string;
+        arrow: string;
+    };
+};

package/dist/src/config.d.ts

@@ -0,0 +1,8 @@
+export declare const APP_NAME = "ytdwn";
+export declare const APP_TAGLINE = "YouTube to MP3 \u2022 Fast & Simple";
+export declare const APP_VERSION = "1.0.0";
+export declare const DEFAULT_FORMAT = "mp3";
+export declare const DEFAULT_AUDIO_QUALITY = "0";
+export declare const CONCURRENT_FRAGMENTS = "8";
+export declare const BIN_DIR: string;
+export declare const getOutputTemplate: (downloadDir: string) => string;

package/dist/src/download.d.ts

@@ -0,0 +1,16 @@
+interface DownloadOptions {
+    format: string;
+    clip?: string;
+    quiet?: boolean;
+}
+interface DownloadResult {
+    filePath: string;
+    fileName: string;
+    fileSize?: string;
+}
+/**
+ * Downloads audio from a URL using yt-dlp.
+ * @returns Download result with file info
+ */
+export declare function downloadAudio(url: string, options: DownloadOptions): Promise<DownloadResult>;
+export {};

package/dist/src/settings.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Gets the download directory. Falls back to current directory if not set.
+ */
+export declare function getDownloadDir(): Promise<string>;
+/**
+ * Sets the download directory.
+ */
+export declare function setDownloadDir(dir: string): Promise<void>;
+/**
+ * Resets the download directory to default (current directory).
+ */
+export declare function resetDownloadDir(): Promise<void>;
+/**
+ * Gets the cached binary path.
+ */
+export declare function getCachedBinaryPath(): Promise<string | null>;
+/**
+ * Sets the cached binary path.
+ */
+export declare function setCachedBinaryPath(path: string): Promise<void>;
+/**
+ * Clears the cached binary path.
+ */
+export declare function clearCachedBinaryPath(): Promise<void>;

package/dist/src/timestamp.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Parses a raw timestamp string into HH:MM:SS format.
+ * Accepts MM:SS or HH:MM:SS formats.
+ */
+export declare function parseTimestamp(raw: string): string;
+/**
+ * Parses a clip range string (start-end) into normalized format.
+ */
+export declare function parseClipRange(range: string): string;

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "ytdwn",
+  "version": "1.0.0",
+  "description": "A fast and simple CLI tool to download audio from YouTube videos",
+  "author": {
+    "name": "Batikan Kutluer",
+    "url": "https://github.com/batikankutluer"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/batikankutluer/ytdwn.git"
+  },
+  "homepage": "https://github.com/batikankutluer/ytdwn#readme",
+  "bugs": {
+    "url": "https://github.com/batikankutluer/ytdwn/issues"
+  },
+  "keywords": [
+    "youtube",
+    "download",
+    "mp3",
+    "audio",
+    "yt-dlp",
+    "cli",
+    "music",
+    "converter",
+    "extractor",
+    "bun"
+  ],
+  "engines": {
+    "node": ">=18.0.0",
+    "bun": ">=1.0.0"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "ytdwn": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "dev": "bun run index.ts",
+    "build": "bun run build:clean && bun run build:bundle && bun run build:types && bun run build:chmod",
+    "build:clean": "rm -rf dist",
+    "build:bundle": "bun build ./index.ts --outfile ./dist/index.js --target node --packages external",
+    "build:types": "bun x tsc --project tsconfig.build.json --emitDeclarationOnly",
+    "build:chmod": "chmod +x dist/index.js",
+    "typecheck": "bun x tsc --noEmit",
+    "prepublishOnly": "bun run build"
+  },
+  "dependencies": {
+    "@ffmpeg-installer/ffmpeg": "^1.1.0",
+    "cfonts": "^3.3.1",
+    "commander": "^14.0.2",
+    "gradient-string": "^3.0.0",
+    "picocolors": "^1.1.1",
+    "yt-dlp-wrap": "^2.3.12"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.1.14",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0"
+  }
+}