@mailo037/veo 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 veo 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,104 @@
+# veo
+
+A small, clean video-downloading CLI powered by [yt-dlp](https://github.com/yt-dlp/yt-dlp). No banners, just progress and the saved file path.
+
+**Only download content you own or are authorized or legally permitted to download.** Respect copyright, website terms, and access restrictions. veo does not bypass DRM, private-content access controls, or paywalls.
+
+## Install and run
+
+Requires **Node.js 22+** and npm. Internet access is needed for installation and first-use backend setup.
+
+The npm package is `@mailo037/veo`; the installed command is `veo`.
+Once this package has been published:
+
+```bash
+npx @mailo037/veo "https://example.com/video.mp4"
+```
+
+Or install globally:
+
+```bash
+npm install -g @mailo037/veo
+veo "https://example.com/video.mp4"
+```
+
+From this checkout, without publishing:
+
+```bash
+npm install
+node bin/veo.js --help
+npm link
+veo "https://example.com/video.mp4"
+```
+
+`package.json` maps `"veo": "./bin/veo.js"`; npm creates the executable/shim automatically. No custom command prefix is needed. Use only trusted URLs, and quote URLs to protect query strings from your shell.
+
+## Usage
+
+```text
+veo <url> [options]
+
+-q, --quality <quality>   best, 2160p, 1440p, 1080p, 720p, 480p, 360p
+-o, --output <path>       Output directory (default: current working directory)
+--audio                  Audio only (MP3 by default)
+--format <format>        Video: mp4, mkv, webm, mov
+                         Audio: mp3, m4a, aac, opus, flac, wav
+--version                Show version
+-h, --help               Show help
+```
+
+```bash
+veo "https://youtube.com/watch?v=VIDEO_ID" -q 1080p
+veo "https://x.com/USER/status/STATUS_ID" -q best
+veo "https://example.com/video.mp4" --audio
+veo "https://example.com/video.mp4" --audio --format flac
+veo "https://example.com/video.mp4" --format webm -o ./videos
+npx @mailo037/veo "https://example.com/video.mp4" --output ./downloads
+```
+
+- One video per invocation; playlists and live streams are not supported.
+- Numeric quality selects the nearest **available video height**, not just a maximum. Ties choose the lower height. Unknown heights fall back to best. `--quality` does not apply to audio.
+- MP4-compatible codecs are preferred at the selected resolution; merged video prefers MP4 with MKV fallback. A single-file source may retain its original container. Use `--format mp4` to explicitly require MP4 (conversion may be slow or lossy).
+- `--format` on video enables conversion when necessary. Audio formats require `--audio`.
+- Original titles are preserved, with invalid filename characters sanitized and overly long names shortened. Existing files are never intentionally overwritten: duplicates get ` (1)`, ` (2)`, etc.
+- Downloads and conversion use a private temporary directory inside the output directory. The completed file is copied to a collision-safe final name, so allow extra disk space. Temporary files are removed on ordinary failure or Ctrl+C; force-killing the process may leave `.veo-*` directories to remove manually. Partial downloads are not resumed between invocations.
+- Progress shows percentage, speed, downloaded/total size and ETA on stderr; unknown values appear as `?`. Separate audio/video streams each have their own progress. Non-interactive output is throttled. The final path is printed on stdout as `Saved: ...`.
+- Exit status is `0` on success, `1` on errors, and `130` on cancellation.
+
+## Supported sites and backend
+
+YouTube, X/Twitter, TikTok, Vimeo, Reddit, Instagram, and [many other yt-dlp sites](https://github.com/yt-dlp/yt-dlp/blob/master/supportedsites.md) are supported **when publicly accessible and technically available**. Support changes with websites, regions, rate limits, and backend versions; it is not a guarantee that every URL will work. Authentication/cookie flags are not exposed in this initial version.
+
+Official standalone yt-dlp is acquired on first download and cached outside the package directory; help/version never download it. The release is pinned and SHA-256 verified against hashes shipped with this package. FFmpeg and FFprobe are supplied by the `ffmpeg-static` and `ffprobe-static` dependencies during npm installation. These binaries have their own licenses; see their upstream packages. Normal installs must allow dependency install scripts. No Python installation is needed on supported standalone platforms.
+
+The existing Node executable is explicitly enabled as yt-dlp's JavaScript runtime for YouTube. Local yt-dlp configuration and plugins are disabled for predictable execution. Arguments are passed without a shell.
+
+Advanced overrides for managed installations:
+
+- `VEO_YT_DLP_PATH`: absolute path to a trusted, current yt-dlp executable.
+- `VEO_FFMPEG_PATH`: directory containing both `ffmpeg` and `ffprobe` executables (with `.exe` on Windows).
+
+Automatic yt-dlp acquisition covers mainstream Windows, macOS and Linux architectures; FFmpeg/FFprobe platform availability may be narrower. Unsupported systems should supply trusted native binaries. A blocked GitHub request, proxy, disabled install scripts, or unsupported native binary can prevent setup; errors include guidance. Maintainers should update the pinned yt-dlp release and hashes as websites change, or users can supply an up-to-date executable override.
+
+## Develop and publish
+
+```bash
+npm install
+npm test
+npm run test:smoke
+npm pack --dry-run
+npm link
+veo --version
+# Then, authenticated as the account that owns the name:
+npm publish
+```
+
+The smoke test generates a two-second synthetic video with FFmpeg, serves it on loopback, and runs real yt-dlp downloads. It checks default output, duplicate names, quality fallback, audio extraction, conversion and nonzero failures. It needs network access once for yt-dlp acquisition; it downloads no third-party video. Unit tests require no network.
+
+The published tarball only includes `bin/`, `src/`, package metadata, README and LICENSE. The lockfile is kept for reproducible development. There is no build step. npm makes the shebang-bearing bin executable on installation (on Unix, `chmod +x bin/veo.js` also enables direct checkout execution).
+
+Modules separate argument parsing (`src/cli.js`), backend setup (`src/backend.js`), download orchestration (`src/downloader.js`), progress (`src/progress.js`), and filename/error helpers (`src/utils.js`) so new options and providers can be added without replacing the CLI.
+
+## License
+
+MIT for this CLI. yt-dlp and FFmpeg/FFprobe retain their respective upstream licenses.

package/bin/veo.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { main } from '../src/cli.js';
+
+process.exitCode = await main();

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@mailo037/veo",
+  "version": "1.0.0",
+  "description": "A clean, simple video downloader powered by yt-dlp.",
+  "type": "module",
+  "bin": {
+    "veo": "bin/veo.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "test": "node --test",
+    "test:smoke": "node scripts/smoke.js",
+    "prepublishOnly": "npm test"
+  },
+  "keywords": [
+    "cli",
+    "video",
+    "downloader",
+    "yt-dlp",
+    "audio"
+  ],
+  "license": "MIT",
+  "preferGlobal": true,
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "ffmpeg-static": "5.3.0",
+    "ffprobe-static": "3.1.0"
+  }
+}

package/src/backend.js

@@ -0,0 +1,223 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { createReadStream, createWriteStream, constants } from 'node:fs';
+import { access, chmod, copyFile, lstat, mkdir, rename, rm, stat } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import os from 'node:os';
+import path from 'node:path';
+import { Readable, Transform } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+
+const require = createRequire(import.meta.url);
+export const RELEASE = '2026.08.19';
+const RELEASE_URL = `https://github.com/yt-dlp/yt-dlp/releases/download/${RELEASE}`;
+const MAX_BYTES = 256 * 1024 * 1024;
+const DOWNLOAD_TIMEOUT = 180_000;
+// Official hashes fetched at development time; never trust a runtime checksum download.
+// https://github.com/yt-dlp/yt-dlp/releases/download/2026.08.19/SHA2-256SUMS
+const HASHES = Object.freeze({
+  'yt-dlp.exe': '66674953fe251b89f4d08c5f0e35e0728679bd67ab3d7d05c0562af101dd3e7a',
+  'yt-dlp_arm64.exe': '05b438997bafc3affdfda9d041353c9d73e04dc842207254b655b0887c4445b0',
+  'yt-dlp_x86.exe': 'a8f91bd41452506bc81ebd2f369b186fea0ee7075413ba00cef9fd346a0a5d0c',
+  'yt-dlp_macos': '0f192b7ec147ab6288885d6351d9ab67367640029b4377576ef46dd79cf7b202',
+  'yt-dlp_linux': '58162f9bfdc27458ea47bfcb311cf47028f17d8154a8bf7d689861d46399230a',
+  'yt-dlp_linux_aarch64': 'b16e4dab368a816cd05d477d698a605a6ae87ccee1c8ffd38fa21d7254141fcc',
+  'yt-dlp_musllinux': 'f3dec9cfeaf304cec98290fe41c6ad465d4b747d302473559643e7af24929722',
+  'yt-dlp_musllinux_aarch64': '17b164c4d258be92bb1ad146cb7c336b783aedb380814aabbcb7d52937f77e57',
+});
+
+export function selectAsset(platform = process.platform, arch = process.arch, musl = false) {
+  if (platform === 'win32') return { x64: 'yt-dlp.exe', arm64: 'yt-dlp_arm64.exe', ia32: 'yt-dlp_x86.exe' }[arch];
+  if (platform === 'darwin' && ['x64', 'arm64'].includes(arch)) return 'yt-dlp_macos';
+  if (platform === 'linux' && ['x64', 'arm64'].includes(arch)) return `yt-dlp_${musl ? 'musl' : ''}linux${arch === 'arm64' ? '_aarch64' : ''}`;
+}
+
+function cacheDirectory(asset) {
+  const home = os.homedir();
+  let base;
+  if (process.platform === 'win32') base = process.env.LOCALAPPDATA || path.join(home, 'AppData', 'Local');
+  else if (process.platform === 'darwin') base = path.join(home, 'Library', 'Caches');
+  else base = process.env.XDG_CACHE_HOME || path.join(home, '.cache');
+  // Invalid relative OS cache settings must not write into the working directory.
+  if (!path.isAbsolute(base)) base = path.join(home, '.cache');
+  return path.join(base, 'veo', 'backends', RELEASE, `${process.platform}-${process.arch}`);
+}
+
+function envPath(name) {
+  if (!(name in process.env)) return undefined;
+  const value = process.env[name];
+  if (!value?.trim() || value.includes('\0')) throw new Error(`${name} must be a non-empty filesystem path.`);
+  return path.resolve(value);
+}
+
+async function executable(file, label) {
+  if (typeof file !== 'string' || !file) throw new Error(`${label} is unavailable on ${process.platform}/${process.arch}.`);
+  try {
+    if (!(await stat(file)).isFile()) throw new Error('not a regular file');
+    await access(file, process.platform === 'win32' ? constants.R_OK : constants.X_OK);
+  } catch (cause) {
+    throw new Error(`${label} is missing or not executable: ${file}`, { cause });
+  }
+  return path.resolve(file);
+}
+
+async function sha256(file, signal) {
+  signal?.throwIfAborted();
+  const hash = createHash('sha256');
+  let bytes = 0;
+  for await (const chunk of createReadStream(file, { signal })) {
+    bytes += chunk.length;
+    if (bytes > MAX_BYTES) throw new Error(`Backend file exceeds ${MAX_BYTES / 1024 / 1024} MiB: ${file}`);
+    hash.update(chunk);
+  }
+  return hash.digest('hex');
+}
+
+async function matches(file, expected, signal) {
+  try {
+    const info = await lstat(file);
+    // Do not accept cached symlinks or special files.
+    if (!info.isFile() || info.size > MAX_BYTES) return false;
+    return await sha256(file, signal) === expected;
+  } catch (error) {
+    if (error.code === 'ENOENT') return false;
+    throw error;
+  }
+}
+
+async function publish(temp, destination, expected, signal) {
+  signal?.throwIfAborted();
+  if (process.platform !== 'win32') await chmod(temp, 0o755);
+  try {
+    await rename(temp, destination);
+  } catch (error) {
+    // Another process may have finished the same acquisition on Windows.
+    if (['EEXIST', 'EPERM', 'EACCES'].includes(error.code)
+      && await matches(destination, expected, signal)) return;
+    // A directory at the destination is stale cache from an older layout.
+    if (['EEXIST', 'EPERM', 'EACCES', 'ENOTEMPTY', 'EISDIR'].includes(error.code)) {
+      const info = await lstat(destination).catch(() => undefined);
+      if (info?.isDirectory()) {
+        await rm(destination, { recursive: true, force: true });
+        try { await rename(temp, destination); return; } catch { /* Fall through. */ }
+      }
+    }
+    throw error;
+  }
+}
+
+async function acquire(asset, directory, signal, status) {
+  const destination = path.join(directory, process.platform === 'win32' ? 'yt-dlp.exe' : 'yt-dlp');
+  const expected = HASHES[asset];
+  status('Checking yt-dlp…');
+  if (await matches(destination, expected, signal)) {
+    if (process.platform !== 'win32') await chmod(destination, 0o755);
+    return destination;
+  }
+  const temp = `${destination}.${randomUUID()}.tmp`;
+  const timeout = AbortSignal.timeout(DOWNLOAD_TIMEOUT);
+  const downloadSignal = signal ? AbortSignal.any([signal, timeout]) : timeout;
+  status(`Downloading yt-dlp ${RELEASE} (first use)…`);
+  try {
+    const response = await fetch(`${RELEASE_URL}/${asset}`, { signal: downloadSignal });
+    if (!response.ok || !response.body) {
+      await response.body?.cancel();
+      throw new Error(`yt-dlp download failed: HTTP ${response.status}.`);
+    }
+    if (Number(response.headers.get('content-length')) > MAX_BYTES) {
+      await response.body.cancel();
+      throw new Error('yt-dlp download exceeds the size limit.');
+    }
+    let bytes = 0;
+    const hash = createHash('sha256');
+    const verifier = new Transform({
+      transform(chunk, encoding, callback) {
+        bytes += chunk.length;
+        if (bytes > MAX_BYTES) return callback(new Error('yt-dlp download exceeds the size limit.'));
+        hash.update(chunk);
+        callback(null, chunk);
+      },
+    });
+    await pipeline(Readable.fromWeb(response.body), verifier,
+      createWriteStream(temp, { flags: 'wx', mode: 0o600 }), { signal: downloadSignal });
+    if (hash.digest('hex') !== expected) throw new Error('yt-dlp SHA-256 verification failed. The download was discarded.');
+    await publish(temp, destination, expected, downloadSignal);
+    return destination;
+  } catch (cause) {
+    signal?.throwIfAborted();
+    if (timeout.aborted) throw new Error('yt-dlp download timed out after 3 minutes. Please retry.', { cause });
+    throw new Error(`Unable to prepare yt-dlp: ${cause.message} You can set VEO_YT_DLP_PATH to a trusted local executable.`, { cause });
+  } finally {
+    await rm(temp, { force: true });
+  }
+}
+
+async function stage(source, destination, signal) {
+  const expected = await sha256(source, signal);
+  if (await matches(destination, expected, signal)) {
+    if (process.platform !== 'win32') await chmod(destination, 0o755);
+    return;
+  }
+  const temp = `${destination}.${randomUUID()}.tmp`;
+  try {
+    signal?.throwIfAborted();
+    await copyFile(source, temp, constants.COPYFILE_EXCL);
+    if (!await matches(temp, expected, signal)) throw new Error(`Backend copy verification failed: ${source}`);
+    await publish(temp, destination, expected, signal);
+  } finally {
+    await rm(temp, { force: true });
+  }
+}
+
+/**
+ * Resolve native tools without executing them or using a shell.
+ * VEO_YT_DLP_PATH: trusted executable file; bypasses acquisition/pinned hash checks.
+ * VEO_FFMPEG_PATH: directory containing both ffmpeg[.exe] and ffprobe[.exe].
+ * Relative overrides resolve against cwd; no PATH search or install-time custom hook.
+ * ffmpeg-static's own FFMPEG_BIN override is honored by its normal module API.
+ * onStatus receives plain strings. Throws on cancellation or acquisition failure.
+ */
+export async function resolveBackend({ signal, onStatus } = {}) {
+  if (signal !== undefined && !(signal instanceof AbortSignal)) throw new TypeError('signal must be an AbortSignal.');
+  if (onStatus !== undefined && typeof onStatus !== 'function') throw new TypeError('onStatus must be a function.');
+  signal?.throwIfAborted();
+  const status = onStatus || (() => {});
+  const ytOverride = envPath('VEO_YT_DLP_PATH');
+  const ffOverride = envPath('VEO_FFMPEG_PATH');
+  // Diagnostic reports expose glibc when linked against it; no shell probe needed.
+  const musl = process.platform === 'linux' && !process.report.getReport().header.glibcVersionRuntime;
+  const asset = ytOverride ? undefined : selectAsset(process.platform, process.arch, musl);
+  if (!ytOverride && !asset) throw new Error(`No standalone yt-dlp is available for ${process.platform}/${process.arch}. Set VEO_YT_DLP_PATH to a trusted executable.`);
+  // Validate overrides and dependencies before doing any network work.
+  let ytDlp = ytOverride ? await executable(ytOverride, 'VEO_YT_DLP_PATH') : undefined;
+  const suffix = process.platform === 'win32' ? '.exe' : '';
+  let ffmpeg;
+  let ffprobe;
+  if (ffOverride) {
+    await executable(path.join(ffOverride, `ffmpeg${suffix}`), 'VEO_FFMPEG_PATH ffmpeg');
+    await executable(path.join(ffOverride, `ffprobe${suffix}`), 'VEO_FFMPEG_PATH ffprobe');
+  } else {
+    // ffprobe-static exits the process on unsupported OSes/arches: guard before require.
+    if (!['win32', 'darwin', 'linux'].includes(process.platform)
+      || (process.platform === 'darwin' && !['x64', 'arm64'].includes(process.arch))
+      || (process.platform === 'win32' && process.arch === 'arm64')) {
+      throw new Error('Static media tools do not support this platform. Set VEO_FFMPEG_PATH to a directory containing ffmpeg and ffprobe.');
+    }
+    try {
+      ffmpeg = await executable(require('ffmpeg-static'), 'ffmpeg-static');
+      ffprobe = await executable(require('ffprobe-static').path, 'ffprobe-static');
+    } catch (cause) {
+      throw new Error(`Cannot load media tools: ${cause.message} Install ffmpeg-static and ffprobe-static, or set VEO_FFMPEG_PATH to a directory containing both binaries.`, { cause });
+    }
+  }
+  const directory = cacheDirectory(asset);
+  if (!ytOverride || !ffOverride) await mkdir(directory, { recursive: true, mode: 0o700 });
+  if (!ytDlp) ytDlp = await acquire(asset, directory, signal, status);
+  else status('Using VEO_YT_DLP_PATH override.');
+  if (!ffOverride) {
+    status('Preparing ffmpeg and ffprobe…');
+    await stage(ffmpeg, path.join(directory, `ffmpeg${suffix}`), signal);
+    await stage(ffprobe, path.join(directory, `ffprobe${suffix}`), signal);
+  } else status('Using VEO_FFMPEG_PATH override.');
+  signal?.throwIfAborted();
+  return { ytDlp, ffmpegLocation: ffOverride || directory };
+}

package/src/cli.js

@@ -0,0 +1,73 @@
+import { parseArgs } from 'node:util';
+import { readFile } from 'node:fs/promises';
+import { createReporter } from './progress.js';
+import { QUALITIES, VIDEO_FORMATS, AUDIO_FORMATS, validateUrl, readableError, cleanText } from './utils.js';
+
+export const HELP = `veo - simple video downloader
+
+Usage:
+  veo <url> [options]
+
+Options:
+  -q, --quality <quality>   Video quality (best, 2160p, 1440p, 1080p, 720p, 480p, 360p)
+  -o, --output <path>       Output directory (default: current directory)
+  --audio                  Download audio only (default: mp3)
+  --format <format>        Video: mp4, mkv, webm, mov; audio: mp3, m4a, aac, opus, flac, wav
+  --version                Show version
+  -h, --help               Show help
+
+Examples:
+  veo "https://youtube.com/watch?v=..."
+  veo <url> -q 1080p
+  veo <url> --audio
+  veo <url> -o ./downloads
+
+Only download content you are authorized or legally permitted to download.
+`;
+
+export function parseCli(args) {
+  const { values, positionals } = parseArgs({ args, allowPositionals: true, strict: true, options: {
+    quality: { type: 'string', short: 'q', default: 'best' },
+    output: { type: 'string', short: 'o', default: process.cwd() },
+    audio: { type: 'boolean', default: false },
+    format: { type: 'string' },
+    help: { type: 'boolean', short: 'h' },
+    version: { type: 'boolean' },
+  } });
+  if (values.help || values.version) return values;
+  if (positionals.length !== 1) throw new Error('Provide exactly one video URL. Run veo --help for usage.');
+  if (!QUALITIES.includes(values.quality)) throw new Error(`Invalid quality. Choose: ${QUALITIES.join(', ')}.`);
+  if (!values.output.trim()) throw new Error('The output directory cannot be empty.');
+  if (values.audio && values.quality !== 'best') throw new Error('--quality is for video; omit it when using --audio.');
+  const formats = values.audio ? AUDIO_FORMATS : VIDEO_FORMATS;
+  if (values.format && !formats.includes(values.format)) throw new Error(`Invalid ${values.audio ? 'audio' : 'video'} format. Choose: ${formats.join(', ')}.${!values.audio && AUDIO_FORMATS.includes(values.format) ? ' Use --audio for audio formats.' : ''}`);
+  return { ...values, url: validateUrl(positionals[0]) };
+}
+
+export async function main(args = process.argv.slice(2)) {
+  const reporter = createReporter();
+  const controller = new AbortController();
+  const cancel = () => controller.abort();
+  process.once('SIGINT', cancel);
+  process.once('SIGTERM', cancel);
+  try {
+    const options = parseCli(args);
+    if (options.help) { process.stdout.write(HELP); return 0; }
+    if (options.version) {
+      const pkg = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8'));
+      process.stdout.write(`${pkg.version}\n`);
+      return 0;
+    }
+    const { download } = await import('./downloader.js');
+    const saved = await download(options, { signal: controller.signal, reporter });
+    process.stdout.write(`Saved: ${cleanText(saved)}\n`);
+    return 0;
+  } catch (error) {
+    reporter.finish();
+    process.stderr.write(`veo: ${readableError(error)}\n`);
+    return controller.signal.aborted ? 130 : 1;
+  } finally {
+    process.removeListener('SIGINT', cancel);
+    process.removeListener('SIGTERM', cancel);
+  }
+}

package/src/downloader.js

@@ -0,0 +1,87 @@
+import { spawn } from 'node:child_process';
+import { createInterface } from 'node:readline';
+import { mkdir, mkdtemp, rm, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { resolveBackend } from './backend.js';
+import { closestHeight, saveUnique } from './utils.js';
+
+export function runBackend(executable, args, { signal, onLine } = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(executable, args, { shell: false, windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'], signal });
+    let output = '';
+    let errors = '';
+    let failure;
+    const lines = createInterface({ input: child.stdout });
+    lines.on('line', line => {
+      if (onLine) {
+        try { onLine(line); } catch (error) { failure = error; child.kill(); }
+      } else if (output.length < 32 * 1024 * 1024) output += `${line}\n`;
+      else { failure = new Error('Video metadata exceeded the supported size.'); child.kill(); }
+    });
+    child.stderr.on('data', data => { errors = (errors + data).slice(-16000); });
+    child.on('error', error => { failure = error; });
+    child.on('close', code => {
+      lines.close();
+      if (failure) reject(failure);
+      else if (signal?.aborted) reject(new DOMException('Cancelled', 'AbortError'));
+      else if (code !== 0) reject(new Error(errors || `Downloading backend exited with code ${code}.`));
+      else resolve(output);
+    });
+  });
+}
+
+export function formatSelector(height) {
+  const filter = height ? `[height=${height}]` : '';
+  return `bv${filter}+ba/b${filter}/bv${filter}`;
+}
+
+export async function download(options, { signal, reporter, backendResolver = resolveBackend } = {}) {
+  const directory = path.resolve(options.output);
+  await mkdir(directory, { recursive: true });
+  const backend = await backendResolver({ signal, onStatus: message => reporter?.status(message) });
+  const common = ['--ignore-config', '--no-plugin-dirs', '--no-playlist', '--no-colors', '--no-warnings',
+    '--socket-timeout', '30', '--retries', '3', '--fragment-retries', '3',
+    '--no-js-runtimes', '--js-runtimes', `node:${process.execPath}`,
+    '--ffmpeg-location', backend.ffmpegLocation];
+  reporter?.status('Reading video…');
+  const metadata = JSON.parse(await runBackend(backend.ytDlp,
+    [...common, '--dump-single-json', '--skip-download', '--', options.url], { signal }));
+  if (metadata._type === 'playlist' || metadata.entries) throw new Error('This URL is a collection. Please provide a single video URL.');
+  if (metadata.is_live) throw new Error('Live streams are not supported. Please use a finished video.');
+  if (metadata.has_drm) throw new Error('This content is DRM-protected.');
+  const height = options.audio ? null : closestHeight(metadata.formats || [metadata], options.quality);
+  if (!options.audio && options.quality !== 'best') {
+    reporter?.status(height ? `Quality: ${height}p${height !== parseInt(options.quality, 10) ? ` (closest to ${options.quality})` : ''}` : 'Resolution unknown; using the best available stream.');
+  }
+  const temporary = await mkdtemp(path.join(directory, '.veo-'));
+  try {
+    // A private staging directory keeps titles out of yt-dlp templates and isolates partial files.
+    const template = path.join(temporary, 'media.%(ext)s').replaceAll('%', '%%').replace('%%(ext)s', '%(ext)s');
+    const args = [...common, '--no-overwrites', '--no-continue', '--newline', '--progress', '--progress-delta', '0.2',
+      '--progress-template', 'download:veo-progress:%(progress)j',
+      '--print', 'after_move:veo-file:%(filepath)j', '--no-simulate', '-o', template];
+    if (options.audio) args.push('-f', 'ba/b', '--extract-audio', '--audio-format', options.format || 'mp3', '--audio-quality', '0');
+    else {
+      args.push('-f', formatSelector(height));
+      // Merge into a permissive container first; e.g. H.264 cannot be merged
+      // straight into WebM before the requested codec conversion runs.
+      if (options.format) args.push('--merge-output-format', 'mkv', '--recode-video', options.format);
+      else args.push('-S', 'vcodec:h264,acodec:aac', '--merge-output-format', 'mp4/mkv');
+    }
+    args.push('--', options.url);
+    let saved;
+    reporter?.status(options.audio ? 'Downloading audio…' : 'Downloading…');
+    await runBackend(backend.ytDlp, args, { signal, onLine(line) {
+      if (line.startsWith('veo-progress:')) reporter?.progress(JSON.parse(line.slice('veo-progress:'.length)));
+      if (line.startsWith('veo-file:')) saved = JSON.parse(line.slice('veo-file:'.length));
+    } });
+    if (!saved) throw new Error('The backend finished without producing a file.');
+    saved = path.resolve(saved);
+    if (path.dirname(saved) !== temporary || !(await stat(saved)).isFile()) throw new Error('The backend returned an invalid saved file path.');
+    signal?.throwIfAborted();
+    return await saveUnique(saved, directory, metadata.title || metadata.id || 'video');
+  } finally {
+    reporter?.finish();
+    await rm(temporary, { recursive: true, force: true });
+  }
+}

package/src/progress.js

@@ -0,0 +1,40 @@
+import { cleanText } from './utils.js';
+
+function bytes(value) {
+  if (!Number.isFinite(value) || value < 0) return '?';
+  const units = ['B', 'KiB', 'MiB', 'GiB', 'TiB'];
+  let i = 0;
+  while (value >= 1024 && i < units.length - 1) { value /= 1024; i++; }
+  return `${value.toFixed(i ? 1 : 0)} ${units[i]}`;
+}
+
+export function formatProgress(data) {
+  const done = Number.isFinite(data.downloaded_bytes) ? data.downloaded_bytes : 0;
+  const total = data.total_bytes || data.total_bytes_estimate;
+  const percent = total > 0 ? Math.min(100, done / total * 100) : null;
+  const filled = percent === null ? 0 : Math.round(percent / 5);
+  const eta = Number.isFinite(data.eta) ? `${Math.floor(data.eta / 60)}:${String(Math.floor(data.eta % 60)).padStart(2, '0')}` : '?';
+  return `[${'='.repeat(filled)}${'-'.repeat(20 - filled)}] ${percent === null ? '  ?' : percent.toFixed(0).padStart(3)}%  ${bytes(data.speed)}/s  ${bytes(done)} / ${bytes(total)}  ETA ${eta}`;
+}
+
+export function createReporter(stream = process.stderr) {
+  let active = false;
+  let lastLog = 0;
+  function clear() {
+    if (active && stream.isTTY) stream.write('\r\x1b[2K');
+    active = false;
+  }
+  return {
+    status(message) { clear(); stream.write(`${cleanText(message)}\n`); },
+    progress(data) {
+      if (stream.isTTY) {
+        stream.write(`\r\x1b[2K${formatProgress(data)}`);
+        active = true;
+      } else if (Date.now() - lastLog >= 5000 || data.status === 'finished') {
+        stream.write(`${formatProgress(data)}\n`);
+        lastLog = Date.now();
+      }
+    },
+    finish: clear,
+  };
+}

package/src/utils.js

@@ -0,0 +1,76 @@
+import path from 'node:path';
+import { copyFile, unlink } from 'node:fs/promises';
+import { constants } from 'node:fs';
+
+export const QUALITIES = ['best', '2160p', '1440p', '1080p', '720p', '480p', '360p'];
+export const VIDEO_FORMATS = ['mp4', 'mkv', 'webm', 'mov'];
+export const AUDIO_FORMATS = ['mp3', 'm4a', 'aac', 'opus', 'flac', 'wav'];
+
+export function validateUrl(input) {
+  try {
+    const url = new URL(input);
+    if (!['http:', 'https:'].includes(url.protocol) || !url.hostname || url.username || url.password) throw new Error();
+    return url.href;
+  } catch {
+    throw new Error('Invalid URL. Use a complete http:// or https:// video URL without embedded credentials.');
+  }
+}
+
+// Untrusted site titles must never become paths, terminal escapes, or device names.
+export function sanitizeTitle(title) {
+  let name = String(title || 'video').normalize('NFC')
+    .replace(/[<>:"/\\|?*\x00-\x1f\x7f-\x9f\u202a-\u202e\u2066-\u2069]/g, '_')
+    .trim().replace(/[. ]+$/g, '');
+  if (/^(con|prn|aux|nul|com[1-9¹²³]|lpt[1-9¹²³])(?:\.|$)/i.test(name)) name = `_${name}`;
+  let shortened = '';
+  for (const char of name) {
+    if (Buffer.byteLength(shortened + char) > 180) break;
+    shortened += char;
+  }
+  return shortened.replace(/[. ]+$/g, '') || 'video';
+}
+
+export function cleanText(value) {
+  return String(value).replace(/\x1b\[[0-?]*[ -/]*[@-~]/g, '').replace(/[\x00-\x1f\x7f-\x9f\u202a-\u202e\u2066-\u2069]/g, ' ').trim();
+}
+
+export function closestHeight(formats, quality) {
+  if (quality === 'best') return null;
+  const target = Number.parseInt(quality, 10);
+  const heights = [...new Set(formats.filter(f => f.vcodec !== 'none' && !f.has_drm && Number.isFinite(f.height) && f.height > 0).map(f => f.height))];
+  // Equidistant alternatives prefer the smaller download.
+  return heights.sort((a, b) => Math.abs(a - target) - Math.abs(b - target) || a - b)[0] ?? null;
+}
+
+// COPYFILE_EXCL makes name allocation race-safe, including concurrent veo processes.
+export async function saveUnique(source, directory, title) {
+  const extension = path.extname(source).toLowerCase();
+  if (!/^\.[a-z0-9]{1,8}$/.test(extension)) throw new Error('The backend returned an invalid output extension.');
+  const name = sanitizeTitle(title);
+  for (let number = 0; ; number++) {
+    const destination = path.join(directory, `${name}${number ? ` (${number})` : ''}${extension}`);
+    try {
+      await copyFile(source, destination, constants.COPYFILE_EXCL);
+    } catch (error) {
+      if (error.code === 'EEXIST') continue;
+      throw error;
+    }
+    await unlink(source);
+    return destination;
+  }
+}
+
+export function readableError(error) {
+  if (error.name === 'AbortError') return 'Cancelled.';
+  if (error.code === 'EACCES' || error.code === 'EPERM') return 'Permission denied. Choose a writable output directory or check executable permissions.';
+  if (error.code === 'ENOSPC') return 'Not enough disk space to save the download.';
+  const text = cleanText(error.message || error);
+  if (/unsupported url|no suitable extractor/i.test(text)) return 'This URL or website is not supported by the downloading backend.';
+  if (/private|login required|sign in|log in|authentication|members.only|not a bot|cookies/i.test(text)) return 'This content is private or requires authentication. veo does not bypass access controls; use a publicly accessible video you are allowed to download.';
+  if (/deleted|removed|no longer available|404|not found|does not exist/i.test(text)) return 'The content was deleted, removed, or could not be found.';
+  if (/requested format|no video formats|no suitable formats|conversion failed|error opening encoder|could not find tag/i.test(text)) return 'The requested format is unavailable or could not be converted. Try -q best or another --format.';
+  if (/drm.protected|digital rights/i.test(text)) return 'This content is DRM-protected. veo does not remove DRM.';
+  if (/network|timed? ?out|connection|resolve|ENOTFOUND|ECONN|fetch failed|HTTP Error (403|429|5\d\d)/i.test(text)) return 'Network request failed or the site blocked the request. Check your connection and URL, then try again later.';
+  if (/not available|unavailable|geo.?restrict|country/i.test(text)) return 'This content is unavailable or restricted in your region.';
+  return text.slice(-1200) || 'Download failed. Please try again.';
+}