veodl 1.8.1

package/src/execution.js

@@ -0,0 +1,68 @@
+import { setTimeout as delay } from 'node:timers/promises';
+
+// Workers finish active work before settling, including cancellation and failures.
+export async function runPool(items, limit, work, { signal } = {}) {
+  let next = 0;
+  const maximum = typeof limit === 'function' ? limit : () => limit;
+  const workers = Array.from({ length: Math.min(maximum(), items.length) }, (_, worker) => (async () => {
+    while (next < items.length && worker < maximum()) {
+      signal?.throwIfAborted();
+      const index = next++;
+      await work(items[index], index);
+    }
+  })());
+  const results = await Promise.allSettled(workers);
+  const failure = results.find(result => result.status === 'rejected');
+  if (failure) throw failure.reason;
+}
+
+export function serialQueue() {
+  let tail = Promise.resolve();
+  return work => {
+    const result = tail.then(work);
+    tail = result.catch(() => {});
+    return result;
+  };
+}
+
+export const reducedLimit = (limit, state) => Math.max(1, Math.floor(limit / (state?.divisor || 1)));
+// yt-dlp reports a failed concurrent fragment fetch as a local ENOENT on the
+// fragment temp file (e.g. "...media.mp4.part-Frag29"), hiding the server-side
+// hiccup or expired segment URL behind it. Those are worth retrying with
+// reduced fragment parallelism and a refetched playlist; anything else yt-dlp
+// reports as "Unable to download video" (unavailable, private, ...) still
+// fails fast so permanent failures do not burn repeated full downloads.
+export function retryable(error) {
+  return /HTTP(?: Error)?\s*(?:429|5\d\d)|too many requests|timed? ?out|ECONNRESET|ECONNREFUSED|ETIMEDOUT|temporary failure|connection (?:reset|aborted)|\.part-Frag\d+/i.test(error?.message || '');
+}
+
+export async function adaptiveRun(run, { enabled = true, state = { divisor: 1 }, signal, reporter, wait = delay, timer } = {}) {
+  for (let attempt = 0; ; attempt++) {
+    signal?.throwIfAborted();
+    try { return await run(attempt); }
+    catch (error) {
+      if (!enabled || signal?.aborted || !retryable(error) || attempt >= 2) throw error;
+      state.divisor = Math.min(16, (state.divisor || 1) * 2);
+      const ms = 2000 * 2 ** attempt;
+      reporter?.status(`Source busy or connection interrupted; reducing parallelism and retrying in ${ms / 1000}s (${attempt + 1}/2).`);
+      const previous = timer?.phase;
+      timer?.switch('retryWait');
+      try { await wait(ms, undefined, { signal }); } finally { if (previous) timer?.switch(previous); }
+    }
+  }
+}
+
+export function phaseTimer(now = () => performance.now()) {
+  const totals = {};
+  let phase = 'setup', start = now();
+  return {
+    get phase() { return phase; },
+    switch(next) { const end = now(); totals[phase] = (totals[phase] || 0) + end - start; phase = next; start = end; },
+    result() { this.switch(phase); return Object.fromEntries(Object.entries(totals).map(([key, value]) => [key, Math.round(value)])); },
+  };
+}
+
+export function formatTimings(timings) {
+  const labels = { setup: 'setup', metadata: 'metadata', download: 'download/backend', processing: 'merge/processing', saving: 'saving', retryWait: 'retry wait' };
+  return 'Timing: ' + Object.entries(timings).map(([phase, ms]) => `${labels[phase] || phase} ${(ms / 1000).toFixed(1)}s`).join(' | ');
+}

package/src/flush.js

@@ -0,0 +1,66 @@
+import { commandOutput } from './output.js';
+import { lstat, mkdir, readdir, rm, rmdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { cacheBase } from './paths.js';
+import { listRuns, waitForExit } from './runs.js';
+
+const exists = file => lstat(file).then(() => true, error => { if (error.code === 'ENOENT') return false; throw error; });
+const ID = '[a-f0-9-]{36}';
+
+async function children(root, name) {
+  const directory = path.resolve(root, name);
+  const info = await lstat(directory).catch(error => { if (error.code === 'ENOENT') return null; throw error; });
+  if (!info) return [];
+  if (!info.isDirectory() || info.isSymbolicLink()) throw new Error(`Refusing to clean a redirected cache directory: ${directory}`);
+  return (await readdir(directory, { withFileTypes: true })).map(entry => ({ entry, file: path.join(directory, entry.name) }));
+}
+
+export async function flush({ root = cacheBase(), timeoutMs = 30000, status = () => {}, stats = false } = {}) {
+  root = path.resolve(root);
+  await mkdir(root, { recursive: true });
+  const gate = path.join(root, '.flush');
+  try { await mkdir(gate); }
+  catch (error) { if (error.code === 'EEXIST') throw new Error(`Another flush is active, or an interrupted flush left ${gate}. Remove this empty lock directory only when no flush is running.`); throw error; }
+  let stopped = 0, downloads = 0, jobs = 0, skipped = 0;
+  try {
+    const runs = await listRuns(root);
+    const live = runs.filter(run => run.alive);
+    for (const run of live) { await writeFile(`${run.file}.cancel`, 'flush'); stopped++; }
+    status(`Stopping ${stopped} active veo run(s)…`);
+    if (!await waitForExit(live, timeoutMs)) {
+      throw new Error('Some veo runs did not stop in time. No download or job files were removed. Try veo flush again after they stop.');
+    }
+    for (const { entry, file } of await children(root, 'downloads')) {
+      if (!entry.isDirectory() || !/^\.veo-part-[a-f0-9]{24}$/.test(entry.name)) continue;
+      // Unregistered older versions might still own these locks.
+      if (await exists(path.join(file, '.lock'))) { skipped++; continue; }
+      await rm(file, { recursive: true, force: true });
+      downloads++;
+    }
+    for (const { entry, file } of await children(root, 'jobs')) {
+      if (skipped) continue; // Older runs may still be updating their retry jobs.
+      if (!entry.isFile() || !new RegExp(`^\\d+-${ID}\\.json(?:\\.${ID}\\.tmp)?$`).test(entry.name)) continue;
+      await rm(file, { force: true }); jobs++;
+    }
+    for (const run of runs) {
+      await rm(run.file, { force: true });
+      await rm(`${run.file}.cancel`, { force: true });
+    }
+    if (stats) await (await import('./stats.js')).resetStats(root);
+    return { stopped, downloads, jobs, skipped };
+  } finally { await rmdir(gate); }
+}
+
+export async function flushMain(args = [], { stdout = process.stdout, ...options } = {}) {
+  [args, stdout] = commandOutput(args, stdout);
+  if (args.length === 1 && ['--help', '-h'].includes(args[0])) {
+    stdout.write('veo flush [--stats]\n\nStop registered veo runs and remove local downloads (including retained and resume data)\nand retry job JSON files. Saved media, config, history and backend tools are kept.\nStatistics are kept unless --stats is supplied to reset them.\nLocked downloads from older or interrupted processes are skipped.\n');
+    return 0;
+  }
+  if (args.length && (args.length !== 1 || args[0] !== '--stats')) throw new Error('Usage: veo flush [--stats] (or veo flush --help)');
+  const result = await flush({ ...options, stats: args.includes('--stats'), status: text => stdout.write(`${text}\n`) });
+  if (args.includes('--stats')) stdout.write('Statistics reset.\n');
+  stdout.write(`Flushed: ${result.downloads} local download folder(s), ${result.jobs} job file(s); ${result.stopped} run(s) stopped.\n`);
+  if (result.skipped) stdout.write(`Skipped ${result.skipped} locked folder(s) and kept retry jobs; check older veo processes before removing their locks.\n`);
+  return result.skipped ? 1 : 0;
+}

package/src/history.js

@@ -0,0 +1,173 @@
+import { commandOutput } from './output.js';
+import { randomUUID } from 'node:crypto';
+import { lstat, readdir } from 'node:fs/promises';
+import path from 'node:path';
+import { cacheBase } from './paths.js';
+import { readJson, writeJson } from './state.js';
+import { cleanText, localStamp } from './utils.js';
+
+/**
+ * `veo history` shows the most recent download attempts. Every finished item is
+ * written as its own small file named after its millisecond timestamp, so
+ * parallel veo runs never rewrite each other's records and the newest entries
+ * can be listed without parsing an ever-growing log.
+ */
+export const HISTORY_LIMIT = 5;
+const SHOWN_FILES = 5;
+const MAX_FILES = 200;
+const STATUSES = new Set(['saved', 'skipped', 'failed', 'cancelled']);
+const NAME = /^(\d{13})-[a-f0-9-]{36}\.json$/;
+
+export const HISTORY_HELP = `veo history [--json] [--limit <n>] [--failed]
+
+Show the last ${HISTORY_LIMIT} download attempts by default, newest first, with title, status, media
+type, date, URL and saved files. Saved, skipped, failed and cancelled items are
+recorded; playlist entries and retried attempts count individually.
+Use --limit to show 1-1000 attempts, and --failed to show only failed or cancelled
+attempts. Use --json for scripting. Failed entries show their retry command while
+the job file is available. History is kept in the per-user veo cache
+and survives veo flush. Active downloads appear once they finish.
+`;
+
+/** Directory holding one JSON record per finished download attempt. */
+export function historyRoot(root = cacheBase()) {
+  return path.join(path.resolve(root), 'history');
+}
+
+function valid(record) {
+  return record?.version === 1
+    && Number.isFinite(Date.parse(record.at))
+    && typeof record.url === 'string' && Boolean(record.url)
+    && typeof record.title === 'string'
+    && STATUSES.has(record.status)
+    && ['video', 'audio'].includes(record.media)
+    && [record.quality, record.format, record.error].every(value => value === null || typeof value === 'string')
+    && (record.job === undefined || record.job === null || typeof record.job === 'string')
+    && (record.runId === undefined || record.runId === null || /^[0-9a-z]{6}$/.test(record.runId))
+    && Array.isArray(record.files) && record.files.every(file => typeof file === 'string' && Boolean(file));
+}
+
+// Only strings can become history text; a missing title must not become "undefined".
+function text(value, limit) {
+  if (typeof value !== 'string') return '';
+  const cleaned = cleanText(value);
+  return limit === undefined ? cleaned : cleaned.slice(0, limit);
+}
+
+/**
+ * Records must never write into the output directory, contain terminal escapes
+ * or grow without bound, so untrusted titles, paths and messages are cleaned and
+ * the file list is capped here.
+ */
+export function createHistoryRecorder(root = cacheBase(), { now = Date.now } = {}) {
+  const directory = historyRoot(root);
+  let previous = 0;
+  return async item => {
+    // Strictly increasing names keep "newest first" deterministic even when
+    // several items finish inside the same millisecond.
+    const at = Math.max(now(), previous + 1);
+    previous = at;
+    const audio = Boolean(item.audio);
+    const record = {
+      version: 1,
+      at: new Date(at).toISOString(),
+      url: text(item.url),
+      title: text(item.title) || text(item.url),
+      status: STATUSES.has(item.status) ? item.status : 'failed',
+      media: audio ? 'audio' : 'video',
+      quality: audio ? null : text(item.quality) || null,
+      format: text(item.format) || (audio ? 'mp3' : null),
+      files: (Array.isArray(item.files) ? item.files : []).slice(0, MAX_FILES).map(file => text(file)).filter(Boolean),
+      error: text(item.error, 400) || null,
+      ...(item.job ? { job: text(item.job) } : {}),
+      ...(item.runId ? { runId: text(item.runId) } : {}),
+      elapsedMs: Number.isFinite(item.elapsedMs) && item.elapsedMs >= 0 ? Math.round(item.elapsedMs) : 0,
+    };
+    await writeJson(path.join(directory, `${at}-${randomUUID()}.json`), record);
+  };
+}
+
+/** The newest `limit` records, newest first. Missing history is not an error. */
+export async function readHistory(root = cacheBase(), limit = HISTORY_LIMIT, { failed = false } = {}) {
+  const directory = historyRoot(root);
+  const info = await lstat(directory).catch(error => { if (error.code === 'ENOENT') return null; throw error; });
+  if (!info) return [];
+  if (!info.isDirectory() || info.isSymbolicLink()) throw new Error(`Invalid history directory: ${directory}`);
+  const names = (await readdir(directory, { withFileTypes: true }))
+    .filter(entry => entry.isFile() && NAME.test(entry.name))
+    .map(entry => entry.name)
+    .sort((a, b) => Number(b.slice(0, 13)) - Number(a.slice(0, 13)));
+  const records = [];
+  for (const name of names) {
+    if (records.length >= limit) break;
+    const file = path.join(directory, name);
+    const record = await readJson(file, null);
+    if (!valid(record)) throw new Error(`Invalid history file: ${file}`);
+    if (failed && !['failed', 'cancelled'].includes(record.status)) continue;
+    records.push(record);
+  }
+  return records;
+}
+
+function describeDuration(ms) {
+  if (ms < 1000) return `${ms} ms`;
+  const seconds = ms / 1000;
+  if (seconds < 60) return `${seconds.toFixed(1)} s`;
+  return `${Math.floor(seconds / 60)}m ${Math.floor(seconds % 60)}s`;
+}
+
+function describeMedia(entry) {
+  const detail = entry.media === 'audio' ? entry.format : entry.quality;
+  return detail ? `${entry.media}, ${detail}` : entry.media;
+}
+
+export function formatHistory(entries, limit = HISTORY_LIMIT, { failed = false } = {}) {
+  if (!entries.length) return failed ? 'veo history\n\nNo failed or cancelled downloads recorded.\n' : 'veo history\n\nNo downloads recorded yet. Download something with veo first.\n';
+  const lines = [`veo history (last ${limit}${failed ? ' failed/cancelled' : ''}, newest first)`, ''];
+  for (const [index, entry] of entries.entries()) {
+    lines.push(`${index + 1}. ${entry.title}`);
+    lines.push(`   Status: ${entry.status}${entry.status === 'skipped' ? ' (already on disk)' : ''}`);
+    if (entry.runId) lines.push(`   Run ID: ${entry.runId}  (veo inspect run ${entry.runId})`);
+    lines.push(`   Media:  ${describeMedia(entry)}`);
+    lines.push(`   Date:   ${localStamp(entry.at)}${entry.elapsedMs ? ` (${describeDuration(entry.elapsedMs)})` : ''}`);
+    lines.push(`   URL:    ${entry.url}`);
+    if (entry.error) lines.push(`   Error:  ${entry.error}`);
+    if (entry.job) lines.push(`   Retry:  veo --retry-failed "${entry.job}"`);
+    for (const [position, file] of entry.files.slice(0, SHOWN_FILES).entries()) {
+      lines.push(`${position ? '           ' : '   Saved:  '}${file}`);
+    }
+    if (entry.files.length > SHOWN_FILES) lines.push(`           … and ${entry.files.length - SHOWN_FILES} more file(s); use veo history --json for the full list.`);
+    if (index !== entries.length - 1) lines.push('');
+  }
+  return `${lines.join('\n')}\n`;
+}
+
+export async function historyMain(args = [], { stdout = process.stdout, root = cacheBase(), limit = HISTORY_LIMIT } = {}) {
+  [args, stdout] = commandOutput(args, stdout);
+  if (args.length === 1 && ['--help', '-h'].includes(args[0])) {
+    stdout.write(HISTORY_HELP);
+    return 0;
+  }
+  let json = false, failed = false;
+  for (let index = 0; index < args.length; index++) {
+    const arg = args[index];
+    if (arg === '--json' && !json) json = true;
+    else if (arg === '--failed' && !failed) failed = true;
+    else if (arg === '--limit') {
+      const value = args[++index];
+      if (!value || !/^[1-9]\d*$/.test(value) || Number(value) > 1000) throw new Error('--limit must be a whole number between 1 and 1000.');
+      limit = Number(value);
+    } else throw new Error('Usage: veo history [--json] [--limit <n>] [--failed]');
+  }
+  const entries = await readHistory(root, limit, { failed });
+  if (json) stdout.write(`${JSON.stringify({ count: entries.length, entries })}\n`);
+  else {
+    const visible = await Promise.all(entries.map(async entry => {
+      if (!entry.job) return entry;
+      const info = await lstat(entry.job).catch(() => null);
+      return info?.isFile() && !info.isSymbolicLink() ? entry : { ...entry, job: null };
+    }));
+    stdout.write(formatHistory(visible, limit, { failed }));
+  }
+  return 0;
+}

package/src/inspect-media.js

@@ -0,0 +1,168 @@
+import { spawn } from 'node:child_process';
+import { mkdir, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { backendCacheDirectory, exeSuffix, resolveMediaTools } from './backend.js';
+import { commandOutput } from './output.js';
+import { locateRunFiles, readRunArchive, RUN_ARCHIVE_ID } from './run-archive.js';
+
+const SIGNAL_THRESHOLD_DBFS = -60;
+const OUTPUT_LIMIT = 2 * 1024 * 1024;
+
+export const INSPECT_HELP = `veo inspect <media-file> [--check-audio] [--json]
+veo inspect run <id> [--check-audio] [--search <directory>] [--json]
+
+Read local media metadata with ffprobe. --check-audio decodes every audio track
+from start to end and measures its peak level with FFmpeg. A signal is detected
+when the peak is above -60 dBFS; this is a level check, not a listening test.
+Inspect a finished run by its persistent id. Missing media is searched by its
+file fingerprint under the original output directory; --search adds another
+directory after a move. Missing files are reported before media probing.
+Inspection uses locally available media tools and does not contact the network.
+`;
+
+export function runMediaTool(executable, args, { signal, env } = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(executable, args, { shell: false, windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'], signal, ...(env ? { env } : {}) });
+    let stdout = '', stderr = '', overflow = false;
+    const append = (current, chunk) => {
+      if (current.length + chunk.length > OUTPUT_LIMIT) { overflow = true; child.kill(); return current; }
+      return current + chunk;
+    };
+    child.stdout.on('data', chunk => { stdout = append(stdout, chunk.toString()); });
+    child.stderr.on('data', chunk => { stderr = append(stderr, chunk.toString()); });
+    child.on('error', reject);
+    child.on('close', code => {
+      if (overflow) reject(new Error('Media tool output exceeded the supported size.'));
+      else if (signal?.aborted) reject(new DOMException('Cancelled', 'AbortError'));
+      else if (code !== 0) reject(new Error(stderr.trim().split(/\r?\n/).at(-1) || `Media tool exited with code ${code}.`));
+      else resolve({ stdout, stderr });
+    });
+  });
+}
+
+async function localMediaTools() {
+  const directory = backendCacheDirectory();
+  await mkdir(directory, { recursive: true });
+  const location = await resolveMediaTools({ directory, offline: true });
+  return { ffmpeg: path.join(location, `ffmpeg${exeSuffix()}`), ffprobe: path.join(location, `ffprobe${exeSuffix()}`) };
+}
+
+function number(value) {
+  if (value === undefined || value === null || value === '') return null;
+  const parsed = Number(value);
+  return Number.isFinite(parsed) && parsed >= 0 ? parsed : null;
+}
+
+export function parsePeak(output) {
+  const match = output.match(/max_volume:\s*(-inf|-?\d+(?:\.\d+)?)\s*dB/i);
+  if (!match) throw new Error('FFmpeg did not report an audio peak level.');
+  return match[1].toLowerCase() === '-inf' ? null : Number(match[1]);
+}
+
+export async function inspectMedia(file, { checkAudio = false, signal, runner = runMediaTool, tools = localMediaTools } = {}) {
+  const target = path.resolve(file);
+  if (!(await stat(target)).isFile()) throw new Error(`Not a regular media file: ${target}`);
+  const { ffprobe, ffmpeg } = await tools();
+  const probe = await runner(ffprobe, ['-v', 'error', '-show_format', '-show_streams', '-of', 'json', '-i', target], { signal });
+  let metadata;
+  try { metadata = JSON.parse(probe.stdout); }
+  catch { throw new Error(`ffprobe returned invalid metadata for ${target}.`); }
+  if (!Array.isArray(metadata.streams)) throw new Error(`ffprobe found no stream metadata for ${target}.`);
+  const streams = metadata.streams.map(stream => ({
+    index: stream.index, type: stream.codec_type || null, codec: stream.codec_name || null,
+    language: stream.tags?.language || null, width: number(stream.width), height: number(stream.height),
+    channels: number(stream.channels), sampleRate: number(stream.sample_rate),
+  }));
+  const audioTracks = streams.filter(stream => stream.type === 'audio');
+  const result = { file: target, format: metadata.format?.format_name || null,
+    durationSeconds: number(metadata.format?.duration), sizeBytes: number(metadata.format?.size),
+    streams, hasAudioTrack: audioTracks.length > 0, hasVideoTrack: streams.some(stream => stream.type === 'video'),
+    audioCheck: null };
+  if (checkAudio) {
+    const tracks = [];
+    for (const [audioIndex, stream] of audioTracks.entries()) {
+      const report = await runner(ffmpeg, ['-hide_banner', '-nostdin', '-nostats', '-i', target,
+        '-map', `0:a:${audioIndex}`, '-vn', '-sn', '-dn', '-af', 'volumedetect', '-f', 'null', '-'], { signal });
+      const maxDbfs = parsePeak(report.stderr);
+      tracks.push({ streamIndex: stream.index, maxDbfs, hasSignal: maxDbfs !== null && maxDbfs > SIGNAL_THRESHOLD_DBFS });
+    }
+    result.audioCheck = { checked: true, scope: 'full_file', thresholdDbfs: SIGNAL_THRESHOLD_DBFS,
+      hasSignal: tracks.some(track => track.hasSignal), tracks };
+  }
+  return result;
+}
+
+export async function inspectRun(id, { checkAudio = false, searchRoot, signal, root, inspect = inspectMedia } = {}) {
+  if (!RUN_ARCHIVE_ID.test(id)) throw new Error('Run ids have 6 letters or digits. List active runs with veo runs --json or finished attempts with veo history --json.');
+  const archive = await readRunArchive(id, root);
+  const located = await locateRunFiles(archive, { searchRoot, signal });
+  const items = [];
+  let missingFiles = 0;
+  for (const item of located) {
+    const files = [];
+    for (const file of item.files) {
+      if (!file.found) missingFiles++;
+      let metadata = null;
+      if (file.found && file.media) {
+        // locateRunFiles verifies that this is a regular file before any probe.
+        try { metadata = await inspect(file.path, { checkAudio, signal }); }
+        catch (error) {
+          if (error.code !== 'ENOENT') throw error;
+          file.found = false; file.path = null; missingFiles++;
+        }
+      }
+      files.push({ ...file, metadata });
+    }
+    items.push({ ...item, files });
+  }
+  return { runId: archive.id, status: archive.status, startedAt: archive.startedAt,
+    finishedAt: archive.finishedAt, missingFiles, items };
+}
+
+export async function inspectMain(args = [], { stdout = process.stdout, inspect = inspectMedia, inspectRunImpl = inspectRun } = {}) {
+  [args, stdout] = commandOutput(args, stdout);
+  if (args.length === 1 && ['--help', '-h'].includes(args[0])) { stdout.write(INSPECT_HELP); return 0; }
+  const json = args.includes('--json');
+  const checkAudio = args.includes('--check-audio');
+  const runMode = args[0] === 'run';
+  let searchRoot;
+  const positionals = [];
+  for (let index = 0; index < args.length; index++) {
+    const arg = args[index];
+    if (['--json', '--check-audio'].includes(arg)) continue;
+    if (arg === '--search' && runMode && !searchRoot) { searchRoot = args[++index]; continue; }
+    positionals.push(arg);
+  }
+  if (runMode ? positionals.length !== 2 || positionals[0] !== 'run' || !RUN_ARCHIVE_ID.test(positionals[1]) || args.includes('--search') && (!searchRoot || searchRoot.startsWith('--'))
+    : positionals.length !== 1 || positionals[0].startsWith('--')) {
+    throw new Error('Usage: veo inspect <media-file> [--check-audio] [--json] | veo inspect run <id> [--check-audio] [--search <directory>] [--json]');
+  }
+  const controller = new AbortController();
+  const cancel = () => controller.abort();
+  process.once('SIGINT', cancel);
+  process.once('SIGTERM', cancel);
+  try {
+    const result = runMode
+      ? await inspectRunImpl(positionals[1], { checkAudio, searchRoot, signal: controller.signal })
+      : await inspect(positionals[0], { checkAudio, signal: controller.signal });
+    if (json) stdout.write(`${JSON.stringify(result)}\n`);
+    else if (runMode) {
+      stdout.write(`Run: ${result.runId} (${result.status})\n`);
+      for (const item of result.items) for (const file of item.files) {
+        stdout.write(`${file.found ? 'File' : 'Missing'}: ${file.path || file.originalPath}${file.renamed ? ` (renamed from ${file.originalPath})` : ''}\n`);
+        if (file.metadata) stdout.write(`  Format: ${file.metadata.format || 'unknown'}; audio tracks: ${file.metadata.streams.filter(stream => stream.type === 'audio').length}${file.metadata.audioCheck ? `; signal: ${file.metadata.audioCheck.hasSignal ? 'detected' : 'not detected'}` : ''}\n`);
+      }
+    }
+    else {
+      stdout.write(`File: ${result.file}\n`);
+      stdout.write(`Format: ${result.format || 'unknown'}; duration: ${result.durationSeconds ?? 'unknown'} s\n`);
+      stdout.write(`Streams: ${result.streams.map(stream => `${stream.type || 'unknown'} ${stream.codec || 'unknown'}`).join(', ') || 'none'}\n`);
+      stdout.write(`Audio tracks: ${result.streams.filter(stream => stream.type === 'audio').length}\n`);
+      if (result.audioCheck) stdout.write(`Audio signal: ${result.audioCheck.hasSignal ? 'detected' : 'not detected'} (threshold ${SIGNAL_THRESHOLD_DBFS} dBFS, full file)\n`);
+    }
+    return runMode && result.missingFiles ? 1 : 0;
+  } finally {
+    process.removeListener('SIGINT', cancel);
+    process.removeListener('SIGTERM', cancel);
+  }
+}

package/src/interactive.js

@@ -0,0 +1,82 @@
+import { outputStream, formatOutput } from './output.js';
+import { createInterface } from 'node:readline/promises';
+import { availableHeights, cleanText, validateUrl } from './utils.js';
+import { applyProfile } from './config.js';
+import { fetchMetadata, prepareBackend, runBackend } from './downloader.js';
+import { describeEstimate, selectedEntries, sizeEstimate, validateItems } from './playlist.js';
+
+export async function interactiveArgs(config, { signal, input = process.stdin, output = process.stderr, ask, inspect } = {}) {
+  const terminalOutput = output;
+  output = outputStream(output);
+  const rl = ask ? null : createInterface({ input, output: terminalOutput });
+  const controller = new AbortController();
+  signal = signal ? AbortSignal.any([signal, controller.signal]) : controller.signal;
+  rl?.on('SIGINT', () => controller.abort());
+  const question = ask || (prompt => rl.question(formatOutput(prompt, terminalOutput), { signal }));
+  const choose = async (prompt, allowed, fallback) => {
+    while (true) {
+      const answer = (await question(prompt)).trim() || fallback;
+      if (allowed.includes(answer)) return answer;
+      output.write(`Choose: ${allowed.join(', ')}\n`);
+    }
+  };
+  try {
+    const args = [];
+    const profiles = Object.keys(config.profiles || {});
+    let defaults = applyProfile(config);
+    if (profiles.length) {
+      const hasDefault = profiles.includes('default');
+      const choices = hasDefault ? profiles : [...profiles, 'none'];
+      const fallback = hasDefault ? 'default' : 'none';
+      const profile = await choose(`Profile (${choices.join(', ')}) [${fallback}]: `, choices, fallback);
+      if (profile !== 'none') { args.push('--profile', profile); defaults = applyProfile(config, profile); }
+    }
+    const url = validateUrl((await question('Video or playlist URL: ')).trim());
+    args.push(url);
+    const type = await choose(`Download (video/audio) [${defaults.audio ? 'audio' : 'video'}]: `, ['video', 'audio'], defaults.audio ? 'audio' : 'video');
+    args.push(type === 'audio' ? '--audio' : '--no-audio');
+    output.write('Reading available media…\n');
+    // Inspect the collection first so ordinary video links do not need a playlist prompt.
+    const inspectionOptions = { ...defaults, url, playlist: true };
+    const metadata = inspect ? await inspect(inspectionOptions) : await fetchMetadata(inspectionOptions, {
+      signal, backend: await prepareBackend(inspectionOptions, { signal }), runner: runBackend,
+    });
+    const isCollection = metadata._type === 'playlist' || Boolean(metadata.entries);
+    const collection = isCollection
+      ? await choose(`Download the playlist? (y/n) [${defaults.playlist === false ? 'n' : 'y'}]: `,
+        ['y', 'n'], defaults.playlist === false ? 'n' : 'y')
+      : 'n';
+    args.push(collection === 'y' ? '--playlist' : '--no-playlist');
+    output.write(`${cleanText(metadata.title || metadata.id || 'Media')}\n`);
+    if (collection === 'y' && metadata.entries) {
+      for (const { entry, index } of selectedEntries(metadata)) output.write(`${index}. ${cleanText(entry?.title || 'Unavailable entry')}\n`);
+      let selection;
+      while (true) {
+        const preferred = defaults.playlistItems || '';
+        selection = (await question(`Entries (e.g. 1,3-5; Enter = ${preferred || 'all'}): `)).trim() || preferred;
+        try { if (selection) validateItems(selection); selectedEntries(metadata, selection); break; }
+        catch (error) { output.write(`${error.message}\n`); }
+      }
+      if (selection) args.push('--playlist-items', selection);
+      output.write(`${describeEstimate(sizeEstimate(selectedEntries(metadata, selection)))}\n`);
+    }
+    if (type === 'video') {
+      const heights = availableHeights(metadata.formats).sort((a, b) => b - a).map(height => `${height}p`);
+      const choices = ['best', ...heights];
+      if (!heights.length) output.write('Resolution metadata unavailable; using best. Set a quality cap with -q in command mode.\n');
+      const fallback = choices.includes(defaults.quality) ? defaults.quality : 'best';
+      args.push('-q', await choose(`Quality (${choices.join(', ')}) [${fallback}]: `, choices, fallback));
+    }
+    // Switching the media type must not leave an incompatible format from a profile.
+    if (type === 'video' && ['mp3', 'm4a', 'aac', 'opus', 'flac', 'wav'].includes(defaults.format)) args.push('--format', 'mp4');
+    if (type === 'audio' && ['mp4', 'mkv', 'webm', 'mov'].includes(defaults.format)) args.push('--format', 'mp3');
+    const directory = (await question(`Output directory [${defaults.output || process.cwd()}]: `)).trim() || defaults.output || process.cwd();
+    args.push('-o', directory, '--resume');
+    const skipDefault = defaults.skipExisting === false ? 'n' : 'y';
+    const skip = await choose(`Skip previously downloaded videos? (y/n) [${skipDefault}]: `, ['y', 'n'], skipDefault);
+    args.push(skip === 'y' ? '--skip-existing' : '--no-skip-existing');
+    output.write(`Ready: ${type}, ${directory}\n`);
+    if (await choose('Start download? (y/n) [y]: ', ['y', 'n'], 'y') === 'n') return null;
+    return args;
+  } finally { rl?.close(); }
+}