veodl 1.10.1 → 1.11.0

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 All notable changes to veo. This project follows [Semantic Versioning](https://semver.org/).
 
+## 1.11.0
+
+### Added
+
+- **Incognito Downloads**: Added `--incognito` (and `"incognito": true` in configuration/profiles) to save media without creating run records, persistent retry jobs, run archives, download history, `.veo-history` records, or download statistics. Uses an isolated temporary staging directory and completely removes it upon completion, failure, or cancellation, and disables yt-dlp's filesystem cache.
+- **Neutral Filenames**: Added `--neutral-filename` (and `"neutralFilename": true`) to generate unidentifiable random filenames (e.g. `video-a1b2c3d4e5f6.mp4`), suppressing video titles, channel names, and custom folder templates in filesystem paths.
+- **Subtitle Inspection & Automatic Captions**:
+  - Added `veo subs <url>` (alias `--list-subs` / `--list-subtitles`) to inspect available manual and automatically generated subtitle tracks, languages, and source formats without downloading.
+  - Added `--auto-subs` (and `"autoSubs": true`) to download automatically generated captions/subtitles.
+  - Added `--sub-format <format>` (and `"subFormat": string`) to express a preferred subtitle source format (e.g. `srt/vtt/best`).
+- **Post-Download Media Verification**: Added `--verify` (and `"verify": true`) to probe saved media files with FFprobe before recording success, verifying container integrity and stream presence. Retains saved files for inspection if verification fails.
+
 ## 1.10.1
 
 ### Added

package/README.md

@@ -71,7 +71,10 @@ Options:
   -N, --concurrent-fragments <n>   Parallel fragments, 1-64 (default: 8; 17-64 experimental)
   --experimental-fragments  Explicitly accept experimental values above 16
   --subs                    Download subtitles (default languages: en)
-  --sub-langs <langs>       Subtitle languages, e.g. "de,en" (implies --subs)
+  --auto-subs               Include automatically generated subtitles
+  --sub-langs <langs>       Subtitle languages, e.g. "de,en" (manual unless --auto-subs)
+  --sub-format <format>     Prefer subtitle formats, e.g. srt/vtt/best
+  --list-subs               Show manual and automatic subtitle availability
   --embed-subs              Embed subtitles into the video file
   --embed-metadata          Embed title, date and other metadata
   --embed-thumbnail         Embed the thumbnail
@@ -80,9 +83,12 @@ Options:
   --cookies <file>          Netscape cookie file, for content you may access
   --cookies-from-browser <browser[:profile]>
   --resume                  Keep partial data and continue an interrupted download
+  --incognito               Save media without run ID, history, stats or retry data
+  --neutral-filename        Optional random filename instead of title and templates
   --list-qualities          Show available video resolutions and exit
   --list-formats            Show available formats and exit
   --dry-run                 Show what would be downloaded and exit
+  --verify                  Probe saved media files with FFprobe (default: off)
   --json                    One JSON object per URL instead of prose
   --profile <name>          Use a named profile from the config file
   --batch-file <file>       Read one URL per line (blank lines and # comments ignored)
@@ -292,8 +298,13 @@ video sites. All new options are also documented in `veo config guide`.
 
 ### Metadata and subtitles
 
-- `--subs` writes subtitle files, `--sub-langs de,en` selects languages, and `--embed-subs`
-  embeds them into the video container instead.
+- `veo subs <URL>` lists manual and automatically generated subtitles separately, including
+  their languages and source formats. `--json` returns one object without subtitle URLs.
+- `--subs` writes manual subtitle files. `--auto-subs` adds generated subtitles, or selects
+  only generated subtitles when used alone. `--sub-langs de,en` selects languages;
+  `--sub-format srt/vtt/best` prefers available source formats in that order. A format
+  preference does not convert subtitles. `--embed-subs` embeds selected subtitles into
+  the video container.
 - `--embed-metadata` and `--embed-thumbnail` use FFmpeg to write metadata and cover art.
 - `--sponsorblock-remove sponsor,selfpromo` cuts sponsor segments (YouTube) and requires
   FFmpeg; the cut re-encodes the affected parts.
@@ -301,6 +312,16 @@ video sites. All new options are also documented in `veo config guide`.
 - `-N 8` downloads several fragments in parallel, which is noticeably faster on HLS/DASH
   sources and heavier on the network.
 
+### Optional post-download verification
+
+Use `veo <URL> --verify` or set `"verify": true` in a config profile to check
+saved media with FFprobe before recording a successful download. It checks that
+the container can be probed and contains a video track (or an audio track for
+`--audio`). Verification is off by default; `--no-verify` overrides a profile.
+This quick check does not decode the whole file or prove that the audio is
+audible. Use `veo inspect <file> --check-audio` for a full audio signal check.
+If verification fails, veo reports failure and keeps the saved file for review.
+
 ### Access and credentials
 
 veo downloads publicly accessible content. It does not bypass access controls, and it does
@@ -397,11 +418,11 @@ are not allowed.
 }
 ```
 
-Supported keys: `output`, `quality`, `format`, `rename`, `audio`, `open`, `resume`,
+Supported keys: `output`, `quality`, `format`, `rename`, `audio`, `open`, `resume`, `incognito`, `neutralFilename`,
 `closestQuality`, `cookies`, `cookiesFromBrowser`, `playlist`, `concurrentFragments`,
 `experimentalFragments`, `playlistConcurrency`, `recode`, `compatible`, `concurrentDownloads`, `adaptiveConcurrency`,
 `filenameTemplate`, `folderTemplate`, `checkSpace`, `timings`, `color`,
-`subs`, `subLangs`, `embedSubs`, `embedMetadata`, `embedThumbnail`, `sponsorblockRemove`,
+`subs`, `autoSubs`, `subLangs`, `subFormat`, `embedSubs`, `embedMetadata`, `embedThumbnail`, `sponsorblockRemove`, `verify`,
 `section`, `json`. An explicit command-line flag always wins over a stored default. An
 unknown key produces a warning; invalid JSON or a wrong value type is an error, because
 silently ignoring a typo would be worse.
@@ -420,6 +441,27 @@ Additional defaults are `skipExisting` and `playlistItems`. Boolean defaults can
 with `--no-open`, `--no-audio`, `--no-resume`, `--no-embed-metadata`, etc. `--no-subs` also
 disables stored subtitle languages and subtitle embedding for that invocation.
 
+### Incognito downloads
+
+Use `veo <url> --incognito` or set `"incognito": true` in a named profile. The
+downloaded media is saved normally. veo does not assign a run ID or write a
+retry job, run archive, download history, output `.veo-history` record, or
+statistics for that attempt. It uses a private temporary staging directory and
+removes it after success, failure, or cancellation. It also disables yt-dlp's
+filesystem cache. `--no-incognito` overrides
+a profile for one request. Incognito cannot be combined with `--resume`,
+`--skip-existing`, or `--retry-failed`; there is no veo retry for an incognito
+attempt. A force-killed process may leave temporary files that the OS can
+clean later. The destination file, shell history, network service, and source
+website can still reveal the download.
+
+Example profile: `"profiles": { "private": { "incognito": true } }`.
+Add `"neutralFilename": true` to that profile, or pass `--neutral-filename`,
+to save files as names such as `video-a1b2c3d4e5f6.mp4`. This is optional:
+incognito keeps the normal title by default. Neutral naming overrides `--rename`,
+`--filename-template`, and `--folder-template` for that request. The selected
+output directory, media contents, and embedded metadata are unaffected.
+
 ### Named profiles
 
 If no profile is selected, `profiles.default` is applied automatically. `veo profile music`
@@ -548,6 +590,7 @@ veo retry --last       # retry the newest failed or unfinished job
 veo runs              # active runs with their id; veo runs <id> for details
 veo runs --json       # machine-readable active run metadata
 veo inspect FILE --check-audio --json  # track metadata and audio signal
+veo subs URL --json    # available manual and automatic subtitles
 veo inspect run ID --check-audio --json  # finished run and saved media
 veo stop [id]         # stop one run, or every active run
 veo flush             # stop runs, clear temporary downloads and retry jobs

package/docs/AGENT_GUIDE.md

@@ -68,6 +68,8 @@ veo retry --last --json
 
 ## Inspect saved media and audio
 
+`veo subs <URL> --json` lists manual and automatic subtitle languages and formats without saving media. Select manual subtitles with `--subs --sub-langs de,en`, generated subtitles with `--auto-subs --sub-langs de,en`, and prefer a source format with `--sub-format srt/vtt/best`. `--verify` optionally probes saved media files before recording success; it is off by default and does not decode the full track.
+
 ```sh
 veo inspect "/downloads/Example.mp4" --json
 veo inspect "/downloads/Example.mp4" --check-audio --json
@@ -85,6 +87,9 @@ The run record is stored in veo's per-user cache on the device that ran the down
 
 ## Operational notes
 
+- `veo <URL> --incognito --json` saves media without a run ID, retry job, history, run archive, output duplicate record or statistics. It disables yt-dlp's filesystem cache. A config profile can set `"incognito": true`; `--no-incognito` overrides it. Incognito cannot use `--resume`, `--skip-existing`, or retry. Its temporary staging data is removed after the attempt; the output file and records outside veo (such as shell history or server logs) still exist.
+- Add `--neutral-filename` or `"neutralFilename": true` to use random media filenames instead of titles. This option is independent of `--incognito` and overrides custom file and folder naming for that request.
+
 - Fragment concurrency defaults to 8. Values 1-16 need no confirmation; 17-64 are experimental and require terminal `y/N` confirmation before downloading. Scripts and JSON calls must explicitly accept with `--experimental-fragments` or `"experimentalFragments": true` in the config/profile. Values above 64 are always rejected. More connections may trigger server limits and do not guarantee higher speed. Dry-runs and source/format listings do not require confirmation.
 - Example profile: `"experimental": { "concurrentFragments": 32, "experimentalFragments": true }`. Run with `veo <URL> --profile experimental`; use `--no-experimental-fragments` to revoke a stored opt-in.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "veodl",
-  "version": "1.10.1",
+  "version": "1.11.0",
   "description": "A clean, simple video downloader powered by yt-dlp.",
   "type": "module",
   "bin": {

package/src/cli.js

@@ -48,7 +48,10 @@ Options:
   --experimental-fragments  Explicitly accept experimental values above 16
                            Otherwise requires terminal confirmation before download
   --subs                   Download subtitles (default languages: en)
-  --sub-langs <langs>      Subtitle languages, e.g. "de,en" (implies --subs)
+  --auto-subs              Include automatically generated subtitles
+  --sub-langs <langs>      Subtitle languages, e.g. "de,en" (manual unless --auto-subs)
+  --sub-format <format>    Preferred subtitle format, e.g. srt/vtt/best
+  --list-subs              Show manual and automatic subtitle languages, then exit
   --embed-subs             Embed subtitles into the video file
   --embed-metadata         Embed title, date and other metadata
   --embed-thumbnail        Embed the thumbnail
@@ -59,6 +62,8 @@ Options:
   --cookies-from-browser <browser[:profile]>
                            Read cookies from an installed browser
   --resume                 Keep partial data and continue an interrupted download
+  --incognito              Save media without run IDs, history, stats or retry data
+  --neutral-filename       Use a random video name; omit title and naming templates
   --list-qualities         Show available video resolutions and exit
   --list-qualitys          Alias for --list-qualities
   --list-formats           Show the available formats and exit
@@ -68,6 +73,7 @@ Options:
   --deep-scan              Check every media candidate found during source search
   --timeout <duration>     Source search deadline, e.g. 30, 30s or 2m (5s-10m)
   --dry-run                Show what would be downloaded and exit
+  --verify                 Probe saved media files with FFprobe (default: off)
   --json                   Print one JSON object per URL instead of prose
   --profile <name>         Apply a named config profile
   --batch-file <file>      Read URLs from a file (one per line; # comments)
@@ -89,6 +95,7 @@ Commands:
   veo history --failed --limit 20  Filter and extend download history
   veo runs [id]            List active runs; add --json for metadata and progress
   veo inspect <file>        Read media metadata; --check-audio measures audio signal
+  veo subs <url>            List available manual and automatic subtitles
   veo inspect run <id>     Inspect saved files from a finished run by its id
   veo stop [id]            Stop one run, or every active run
   veo alias list|add|remove  Manage extra command names (wrappers calling veo)
@@ -128,6 +135,7 @@ const STRING_OPTIONS = {
   'cookies-from-browser': {},
   'concurrent-fragments': { short: 'N' },
   'sub-langs': {},
+  'sub-format': {},
   'sponsorblock-remove': {},
   section: {},
   profile: {},
@@ -149,8 +157,13 @@ const BOOLEAN_OPTIONS = {
   open: {},
   audio: {},
   resume: {},
+  incognito: {},
+  'neutral-filename': {},
   playlist: {},
   subs: {},
+  'auto-subs': {},
+  'list-subs': {},
+  verify: {},
   'embed-subs': {},
   'embed-metadata': {},
   'embed-thumbnail': {},
@@ -195,8 +208,13 @@ export function optionDefaults(config = {}) {
     open: config.open ?? false,
     audio: config.audio ?? false,
     resume: config.resume ?? false,
+    incognito: config.incognito ?? false,
+    'neutral-filename': config.neutralFilename ?? false,
     playlist: config.playlist ?? false,
     subs: config.subs ?? false,
+    'auto-subs': config.autoSubs ?? false,
+    'sub-format': config.subFormat,
+    verify: config.verify ?? false,
     'embed-subs': config.embedSubs ?? false,
     'embed-metadata': config.embedMetadata ?? false,
     'embed-thumbnail': config.embedThumbnail ?? false,
@@ -238,7 +256,7 @@ const COMMAND_FLAGS = {
   config: ['--profile', '--external', '--terminal'],
   profile: [],
 };
-const COMMAND_NAMES = [...Object.keys(COMMAND_FLAGS), 'retry', 'help', 'version'];
+const COMMAND_NAMES = [...Object.keys(COMMAND_FLAGS), 'retry', 'subs', 'help', 'version'];
 
 function mistypedCommandOption(args) {
   const command = args[0];
@@ -296,9 +314,18 @@ export function parseCli(args, { config = {} } = {}) {
     } else { validateItems(values['playlist-items']); values.playlist = true; }
   }
   if (values['retry-failed'] && (positionals.length || values['batch-file'])) throw new Error('--retry-failed cannot be combined with URLs or --batch-file.');
+  if (values.incognito && values['retry-failed']) throw new Error('--incognito cannot retry a saved job. Use --no-incognito for this request.');
+  if (values.incognito && values.resume) {
+    if (tokens.some(token => token.name === 'resume')) throw new Error('--incognito cannot be combined with --resume.');
+    values.resume = false;
+  }
+  if (values.incognito && values['skip-existing']) {
+    if (tokens.some(token => token.name === 'skip-existing')) throw new Error('--incognito cannot be combined with --skip-existing.');
+    values['skip-existing'] = false;
+  }
   if (!values.output.trim()) throw new Error('The output directory cannot be empty.');
   if (values.rename !== undefined && !cleanText(values.rename)) throw new Error('The custom filename cannot be empty.');
-  if (positionals.length > 1 && values.rename !== undefined && !values.rename.includes('*')) throw new Error('--rename only applies to a single URL unless the name contains * for the original title.');
+  if (!values['neutral-filename'] && positionals.length > 1 && values.rename !== undefined && !values.rename.includes('*')) throw new Error('--rename only applies to a single URL unless the name contains * for the original title.');
   if (values.audio && values.quality !== 'best' && typed.quality) throw new Error('--quality is for video; omit it when using --audio.');
   if (values.audio && values['closest-quality'] && typed.closest) throw new Error('--closest-quality is for video; omit it when using --audio.');
   if (values['closest-quality'] && values.quality === 'best' && typed.closest) throw new Error('--closest-quality requires a numeric --quality such as 1080p.');
@@ -306,11 +333,17 @@ export function parseCli(args, { config = {} } = {}) {
   delete values['list-qualitys'];
   if (values['list-qualities']) {
     if (positionals.length !== 1 || values['batch-file'] || values['retry-failed']) throw new Error('--list-qualities accepts exactly one URL.');
-    if (values['list-formats'] || values['list-sources']) throw new Error('--list-qualities cannot be combined with other listing actions.');
+    if (values['list-formats'] || values['list-sources'] || values['list-subs']) throw new Error('--list-qualities cannot be combined with other listing actions.');
     if (values.audio || values.playlist) throw new Error('--list-qualities requires a single video without --audio or --playlist.');
   }
   if (values['list-formats'] && (values.audio || values.format)) throw new Error('--list-formats cannot be combined with --audio or --format.');
   if (values['list-formats'] && positionals.length > 1) throw new Error('--list-formats accepts exactly one URL.');
+  if (values['list-subs']) {
+    if (positionals.length !== 1 || values['batch-file'] || values['retry-failed']) throw new Error('--list-subs accepts exactly one URL.');
+    if (values['list-formats'] || values['list-sources']) throw new Error('--list-subs cannot be combined with other listing actions.');
+    if (values.playlist) throw new Error('--list-subs requires a single video without --playlist.');
+  }
+  if (values['sub-format'] && (!/^[a-z0-9]+(?:\/[a-z0-9]+)*$/i.test(values['sub-format']) || values['sub-format'].length > 100)) throw new Error('--sub-format must be a format or preference list such as srt/vtt/best.');
   if (values.source && (!/^[1-9]\d*$/.test(values.source) || !Number.isSafeInteger(Number(values.source)))) throw new Error('--source requires a positive source number.');
   if (values.source && values['list-sources'] && !tokens.some(token => token.name === 'list-sources')) values['list-sources'] = false;
   if (values['list-sources'] && !tokens.some(token => token.name === 'list-sources')
@@ -356,12 +389,12 @@ export function parseCli(args, { config = {} } = {}) {
   if (!Number.isInteger(options.concurrentDownloads) || options.concurrentDownloads < 1 || options.concurrentDownloads > 4) throw new Error('--concurrent-downloads must be a whole number between 1 and 4.');
   if (options.filenameTemplate !== undefined) validateTemplate(options.filenameTemplate);
   if (options.folderTemplate !== undefined) validateTemplate(options.folderTemplate, { folders: true });
-  if (options.rename && options.filenameTemplate) throw new Error('--rename and --filename-template cannot be combined.');
+  if (options.rename && options.filenameTemplate && !options.neutralFilename) throw new Error('--rename and --filename-template cannot be combined.');
   const disableSubs = values.subs === false && tokens.some(token => token.name === 'subs');
-  if (options.subLangs && !disableSubs) options.subs = true;
+  if (options.subLangs && !disableSubs && !options.autoSubs) options.subs = true;
   if (disableSubs) {
-    options.subLangs = undefined;
     options.embedSubs = false;
+    if (!options.autoSubs) options.subLangs = undefined;
   }
   options.profile = profileName;
   return options;
@@ -373,9 +406,11 @@ export async function main(args = process.argv.slice(2), { config } = {}) {
   if (mistyped) { process.stderr.write(`veo: ${mistyped}\n`); return 1; }
   let color = !args.includes('--no-color') && !args.includes('--json');
   let display;
+  let loadedConfig;
   try {
     display = outputOptions(args);
     const loaded = config ?? await loadConfig();
+    loadedConfig = loaded.config || {};
     color = !args.includes('--json') && (display.color ?? applyProfile(loaded.config || {}, display.profile).color ?? true);
     // Validate explicit profiles even when a color flag overrides their setting.
     if (display.profile) applyProfile(loaded.config || {}, display.profile);
@@ -391,7 +426,12 @@ export async function main(args = process.argv.slice(2), { config } = {}) {
   // One throttled (once per day) update hint after every successful command.
   // Failures, cancellations, help/version output and the update commands
   // themselves never trigger it; VEO_NO_UPDATE_CHECK=1 disables it for scripts.
-  if (code === 0 && shouldUpdateNotice(args)) {
+  let incognitoRequest = !args.length;
+  if (!incognitoRequest && code === 0 && shouldUpdateNotice(args)) {
+    try { incognitoRequest = Boolean(parseCli(args, { config: loadedConfig }).incognito); }
+    catch { /* Non-download commands have their own argument parser. */ }
+  }
+  if (code === 0 && shouldUpdateNotice(args) && !incognitoRequest) {
     try {
       const notice = await maybeUpdateNotice({ currentVersion: await packageVersion() });
       if (notice) process.stderr.write(`${notice}\n`);
@@ -447,6 +487,17 @@ async function runMain(args, { config }) {
       args = ['--retry-failed', await latestFailedJob(), ...args.slice(2)];
     } catch (error) { stderr.write(`veo: ${readableError(error)}\n`); return 1; }
   }
+  if (args[0] === 'subs') {
+    if (args[1] === '--help' || args[1] === '-h') {
+      stdout.write('veo subs <url> [--json] [--source <n>] [--profile <name>]\n\nList manual and automatically generated subtitle languages and source formats without downloading media.\n');
+      return 0;
+    }
+    if (!args[1] || args[1].startsWith('-')) {
+      stderr.write('veo: Usage: veo subs <url> [--json] [--source <n>]\n');
+      return 1;
+    }
+    args = [args[1], '--list-subs', ...args.slice(2)];
+  }
   if (args[0] === 'profile') {
     try { return await profileMain(args.slice(1)); }
     catch (error) { stderr.write(`veo: ${readableError(error)}\n`); return 1; }
@@ -509,9 +560,6 @@ async function runMain(args, { config }) {
   process.once('SIGINT', cancel);
   process.once('SIGTERM', cancel);
   try {
-    if (!args.includes('--help') && !args.includes('-h') && !args.includes('--version')) {
-      run = await (await import('./runs.js')).registerRun(cancel);
-    }
     const loaded = config ?? await loadConfig();
     for (const warning of loaded.warnings || []) stderr.write(`veo: ${warning}\n`);
     if (!args.length && process.stdin.isTTY && process.stderr.isTTY) {
@@ -526,6 +574,7 @@ async function runMain(args, { config }) {
       stdout.write(`${pkg.version}\n`);
       return 0;
     }
+    if (!options.incognito) run = await (await import('./runs.js')).registerRun(cancel);
     let retryItems;
     if (options.retryFailed) {
       retryItems = await retryOptions(options.retryFailed);
@@ -546,19 +595,19 @@ async function runMain(args, { config }) {
       options.urls.push(...lines.map(validateUrl));
       options.url = options.urls[0];
       if (!options.urls.length) throw new Error('The URL list is empty.');
-      if (options.rename && options.urls.length > 1 && !options.rename.includes('*')) throw new Error('--rename only applies to a single URL unless the name contains * for the original title.');
+      if (!options.neutralFilename && options.rename && options.urls.length > 1 && !options.rename.includes('*')) throw new Error('--rename only applies to a single URL unless the name contains * for the original title.');
       if (options.listFormats && options.urls.length > 1) throw new Error('--list-formats accepts exactly one URL.');
     }
     await confirmExperimentalFragments(retryItems || [options], { signal: controller.signal });
     // The job file is created before the first download, so another terminal can
     // follow this run's per-item progress with `veo runs <id>`.
-    const jobFile = options.listQualities || options.listFormats || options.listSources || options.dryRun ? null : jobFilePath();
+    const jobFile = options.incognito || options.listQualities || options.listFormats || options.listSources || options.listSubs || options.dryRun ? null : jobFilePath();
     await run?.describe({ urls: options.urls, output: options.output ? path.resolve(options.output) : null,
       audio: options.audio, quality: options.quality, format: options.format, profile: options.profile || null,
       playlist: options.playlist, job: jobFile });
     reporter.configure?.({ color: options.color && !options.json });
     reporter.start(options.rename);
-    if (!options.dryRun && !options.listQualities && !options.listFormats && !options.listSources) reporter.profile(options.profile);
+    if (!options.dryRun && !options.listQualities && !options.listFormats && !options.listSources && !options.listSubs) reporter.profile(options.profile);
     const preparedBackends = new Map();
     const reuseBackend = request => preparedBackends.has(request.url) ? async () => preparedBackends.get(request.url) : undefined;
     const cookieWarning = cookieFileWarning(options.cookies);
@@ -596,6 +645,20 @@ async function runMain(args, { config }) {
       item.mediaUrl = discovery.mediaUrl;
     }
 
+    if (options.listSubs) {
+      const { listSubtitles } = await import('./downloader.js');
+      const result = await listSubtitles(options, { signal: controller.signal, reporter, backendResolver: reuseBackend(options) });
+      if (options.json) stdout.write(`${JSON.stringify(result)}\n`);
+      else {
+        stdout.write(`Subtitles: ${cleanText(result.title || options.url)}\n`);
+        for (const [label, entries] of [['Manual', result.manual], ['Automatic', result.automatic]]) {
+          stdout.write(`${label}:\n`);
+          if (!entries.length) stdout.write('  none\n');
+          for (const entry of entries) stdout.write(`  ${cleanText(entry.language)}${entry.name ? ` (${cleanText(entry.name)})` : ''}: ${entry.formats.join(', ') || 'unknown'}\n`);
+        }
+      }
+      return 0;
+    }
     if (options.listQualities) {
       const { listQualities } = await import('./downloader.js');
       const result = await listQualities(options, { signal: controller.signal, reporter, backendResolver: reuseBackend(options) });
@@ -631,7 +694,8 @@ async function runMain(args, { config }) {
     const { createHistoryRecorder } = await import('./history.js');
     if (!options.json && process.stdout.isTTY) reporter.enableInline();
     const result = await runJob(options, { download: (request, dependencies) => download(request, { ...dependencies, backendResolver: reuseBackend(request) }),
-      reporter, stdout: reporter.output(stdout), stderr: reporter.output(stderr), signal: controller.signal, openFile, items: retryItems, jobFile: jobFile || undefined, runId: run?.id, recordStats: createStatsRecorder(), recordHistory: createHistoryRecorder() });
+      reporter, stdout: reporter.output(stdout), stderr: reporter.output(stderr), signal: controller.signal, openFile, items: retryItems, jobFile: jobFile || undefined, runId: run?.id,
+      recordStats: options.incognito ? undefined : createStatsRecorder(), recordHistory: options.incognito ? undefined : createHistoryRecorder() });
     return result;
   } catch (error) {
     reporter.fail(controller.signal.aborted);

package/src/config-template.js

@@ -40,7 +40,10 @@ export const PROFILE_OPTIONS_GUIDE = String.raw`${PROFILE_OPTIONS_MARKER}
 // "folderTemplate": "{channel}/{year}",
 // "filenameTemplate": "{index} - {title}", // Without extension; do not combine with rename
 // "resume": true,
+// "incognito": false,        // Save only media; no run ID, history, stats or retry data
+// "neutralFilename": false,  // Optional random filenames; ignores rename and naming templates
 // "skipExisting": true
+// "verify": false,           // Probe saved media with FFprobe; no full decode
 // Lossless container change (the selected codecs must fit the container):
 // "format": "mkv",
 // "compatible": false,        // Opt-in H.264/AAC MP4; converts only when needed
@@ -82,7 +85,10 @@ const TEMPLATE_SOURCE = String.raw`${TEMPLATE_MARKER}
   // "section": "*10:00-12:00", // Download only a time range
   // "open": false,              // Open the completed file automatically
   // "resume": true,             // Resume interrupted downloads
+  // "incognito": true,          // Save only media; no run ID, history, stats or retry data
+  // "neutralFilename": false,  // Set true for random filenames without title or template folders
   // "skipExisting": true,       // Skip previously saved downloads
+  // "verify": false,           // Check saved media container and tracks with FFprobe
   // "concurrentFragments": 8,   // Concurrent fragments: 1 to 64; default 8
   // Values above 16 require confirmation or the explicit opt-in below.
   // "experimentalFragments": false, // true accepts experimental values 17-64
@@ -95,7 +101,9 @@ ${SOURCE_OPTIONS_GUIDE}
 
   // Subtitles and additional information:
   // "subs": true,              // Download subtitles; defaults to English
+  // "autoSubs": false,         // Include automatically generated subtitles
   // "subLangs": "de,en",        // Enable subtitles for these languages
+  // "subFormat": "srt/vtt/best", // Prefer these available subtitle formats
   // "embedSubs": true,          // Embed subtitles in the video
   // "embedMetadata": true,      // Embed the title, date and other metadata
   // "embedThumbnail": true,     // Embed the thumbnail

package/src/config.js

@@ -29,6 +29,8 @@ export const CONFIG_KEYS = Object.freeze({
   audio: 'boolean',
   open: 'boolean',
   resume: 'boolean',
+  incognito: 'boolean',
+  neutralFilename: 'boolean',
   closestQuality: 'boolean',
   cookies: 'string',
   cookiesFromBrowser: 'string',
@@ -36,7 +38,10 @@ export const CONFIG_KEYS = Object.freeze({
   concurrentFragments: 'number',
   experimentalFragments: 'boolean',
   subs: 'boolean',
+  autoSubs: 'boolean',
   subLangs: 'string',
+  subFormat: 'string',
+  verify: 'boolean',
   embedSubs: 'boolean',
   embedMetadata: 'boolean',
   embedThumbnail: 'boolean',

package/src/downloader.js

@@ -9,6 +9,7 @@ import path from 'node:path';
 import { resolveBackend } from './backend.js';
 import { availableHeights, cappedHeight, closestHeight, saveUnique, sanitizeTitle } from './utils.js';
 import { digest, readJson, writeJson } from './state.js';
+import { isMediaFile } from './run-archive.js';
 import { cleanupDownloadCache, downloadCacheRoot, TRANSFER_RETENTION_MS } from './download-cache.js';
 import { selectedEntries, sizeEstimate, describeEstimate } from './playlist.js';
 
@@ -157,6 +158,8 @@ function downloadSettings(options) {
     embedMetadata: false, embedThumbnail: false, ...options };
   const settings = Object.fromEntries(['quality', 'audio', 'format', 'closestQuality', 'subs', 'subLangs', 'embedSubs',
     'embedMetadata', 'embedThumbnail', 'sponsorblockRemove', 'section'].map(key => [key, options[key] ?? null]));
+  if (options.autoSubs) settings.autoSubs = true;
+  if (options.subFormat) settings.subFormat = options.subFormat;
   // Existing conversion jobs retain their keys; remux requests must not reuse them.
   if (options.format && !options.audio && !options.recode) settings.videoRemux = true;
   if (options.compatible) settings.compatible = true;
@@ -229,6 +232,7 @@ function backendArgs(options, backend) {
     '--socket-timeout', '30', '--retries', '3', '--fragment-retries', '3',
     '--no-js-runtimes', '--js-runtimes', `node:${process.execPath}`,
     '--ffmpeg-location', backend.ffmpegLocation];
+  if (options.incognito) common.push('--no-cache-dir');
   if (!options.playlist) common.push('--no-playlist');
   if (options._entryIndex) common.push('--playlist-items', String(options._entryIndex));
   common.push('--concurrent-fragments', String(options.concurrentFragments ?? 8));
@@ -265,9 +269,12 @@ function mediaArgs(options, quality) {
   // WebM keep their own source selection. Resolution remains the primary choice.
   const selectedSort = options.recode || options.format === 'webm' ? quality.sort : sort;
   if (!options.audio && selectedSort) args.push('-S', selectedSort);
-  if (options.subs || options.subLangs || options.embedSubs) {
-    args.push('--write-subs', '--sub-langs', options.subLangs || 'en.*,en');
+  if (options.subs || options.autoSubs || options.subLangs || options.embedSubs) {
+    if (options.subs || (options.embedSubs && !options.autoSubs)) args.push('--write-subs');
+    if (options.autoSubs) args.push('--write-auto-subs');
+    args.push('--sub-langs', options.subLangs || 'en.*,en');
   }
+  if (options.subFormat) args.push('--sub-format', options.subFormat);
   if (options.embedSubs) args.push('--embed-subs');
   if (options.embedMetadata) args.push('--embed-metadata');
   if (options.embedThumbnail) args.push('--embed-thumbnail');
@@ -334,6 +341,19 @@ export async function listQualities(options, { signal, backendResolver = resolve
   return { url: options.url, status: 'qualities', title: metadata.title || null, qualities };
 }
 
+/** List subtitle languages and source formats without exposing signed subtitle URLs. */
+export async function listSubtitles(options, { signal, backendResolver = resolveBackend, runner = runBackend, reporter } = {}) {
+  const backend = await prepareBackend(options, { signal, backendResolver, reporter });
+  const metadata = await fetchMetadata({ ...options, playlist: false }, { signal, backend, runner, reporter });
+  const summarize = source => Object.entries(source || {}).map(([language, tracks]) => ({
+    language,
+    name: Array.isArray(tracks) ? tracks.find(track => typeof track?.name === 'string')?.name || null : null,
+    formats: Array.isArray(tracks) ? [...new Set(tracks.map(track => track?.ext).filter(ext => typeof ext === 'string' && /^[a-z0-9]+$/i.test(ext)))].sort() : [],
+  })).sort((a, b) => a.language.localeCompare(b.language));
+  return { url: options.url, status: 'subtitles', title: metadata.title || null,
+    manual: summarize(metadata.subtitles), automatic: summarize(metadata.automatic_captions) };
+}
+
 /** `veo --list-formats`: print the backend's own format table and stop. */
 export async function listFormats(options, { signal, backendResolver = resolveBackend, runner = runBackend, reporter } = {}) {
   const backend = await prepareBackend(options, { signal, backendResolver, reporter });
@@ -405,8 +425,9 @@ async function downloadCollection(options, metadata, dependencies) {
       } catch (error) {
         if (signal?.aborted) throw error;
         failures.push({ index, error: error.message });
+        results[offset] = error.files || [];
         reporter?.status(`Entry ${index} failed: ${error.message}`);
-        outcome = { index, status: 'failed', error: error.message };
+        outcome = { index, status: 'failed', error: error.message, files: error.files || [] };
       }
       await notify(outcome);
     }
@@ -417,7 +438,9 @@ async function downloadCollection(options, metadata, dependencies) {
   if (rejected) throw rejected.reason;
   const files = results.flatMap(files => files || []);
   failures.sort((a, b) => a.index - b.index);
-  return { url: options.url, title: metadata.title || metadata.id || 'Playlist', files, saved, skipped, failures, ...(entryTimings.length ? { entryTimings: entryTimings.sort((a, b) => a.index - b.index) } : {}),
+  return { url: options.url, title: metadata.title || metadata.id || 'Playlist', files, saved, skipped, failures,
+    ...(options.verify && !failures.length && !skipped ? { verified: true } : {}),
+    ...(entryTimings.length ? { entryTimings: entryTimings.sort((a, b) => a.index - b.index) } : {}),
     status: failures.length ? 'failed' : saved ? 'saved' : 'skipped' };
 }
 
@@ -425,7 +448,7 @@ async function downloadCollection(options, metadata, dependencies) {
  * Download one URL. Returns every file that was saved, in the order the
  * backend produced them, so collections and subtitle sidecars are reported.
  */
-export async function download(options, { signal, reporter, backendResolver = resolveBackend, runner = runBackend, onEntry, localRoot = downloadCacheRoot(), skipCacheCleanup = false, adaptiveState = { divisor: 1 }, wait, diskChecker = reserveSpace, now, compatibilityRunner = runBackend } = {}) {
+export async function download(options, { signal, reporter, backendResolver = resolveBackend, runner = runBackend, onEntry, localRoot = downloadCacheRoot(), skipCacheCleanup = false, adaptiveState = { divisor: 1 }, wait, diskChecker = reserveSpace, now, compatibilityRunner = runBackend, verifier } = {}) {
   const timer = phaseTimer(now);
   const timingResult = () => {
     if (options.timings === false) return {};
@@ -438,13 +461,13 @@ export async function download(options, { signal, reporter, backendResolver = re
   const stagingPath = path.join(localRoot, `${PARTIAL_PREFIX}${requestKey}`);
   const existingStage = await lstat(stagingPath).catch(error => { if (error.code === 'ENOENT') return null; throw error; });
   if (existingStage && (!existingStage.isDirectory() || existingStage.isSymbolicLink())) throw new Error(`The partial download path is not a plain directory: ${stagingPath}`);
-  const cached = await readJson(path.join(stagingPath, 'job.json'), null);
+  const cached = options.incognito ? null : await readJson(path.join(stagingPath, 'job.json'), null);
   const readyToTransfer = cached?.requestKey === requestKey && cached.ready?.length && cached.metadata
     && (cached.backendSucceeded === true || cached.compatibilityChecked === true || cached.files?.length);
   const backend = readyToTransfer ? null : await prepareBackend(options, { signal, backendResolver, reporter });
   timer.switch('metadata');
   const metadata = readyToTransfer ? cached.metadata : await adaptiveRun(() => fetchMetadata(options, { signal, backend, runner, reporter }), { enabled: options.adaptiveConcurrency !== false, state: adaptiveState, signal, reporter, wait, timer });
-  if (metadata.entries && !options._entryIndex) return downloadCollection(options, metadata, { signal, reporter, backendResolver: async () => backend, runner, onEntry, localRoot, adaptiveState, wait, diskChecker, now, compatibilityRunner });
+  if (metadata.entries && !options._entryIndex) return downloadCollection(options, metadata, { signal, reporter, backendResolver: async () => backend, runner, onEntry, localRoot, adaptiveState, wait, diskChecker, now, compatibilityRunner, verifier });
   const destination = mediaDestination(options, metadata, stagedTitle('media.mp4', metadata, options.rename));
   directory = destination.directory;
   await prepareDestination(options.output, directory);
@@ -456,10 +479,23 @@ export async function download(options, { signal, reporter, backendResolver = re
 
   const key = partialKey(metadata, options.url, options);
   const historyFile = path.join(directory, '.veo-history', `${key}.json`);
-  const history = options.skipExisting || (options.resume && options._entryIndex) ? await readJson(historyFile, null) : null;
-  if (await pruneHistoryRecord(historyFile, directory, history)) {
+  const history = !options.incognito && (options.skipExisting || (options.resume && options._entryIndex)) ? await readJson(historyFile, null) : null;
+  if (!options.incognito && await pruneHistoryRecord(historyFile, directory, history)) {
+    if (options.verify) {
+      const verifyFile = verifier || (await import('./inspect-media.js')).verifySavedMedia;
+      try {
+        const media = history.files.filter(isMediaFile);
+        if (!media.length) throw new Error('Verification failed: no saved media file was found.');
+        for (const file of media) await verifyFile(file, { audio: Boolean(options.audio), signal });
+      } catch (error) {
+        error.files = history.files;
+        error.verificationFailed = true;
+        throw error;
+      }
+    }
     reporter?.status('Already downloaded; skipped.');
-    return { url: options.url, title: metadata.title, files: [], status: 'skipped', saved: 0, skipped: 1, ...timingResult() };
+    return { url: options.url, title: metadata.title, files: [], status: 'skipped', saved: 0, skipped: 1,
+      ...(options.verify ? { verified: true } : {}), ...timingResult() };
   }
   const staging = await prepareStaging(stagingPath);
   const lockPath = path.join(staging, '.lock');
@@ -562,15 +598,30 @@ export async function download(options, { signal, reporter, backendResolver = re
       files.push(saved);
       files.push(...await saveSidecars(staging, resolved, saved, { signal, manifest, manifestFile }));
     }
-    await writeJson(historyFile, { version: 1, source: sourceKey(metadata, options.url), settings: downloadSettings(options), files });
-    return { url: options.url, title: metadata.title || metadata.id || 'video', files, status: 'saved', saved: 1, skipped: 0, ...timingResult() };
+    if (options.verify) {
+      const media = files.filter(isMediaFile);
+      if (!media.length) throw new Error('Verification failed: no saved media file was found.');
+      const verifyFile = verifier || (await import('./inspect-media.js')).verifySavedMedia;
+      try {
+        reporter?.status('Verifying saved media…');
+        for (const file of media) await verifyFile(file, { audio: Boolean(options.audio), signal });
+        reporter?.status('Media verification passed.');
+      } catch (error) {
+        error.files = files;
+        error.verificationFailed = true;
+        throw error;
+      }
+    }
+    if (!options.incognito) await writeJson(historyFile, { version: 1, source: sourceKey(metadata, options.url), settings: downloadSettings(options), files });
+    return { url: options.url, title: metadata.title || metadata.id || 'video', files, status: 'saved', saved: 1, skipped: 0,
+      ...(options.verify ? { verified: true } : {}), ...timingResult() };
   } catch (error) {
     if (!signal?.aborted) reporter?.failStep?.();
     // A kept staging directory is the whole point of --resume, and cancellation
     // is the most common reason to want one.
-    keepPartial = Boolean(options.resume || manifest?.ready?.length || unconfirmedOutput);
+    keepPartial = !options.incognito && !error.verificationFailed && Boolean(options.resume || manifest?.ready?.length || unconfirmedOutput);
     if (manifest && unconfirmedOutput) manifest.unconfirmedOutput = true;
-    if (manifest?.ready?.length || (unconfirmedOutput && !options.resume)) {
+    if (keepPartial && (manifest?.ready?.length || (unconfirmedOutput && !options.resume))) {
       manifest.expiresAt = Date.now() + TRANSFER_RETENTION_MS;
       await writeJson(manifestFile, manifest);
     }

package/src/inspect-media.js

@@ -92,6 +92,17 @@ export async function inspectMedia(file, { checkAudio = false, signal, runner =
   return result;
 }
 
+/** A fast post-download container/stream check; it does not decode the full file. */
+export async function verifySavedMedia(file, { audio = false, signal, inspect = inspectMedia } = {}) {
+  let report;
+  try { report = await inspect(file, { signal }); }
+  catch (error) { throw new Error(`Verification failed for ${file}: ${error.message}`); }
+  if (audio ? !report.hasAudioTrack : !report.hasVideoTrack) {
+    throw new Error(`Verification failed for ${file}: no ${audio ? 'audio' : 'video'} track found.`);
+  }
+  return report;
+}
+
 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);

package/src/interactive.js

@@ -104,10 +104,15 @@ export async function interactiveArgs(config, { signal, input = process.stdin, o
     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');
+    args.push('-o', directory);
+    if (defaults.incognito) {
+      args.push('--no-resume', '--no-skip-existing');
+    } else {
+      args.push('--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;

package/src/jobs.js

@@ -1,7 +1,8 @@
 import { runPool, serialQueue, reducedLimit, formatTimings } from './execution.js';
 import { styleText, terminalText } from './progress.js';
 import path from 'node:path';
-import { lstat, readdir } from 'node:fs/promises';
+import { lstat, mkdtemp, readdir, rm } from 'node:fs/promises';
+import os from 'node:os';
 import { randomUUID } from 'node:crypto';
 import { cacheBase } from './paths.js';
 import { publicOptions, readJson, writeJson } from './state.js';
@@ -74,6 +75,13 @@ export async function latestFailedJob(root = cacheBase()) {
 }
 
 export async function runJob(options, { download, reporter, signal, openFile, stdout = process.stdout, stderr = process.stderr, jobFile, items, recordStats, recordHistory, runId, archiveRoot } = {}) {
+  if (options.incognito) {
+    runId = undefined;
+    recordStats = undefined;
+    recordHistory = undefined;
+  }
+  const concurrency = options.concurrentDownloads ?? 2;
+  if (!Number.isInteger(concurrency) || concurrency < 1 || concurrency > 4) throw new Error('Concurrent downloads must be between 1 and 4.');
   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) }),
@@ -81,17 +89,17 @@ export async function runJob(options, { download, reporter, signal, openFile, st
   // 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();
+  if (!options.incognito) await cleanupDownloadCache();
+  const privateRoot = options.incognito ? await mkdtemp(path.join(os.tmpdir(), 'veo-incognito-')) : null;
   const queue = serialQueue();
-  const persist = () => queue(() => writeJson(file, job));
+  const persist = () => options.incognito ? Promise.resolve() : 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) => {
+  try {
+    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;
@@ -133,7 +141,8 @@ export async function runJob(options, { download, reporter, signal, openFile, st
       try {
         item.status = 'running';
         await persist();
-        const result = await download(request, { reporter: itemReporter, signal, adaptiveState, skipCacheCleanup: true, onEntry: async entry => {
+        const result = await download(request, { reporter: itemReporter, signal, adaptiveState, skipCacheCleanup: true,
+          ...(privateRoot ? { localRoot: privateRoot } : {}), onEntry: async entry => {
           await captureFiles(entry.files);
           item.entries.push(entry);
           await persist();
@@ -156,9 +165,10 @@ export async function runJob(options, { download, reporter, signal, openFile, st
         item.status = signal?.aborted ? 'cancelled' : 'failed';
         item.error = readableError(error);
         if (!signal?.aborted) failed++;
-        item.files = item.entries.flatMap(entry => entry.files || []);
+        item.files = [...new Set([...item.entries.flatMap(entry => entry.files || []), ...(error.files || [])])];
         if (options.json) stdout.write(`${JSON.stringify({ url: request.url, status: item.status, profile: request.profile || null, error: item.error, files: item.files, ...(runId ? { runId } : {}) })}\n`);
         else stderr.write(styleText(stderr, terminalText(stderr, `veo: ${item.error} (${request.url})`), 'error', options.color !== false) + '\n');
+        if (error.verificationFailed && !options.json) for (const file of item.files) stderr.write(`Saved file retained: ${cleanText(file)}\n`);
       }
       if (recordStats) {
         try {
@@ -180,7 +190,10 @@ export async function runJob(options, { download, reporter, signal, openFile, st
       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; });
+    }, { signal }).catch(error => { if (!signal?.aborted) throw error; });
+  } finally {
+    if (privateRoot) await rm(privateRoot, { recursive: true, force: true });
+  }
   const { saved, skipped, failed } = totals;
   if (runId) {
     try {
@@ -199,7 +212,7 @@ export async function runJob(options, { download, reporter, signal, openFile, st
     }
     if (Object.keys(totals).length) stderr.write(styleText(stderr, formatTimings(totals), 'muted', options.color !== false && !options.json) + '\n');
   }
-  if (unfinished) stderr.write(`Retry failed/unfinished downloads: veo --retry-failed ${runId || `"${file}"`}\n`);
+  if (unfinished && !options.incognito) stderr.write(`Retry failed/unfinished downloads: veo --retry-failed ${runId || `"${file}"`}\n`);
   if (unfinished) reporter.fail(Boolean(signal?.aborted)); else reporter.complete();
   return signal?.aborted ? 130 : unfinished ? 1 : 0;
 }

package/src/naming.js

@@ -1,5 +1,6 @@
 import path from 'node:path';
 import { lstat, mkdir } from 'node:fs/promises';
+import { randomBytes } from 'node:crypto';
 import { sanitizeTitle } from './utils.js';
 
 const FIELDS = new Set(['title', 'id', 'channel', 'year', 'playlist', 'index']);
@@ -17,6 +18,9 @@ export function validateTemplate(template, { folders = false } = {}) {
 }
 
 export function mediaDestination(options, metadata, fallbackTitle) {
+  if (options.neutralFilename) {
+    return { directory: path.resolve(options.output), title: `video-${randomBytes(6).toString('hex')}` };
+  }
   const fields = {
     title: metadata.title || metadata.id || 'video', id: metadata.id || 'unknown',
     channel: metadata.channel || metadata.uploader || 'Unknown channel',