veodl 1.8.1

package/src/jobs.js

@@ -0,0 +1,172 @@
+import { runPool, serialQueue, reducedLimit } from './execution.js';
+import { styleText } from './progress.js';
+import path from 'node:path';
+import { lstat, readdir } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import { cacheBase } from './paths.js';
+import { publicOptions, readJson, writeJson } from './state.js';
+import { cleanText, readableError, validateUrl } from './utils.js';
+
+export async function retryOptions(file) {
+  const job = await readJson(path.resolve(file), null);
+  if (job?.version !== 1 || !Array.isArray(job.items)) throw new Error('Invalid retry job file.');
+  const pending = job.items.filter(item => !['saved', 'skipped'].includes(item.status));
+  if (!pending.length) throw new Error('This job has no failed or unfinished downloads.');
+  return pending.map(item => {
+    validateUrl(item.url);
+    const entries = item.entries || [];
+    // After interruption, retry the original selection; resume history skips completed entries.
+    const failures = entries.filter(entry => entry.status === 'failed');
+    return { ...job.options, ...item.options, url: item.url, resume: true,
+      ...(item.status === 'failed' && failures.length && item.finished ? { playlistItems: failures.map(entry => entry.index).join(',') } : {}) };
+  });
+}
+
+/**
+ * Location of one run's job file. It is created before the first download starts
+ * so `veo runs <id>` can report per-item progress from it.
+ */
+export function jobFilePath(root = cacheBase()) {
+  return path.join(root, 'jobs', `${Date.now()}-${randomUUID()}.json`);
+}
+
+/** Find the newest retryable job, skipping finished jobs and active runs. */
+export async function latestFailedJob(root = cacheBase()) {
+  const directory = path.join(path.resolve(root), 'jobs');
+  const info = await lstat(directory).catch(error => { if (error.code === 'ENOENT') return null; throw error; });
+  if (!info) throw new Error('No retry jobs found. Run a download first.');
+  if (!info.isDirectory() || info.isSymbolicLink()) throw new Error(`Invalid retry job directory: ${directory}`);
+  const { listRuns } = await import('./runs.js');
+  const active = new Set((await listRuns(root)).filter(run => run.alive && run.job).map(run => path.resolve(run.job)));
+  const names = (await readdir(directory, { withFileTypes: true }))
+    .filter(entry => entry.isFile() && /^\d{13}-[a-f0-9-]{36}\.json$/.test(entry.name))
+    .map(entry => entry.name).sort().reverse();
+  for (const name of names) {
+    const file = path.join(directory, name);
+    if (active.has(file)) continue;
+    const job = await readJson(file, null).catch(error => { if (error instanceof SyntaxError) return null; throw error; });
+    if (job?.version === 1 && job.options && typeof job.options === 'object' && !Array.isArray(job.options)
+      && Array.isArray(job.items) && job.items.every(item => item && typeof item.url === 'string' && typeof item.status === 'string')
+      && job.items.some(item => !['saved', 'skipped'].includes(item.status))) return file;
+  }
+  throw new Error('No failed or unfinished retry job found.');
+}
+
+export async function runJob(options, { download, reporter, signal, openFile, stdout = process.stdout, stderr = process.stderr, jobFile, items, recordStats, recordHistory, runId, archiveRoot } = {}) {
+  const file = jobFile || jobFilePath();
+  const requests = items || options.urls.map(url => ({ ...options, url }));
+  const job = { version: 1, ...(runId ? { runId } : {}), startedAt: new Date().toISOString(), options: publicOptions({ ...options, output: path.resolve(options.output) }),
+    items: requests.map(item => ({ url: item.url, status: 'pending', entries: [] })) };
+  // Each retry item can have its own playlist selection.
+  job.items.forEach((item, index) => { item.options = publicOptions(requests[index]); });
+  const { cleanupDownloadCache } = await import('./download-cache.js');
+  await cleanupDownloadCache();
+  const queue = serialQueue();
+  const persist = () => queue(() => writeJson(file, job));
+  await persist();
+  const activeTargets = new Map();
+  const totals = { saved: 0, skipped: 0, failed: 0 };
+  const adaptiveState = { divisor: 1 };
+  const archiveTools = runId ? await import('./run-archive.js') : null;
+  const concurrency = options.concurrentDownloads ?? 2;
+  if (!Number.isInteger(concurrency) || concurrency < 1 || concurrency > 4) throw new Error('Concurrent downloads must be between 1 and 4.');
+  await runPool(requests, () => reducedLimit(concurrency, adaptiveState), async (request, index) => {
+    const targetKey = JSON.stringify([request.url, path.resolve(request.output)]);
+    const previous = activeTargets.get(targetKey);
+    let release;
+    const current = new Promise(resolve => { release = resolve; });
+    activeTargets.set(targetKey, current);
+    try {
+      await previous;
+      signal?.throwIfAborted();
+      let saved = 0, skipped = 0, failed = 0;
+      const itemReporter = concurrency > 1 && requests.length > 1 ? reporter.scoped?.(index + 1, requests.length, request.url) || reporter : reporter;
+      const item = job.items[index];
+      const captureFiles = async files => {
+        if (!archiveTools) return;
+        item.fingerprints ||= {};
+        for (const target of files || []) {
+          if (!archiveTools.isMediaFile(target) || item.fingerprints[target]) continue;
+          item.fingerprints[target] = await archiveTools.fileFingerprint(target).catch(() => null);
+        }
+      };
+      const started = performance.now();
+      const published = new Set();
+      let opened = false;
+      let title;
+      const publish = async files => {
+        if (!options.json) for (const target of files) {
+          if (!published.has(target)) stdout.write(styleText(stdout, `Saved: ${cleanText(target)}`, 'success', options.color !== false) + '\n');
+          published.add(target);
+        }
+        if (request.open && !opened && files.length) {
+          opened = true;
+          try { await openFile(files[0]); }
+          catch (error) { stderr.write(`veo: File saved, but could not launch the default app: ${readableError(error)}\n`); }
+        }
+      };
+      if (itemReporter === reporter) reporter.item?.(index + 1, requests.length, request.url);
+      try {
+        item.status = 'running';
+        await persist();
+        const result = await download(request, { reporter: itemReporter, signal, adaptiveState, skipCacheCleanup: true, onEntry: async entry => {
+          await captureFiles(entry.files);
+          item.entries.push(entry);
+          await persist();
+          if (entry.status === 'saved') saved++;
+          if (entry.status === 'skipped') skipped++;
+          if (entry.status === 'failed') failed++;
+          await publish(entry.files || []);
+        } });
+        await captureFiles(result.files);
+        Object.assign(item, { status: result.status || 'saved', files: result.files, timings: result.timings, entryTimings: result.entryTimings, finished: true });
+        title = result.title;
+        if (!item.entries.length) {
+          saved += result.saved ?? (item.status === 'saved' ? 1 : 0);
+          skipped += result.skipped ?? 0;
+          failed += result.failures?.length ?? (item.status === 'failed' ? 1 : 0);
+        }
+        if (options.json) stdout.write(`${JSON.stringify({ ...result, status: item.status, ...(runId ? { runId } : {}) })}\n`);
+        await publish(result.files);
+      } catch (error) {
+        item.status = signal?.aborted ? 'cancelled' : 'failed';
+        item.error = readableError(error);
+        if (!signal?.aborted) failed++;
+        item.files = item.entries.flatMap(entry => entry.files || []);
+        if (options.json) stdout.write(`${JSON.stringify({ url: request.url, status: item.status, error: item.error, files: item.files, ...(runId ? { runId } : {}) })}\n`);
+        else stderr.write(styleText(stderr, `veo: ${cleanText(request.url)}: ${item.error}`, 'error', options.color !== false) + '\n');
+      }
+      if (recordStats) {
+        try {
+          await recordStats({ videos: request.audio ? 0 : saved,
+            audio: request.audio ? saved : 0, failed: failed,
+            skipped: skipped, cancelled: item.status === 'cancelled' ? 1 : 0,
+            elapsedMs: Math.round(performance.now() - started) });
+        } catch (error) { stderr.write(`veo: Could not save statistics: ${readableError(error)}\n`); }
+      }
+      // History is written per finished item, so `veo history` never reports an
+      // attempt that is still running.
+      if (recordHistory) {
+        try {
+          await recordHistory({ url: request.url, title, status: item.status, runId, job: ['failed', 'cancelled'].includes(item.status) ? file : null, audio: Boolean(request.audio),
+            quality: request.quality, format: request.format, files: item.files || [], error: item.error,
+            elapsedMs: Math.round(performance.now() - started) });
+        } catch (error) { stderr.write(`veo: Could not save download history: ${readableError(error)}\n`); }
+      }
+      await persist();
+      totals.saved += saved; totals.skipped += skipped; totals.failed += failed;
+    } finally { release(); if (activeTargets.get(targetKey) === current) activeTargets.delete(targetKey); }
+  }, { signal }).catch(error => { if (!signal?.aborted) throw error; });
+  const { saved, skipped, failed } = totals;
+  if (runId) {
+    try {
+      await archiveTools.archiveRun(job, { ...(archiveRoot ? { root: archiveRoot } : {}) });
+    } catch (error) { stderr.write(`veo: Could not archive run ${runId}: ${readableError(error)}\n`); }
+    stderr.write(`Run ID: ${runId}\n`);
+  }
+  const unfinished = job.items.some(item => !['saved', 'skipped'].includes(item.status));
+  stderr.write(styleText(stderr, `Summary: ${saved} saved, ${skipped} skipped, ${failed} failed${signal?.aborted ? ', cancelled' : ''}.`, unfinished ? 'error' : 'success', options.color !== false && !options.json) + '\n');
+  if (unfinished) stderr.write(`Retry failed/unfinished downloads: veo --retry-failed "${file}"\n`);
+  if (unfinished) reporter.fail(Boolean(signal?.aborted)); else reporter.complete();
+  return signal?.aborted ? 130 : unfinished ? 1 : 0;
+}

package/src/legacy-config-comments.js

@@ -0,0 +1,106 @@
+// Compatibility data for comments generated by the former German template.
+// These strings are recognized during migration, never emitted as new UI text.
+const translations = new Map([
+  [
+    "// veo: kommentierte Konfigurationsvorlage",
+    "// veo: commented configuration template"
+  ],
+  [
+    "// Speichern und den Editor schliessen. Beim naechsten Aufruf gelten die Einstellungen.",
+    "// Save and close the editor. Settings apply the next time you run veo."
+  ],
+  [
+    "// Kommentare mit // oder /* ... */ sind erlaubt. CLI-Optionen haben Vorrang.",
+    "// Comments using // or /* ... */ are supported. Command-line options take priority."
+  ],
+  [
+    "// Option aktivieren: die beiden // davor entfernen und den Wert anpassen.",
+    "// To enable an option, remove its leading // and adjust the value."
+  ],
+  [
+    "// Zwischen aktiven Eintraegen steht ein Komma, nach dem letzten keines.",
+    "// Separate active entries with commas. Do not add a comma after the last entry."
+  ],
+  [
+    "// Zielordner: / oder doppelte Backslashes verwenden, z.B. \"D:\\\\Videos\".",
+    "// Output directory: use / or double backslashes, for example \"D:\\\\Videos\"."
+  ],
+  [
+    "// Ohne output wird im aktuellen Arbeitsordner gespeichert.",
+    "// Without output, downloads are saved in the current working directory."
+  ],
+  [
+    "// Maximale Videoaufloesung: best, 2160p, 1440p, 1080p, 720p, ...",
+    "// Maximum video resolution: best, 2160p, 1440p, 1080p, 720p, ..."
+  ],
+  [
+    "// Videoformat: mp4, mkv, webm, mov. Konvertierung kann Zeit brauchen.",
+    "// Video format: mp4, mkv, webm, mov. Conversion can take time."
+  ],
+  [
+    "// \"open\": false,              // Fertige Datei automatisch oeffnen",
+    "// \"open\": false,              // Open the completed file automatically"
+  ],
+  [
+    "// \"resume\": true,             // Abgebrochene Downloads fortsetzen",
+    "// \"resume\": true,             // Resume interrupted downloads"
+  ],
+  [
+    "// \"skipExisting\": true,       // Bereits gespeicherte Downloads ueberspringen",
+    "// \"skipExisting\": true,       // Skip previously saved downloads"
+  ],
+  [
+    "// \"concurrentFragments\": 4,   // Gleichzeitige Fragmente: 1 bis 16",
+    "// \"concurrentFragments\": 4,   // Concurrent fragments: 1 to 16"
+  ],
+  [
+    "// Untertitel und Zusatzinformationen:",
+    "// Subtitles and additional information:"
+  ],
+  [
+    "// \"subLangs\": \"de,en\",        // Aktiviert Untertitel fuer diese Sprachen",
+    "// \"subLangs\": \"de,en\",        // Enable subtitles for these languages"
+  ],
+  [
+    "// \"embedSubs\": true,          // Untertitel ins Video einbetten",
+    "// \"embedSubs\": true,          // Embed subtitles in the video"
+  ],
+  [
+    "// \"embedMetadata\": true,      // Titel, Datum usw. einbetten",
+    "// \"embedMetadata\": true,      // Embed the title, date and other metadata"
+  ],
+  [
+    "// \"embedThumbnail\": true,     // Vorschaubild einbetten",
+    "// \"embedThumbnail\": true,     // Embed the thumbnail"
+  ],
+  [
+    "// Profile werden nur mit --profile NAME oder im interaktiven Dialog aktiviert.",
+    "// Profiles are activated only with --profile NAME or in the interactive wizard."
+  ],
+  [
+    "// Beispiel: veo \"https://example.com/video.mp4\" --profile musik",
+    "// Example: veo \"https://example.com/video.mp4\" --profile music"
+  ],
+  [
+    "// Nur Audio. Formate: mp3, m4a, aac, opus, flac, wav.",
+    "// Audio only. Formats: mp3, m4a, aac, opus, flac, wav."
+  ],
+  [
+    "// Referenz: Beispiele bei Bedarf in die bestehende Konfiguration unten uebernehmen.",
+    "// Reference: copy any examples you need into your existing configuration below."
+  ],
+  [
+    "// Deine bestehenden Einstellungen:",
+    "// Your existing settings:"
+  ]
+]);
+
+export function translateLegacyConfigComments(text) {
+  if (!text.replace(/^\uFEFF/, '').startsWith('// veo: kommentierte Konfigurationsvorlage')) return text;
+  return text.replace(/^([ \t]*(?:\/\/[ \t]*)?)(\/\/[^\r\n]*)/gm, (line, prefix, comment) => {
+    const translated = translations.get(comment);
+    if (translated) return prefix + translated.replace('--profile music', '--profile NAME');
+    // Profile names in the commented reference are examples, not active settings.
+    return prefix + comment.replace(/^(\/\/[ \t]*")musik("\s*:)/, '$1music$2').replace(/^(\/\/[ \t]*")archiv("\s*:)/, '$1archive$2');
+  });
+}

package/src/naming.js

@@ -0,0 +1,50 @@
+import path from 'node:path';
+import { lstat, mkdir } from 'node:fs/promises';
+import { sanitizeTitle } from './utils.js';
+
+const FIELDS = new Set(['title', 'id', 'channel', 'year', 'playlist', 'index']);
+export function validateTemplate(template, { folders = false } = {}) {
+  if (typeof template !== 'string' || !template.trim()) throw new Error('A naming template cannot be empty.');
+  if (path.win32.isAbsolute(template) || path.posix.isAbsolute(template) || /[:\\\x00-\x1f]/.test(template)) throw new Error('Templates must be relative and use / for subfolders.');
+  if (!folders && template.includes('/')) throw new Error('Use --folder-template for subfolders.');
+  if (template.split('/').some(part => !part.trim() || ['.', '..'].includes(part.trim()))) throw new Error('Templates cannot contain empty, . or .. path components.');
+  const rest = template.replace(/\{([^{}]+)\}/g, (_, field) => {
+    if (!FIELDS.has(field)) throw new Error(`Unknown template field: ${field}. Use ${[...FIELDS].map(key => `{${key}}`).join(', ')}.`);
+    return '';
+  });
+  if (/[{}]/.test(rest)) throw new Error('Unbalanced braces in naming template.');
+  return template;
+}
+
+export function mediaDestination(options, metadata, fallbackTitle) {
+  const fields = {
+    title: metadata.title || metadata.id || 'video', id: metadata.id || 'unknown',
+    channel: metadata.channel || metadata.uploader || 'Unknown channel',
+    year: /^\d{4}/.exec(metadata.upload_date || '')?.[0] || 'Unknown year',
+    playlist: options._playlistTitle || metadata.playlist_title || metadata.playlist || 'No playlist',
+    index: String(options._entryIndex || metadata.playlist_index || 1).padStart(3, '0'),
+  };
+  const expand = template => template.replace(/\{([^{}]+)\}/g, (_, field) => sanitizeTitle(String(fields[field])));
+  const title = options.filenameTemplate ? sanitizeTitle(expand(validateTemplate(options.filenameTemplate))) : fallbackTitle;
+  const folders = options.folderTemplate ? validateTemplate(options.folderTemplate, { folders: true }).split('/').map(part => sanitizeTitle(expand(part))) : [];
+  return { directory: path.resolve(options.output, ...folders), title };
+}
+
+// Refuse symlink/junction subfolders: metadata must never redirect a save outside output.
+export async function prepareDestination(root, directory, { create = false } = {}) {
+  root = path.resolve(root); directory = path.resolve(directory);
+  const relative = path.relative(root, directory);
+  if (relative.startsWith('..' + path.sep) || relative === '..' || path.isAbsolute(relative)) throw new Error('Destination escapes output directory.');
+  if (create) await mkdir(root, { recursive: true });
+  let current = root;
+  for (const component of relative.split(path.sep).filter(Boolean)) {
+    current = path.join(current, component);
+    const info = await lstat(current).catch(error => { if (error.code === 'ENOENT') return null; throw error; });
+    if (info && (!info.isDirectory() || info.isSymbolicLink())) throw new Error(`Output subfolder is not a plain directory: ${current}`);
+    if (!info && create) {
+      await mkdir(current).catch(error => { if (error.code !== 'EEXIST') throw error; });
+      const created = await lstat(current);
+      if (!created.isDirectory() || created.isSymbolicLink()) throw new Error(`Output subfolder is not a plain directory: ${current}`);
+    }
+  }
+}

package/src/open-file.js

@@ -0,0 +1,15 @@
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+
+// Pass the absolute filename as one argument, never through a shell. Detach so
+// a media player that stays running does not keep the CLI alive.
+export function openFile(filename, { platform = process.platform, spawnProcess = spawn } = {}) {
+  const command = platform === 'win32' ? 'explorer.exe' : platform === 'darwin' ? 'open'
+    : platform === 'android' ? 'termux-open' : 'xdg-open';
+  const absolute = path.resolve(filename);
+  return new Promise((resolve, reject) => {
+    const child = spawnProcess(command, [absolute], { shell: false, detached: true, stdio: 'ignore', windowsHide: true });
+    child.once('error', reject);
+    child.once('spawn', () => { child.unref(); resolve(); });
+  });
+}

package/src/output.js

@@ -0,0 +1,61 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { styleText } from './progress.js';
+
+const settings = new AsyncLocalStorage();
+export const withOutputSettings = (enabled, work) => settings.run({ enabled }, work);
+
+export function outputOptions(args) {
+  let profile, color;
+  const remaining = [];
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--') { remaining.push(...args.slice(i)); break; }
+    if (arg === '--profile' || arg.startsWith('--profile=')) {
+      profile = arg === '--profile' ? args[++i] : arg.slice(10);
+      if (!profile || profile.startsWith('--')) throw new Error('--profile requires a profile name.');
+    } else {
+      if (arg === '--color') color = true;
+      if (arg === '--no-color') color = false;
+      remaining.push(arg);
+    }
+  }
+  return { profile, color, remaining };
+}
+
+export function formatOutput(text, stream, enabled = settings.getStore()?.enabled !== false) {
+  return text.split(/(\r?\n)/).map(line => {
+    if (!line.trim() || /\x1b/.test(line)) return line;
+    const value = line.trim();
+    let role = 'muted';
+    if (/^(?:veo (?:stats|history|runs|stop|doctor|flush|update|backend)\b|veo \d[^ ]* doctor|ID\s+PID\s+STATE|Usage:|Options:|Commands:|Examples:|\d+\. )/.test(value)) role = 'title';
+    if (/^(?:\[?OK\]?\s|Saved:|Flushed:|Stopped\b|Removed\b|Config OK:|Statistics reset|Managed tools are ready)|\bis up to date\b|\bupdated to\b|\binstalled and will be used\b/i.test(value)) role = 'success';
+    if (/^(?:\[?FAIL\]?\s|Error:|veo: (?!note:))|Status:\s*(?:failed|cancelled)/i.test(value)) role = 'error';
+    if (/Status:\s*saved/.test(value)) role = 'success';
+    if (/^(?:Videos saved|Audio saved|Download time):/.test(value)) role = 'title';
+    if (/^Total failures:\s*[1-9]/.test(value)) role = 'error';
+    if (/^[1-9]\d* problems? found/.test(value)) role = 'error';
+    if (/^No problems found/.test(value)) role = 'success';
+    if (/^Config reset:/.test(value)) role = 'success';
+    if (/^Summary:/.test(value)) role = /\b[1-9]\d* failed\b|cancelled/.test(value) ? 'error' : 'success';
+    return styleText(stream, line, role, enabled);
+  }).join('');
+}
+
+// Wrap only application-owned prose; no global stream monkey-patching.
+export function outputStream(stream, { enabled = settings.getStore()?.enabled !== false, plain = false } = {}) {
+  if (plain || !enabled || !stream.isTTY) return stream;
+  return {
+    isTTY: stream.isTTY,
+    get columns() { return stream.columns; },
+    write(chunk, ...args) {
+      if (typeof chunk !== 'string') return stream.write(chunk, ...args);
+      return stream.write(formatOutput(chunk, stream, enabled), ...args);
+    },
+  };
+}
+
+export function commandOutput(args, ...streams) {
+  const enabled = (outputOptions(args).color ?? settings.getStore()?.enabled) !== false;
+  const plain = args.includes('--json');
+  return [args.filter(arg => arg !== '--no-color' && arg !== '--color'), ...streams.map(stream => outputStream(stream, { enabled, plain }))];
+}

package/src/paths.js

@@ -0,0 +1,26 @@
+import os from 'node:os';
+import path from 'node:path';
+
+/**
+ * Single source of truth for veo's per-user cache root. Used for the yt-dlp
+ * backend, the staged FFmpeg binaries, and small state files.
+ * An invalid relative OS cache setting must never write into the output directory.
+ */
+export function cacheBase({ platform = process.platform, env = process.env, home = os.homedir() } = {}) {
+  let base;
+  if (platform === 'win32') base = env.LOCALAPPDATA || path.join(home, 'AppData', 'Local');
+  else if (platform === 'darwin') base = path.join(home, 'Library', 'Caches');
+  else base = env.XDG_CACHE_HOME || path.join(home, '.cache');
+  if (!path.isAbsolute(base)) base = path.join(home, '.cache');
+  return path.join(base, 'veo');
+}
+
+/** Per-user configuration directory, following each platform's own convention. */
+export function configBase({ platform = process.platform, env = process.env, home = os.homedir() } = {}) {
+  let base;
+  if (platform === 'win32') base = env.APPDATA || path.join(home, 'AppData', 'Roaming');
+  else if (platform === 'darwin') base = path.join(home, 'Library', 'Application Support');
+  else base = env.XDG_CONFIG_HOME || path.join(home, '.config');
+  if (!path.isAbsolute(base)) base = path.join(home, '.config');
+  return path.join(base, 'veo');
+}

package/src/playlist.js

@@ -0,0 +1,31 @@
+export function validateItems(value) {
+  if (typeof value !== 'string' || !/^\d+(?:-\d+)?(?:,\d+(?:-\d+)?)*$/.test(value)) {
+    throw new Error('--playlist-items expects positive indices or ranges, e.g. 1,3-5.');
+  }
+  for (const part of value.split(',')) {
+    const [start, end = start] = part.split('-').map(Number);
+    if (!Number.isSafeInteger(start) || !Number.isSafeInteger(end) || start < 1 || end < start) {
+      throw new Error('--playlist-items requires ascending, positive ranges.');
+    }
+  }
+  return value;
+}
+
+export function selectedEntries(metadata, selection) {
+  const ranges = selection ? validateItems(selection).split(',').map(part => part.split('-').map(Number)) : null;
+  const entries = (metadata.entries || []).map((entry, offset) => ({ entry, index: entry?.playlist_index || offset + 1 }));
+  const selected = entries.filter(({ index }) => !ranges || ranges.some(([start, end = start]) => index >= start && index <= end));
+  if (!selected.length) throw new Error('No playlist entries match the selection.');
+  return selected;
+}
+
+export function sizeEstimate(entries) {
+  const sizes = entries.map(({ entry }) => entry?.filesize || entry?.filesize_approx);
+  const known = sizes.filter(value => Number.isFinite(value) && value > 0);
+  return { estimatedBytes: known.reduce((sum, value) => sum + value, 0), knownSizes: known.length, totalEntries: entries.length };
+}
+
+export function describeEstimate(estimate) {
+  if (!estimate.knownSizes) return `${estimate.totalEntries} entries; total size unknown`;
+  return `${estimate.totalEntries} entries; approximately ${(estimate.estimatedBytes / 1048576).toFixed(1)} MiB${estimate.knownSizes < estimate.totalEntries ? ` for ${estimate.knownSizes} entries; remaining sizes unknown` : ''}`;
+}

package/src/progress.js

@@ -0,0 +1,152 @@
+import { cleanText } from './utils.js';
+import { createTerminalTitle } from './terminal-title.js';
+
+const PROCESSING_LABELS = { Merger: 'Merging audio/video', VideoRemuxer: 'Changing video container', VideoConvertor: 'Converting video', ExtractAudio: 'Converting audio', EmbedSubtitle: 'Embedding subtitles', Metadata: 'Writing metadata', EmbedThumbnail: 'Embedding thumbnail', MoveFiles: 'Preparing saved file' };
+
+export function styleText(stream, text, role = 'muted', enabled = true, env = process.env) {
+  if (!enabled || !stream.isTTY || Object.hasOwn(env, 'NO_COLOR') || env.TERM === 'dumb') return text;
+  const codes = { muted: 90, title: 1, success: 32, error: 31 };
+  return '\x1b[' + (codes[role] || 90) + 'm' + text + '\x1b[0m';
+}
+
+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]}`;
+}
+
+// Count terminal cells conservatively, including wide titles and emoji.
+function cells(text) {
+  return [...text].reduce((width, char) => width + (/\p{Mark}|\u200d/u.test(char) ? 0 : /[\u1100-\u115f\u2329\u232a\u2e80-\ua4cf\uac00-\ud7a3\uf900-\ufaff\ufe10-\ufe19\ufe30-\ufe6f\uff01-\uff60\uffe0-\uffe6]|\p{Extended_Pictographic}/u.test(char) ? 2 : 1), 0);
+}
+
+function fit(text, width) {
+  if (cells(text) <= width) return text;
+  let result = '';
+  for (const char of text) {
+    if (cells(result + char) > width - 1) break;
+    result += char;
+  }
+  return width > 0 ? result + '…' : '';
+}
+
+export function formatProgress(data, { columns = Infinity, prefix = '' } = {}) {
+  const done = Number.isFinite(data.downloaded_bytes) ? data.downloaded_bytes : 0;
+  const total = data.total_bytes || data.total_bytes_estimate;
+  const estimated = !data.total_bytes && Boolean(data.total_bytes_estimate);
+  const percent = total > 0 ? Math.max(0, Math.min(estimated && data.status !== 'finished' ? 99 : 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')}` : '?';
+  const pct = `${estimated && data.status !== 'finished' ? '~' : ''}${percent === null ? '?' : percent.toFixed(0)}%`;
+  const size = `${estimated ? '~' : ''}${bytes(total)}`;
+  const compact = value => bytes(value).replace(' ', '');
+  const label = prefix ? fit(cleanText(prefix), Math.max(0, Math.floor(columns / 3))) + ' ' : '';
+  const variants = data.status === 'finished'
+    ? [`${bytes(done)} received; processing…`, `${compact(done)} received`, 'Received']
+    : [
+      `[${'='.repeat(filled)}${'-'.repeat(20 - filled)}] ${pct.padStart(4)}  ${bytes(data.speed)}/s  ${bytes(done)} / ${size}  ETA ${eta}`,
+      `${pct} ${compact(data.speed)}/s ${compact(done)}/${estimated ? '~' : ''}${compact(total)} ETA ${eta}`,
+      `${pct} ${compact(data.speed)}/s ETA ${eta}`,
+      `${pct} ${compact(done)}`,
+      pct,
+    ];
+  for (const variant of variants) if (cells(label + variant) <= columns) return label + variant;
+  return fit(variants.at(-1), columns);
+}
+
+export function createReporter(stream = process.stderr, { setTitle = createTerminalTitle(stream) } = {}) {
+  let color = true;
+  const muted = text => styleText(stream, text, 'muted', color);
+  const heading = text => styleText(stream, text, 'title', color);
+  let active = false;
+  let lastLog = 0;
+  let name = '';
+  let phase = 'Starting…';
+  let started = false;
+  let position = '';
+  let hasItem = false;
+  let streamName = '';
+  const line = (data, prefix) => formatProgress(data, { prefix, columns: stream.isTTY ? Math.max(1, (stream.columns || 80) - 1) : Infinity });
+  const draw = (data, prefix) => { stream.write(`\r\x1b[2K${line(data, prefix)}`); active = true; };
+  const updateTitle = () => setTitle(`veo | ${phase}${name ? ` | ${name}` : ''}`);
+  function clear() {
+    if (active && stream.isTTY) stream.write('\r\x1b[2K');
+    active = false;
+  }
+  const scoped = (index, total, title, parent = '') => {
+    let childName = cleanText(title), lastProgress = 0;
+    const prefix = parent + '[' + index + '/' + total + '] ';
+    const log = (message, quiet = true) => {
+      clear();
+      const line = prefix + childName + ': ' + cleanText(message);
+      stream.write((quiet ? muted(line) : line) + '\n');
+      phase = cleanText(message); name = childName;
+      if (started) updateTitle();
+    };
+    return {
+      scoped: (index, total, title) => scoped(index, total, title, prefix),
+      name(value) { childName = cleanText(value); },
+      status: log,
+      progress(data) {
+        if (stream.isTTY) {
+          draw(data, prefix + childName + ': ' + (data.stream || 'Media'));
+        } else if (Date.now() - lastProgress >= 5000 || data.status === 'finished') {
+          log((data.stream || 'Media') + ' ' + formatProgress(data), false);
+          lastProgress = Date.now();
+        }
+      },
+      processing(data) { log((PROCESSING_LABELS[data.postprocessor] || 'Processing media') + (data.status === 'finished' ? ': done' : '…')); },
+      finish() {},
+    };
+  };
+  return {
+    configure(options) { color = options.color !== false; },
+    scoped,
+    item(index, total, title) {
+      clear(); position = total > 1 ? `[${index}/${total}] ` : ''; hasItem = true; name = cleanText(title); streamName = ''; lastLog = 0;
+      stream.write(heading(`${position}${name}`) + '\n');
+      phase = 'Starting…'; if (started) updateTitle();
+    },
+    processing(data) {
+      const processor = cleanText(data.postprocessor || 'Processing');
+      const label = PROCESSING_LABELS[processor] || 'Processing media';
+      clear(); phase = `${label}${data.status === 'finished' ? ': done' : '…'}`;
+      if (started) updateTitle();
+      stream.write(muted(`${position}${phase}`) + '\n');
+    },
+    start(title = '') { started = true; name = cleanText(title); phase = 'Starting…'; updateTitle(); },
+    name(title) {
+      const next = cleanText(title);
+      if (hasItem && next !== name) { clear(); stream.write(heading(`${position}${next}`) + '\n'); }
+      name = next; if (started) updateTitle();
+    },
+    status(message) {
+      clear();
+      phase = cleanText(message);
+      if (started) updateTitle();
+      stream.write(muted(phase) + '\n');
+    },
+    complete() { clear(); phase = 'Done'; if (started) updateTitle(); },
+    fail(cancelled = false) { clear(); phase = cancelled ? 'Cancelled' : 'Failed'; if (started) updateTitle(); },
+    progress(data) {
+      if (data.stream && data.stream !== streamName) {
+        clear(); streamName = data.stream; lastLog = 0;
+        stream.write(muted(`${position}${streamName} download`) + '\n');
+      }
+      const total = data.total_bytes;
+      const percent = Number.isFinite(total) && total > 0 && Number.isFinite(data.downloaded_bytes)
+        ? Math.max(0, Math.min(100, Math.round(data.downloaded_bytes / total * 100))) : null;
+      phase = data.status === 'finished' ? 'Processing…' : percent === null ? 'Downloading…' : `${percent}%`;
+      if (started) updateTitle();
+      if (stream.isTTY) {
+        draw(data, `${position}${streamName}`);
+      } else if (Date.now() - lastLog >= 5000 || data.status === 'finished') {
+        stream.write(`${position}${streamName ? `${streamName} ` : ''}${formatProgress(data)}\n`);
+        lastLog = Date.now();
+      }
+    },
+    finish: clear,
+  };
+}