veodl 1.12.1 → 2.0.1

package/README.md

@@ -1,910 +1,1040 @@
-# veo
-
-A small, clean video-downloading CLI powered by [yt-dlp](https://github.com/yt-dlp/yt-dlp). No banners, just progress and the saved file path.
-
-Automating with an agent? Start with the [agent guide](docs/AGENT_GUIDE.md) for JSON output, run inspection and audio verification.
-
-**Only download content you own or are authorized or legally permitted to download.** Respect copyright, website terms, and access restrictions. veo does not bypass DRM, private-content access controls, or paywalls.
-
-## Install and run
-
-Requires **Node.js 22+** and npm. Internet access is needed for installation and first-use backend setup.
-
-The npm package is `veodl`; the installed commands are `veo` and `veodl`.
-
-```bash
-npx veodl "https://example.com/video.mp4"
-```
-
-Or install globally:
-
-```bash
-npm install -g veodl
-veo "https://example.com/video.mp4"
-# or: veodl "https://example.com/video.mp4"
-```
-
-The first download automatically prepares missing yt-dlp, FFmpeg and FFprobe.
-On Android/Termux this includes installing the native packages and yt-dlp's
-JavaScript support with `pkg install -y`. On desktop systems, missing media tools
-are downloaded into veo's own cache. Run `veo doctor fix` to prepare everything
-before downloading. Plain `veo doctor`, help and version do not install tools.
-
-From this checkout, without publishing:
-
-```bash
-npm install
-node bin/veo.js --help
-npm link
-veo "https://example.com/video.mp4"
-```
-
-`package.json` maps `"veo": "./bin/veo.js"`; npm creates the executable/shim automatically. No custom command prefix is needed. Use only trusted URLs, and quote URLs to protect query strings from your shell.
-
-If something does not work, run `veo doctor` first: it inspects the whole local setup and prints one line per check.
-
-Run `veo` without arguments in an interactive terminal for a guided download: choose a
-profile, enter a link, select video or audio, choose available resolution and output
-directory, and start. The wizard checks the link and asks about playlist mode only when
-it finds a collection; configured playlist and entry selection values are preselected.
-Playlist mode also lists entries for selection. The wizard enables
-resume and offers skipping previously downloaded files. With redirected input, use the
-regular command arguments; veo never starts a prompt in a script.
-
-## Usage
-
-```text
-veo <url> [<url>...] [options]
-
-Options:
-  -q, --quality <quality>   best, 2160p, 1440p, 1080p, 720p, 480p, 360p
-  -o, --output <path>       Output directory (default: current working directory)
-  -r, --rename <name>       Filename without extension; * inserts the original title
-  --closest-quality         Nearest available resolution instead of an upper bound
-  --open                    Open the saved file with your default app
-  --audio                   Audio only (MP3 by default)
-  --format <format>         Video: mp4, mkv, webm, mov
-                            Audio: mp3, m4a, aac, opus, flac, wav
-  --recode                  Explicit video conversion (requires --format)
-  --playlist-concurrency <n> Parallel playlist entries, 1-4 (default: 2)
-  --playlist                Download every entry of a playlist or channel URL
-  -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)
-  --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
-  --sponsorblock-remove <categories>   e.g. "sponsor,selfpromo"
-  --section <range>         Only a time range, e.g. "*10:00-12:00"
-  --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)
-  --retry-failed <id|file>  Retry failed/unfinished downloads by run ID or job file
-  --playlist-items <list>   Select entries, e.g. 1,3-5 (implies --playlist)
-  --skip-existing          Skip matching downloads that are still on disk
-  --no-<boolean-option>    Disable a default, e.g. --no-open or --no-audio
-  -v, --version             Show installed version (also: veo version)
-  -h, --help                Show help
-```
-
-```bash
-veo "https://youtube.com/watch?v=VIDEO_ID" -q 1080p
-veo "https://x.com/USER/status/STATUS_ID" -q best
-veo "https://example.com/video.mp4" --audio
-veo "https://example.com/video.mp4" --audio --format flac
-veo "https://example.com/video.mp4" --format webm --recode -o ./videos
-veo "https://example.com/video.mp4" -r "My Video" --format mp4 --open
-veo "https://example.com/video.mp4" --audio -r "My Music"
-veo <url1> <url2> <url3> --embed-metadata --subs
-veo "https://youtube.com/playlist?list=LIST_ID" --playlist -q 720p
-veo "https://example.com/video.mp4" --resume
-npx veodl "https://example.com/video.mp4" --output ./downloads
-```
-
-### Several URLs and playlists
-
-Playlist downloads use two concurrent entries by default; use `--playlist-concurrency 1` for sequential downloads. Each entry uses up to eight concurrent DASH/HLS fragments by default (`-N 1` disables fragment parallelism). Fragment counts between 1 and 16 need no confirmation. Values from 17 to 64 are experimental and prompt for `y/N` confirmation in terminals, or require `--experimental-fragments` (or `"experimentalFragments": true` in configuration/profiles) in non-interactive environments and JSON mode. Values above 64 are rejected. More connections help only when the source and connection have spare capacity, and excessive connections may trigger server limits. Video format changes preserve the encoded streams unless `--recode` is explicitly enabled; audio extraction and precise section cuts retain their existing conversion behavior.
-
-- Pass any number of URLs; up to two run concurrently by default. Use
-  `--concurrent-downloads 1` for sequential processing. A failure is reported
-  with its URL and does not stop the remaining URLs; the exit status is `1` if anything
-  failed.
-- Playlists, channels and other collections are refused by default with a hint. Add
-  `--playlist` to download every entry. Each entry keeps its own title; `--rename` applies
-  a name prefix per entry (`My Name - 001`), or substitutes each title with `movie_*`.
-- Use `--playlist-items 1,3-5` to select entries by their original, one-based index.
-  Playlist entries run with bounded parallelism: a failed entry does not discard successful
-  files or stop the remaining entries. Before downloading, veo displays the selected count
-  and a size estimate when the source supplies sizes. Unknown sizes are labeled explicitly;
-  metadata estimates do not predict conversion size.
-- `--batch-file links.txt` accepts a UTF-8 URL list, optionally alongside URLs on the command
-  line. A final summary counts saved, skipped and failed videos. Successful files are opened
-  with `--open` even if another URL or playlist entry fails.
-- Failed or cancelled jobs print a ready-to-use `veo --retry-failed <runId>` command. Saved job file paths are also accepted.
-- Use `veo retry --last` to retry the newest failed or unfinished job without copying its path. Active runs are ignored; use `veo runs` to inspect them.
-  Jobs are stored under the per-user veo cache's `jobs` directory. Retries retain resolved
-  output directories and settings, even from a different working directory, and explicit
-  flags can override them. Completed playlist jobs retry only failed indices; interrupted
-  playlists revisit their selection and skip completed entries through resume history.
-  Playlist indices refer to the playlist's current order, so changes to that order can
-  change what an index selects. Cookie paths and browser-session settings are not saved in
-  retry jobs; pass those flags again if needed. Job files contain URLs, settings and local
-  file paths and can be deleted when no longer needed.
-
-```bash
-veo --batch-file links.txt --profile archive
-veo "https://example.com/playlist" --playlist-items 1,3-5 --resume
-veo "https://example.com/playlist" --playlist --skip-existing
-veo --retry-failed "C:\path\to\job.json"
-veo --retry-failed abc123
-veo retry --last
-```
-
-### Quality
-
-- Numeric qualities are an **upper bound**: `-q 720p` downloads the best resolution at or
-  below 720p, so a metered connection can never accidentally receive a 2160p file. If a
-  source offers nothing at or below the request, veo stops before downloading and lists
-  the resolutions that do exist.
-- `--closest-quality` restores the former "nearest available resolution" rule, which may
-  pick a resolution *above* the request. It needs a numeric `--quality`.
-- Sources that report no resolution metadata fall back to the best available stream.
-  Collections resolve and enforce the quality limit separately for each entry.
-- Other positive numeric resolutions, such as `-q 540p`, are also accepted. The interactive
-  wizard offers the resolutions reported by the source; without resolution metadata it
-  offers `best` rather than inventing available streams.
-- `--quality` does not apply to audio.
-- MP4-compatible codecs are preferred at the selected resolution; merged video prefers MP4
-  with MKV fallback. A single-file source may retain its original container. Use
-  `--format mp4` to require MP4 through lossless remuxing. Incompatible codecs cause an error.
-- `--format` on video remuxes without re-encoding. Add `--recode` to explicitly allow conversion, which may be slow or lossy. Audio formats require `--audio`.
-
-### Playback compatibility
-
-H.264/AAC sources are preferred at the selected quality, including explicit MP4 output.
-Original codecs are retained by default; a playback note identifies media needing extra
-player codecs. MP4 is a container, not a promise of a particular codec.
-
-Use `veo URL --compatible` to ensure MP4 with H.264 8-bit 4:2:0 and AAC.
-Already compatible streams are copied; only incompatible streams are encoded (H.264 CRF 18,
-AAC 192 kbit/s), which takes time and may lose quality. HDR requiring video conversion
-is refused rather than silently losing correct colors. Embedded subtitles/thumbnails are
-not supported in this mode; separate subtitle files remain supported.
-New configs include a `kompatibel` profile; existing configs receive a commented profile
-example through `veo config edit`. Enable it with `veo URL --profile kompatibel`.
-
-### Download controls and diagnostics
-
-- URL lists and batch files use `--concurrent-downloads 2` by default (range 1–4).
-  Each playlist independently uses `--playlist-concurrency 2` (range 1–4).
-  The limits multiply when several playlists run at once. JSON emits one complete
-  object per URL in completion order; the `url` field identifies each result.
-- Adaptive concurrency is on by default. After the backend's own retries are exhausted,
-  HTTP 429/5xx and temporary connection failures trigger at most two further attempts,
-  after 2 and 4 seconds. Fragment parallelism and future URL/playlist workers are reduced
-  for the rest of the run. Active downloads finish normally; format and quality stay fixed.
-  Partials are continued on retry. Use `--no-adaptive-concurrency` to disable this.
-- `--check-space` checks cache and destination free space before media transfer. Known
-  sizes include conservative room for merge output and a destination copy, plus space
-  reserved by concurrent downloads in the same process. Unknown sizes are reported as
-  unknown; conversion sizes and other processes' disk usage cannot be predicted exactly.
-  Use `--no-check-space` to disable this conservative check.
-- `--timings` shows phase times at the end of the run. Single downloads show
-  timing without a summary; multiple downloads show timing below the summary.
-  The phases cover setup, metadata, download/backend, processing, saving and retry waits.
-  Download/backend includes the backend's own startup and extraction overhead;
-  these are summed per-download times, not a diagnosis of network speed.
-  JSON results include `timings` in milliseconds, or `entryTimings` for playlists.
-  Use `--no-timings` to hide/omit them.
-- Terminal details are gray, titles bold, saves green and errors red. The same styling
-  applies to stats, history, runs/stop, doctor, flush, updates, config prose, help and
-  interactive prompts. For example, `veo stats --no-color` disables it for one command. Redirected output
-  and JSON have no color escapes. `--no-color`, `"color": false`, `NO_COLOR`,
-  and `TERM=dumb` disable colors.
-  Terminal reports shorten long URLs, paths and detail values to the current window
-  width. Titles can use up to three lines before an ellipsis is added. This also
-  applies with `--no-color`; JSON and redirected output retain complete values.
-  Downloads stay in the normal terminal flow. Only the current progress block is
-  updated in place; narrow windows put the statistics below the progress bar.
-  Existing logs remain in scrollback and are not replayed or rewritten on resize.
-  This can be set independently per profile, for example
-  `"profiles": { "default": { "color": true }, "plain": { "color": false } }`.
-  Use `veo stats --profile plain` or `veo URL --profile plain`; `--color` or
-  `--no-color` overrides the profile for one invocation (except `NO_COLOR`).
-  External npm/editor output and Node runtime warnings keep their own formatting.
-
-### Filename templates and folders
-
-`--filename-template` controls the name without extension; `--folder-template`
-creates relative subfolders under `--output`. Both support `{title}`, `{id}`,
-`{channel}`, `{year}`, `{playlist}` and `{index}` (three-digit playlist index).
-Missing metadata uses readable fallbacks. `{year}` is the upload year when available.
-Subtitles follow the media name. Existing files are never overwritten. Templates cannot
-escape the output folder, and symlink/junction subfolders are refused. Use forward slashes
-for folders. `--rename` and `--filename-template` are mutually exclusive.
-
-```powershell
-veo "VIDEO-URL" --folder-template "{channel}/{year}" --filename-template "{title} - {id}"
-veo "PLAYLIST-URL" --playlist --folder-template "{playlist}" --filename-template "{index} - {title}"
-veo config check
-veo config check --profile fast
-veo config show --profile fast
-```
-
-Config checks validate every effective profile (or the selected one), including unknown
-settings, ranges and conflicting options. Show prints merged built-in, global and profile
-settings as JSON, with credential paths/browser profiles redacted. Neither command contacts
-video sites. All new options are also documented in `veo config guide`.
-
-### Files, names and resume
-
-- Original titles are preserved by default. Use `-r "My Video"` or `--rename "My Video"`
-  for video or audio. Supply the name **without an extension**; the actual media extension
-  is appended automatically. Use `-o` for the directory. Invalid filename characters are
-  sanitized and overly long names shortened. Existing files are never intentionally
-  overwritten: duplicates get ` (1)`, ` (2)`, etc.
-- Use `-r "movie_*"` or `"rename": "movie_*"` in your config/profile to insert the
-  original title: `My Film` becomes `movie_My Film.mp4`. Every `*` is substituted.
-  Quote the pattern in your shell. Patterns also work with URL batches and playlists.
-- Subtitles and thumbnails are saved beside the media file under the same base name
-  (`My Video.mp4` → `My Video.en.vtt`).
-- Downloads and media processing first finish in the local per-user veo cache, under
-  `downloads` (`%LOCALAPPDATA%\veo\downloads` on Windows). The destination is only written
-  after the media is ready. Saving uses a hard link when supported or an exclusive copy
-  across drives/cloud mounts; copied file sizes are checked. Existing files are never
-  overwritten. The local original is removed only after files and history are saved.
-  Local disk space is therefore needed for the complete download and processing files.
-- If saving fails or is cancelled after media processing completes, the local original and
-  sidecars are kept for **15 minutes**, even without `--resume`. Repeat the same command or
-  use the printed `--retry-failed` command to retry the transfer. Individual completed
-  downloads can be recovered without contacting their source again. The same source,
-  media settings and destination identify a cached transfer; changing those starts a new
-  download. Expired copies are removed on the next veo invocation, not by a background
-  timer while veo is closed. Active transfers are never expired. Another failed transfer
-  starts a fresh 15-minute retention period.
-- `--resume` also keeps unfinished downloads in local `.veo-part-<request-hash>` folders
-  until resumed; unfinished data has no automatic expiry. Without `--resume`, unfinished
-  downloads are discarded on failure or cancellation. The hash separates source URLs,
-  playlist entries, destinations, quality, media type, format, sections and subtitle/metadata
-  options. A manifest records backend-confirmed
-  completion and saved files, so an unprocessed file is not mistaken for a finished video.
-  Each playlist entry has its own state. Completed entries survive later failures and are
-  skipped when resuming the same selection. Partial downloads are never resumed without
-  `--resume`. Legacy partial folders in the output directory are left untouched; the new
-  local cache does not automatically migrate them.
-- A lock prevents two resume processes from using the same partial folder. Normal failures
-  and Ctrl+C release it. After a force kill, remove the named `.lock` file only after making
-  sure no veo process still uses that folder.
-- Successful downloads record their source, output settings and saved paths in
-  `.veo-history` inside the output directory. `--skip-existing` uses these records and checks
-  that the files still exist. A different quality/format or deleted output is downloaded
-  again. Files downloaded before this history existed are not recognized automatically.
-  Deleting history removes duplicate detection, not downloaded media. Records whose files
-  no longer exist are removed on the next download into that folder, and `.veo-history`
-  itself is removed with its last record; `veo doctor` reports stale records.
-
-### Metadata and subtitles
-
-- `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.
-- `--section "*10:00-12:00"` downloads only a time range.
-- `-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
-not expose options that defeat them. If you need your own session for content you are
-authorized to view:
-
-- `--cookies ./cookies.txt` passes a Netscape-format cookie file. The file is validated
-  before any network work, and on Unix a file readable by other users produces a warning.
-- `--cookies-from-browser firefox:Work` reads cookies from an installed browser: `brave`,
-  `chrome`, `chromium`, `edge`, `firefox`, `opera`, `safari`, `vivaldi`, `whale`, optionally
-  with `+gnomekeyring`/`+kwallet`/`+basic` and a profile or container.
-
-Credentials are used for that single invocation only and are never stored by veo. When a
-download fails because a login is required, the error message points at these flags.
-
-### Inspection and scripting
-
-- `veo <page-url> --list-sources` opens the page in a temporary headless Chrome,
-  Edge or Chromium profile, repeatedly checks for visible Play controls (including
-  controls added later or inside frames), and watches media requests after interaction.
-  Use `--json` for numbered source
-  metadata. Each result includes its title, host, HLS/DASH/direct type, known
-  resolutions, estimated MiB size and Mbit/s bitrate when the source provides them. Signed media
-  URLs are not printed. Set `VEO_BROWSER_PATH` if the browser is not found.
-- Add `--deep-scan` to verify every media candidate observed during the source
-  search. The normal search verifies at most 30 candidates. `--timeout 30s`
-  sets a deadline for browser observation and candidate verification; plain
-  numbers mean seconds, and `m` means minutes (5 seconds to 10 minutes).
-  Defaults are 45 seconds, or 2 minutes with `--deep-scan`. If the deadline
-  is reached, verified sources found so far are shown with a timeout notice.
-  A deep scan covers observed requests; it cannot discover sources that the
-  page never loads. The timeout does not stop a subsequent download.
-- For an unsupported single page URL, veo searches for media automatically and
-  uses the only verified source when there is one. If several sources are found,
-  the terminal asks which one to use; scripts receive a numbered source list and
-  a nonzero exit. `veo <page-url> --source 2 --dry-run --json` previews a chosen
-  source, and `veo <page-url> --source 2 --json` downloads it. Scripts never
-  receive an interactive prompt.
-  Retry jobs retain the page URL and selected number and discover a fresh media
-  URL, because player links may expire. Browser discovery uses a temporary
-  profile without copying browser cookies, and cannot unlock DRM content.
-  Misspelled flags and commands show a nearby valid spelling, for example
-  `--deepscan` suggests `--deep-scan`.
-- `veo <url> --list-qualities` lists available video resolutions, highest first,
-  without downloading media. `--list-qualitys` is an alias. Add `--json` for
-  a `qualities` array (e.g. `["1080p", "720p"]`); use `--quality 720p` to select
-  an upper bound. Unknown resolutions are reported without guessing. Audio-only,
-  storyboard and DRM formats are excluded. Supports `--source <number>` for embedded players.
-- `--list-formats` prints the backend's own format table for one URL and exits.
-- `--dry-run` prints the title, the resolved quality and the destination path that would be
-  used — without creating the output directory or downloading anything.
-- `--json` prints one JSON object per line on stdout:
-  `{"url":…,"status":"saved","title":…,"files":[…]}` or
-  `{"url":…,"status":"failed","error":…}`. Progress and status still go to stderr. Without
-  `--json`, every saved file is printed as `Saved: <path>` on stdout.
-  Duplicate detection can return `status: "skipped"`; cancellation returns `"cancelled"`.
-  Playlist results also include `saved`, `skipped` and `failures` (with original indices).
-  A failed or cancelled playlist can still report files saved before the failure.
-- `veo runs [id] --json` reports active run metadata and per-item progress. Finished attempts
-  remain available through `veo history --json`.
-- `veo inspect <file> --json` reports local container and stream metadata. Add
-  `--check-audio` to decode all audio tracks and measure whether any peak exceeds
-  -60 dBFS. A track can exist without a detectable signal. The check reads the full
-  media file and uses only local FFmpeg/FFprobe tools.
-- Download results and history retain a `runId`. `veo inspect run <id> --json` reads
-  a finished run and checks every saved file before probing it. Renamed media is
-  found by file identity, size and a sampled SHA-256 fingerprint within the original output tree;
-  add `--search <directory>` after moving it elsewhere. Ambiguous or missing files
-  are reported without probing another file. Old runs lack this persistent record.
-  Finished run records live in the current device's veo cache. On Windows, macOS,
-  Linux and Termux, `inspect` uses bundled media tools where supported and otherwise
-  uses local `ffmpeg` and `ffprobe` (or `VEO_FFMPEG_PATH`); it does not install them.
-  Copying only the media to another device does not copy its run ID record.
-
-### Config file
-
-Defaults can be stored in a config file, so a long list of flags is not needed for every
-call. `veo doctor` prints the exact path; `VEO_CONFIG` overrides it.
-The file accepts JSON with `//` line comments and `/* ... */` block comments. Strings
-(including URLs and Windows paths) keep their normal JSON escaping rules. Trailing commas
-are not allowed.
-
-- Windows: `%APPDATA%\veo\config.json`
-- macOS: `~/Library/Application Support/veo/config.json`
-- Linux: `$XDG_CONFIG_HOME/veo/config.json` (or `~/.config/veo/config.json`)
-
-```json
-{
-  "output": "D:\\Videos",
-  "quality": "1080p",
-  "embedMetadata": true,
-  "subLangs": "de,en",
-  "concurrentFragments": 4
-}
-```
-
-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`, `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.
-
-Source discovery defaults are `deepScan` (boolean), `timeout` (string such as
-`"30s"` or `"2m"`), `listSources` (boolean) and `autoListSources` (boolean).
-`listSources: true` makes a single URL list sources and exit; use
-`--no-list-sources` to download for one invocation. `autoListSources` defaults
-to `true` and searches when ordinary extraction finds no downloadable video.
-Set it to `false` or pass `--no-auto-list-sources` to disable that fallback.
-A single verified source is selected automatically; multiple sources require
-a choice. `deepScan` and
-`timeout` apply to either kind of source search.
-
-Additional defaults are `skipExisting` and `playlistItems`. Boolean defaults can be disabled
-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`
-selects another named profile for future commands and stores it as `activeProfile` in the
-config; `veo profile` shows the current choice, and `veo profile list` marks it in
-the list. `veo profile reset` removes the stored choice and returns to `default`.
-You can also use `veo profile default` to select it explicitly.
-The names `list` and `reset` are reserved for these commands and cannot be used as profile names.
-`--profile NAME` overrides this choice for one command. Named profiles use global defaults
-rather than inheriting `default`. The wizard preselects the active profile.
-New configurations include an empty `default` profile and the example profiles. Existing configurations are
-left unchanged when opened. An empty profile does not change download behavior.
-
-```json
-{
-  "output": "D:\\Videos",
-  "profiles": {
-    "default": { "quality": "1080p", "resume": true },
-    "music": { "audio": true, "format": "mp3", "output": "D:\\Music" },
-    "archive": { "quality": "1080p", "embedMetadata": true, "subLangs": "de,en" }
-  }
-}
-```
-
-`veo <url> --profile music` merges global defaults, then the selected profile, then explicit
-CLI flags. `veo config profiles` lists profile names; `veo config path` prints the file path.
-The download status shows `Profile: NAME` (or `global (no profile)` when none is configured).
-`veo config edit` creates a small, valid configuration for new or empty files. Opening an
-existing configuration does not add or update comments. The current option guide is kept in
-the program; `veo config guide` prints it without changing the file. In the built-in editor,
-F3 offers **A** to add or update the guide at the top and **R** to remove a previously
-generated guide. Ctrl+S saves that choice. This can also clean up the long duplicate block
-inserted by older versions. Personal settings and notes below a generated block are preserved.
-In an interactive terminal, it opens the built-in editor
-unless `VISUAL` or `EDITOR` is configured (an executable path, without shell arguments).
-The editor provides syntax colors, line numbers and live validation. Syntax errors mark
-the affected line; unknown properties and invalid values are highlighted directly, with
-spelling suggestions, expected types and allowed values in the status area. Validation uses
-the same rules as the CLI, including profile overrides and audio/video formats.
-Press F2 on a property or value to open suggestions, use Up/Down to choose, Enter to apply
-or Esc to cancel. Suggestions require valid JSON syntax; free-text values and custom numeric
-resolutions such as `900p` remain supported. Ctrl+S validates and saves;
-Ctrl+Z undoes edits, Ctrl+Y redoes them, and Ctrl+A selects the whole file.
-Esc or Ctrl+Q exits, asking before discarding changes. Use arrows, Home/End and PageUp/PageDown
-to navigate. Invalid configurations cannot be saved. `--no-color` disables syntax colors.
-In terminals supporting SGR mouse reporting, left-click positions the cursor and dragging
-selects text, including across lines. Holding the pointer at the top or bottom while dragging
-scrolls the file and extends the selection. Backspace/Delete removes the selection; typing replaces
-it. The mouse wheel scrolls without changing the editing position; Ctrl+Up/Down also scrolls.
-Ctrl+C copies selected text to the system clipboard, and Ctrl+V pastes clipboard text at the
-cursor or replaces the selection. Ctrl+Q or Esc exits the editor. The editor disables mouse
-reporting again when it exits. Keyboard editing remains available in terminals without mouse
-support.
-Clipboard access uses the system clipboard on Windows, `pbcopy`/`pbpaste` on macOS, and
-`wl-clipboard` (Wayland), `xclip` or `xsel` (X11) on Linux. Linux requires one of those tools
-and access to a graphical session. The editor reports when no clipboard is available; terminal
-paste shortcuts can still insert text directly when supported by the terminal.
-On Termux, editor clipboard shortcuts use `termux-clipboard-set`/`termux-clipboard-get`
-when the Termux:API app and `termux-api` package are installed.
-
-Use `veo config edit --external` to use `VISUAL`, then `EDITOR`, then Notepad on Windows
-or `vi` elsewhere. `veo config edit --terminal` explicitly selects the built-in editor.
-Set `VEO_CONFIG_EDITOR=external` to disable the built-in editor by default (`auto` restores
-automatic selection, `terminal` forces it). For a persistent Windows preference:
-
-```powershell
-[Environment]::SetEnvironmentVariable('VEO_CONFIG_EDITOR', 'external', 'User')
-$env:VEO_CONFIG_EDITOR = 'external'
-```
-
-Non-interactive sessions use the external editor unless `--terminal` is explicitly selected,
-in which case an interactive-terminal error is reported. The wizard also offers configured profiles.
-Generated guides and app messages are in English. Existing comments, profile names and
-settings are preserved when opening the editor.
-
-### Terminal output
-
-- During a download, the terminal/tab title shows `veo | 50% | My Video` (original title or
-  your `-r` name), plus setup/processing status. It ends with `Done`, `Failed`, or
-  `Cancelled`; the shell may replace it at the next prompt. This uses the native console
-  title on Windows (including PowerShell/Windows Terminal) and OSC title sequences on
-  compatible Linux/macOS terminals. Titles are not changed when stderr is redirected or
-  `TERM=dumb`. Terminal settings that enforce a fixed tab title can override this feature.
-- Progress shows percentage, speed, downloaded/total size and ETA on stderr; unknown values
-  appear as `?`. Separate audio/video streams each have their own progress. Non-interactive
-  output is throttled.
-- Progress labels include the current item (`[3/12]`), source title, video/audio/media stream,
-  postprocessing (merging, conversion, subtitles or metadata) and saving. Stream percentages
-  describe that stream, not the entire multi-step job. Sources without codec metadata use
-  the neutral `Media` label.
-- `--open` launches the completed file in your default app, including renamed files and
-  audio. With several URLs, the primary file of each URL is opened. Uses `explorer.exe` on
-  Windows, `open` on macOS, and `xdg-open` on Linux (requires a graphical desktop,
-  xdg-utils and a file association). The CLI does not wait for the player to close. If the
-  opener cannot be launched, a warning is printed and the successful download still exits
-  with `0`; later errors inside the detached opener/player are not monitored.
-- After each successful command, veo checks the npm registry at most once per day for a
-  newer version and prints a one-line notice on stderr (`Update available: veo X
-  (you have Y). Run: veo up`). Help, version and the update commands themselves
-  stay quiet. Disable it with `VEO_NO_UPDATE_CHECK=1`;
-  `VEO_REGISTRY`/`npm_config_registry` are respected.
-- Exit status is `0` on success, `1` on errors, and `130` on cancellation. With several
-  URLs, `1` means at least one URL failed.
-
-## Commands
-
-```bash
-veo version           # installed version (also: veo --version or veo -v)
-veo                   # interactive download wizard (terminal only)
-veo config edit       # create/open config; F3 offers the optional guide
-veo config guide      # print the current option guide
-veo config reset      # confirm with y; back up config and restore the current template
-veo config profiles   # list available profiles
-veo profile            # show the currently selected profile
-veo profile list       # list all profiles and mark the active one
-veo profile music      # use music as the default for future commands
-veo profile reset      # return to default (or global settings if absent)
-veo config path       # show the config file location
-veo doctor            # diagnose the local setup; exit 1 if a check fails
-veo doctor fix        # restore missing or damaged managed tools
-veo doctor --offline  # skip the network checks
-veo stats             # persistent download totals; --json for scripting
-veo history           # the last 5 downloads; --json for scripting
-veo history --failed --limit 20  # recent failed/cancelled attempts
-veo changes           # released versions, newest first; the installed one is marked
-veo changes 1.10.1    # notes of one release (also: --version 1.10.1)
-veo changes --since 1.10.1  # everything newer than a version
-veo changes --latest --json  # newest release as JSON
-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
-veo flush --stats     # the same, and reset the statistics
-veo update            # install the latest veo with npm
-veo update --check    # only check for a newer veo
-veo up                # short alias for veo update (also: veo up --check)
-veo upgrade           # alias for veo update
-veo check update      # alias for veo update --check
-veo backend update    # install the newest yt-dlp release
-veo backend reset     # back to the release pinned in this veo version
-veo alias list        # shipped (veo, veodl) plus custom wrappers
-veo alias add veo-dl  # create veo-dl as a wrapper that calls veo
-veo alias remove veo-dl  # delete a custom wrapper
-veo uninstall -p veodl   # delete one alias (veo itself stays installed)
-veo uninstall            # plan the full removal (aliases, package, cache, config)
-veo uninstall --yes      # remove everything
-```
-
-`veo update` runs `npm install -g veodl@latest` and then removes yt-dlp backend
-caches from older pinned releases, keeping an explicitly installed backend release. It
-never uses a shell on Linux/macOS, passes fixed arguments only, and prints the manual npm
-command on any failure. The registry can be overridden with `VEO_REGISTRY` (or npm's
-`npm_config_registry`) for mirrors and proxies.
-
-### `veo alias` and `veo uninstall`
-
-The npm package is `veodl`; a global install ships the commands `veo`
-and `veodl`. `veo alias` manages extra command names without reinstalling:
-
-```bash
-veo alias list
-veo alias add veo-dl
-veo alias remove veo-dl
-veo uninstall -p veodl
-```
-
-`add` creates a small wrapper next to the `veo` command found on `PATH` that
-forwards to `veo`, so it survives `veo update`. Names use 2-31 lowercase
-letters, digits or hyphens. `remove` (also `veo alias rm`) deletes the wrapper
-files; `veo` itself can never be removed this way. Removing a shipped name such
-as `veodl` only deletes that shortcut — the next `veo update` recreates it.
-
-`veo uninstall -p <name>` is a shortcut for `veo alias remove <name>`. Bare
-`veo uninstall` removes everything: without flags it only prints the plan
-(package `veodl` with commands veo, veodl, plus custom wrappers, cache
-and config paths); `veo uninstall --yes` deletes all of it — custom wrappers,
-the package with `npm uninstall -g veodl`, veo's cache directory (downloads,
-jobs, backend tools, history, statistics) and the config file. Use
-`--keep-aliases`, `--keep-cache` or `--keep-config` to preserve one part.
-The plan shows the active config path, including a `VEO_CONFIG` override.
-Add `--json` for scripting.
-
-### `veo flush`
-
-Run `veo flush` to stop active veo runs started with this version, then remove
-temporary local downloads, including the 15-minute retained files and unfinished
-resume data, and cached retry job JSON files. Those jobs can no longer be retried.
-Saved media, output history, config/profiles, the `veo history` list, finished-run
-records and backend binaries are kept.
-Cleanup waits for cancellation; if a run cannot stop, it fails without deleting
-download or job files. Locked folders from older or interrupted processes are
-skipped and reported. Only veo's own per-user cache is cleaned. Statistics are
-preserved unless `--stats` is given: `veo flush --stats` resets them too.
-To end runs without removing their downloads and jobs, use `veo stop [id]` instead.
-
-### `veo stats`
-
-Shows saved videos/audio, failed attempts, skips, cancellations and total time spent
-on download requests (including preparation, processing and saving). Parallel run
-times are added together. Playlist entries count individually; retries are new
-attempts. Active requests are recorded when they finish. Tracking starts with this
-version; previous downloads are not imported. `veo stats --json` returns the totals
-as JSON. Statistics contain counters and timestamps, not URLs or filenames.
-
-### `veo history`
-
-Shows the **last 5 download attempts** by default, newest first, with title, status, media type,
-date, duration, URL and the saved files. Saved, skipped, failed and cancelled items are
-recorded, including the reason a failure was reported; playlist entries and retried
-attempts count individually. Active downloads appear once they finish. Long file lists
-are summarized in the text view.
-
-Use `veo history --limit N` to show 1-1000 attempts, or `veo history --failed` to
-show only failed and cancelled attempts; the flags can be combined. Failed attempts
-include their exact retry-job command when one was recorded. New attempts also show
-their persistent run ID for `veo inspect run <id>`. `veo history --json`
-prints `{"count":N,"entries":[…]}` for scripting. Each entry has
-`at`, `url`, `title`, `status`, `media` (`video`/`audio`), `quality`, `format`, the
-complete `files` list, `error`, `elapsedMs` and an optional `job` path. Titles and paths are stored without
-terminal control characters.
-
-History is one small JSON file per attempt in the per-user veo cache's `history`
-directory, so parallel runs cannot overwrite each other and each record stays small. The
-directory keeps one file per attempt and contains URLs, titles and local file paths;
-delete it to remove those records. `veo flush` keeps the list (only `veo flush --stats`
-resets statistics, not history).
-
-### `veo changes`
-
-Lists every **released version**, newest first, and marks the installed one. `veo changelog`
-is an alias. The notes are parsed from the `CHANGELOG.md` that ships inside the package, so
-they always belong to the installed code and the command needs no network access.
-
-```bash
-veo changes                       # all versions with their Added/Changed/Fixed counts
-veo changes 1.10.1                # the notes of one release
-veo changes --version 1.10.1      # the same, spelled out
-veo changes 1.10                  # newest release starting with 1.10
-veo changes --latest              # only the newest release
-veo changes --since 1.10.0        # everything newer than 1.10.0, up to the newest release
-veo changes --range 1.9.0..1.11.0 # a closed range, newest first
-veo changes --json                # machine-readable
-```
-
-An unknown version fails with the known versions listed. Long entries wrap to the terminal
-width, and `--json` returns the complete text. Because the list already names the released
-versions, `veo changes` prints no automatic update hint.
-
-`veo changes --json` prints `{"current":…,"count":N,"versions":[…]}`, where each entry has
-`version`, `date` (currently `null`, since the changelog headings carry no date), `installed`,
-`counts` and `summary`. One version adds `"version"`, `"installed"` and `"sections"`; a range
-adds `"from"` and `"to"` and keeps the per-release `sections`. Sections are
-`{"type":"Added","items":[{"text":"…","items":[…]}]}`, and nested items are preserved.
-
-### `veo runs` and `veo stop`
-
-Every run registers itself while it works, under a **6-character id**, and removes that
-record when it ends:
-
-```bash
-veo runs            # active runs: id, PID, state, start time, progress, output directory
-veo runs k3f9qa     # one run in detail: URLs, settings, job file, per-item state
-veo stop k3f9qa     # ask that run to stop and wait until it exits
-veo stop            # stop every active run
-```
-
-`veo runs` lists the runs of this user, including those started in another terminal, and a
-run disappears from the list as soon as it finishes. Progress such as
-`1/3 done, 1 running` is read from the run's job file, which is created before the first
-download starts, so a run that is still preparing the backend shows `starting`. `veo stop
-<id>` writes a stop request that the run itself polls, so it needs no signals or PIDs and
-works the same on every platform. A stopped run exits like Ctrl+C (`130`) and keeps its
-partial data and retry job, so the printed `veo --retry-failed` command still works —
-unlike `veo flush`, which also removes that data. If a run does not stop within 15 seconds,
-`veo stop` reports it and exits with `1`.
-
-A run that crashed without cleaning up leaves its record behind: `veo runs` marks it
-`stale` and `veo stop` removes it, with or without its id. Records contain the id, process
-id, start time, URLs, output directory and job path — never cookie files, browser sessions
-or other credentials. Unknown or damaged record files are ignored instead of breaking veo,
-because a single stray file in the cache must never stop later runs.
-
-### `veo doctor`
-
-Prints one line per check: `ok`, `warn` or `fail`. It inspects Node.js, the platform, the
-output directory, the backend cache, yt-dlp (including the SHA-256 of the cached binary and
-the version it reports), FFmpeg/FFprobe, a system FFmpeg fallback, the config file, leftover
-partial downloads, stale duplicate-detection records, the npm registry and the yt-dlp release host. It downloads no backend and
-only creates its own probe files plus the backend cache directory. Exit status is `1` when
-at least one check fails.
-
-Run `veo doctor fix` to restore missing or damaged managed tools and check again.
-It stages bundled FFmpeg/FFprobe and downloads verified yt-dlp when needed. Missing
-desktop media tools are installed in veo's cache using npm and the pinned media
-packages. On Termux it installs missing native tools with the package manager.
-With `--offline`, it only uses local binaries; missing tools are reported for an online retry.
-Use `-o PATH` to create and check an output directory. Config errors and invalid overrides
-are reported for manual correction; PATH and config values are never rewritten.
-A missing system FFmpeg is not a warning when the selected media tools work.
-
-## Supported sites and backend
-
-YouTube, X/Twitter, TikTok, Vimeo, Reddit, Instagram, and [many other yt-dlp sites](https://github.com/yt-dlp/yt-dlp/blob/master/supportedsites.md) are supported **when publicly accessible and technically available**. Support changes with websites, regions, rate limits, and backend versions; it is not a guarantee that every URL will work.
-
-Official standalone yt-dlp is acquired on first download and cached outside the package directory; help, version and plain doctor never download the backend. The release is pinned and SHA-256 verified against hashes shipped with this package. The npm package has no runtime dependencies and runs no installation scripts.
-
-When no trusted local FFmpeg/FFprobe pair is available, veo downloads both tools directly from the upstream [ffmpeg-static binary releases](https://github.com/eugeneware/ffmpeg-static/releases/tag/b6.1.1). Release URLs, compressed and executable SHA-256 hashes, and byte counts are pinned in the package. The complete pair and its license and README must pass verification before either executable is started. Later uses verify the cached pair again; legacy or damaged cached binaries are not accepted merely because they are executable. Most targets use FFmpeg 6.1.1; Windows ia32 uses the last available pair, FFmpeg 6.0. Old `FFMPEG_BINARIES_URL`, `FFMPEG_BINARY_RELEASE` and `FFMPEG_BIN` variables do not change these downloads. Use `VEO_FFMPEG_PATH` to choose a trusted installed pair explicitly.
-
-The downloaded binaries retain their separate upstream licenses. `FFmpeg.LICENSE` and `FFmpeg.README` are saved next to the cached tools, including upstream source and build information. The JavaScript CLI remains MIT licensed. No Python installation is needed on supported standalone platforms.
-
-The existing Node executable is explicitly enabled as yt-dlp's JavaScript runtime for YouTube. Local yt-dlp configuration and plugins are disabled for predictable execution. Arguments are passed without a shell.
-
-Windows ARM64 uses an FFmpeg/FFprobe pair found on `PATH`, including the usual
-WinGet, Chocolatey and `C:\ffmpeg\bin` locations, or automatically downloads x64
-media tools for Windows 11's x64 emulation.
-
-### Android / Termux
-
-With Node.js 22+ and npm already installed in Termux:
-
-```sh
-npm install -g veodl
-veo "URL"
-```
-
-On Android, veo automatically finds `yt-dlp`, `ffmpeg` and `ffprobe` on PATH
-(also checking `$PREFIX/bin`). If tools or the `yt-dlp-ejs` Python module are
-missing, it runs `pkg install -y python-yt-dlp yt-dlp-ejs ffmpeg` automatically,
-then checks the installed programs before continuing the download. Python is
-installed as a dependency. Termux with the pacman package manager uses
-`--noconfirm` instead. This needs a working Termux repository and internet access.
-No root access is needed. Later runs reuse the installed tools.
-
-The npm installation does not pull in desktop FFmpeg packages.
-The system yt-dlp is maintained by Termux and is
-not pinned or hash-verified by veo. Explicit `VEO_YT_DLP_PATH` and
-`VEO_FFMPEG_PATH` overrides still take precedence.
-
-`veo doctor fix` also performs this automatic setup; `veo doctor fix --offline`
-never invokes a package manager. Update Termux packages with `pkg upgrade`;
-`veo backend update` prints this platform's update instructions.
-
-To save files in Android's shared Downloads folder, run `termux-setup-storage`,
-grant the storage permission, then use `veo "URL" -o ~/storage/downloads`.
-Keep veo and its tools in Termux's private storage.
-
-For existing published veo 1.6.1 installations (before this automatic setup), run:
-
-```sh
-pkg install python-yt-dlp yt-dlp-ejs ffmpeg
-export VEO_YT_DLP_PATH="$(command -v yt-dlp)"
-export VEO_FFMPEG_PATH="$PREFIX/bin"
-veo doctor
-```
-
-These exports apply to the current shell; add them to your shell startup file
-if you need them on subsequent launches of 1.6.1.
-
-### Advanced overrides
-
-- `VEO_YT_DLP_PATH`: absolute path to a trusted, current yt-dlp executable. It always takes
-  precedence over the managed backend, including one installed by `veo backend update`.
-- `VEO_FFMPEG_PATH`: directory containing both `ffmpeg` and `ffprobe` executables (with
-  `.exe` on Windows).
-- `VEO_CONFIG`: path to the config file.
-
-Automatic setup covers Windows x64/ia32/ARM64, macOS x64/ARM64, Linux x64/ARM64,
-and Android through Termux. Windows ARM64 media tools require x64 emulation.
-`--open` uses `termux-open` in Termux; another Android app must be available to view the file.
-Other systems should supply trusted native binaries. Node.js 22+, npm, internet
-access, executable private storage and working OS libraries are prerequisites;
-network blocks or unavailable repositories can still prevent setup. Android's
-shared-storage permission must be granted by the user. Maintainers should update
-the pinned yt-dlp release and hashes as websites change,
-or users can install a newer release themselves.
-
-### Installing a newer backend
-
-```bash
-veo backend update --check   # is a newer yt-dlp release available?
-veo backend update           # install it
-veo backend reset            # forget it, use the pinned release again
-```
-
-The pinned backend is hash-verified against values compiled into this veo version. That
-guarantee cannot cover a release that did not exist when this version was built, so
-`veo backend update` verifies the download against the `SHA2-256SUMS` file published with
-that release over HTTPS: the trust anchor becomes HTTPS and GitHub instead of the npm
-package. It is opt-in, it says so on stderr when it runs, and `veo backend reset` (plus the
-next `veo update`) returns to the pinned release. An installed release is used only while it
-is newer than the pinned one and its bytes still match the recorded hash; anything else
-silently falls back to the pinned release.
-
-## Develop and publish
-
-```bash
-npm install
-npm test                 # unit tests, no network
-npm run test:smoke       # real downloads: local HTTP server, real yt-dlp, real FFmpeg
-npm run test:open        # real download plus a controlled desktop-opener replacement
-npm pack
-npm run check:package    # inspect the packed tarball
-npm link
-veo --version
-# Then, authenticated as the account that owns the name:
-npm publish
-```
-
-The smoke test generates a two-second synthetic video with FFmpeg, serves it on loopback,
-and runs real yt-dlp downloads. It checks default output, the quality cap, duplicate names,
-audio extraction, conversion, dry-run, format listing, JSON output, metadata embedding,
-resume, batch behaviour, playlist selection and nonzero failures, and verifies that a
-finished download whose destination was unavailable is retried from the local cache
-without contacting the source again. It also confirms that real runs leave `veo history`
-entries, that finished runs clean up their record, and that `veo runs`/`veo stop` report
-nothing left behind. It needs network access once for yt-dlp acquisition; it downloads no
-third-party video. Prepare media tools with `veo doctor fix` before `npm test` on a fresh checkout; the tests themselves use local fixtures and require no network. CI explicitly prepares and verifies the native binary pair before testing.
-
-The published tarball only includes `bin/`, `src/`, package metadata, README and LICENSE.
-The lockfile is kept for reproducible development. There is no build step. npm makes the
-shebang-bearing bin executable on installation (on Unix, `chmod +x bin/veo.js` also enables
-direct checkout execution).
-
-Continuous integration runs the unit tests on Windows, macOS and Linux for Node 22 and 24,
-runs the end-to-end smoke test on Node 22, and verifies the packed tarball.
-
-Modules separate argument parsing (`src/cli.js`), configuration (`src/config.js`,
-`src/config-errors.js`, `src/config-template.js`), backend setup (`src/backend.js`),
-backend updates (`src/backend-update.js`), download orchestration (`src/downloader.js`,
-`src/download-cache.js`), retry jobs (`src/jobs.js`), playlists (`src/playlist.js`),
-statistics, download history, the run registry and cleanup (`src/stats.js`,
-`src/history.js`, `src/runs.js`, `src/flush.js`), diagnostics (`src/doctor.js`),
-progress (`src/progress.js`), and helpers (`src/utils.js`, `src/paths.js`,
-`src/state.js`, `src/version.js`) so new options and providers can be added without
-replacing the CLI.
-
-## License
-
-MIT for this CLI. yt-dlp and FFmpeg/FFprobe retain their respective upstream licenses.
-# Clickable paths
-
-In supported terminals (Windows Terminal, iTerm2, WezTerm, Kitty, VS Code and recent VTE terminals), the `Saved:` path, `veo config path` and the config editor's header link to the containing folder. Use the terminal's link gesture, usually Ctrl+click or Cmd+click. The terminal and operating system decide whether file links open the file manager; unsupported terminals and redirected output show plain paths. Missing paths are not linked. JSON output remains plain.
+# veo
+
+A small, clean video-downloading CLI powered by [yt-dlp](https://github.com/yt-dlp/yt-dlp). No banners, just progress and the saved file path.
+
+Automating with an agent? Start with the [agent guide](docs/AGENT_GUIDE.md) for JSON output, run inspection and audio verification.
+
+**Only download content you own or are authorized or legally permitted to download.** Respect copyright, website terms, and access restrictions. veo does not bypass DRM, private-content access controls, or paywalls.
+
+## Install and run
+
+veo is a single native executable (written in Rust) for Windows, macOS, Linux and
+Android/Termux. Internet access is needed for installation and first-use backend setup.
+
+The npm package is `veodl`; the installed commands are `veo` and `veodl`. npm installs the
+prebuilt binary for your platform from a matching `veodl-<platform>-<arch>` package; no
+install scripts run. Node.js is only needed for npm itself, not to run downloads.
+
+```bash
+npx veodl "https://example.com/video.mp4"
+```
+
+Or install globally:
+
+```bash
+npm install -g veodl
+veo "https://example.com/video.mp4"
+# or: veodl "https://example.com/video.mp4"
+```
+
+The first download automatically prepares missing yt-dlp, FFmpeg and FFprobe.
+On Android/Termux this includes installing the native packages and yt-dlp's
+JavaScript support with `pkg install -y`. On desktop systems, missing media tools
+are downloaded into veo's own cache. Run `veo doctor fix` to prepare everything
+before downloading. Plain `veo doctor`, help and version do not install tools.
+
+Without npm, download the binary for your platform from the GitHub releases page, or
+build it with Rust 1.85+:
+
+```bash
+cargo install --git https://github.com/Mailo037/veodl
+```
+
+From this checkout:
+
+```bash
+cargo build --release     # target/release/veo
+cargo test                # unit and offline end-to-end tests
+cargo test --test smoke -- --ignored   # real downloads with yt-dlp and FFmpeg
+```
+
+Use only trusted URLs, and quote URLs to protect query strings from your shell.
+
+If something does not work, run `veo doctor` first: it inspects the whole local setup and prints one line per check.
+
+Run `veo` without arguments in an interactive terminal for a guided download: choose a
+profile, enter a link, select video or audio, choose available resolution and output
+directory, and start. The wizard checks the link and asks about playlist mode only when
+it finds a collection; configured playlist and entry selection values are preselected.
+Playlist mode also lists entries for selection. The wizard enables
+resume and offers skipping previously downloaded files. With redirected input, use the
+regular command arguments; veo never starts a prompt in a script.
+
+## Usage
+
+```text
+Usage:
+  veo <url> [<url>...] [options]
+
+Download:
+  -q, --quality <quality>     Video quality (best, 2160p, 1440p, 1080p, 720p, 480p, 360p)
+                              Numeric qualities are an upper bound: -q 720p never
+                              downloads 2160p.
+  --closest-quality           Pick the nearest available resolution, above or below
+  -o, --output <path>         Output directory (default: current directory)
+  -r, --rename <name>         Filename without extension; * inserts the original title
+  --audio                     Download audio only (default: mp3)
+  --format <format>           Video: mp4, mkv, webm, mov; audio: mp3, m4a, aac, opus, flac, wav
+                              Video uses lossless remux; incompatible codecs fail.
+  --compatible                Ensure MP4 H.264/AAC; converts only when needed (may lose quality)
+  --recode                    Allow video conversion (requires --format; may lose quality)
+  --open                      Open the saved file with your default app
+  --resume                    Keep partial data and continue an interrupted download
+  --skip-existing             Skip matching downloads still present on disk
+  --section <range>           Download only a time range, e.g. "*10:00-12:00"
+  --sponsorblock-remove <categories>
+                              Remove sponsor segments, e.g. "sponsor,selfpromo"
+
+Subtitles and metadata:
+  --subs                      Download subtitles (default languages: en)
+  --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
+
+Playlists and batches:
+  --playlist                  Download every entry of a playlist or channel URL
+  --playlist-items <list>     Select playlist entries, e.g. 1,3-5 (implies --playlist)
+  --playlist-concurrency <n>  Simultaneous playlist downloads (1-4; default: 2)
+  --concurrent-downloads <n>  Parallel URLs/batch entries (1-4; default: 2)
+  --batch-file <file>         Read URLs from a file (one per line; # comments)
+  --retry-failed <id|file>    Retry failed/unfinished items by run ID or job file
+
+Naming and privacy:
+  --filename-template <s>     Filename without extension, e.g. {index} - {title}
+  --folder-template <s>       Relative folders, e.g. {channel}/{year}
+  --neutral-filename          Use a random video name; omit title and naming templates
+  --incognito                 Save media without run IDs, history, stats or retry data
+
+Inspect before downloading:
+  --list-qualities            Show available video resolutions and exit
+  --list-qualitys             Alias for --list-qualities
+  --list-formats              Show the available formats and exit
+  --list-sources              Find video sources loaded by a web page and exit
+  --auto-list-sources         Search after no video is found (default: on)
+  --source <n>                Select source number from that page (also for scripts)
+  --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
+
+Network and performance:
+  -N, --concurrent-fragments <n>
+                              Parallel fragments (1-64; default: 8); 17-64 are experimental
+  --experimental-fragments    Explicitly accept experimental values above 16
+                              Otherwise requires terminal confirmation before download
+  --adaptive-concurrency      Reduce connections and retry temporary failures (default: on)
+  --check-space               Estimate cache/output space before downloading (default: on)
+  --cookies <file>            Netscape cookie file, for content you may access
+  --cookies-from-browser <browser[:profile]>
+                              Read cookies from an installed browser
+
+Output and scripting:
+  --json                      Print one JSON object per URL instead of prose
+  --verify                    Probe saved media files with FFprobe (default: off)
+  --timings                   Show phase timings (default: on; --no-timings disables)
+  --no-color                  Disable terminal colors (also respects NO_COLOR)
+  --profile <name>            Apply a named config profile
+  --no-<boolean-option>       Disable a stored boolean default, e.g. --no-open
+  -v, --version               Show installed version (also: veo version)
+  -h, --help                  Show help; veo help all lists every option and command
+
+Commands:
+  veo doctor                  Diagnose the local setup
+  veo update|up [--check]     Update veo itself with npm (up is a short alias)
+  veo history                 Show the last 5 downloads (--json for scripting)
+  veo history --failed --limit 20
+                              Filter and extend download history
+  veo retry --last            Retry the newest failed or unfinished job
+  veo runs [id]               List active runs; add --json for metadata and progress
+  veo stop [id]               Stop one run, or every active run
+  veo stats                   Show persistent download statistics
+  veo changes [<version>]     List release notes; --since <version> for newer changes
+  veo subs <url>              List available manual and automatic subtitles
+  veo inspect <file>          Read media metadata; --check-audio measures audio signal
+  veo inspect run <id>        Inspect saved files from a finished run by its id
+  veo backend update          Install a newer yt-dlp release (see veo backend --help)
+  veo flush                   Stop veo runs and clear temporary downloads and jobs
+  veo config edit|path|profiles|guide|check|show|reset
+                              Manage defaults and named profiles
+  veo config edit [--external|--terminal]
+                              Choose the configuration editor
+  veo profile [list|reset|name]
+                              Show, list or change the default profile
+  veo alias list|add|remove   Manage extra command names (wrappers calling veo)
+  veo uninstall [-p <name>]   Remove one alias, or everything with --yes
+  veo version                 Show the installed version
+```
+
+```bash
+veo "https://youtube.com/watch?v=VIDEO_ID" -q 1080p
+veo "https://x.com/USER/status/STATUS_ID" -q best
+veo "https://example.com/video.mp4" --audio
+veo "https://example.com/video.mp4" --audio --format flac
+veo "https://example.com/video.mp4" --format webm --recode -o ./videos
+veo "https://example.com/video.mp4" -r "My Video" --format mp4 --open
+veo "https://example.com/video.mp4" --audio -r "My Music"
+veo <url1> <url2> <url3> --embed-metadata --subs
+veo "https://youtube.com/playlist?list=LIST_ID" --playlist -q 720p
+veo "https://example.com/video.mp4" --resume
+npx veodl "https://example.com/video.mp4" --output ./downloads
+```
+
+### Several URLs and playlists
+
+Playlist downloads use two concurrent entries by default; use `--playlist-concurrency 1` for sequential downloads. Each entry uses up to eight concurrent DASH/HLS fragments by default (`-N 1` disables fragment parallelism). Fragment counts between 1 and 16 need no confirmation. Values from 17 to 64 are experimental and prompt for `y/N` confirmation in terminals, or require `--experimental-fragments` (or `"experimentalFragments": true` in configuration/profiles) in non-interactive environments and JSON mode. Values above 64 are rejected. More connections help only when the source and connection have spare capacity, and excessive connections may trigger server limits. Video format changes preserve the encoded streams unless `--recode` is explicitly enabled; audio extraction and precise section cuts retain their existing conversion behavior.
+
+- Pass any number of URLs; up to two run concurrently by default. Use
+  `--concurrent-downloads 1` for sequential processing. A failure is reported
+  with its URL and does not stop the remaining URLs; the exit status is `1` if anything
+  failed.
+- Playlists, channels and other collections are refused by default with a hint. Add
+  `--playlist` to download every entry. Each entry keeps its own title; `--rename` applies
+  a name prefix per entry (`My Name - 001`), or substitutes each title with `movie_*`.
+- Use `--playlist-items 1,3-5` to select entries by their original, one-based index.
+  Playlist entries run with bounded parallelism: a failed entry does not discard successful
+  files or stop the remaining entries. Before downloading, veo displays the selected count
+  and a size estimate when the source supplies sizes. Unknown sizes are labeled explicitly;
+  metadata estimates do not predict conversion size.
+- `--batch-file links.txt` accepts a UTF-8 URL list, optionally alongside URLs on the command
+  line. A final summary counts saved, skipped and failed videos. Successful files are opened
+  with `--open` even if another URL or playlist entry fails.
+- Failed or cancelled jobs print a ready-to-use `veo --retry-failed <runId>` command. Saved job file paths are also accepted.
+- Use `veo retry --last` to retry the newest failed or unfinished job without copying its path. Active runs are ignored; use `veo runs` to inspect them.
+  Jobs are stored under the per-user veo cache's `jobs` directory. Retries retain resolved
+  output directories and settings, even from a different working directory, and explicit
+  flags can override them. Completed playlist jobs retry only failed indices; interrupted
+  playlists revisit their selection and skip completed entries through resume history.
+  Playlist indices refer to the playlist's current order, so changes to that order can
+  change what an index selects. Cookie paths and browser-session settings are not saved in
+  retry jobs; pass those flags again if needed. Job files contain URLs, settings and local
+  file paths and can be deleted when no longer needed.
+
+```bash
+veo --batch-file links.txt --profile archive
+veo "https://example.com/playlist" --playlist-items 1,3-5 --resume
+veo "https://example.com/playlist" --playlist --skip-existing
+veo --retry-failed "C:\path\to\job.json"
+veo --retry-failed abc123
+veo retry --last
+```
+
+### Quality
+
+- Numeric qualities are an **upper bound**: `-q 720p` downloads the best resolution at or
+  below 720p, so a metered connection can never accidentally receive a 2160p file. If a
+  source offers nothing at or below the request, veo stops before downloading and lists
+  the resolutions that do exist.
+- `--closest-quality` restores the former "nearest available resolution" rule, which may
+  pick a resolution *above* the request. It needs a numeric `--quality`.
+- Sources that report no resolution metadata fall back to the best available stream.
+  Collections resolve and enforce the quality limit separately for each entry.
+- Other positive numeric resolutions, such as `-q 540p`, are also accepted. The interactive
+  wizard offers the resolutions reported by the source; without resolution metadata it
+  offers `best` rather than inventing available streams.
+- `--quality` does not apply to audio.
+- MP4-compatible codecs are preferred at the selected resolution; merged video prefers MP4
+  with MKV fallback. A single-file source may retain its original container. Use
+  `--format mp4` to require MP4 through lossless remuxing. Incompatible codecs cause an error.
+- `--format` on video remuxes without re-encoding. Add `--recode` to explicitly allow conversion, which may be slow or lossy. Audio formats require `--audio`.
+
+### Playback compatibility
+
+H.264/AAC sources are preferred at the selected quality, including explicit MP4 output.
+Original codecs are retained by default; a playback note identifies media needing extra
+player codecs. MP4 is a container, not a promise of a particular codec.
+
+Use `veo URL --compatible` to ensure MP4 with H.264 8-bit 4:2:0 and AAC.
+Already compatible streams are copied; only incompatible streams are encoded (H.264 CRF 18,
+AAC 192 kbit/s), which takes time and may lose quality. HDR requiring video conversion
+is refused rather than silently losing correct colors. Embedded subtitles/thumbnails are
+not supported in this mode; separate subtitle files remain supported.
+New configs include a `kompatibel` profile; existing configs receive a commented profile
+example through `veo config edit`. Enable it with `veo URL --profile kompatibel`.
+
+### Download controls and diagnostics
+
+- URL lists and batch files use `--concurrent-downloads 2` by default (range 1–4).
+  Each playlist independently uses `--playlist-concurrency 2` (range 1–4).
+  The worker limits multiply when several playlists run at once, while media
+  connections share a host-local budget (normally `concurrentFragments`, or the
+  larger of that and `httpConnections` for eligible native HTTP transfers).
+  JSON emits one complete
+  object per URL in completion order; the `url` field identifies each result.
+- Adaptive concurrency is on by default. After the backend's own retries are exhausted,
+  HTTP 429/5xx and temporary connection failures trigger at most two further attempts,
+  after 2 and 4 seconds. Capacity is reduced for that host, then recovers one step
+  after four successful operations. Workers wait for capacity and remain available
+  for later items. Active backend transfers retain their connection count until
+  the next attempt; format and quality stay fixed.
+  Partials are continued on retry. Use `--no-adaptive-concurrency` to disable this.
+- `--native-http` is on by default for anonymous, direct HTTP(S) video files that
+  require no subtitle, metadata or section processing. Rust reuses HTTP connections
+  and writes byte ranges into disjoint offsets of one file, avoiding an assembly
+  copy. `--http-connections 4` controls native connections (1–16); the shared host
+  budget may reduce the effective count. Files smaller than 8 MiB use one range.
+  A strong ETag and valid byte-range responses are required for ranged resume;
+  changed ETags discard partial data. Servers without range support or a strong
+  validator use a full stream. Unsupported responses fall back to yt-dlp.
+  Cookies, custom authentication headers, multiple formats and transformations
+  continue through yt-dlp. Use `--no-native-http` to force that path.
+- Single-video extraction results are reused through a private temporary info
+  file, removed when yt-dlp exits. Expired media information is refreshed. Flat
+  playlists use direct entry page URLs when available, preserving entry indices
+  for naming, selection and retry. Raw extraction results are never archived.
+- `--staging-dir output` stages under `<output>/.veo-staging`, so the final save can
+  use a hard link on supported filesystems instead of copying across drives.
+  `--staging-dir D:/veo-cache` chooses a specific staging directory. The default
+  remains local-cache staging, which can work better for slow network/cloud drives.
+  Explicit roots are registered for expiration cleanup and `veo flush`; flush
+  removes only veo partial directories and keeps saved media. Incognito creates
+  an unregistered private child directory and removes it after the attempt.
+- `--section "*10:00-12:00" --fast-cut` skips forced keyframes for a faster cut
+  aligned to nearby existing keyframes. Start/end positions can be less precise.
+  Omit `--fast-cut` to keep precise cuts. This setting changes download identity,
+  so a previous precise-cut result cannot be reused as a fast-cut result.
+- `--verify` reuses the compatibility probe only when saving preserves the exact
+  file identity, size and modification time. Converted files, copies and retained
+  transfer retries receive a fresh probe.
+- `--check-space` checks cache and destination free space before media transfer. Known
+  sizes include conservative room for merge output and a destination copy, plus space
+  reserved by concurrent downloads in the same process. Unknown sizes are reported as
+  unknown; conversion sizes and other processes' disk usage cannot be predicted exactly.
+  Use `--no-check-space` to disable this conservative check.
+- `--timings` shows phase times at the end of the run. Single downloads show
+  timing without a summary; multiple downloads show timing below the summary.
+  The phases cover setup, metadata, download/backend, processing, saving and retry waits.
+  Download/backend includes the backend's own startup and extraction overhead;
+  these are summed per-download times, not a diagnosis of network speed.
+  JSON results include `timings` in milliseconds, or `entryTimings` for playlists.
+  Use `--no-timings` to hide/omit them.
+- Terminal details are gray, titles bold, saves green and errors red. The same styling
+  applies to stats, history, runs/stop, doctor, flush, updates, config prose, help and
+  interactive prompts. For example, `veo stats --no-color` disables it for one command. Redirected output
+  and JSON have no color escapes. `--no-color`, `"color": false`, `NO_COLOR`,
+  and `TERM=dumb` disable colors.
+  Terminal reports shorten long URLs, paths and detail values to the current window
+  width. Titles can use up to three lines before an ellipsis is added. This also
+  applies with `--no-color`; JSON and redirected output retain complete values.
+  Downloads stay in the normal terminal flow. Only the current progress block is
+  updated in place; narrow windows put the statistics below the progress bar.
+  Existing logs remain in scrollback and are not replayed or rewritten on resize.
+  This can be set independently per profile, for example
+  `"profiles": { "default": { "color": true }, "plain": { "color": false } }`.
+  Use `veo stats --profile plain` or `veo URL --profile plain`; `--color` or
+  `--no-color` overrides the profile for one invocation (except `NO_COLOR`).
+  External npm and editor output keeps its own formatting.
+
+### Filename templates and folders
+
+`--filename-template` controls the name without extension; `--folder-template`
+creates relative subfolders under `--output`. Both support `{title}`, `{id}`,
+`{channel}`, `{year}`, `{playlist}` and `{index}` (three-digit playlist index).
+Missing metadata uses readable fallbacks. `{year}` is the upload year when available.
+Subtitles follow the media name. Existing files are never overwritten. Templates cannot
+escape the output folder, and symlink/junction subfolders are refused. Use forward slashes
+for folders. `--rename` and `--filename-template` are mutually exclusive.
+
+```powershell
+veo "VIDEO-URL" --folder-template "{channel}/{year}" --filename-template "{title} - {id}"
+veo "PLAYLIST-URL" --playlist --folder-template "{playlist}" --filename-template "{index} - {title}"
+veo config check
+veo config check --profile fast
+veo config show --profile fast
+```
+
+Config checks validate every effective profile (or the selected one), including unknown
+settings, ranges and conflicting options. Show prints merged built-in, global and profile
+settings as JSON, with credential paths/browser profiles redacted. Neither command contacts
+video sites. All new options are also documented in `veo config guide`.
+
+### Files, names and resume
+
+- Original titles are preserved by default. Use `-r "My Video"` or `--rename "My Video"`
+  for video or audio. Supply the name **without an extension**; the actual media extension
+  is appended automatically. Use `-o` for the directory. Invalid filename characters are
+  sanitized and overly long names shortened. Existing files are never intentionally
+  overwritten: duplicates get ` (1)`, ` (2)`, etc.
+- Use `-r "movie_*"` or `"rename": "movie_*"` in your config/profile to insert the
+  original title: `My Film` becomes `movie_My Film.mp4`. Every `*` is substituted.
+  Quote the pattern in your shell. Patterns also work with URL batches and playlists.
+- Subtitles and thumbnails are saved beside the media file under the same base name
+  (`My Video.mp4` → `My Video.en.vtt`).
+- Downloads and media processing first finish in the local per-user veo cache, under
+  `downloads` (`%LOCALAPPDATA%\veo\downloads` on Windows). The destination is only written
+  after the media is ready. Saving uses a hard link when supported or an exclusive copy
+  across drives/cloud mounts; copied file sizes are checked. Existing files are never
+  overwritten. The local original is removed only after files and history are saved.
+  Local disk space is therefore needed for the complete download and processing files.
+- If saving fails or is cancelled after media processing completes, the local original and
+  sidecars are kept for **15 minutes**, even without `--resume`. Repeat the same command or
+  use the printed `--retry-failed` command to retry the transfer. Individual completed
+  downloads can be recovered without contacting their source again. The same source,
+  media settings and destination identify a cached transfer; changing those starts a new
+  download. Expired copies are removed on the next veo invocation, not by a background
+  timer while veo is closed. Active transfers are never expired. Another failed transfer
+  starts a fresh 15-minute retention period.
+- `--resume` also keeps unfinished downloads in local `.veo-part-<request-hash>` folders
+  until resumed; unfinished data has no automatic expiry. Without `--resume`, unfinished
+  downloads are discarded on failure or cancellation. The hash separates source URLs,
+  playlist entries, destinations, quality, media type, format, sections and subtitle/metadata
+  options. A manifest records backend-confirmed
+  completion and saved files, so an unprocessed file is not mistaken for a finished video.
+  Each playlist entry has its own state. Completed entries survive later failures and are
+  skipped when resuming the same selection. Partial downloads are never resumed without
+  `--resume`. Legacy partial folders in the output directory are left untouched; the new
+  local cache does not automatically migrate them.
+- A lock prevents two resume processes from using the same partial folder. Normal failures
+  and Ctrl+C release it. After a force kill, remove the named `.lock` file only after making
+  sure no veo process still uses that folder.
+- Successful downloads record their source, output settings and saved paths in
+  `.veo-history` inside the output directory. `--skip-existing` uses these records and checks
+  that the files still exist. A different quality/format or deleted output is downloaded
+  again. Files downloaded before this history existed are not recognized automatically.
+  Deleting history removes duplicate detection, not downloaded media. Records whose files
+  no longer exist are removed on the next download into that folder, and `.veo-history`
+  itself is removed with its last record; `veo doctor` reports stale records.
+
+### Metadata and subtitles
+
+- `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.
+- `--section "*10:00-12:00"` downloads only a time range.
+- `-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
+not expose options that defeat them. If you need your own session for content you are
+authorized to view:
+
+- `--cookies ./cookies.txt` passes a Netscape-format cookie file. The file is validated
+  before any network work, and on Unix a file readable by other users produces a warning.
+- `--cookies-from-browser firefox:Work` reads cookies from an installed browser: `brave`,
+  `chrome`, `chromium`, `edge`, `firefox`, `opera`, `safari`, `vivaldi`, `whale`, optionally
+  with `+gnomekeyring`/`+kwallet`/`+basic` and a profile or container.
+
+Credentials are used for that single invocation only and are never stored by veo. When a
+download fails because a login is required, the error message points at these flags.
+
+### Inspection and scripting
+
+- `veo <page-url> --list-sources` opens the page in a temporary headless Chrome,
+  Edge or Chromium profile, repeatedly checks for visible Play controls (including
+  controls added later or inside frames), and watches media requests after interaction.
+  Use `--json` for numbered source
+  metadata. Each result includes its title, host, HLS/DASH/direct type, known
+  resolutions, estimated MiB size and Mbit/s bitrate when the source provides them. Signed media
+  URLs are not printed. Set `VEO_BROWSER_PATH` if the browser is not found.
+- Add `--deep-scan` to verify every media candidate observed during the source
+  search. The normal search verifies at most 30 candidates. `--timeout 30s`
+  sets a deadline for browser observation and candidate verification; plain
+  numbers mean seconds, and `m` means minutes (5 seconds to 10 minutes).
+  Defaults are 45 seconds, or 2 minutes with `--deep-scan`. If the deadline
+  is reached, verified sources found so far are shown with a timeout notice.
+  A deep scan covers observed requests; it cannot discover sources that the
+  page never loads. The timeout does not stop a subsequent download.
+- For an unsupported single page URL, veo searches for media automatically and
+  uses the only verified source when there is one. If several sources are found,
+  the terminal asks which one to use; scripts receive a numbered source list and
+  a nonzero exit. `veo <page-url> --source 2 --dry-run --json` previews a chosen
+  source, and `veo <page-url> --source 2 --json` downloads it. Scripts never
+  receive an interactive prompt.
+  Retry jobs retain the page URL and selected number and discover a fresh media
+  URL, because player links may expire. Browser discovery uses a temporary
+  profile without copying browser cookies, and cannot unlock DRM content.
+  Misspelled flags and commands show a nearby valid spelling, for example
+  `--deepscan` suggests `--deep-scan`.
+- `veo <url> --list-qualities` lists available video resolutions, highest first,
+  without downloading media. `--list-qualitys` is an alias. Add `--json` for
+  a `qualities` array (e.g. `["1080p", "720p"]`); use `--quality 720p` to select
+  an upper bound. Unknown resolutions are reported without guessing. Audio-only,
+  storyboard and DRM formats are excluded. Supports `--source <number>` for embedded players.
+- `--list-formats` prints the backend's own format table for one URL and exits.
+- `--dry-run` prints the title, the resolved quality and the destination path that would be
+  used — without creating the output directory or downloading anything.
+- `--json` prints one JSON object per line on stdout:
+  `{"url":…,"status":"saved","title":…,"files":[…]}` or
+  `{"url":…,"status":"failed","error":…}`. Progress and status still go to stderr. Without
+  `--json`, every saved file is printed as `Saved: <path>` on stdout.
+  Duplicate detection can return `status: "skipped"`; cancellation returns `"cancelled"`.
+  Playlist results also include `saved`, `skipped` and `failures` (with original indices).
+  A failed or cancelled playlist can still report files saved before the failure.
+- `veo runs [id] --json` reports active run metadata and per-item progress. Finished attempts
+  remain available through `veo history --json`.
+- `veo inspect <file> --json` reports local container and stream metadata. Add
+  `--check-audio` to decode all audio tracks and measure whether any peak exceeds
+  -60 dBFS. A track can exist without a detectable signal. The check reads the full
+  media file and uses only local FFmpeg/FFprobe tools.
+- Download results and history retain a `runId`. `veo inspect run <id> --json` reads
+  a finished run and checks every saved file before probing it. Renamed media is
+  found by file identity, size and a sampled SHA-256 fingerprint within the original output tree;
+  add `--search <directory>` after moving it elsewhere. Ambiguous or missing files
+  are reported without probing another file. Old runs lack this persistent record.
+  Finished run records live in the current device's veo cache. On Windows, macOS,
+  Linux and Termux, `inspect` uses bundled media tools where supported and otherwise
+  uses local `ffmpeg` and `ffprobe` (or `VEO_FFMPEG_PATH`); it does not install them.
+  Copying only the media to another device does not copy its run ID record.
+
+### Config file
+
+Defaults can be stored in a config file, so a long list of flags is not needed for every
+call. `veo doctor` prints the exact path; `VEO_CONFIG` overrides it.
+The file accepts JSON with `//` line comments and `/* ... */` block comments. Strings
+(including URLs and Windows paths) keep their normal JSON escaping rules. Trailing commas
+are not allowed.
+
+- Windows: `%APPDATA%\veo\config.json`
+- macOS: `~/Library/Application Support/veo/config.json`
+- Linux: `$XDG_CONFIG_HOME/veo/config.json` (or `~/.config/veo/config.json`)
+
+```json
+{
+  "output": "D:\\Videos",
+  "quality": "1080p",
+  "embedMetadata": true,
+  "subLangs": "de,en",
+  "concurrentFragments": 4
+}
+```
+
+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`,
+`nativeHttp`, `httpConnections`, `stagingDir`, `fastCut`,
+`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.
+
+Source discovery defaults are `deepScan` (boolean), `timeout` (string such as
+`"30s"` or `"2m"`), `listSources` (boolean) and `autoListSources` (boolean).
+`listSources: true` makes a single URL list sources and exit; use
+`--no-list-sources` to download for one invocation. `autoListSources` defaults
+to `true` and searches when ordinary extraction finds no downloadable video.
+Set it to `false` or pass `--no-auto-list-sources` to disable that fallback.
+A single verified source is selected automatically; multiple sources require
+a choice. `deepScan` and
+`timeout` apply to either kind of source search.
+
+Additional defaults are `skipExisting` and `playlistItems`. Boolean defaults can be disabled
+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`
+selects another named profile for future commands and stores it as `activeProfile` in the
+config; `veo profile` shows the current choice, and `veo profile list` marks it in
+the list. `veo profile reset` removes the stored choice and returns to `default`.
+You can also use `veo profile default` to select it explicitly.
+The names `list` and `reset` are reserved for these commands and cannot be used as profile names.
+`--profile NAME` overrides this choice for one command. Named profiles use global defaults
+rather than inheriting `default`. The wizard preselects the active profile.
+New configurations include an empty `default` profile and the example profiles. Existing configurations are
+left unchanged when opened. An empty profile does not change download behavior.
+
+```json
+{
+  "output": "D:\\Videos",
+  "profiles": {
+    "default": { "quality": "1080p", "resume": true },
+    "music": { "audio": true, "format": "mp3", "output": "D:\\Music" },
+    "archive": { "quality": "1080p", "embedMetadata": true, "subLangs": "de,en" }
+  }
+}
+```
+
+`veo <url> --profile music` merges global defaults, then the selected profile, then explicit
+CLI flags. `veo config profiles` lists profile names; `veo config path` prints the file path.
+The download status shows `Profile: NAME` (or `global (no profile)` when none is configured).
+`veo config edit` creates a small, valid configuration for new or empty files. Opening an
+existing configuration does not add or update comments. The current option guide is kept in
+the program; `veo config guide` prints it without changing the file. In the built-in editor,
+F3 offers **A** to add or update the guide at the top and **R** to remove a previously
+generated guide. Ctrl+S saves that choice. This can also clean up the long duplicate block
+inserted by older versions. Personal settings and notes below a generated block are preserved.
+In an interactive terminal, it opens the built-in editor
+unless `VISUAL` or `EDITOR` is configured (an executable path, without shell arguments).
+The editor provides syntax colors, line numbers and live validation. Syntax errors mark
+the affected line; unknown properties and invalid values are highlighted directly, with
+spelling suggestions, expected types and allowed values in the status area. Validation uses
+the same rules as the CLI, including profile overrides and audio/video formats.
+Press F2 on a property or value to open suggestions, use Up/Down to choose, Enter to apply
+or Esc to cancel. Suggestions require valid JSON syntax; free-text values and custom numeric
+resolutions such as `900p` remain supported. Ctrl+S validates and saves;
+Ctrl+Z undoes edits, Ctrl+Y redoes them, and Ctrl+A selects the whole file.
+Esc or Ctrl+Q exits, asking before discarding changes. Use arrows, Home/End and PageUp/PageDown
+to navigate. Invalid configurations cannot be saved. `--no-color` disables syntax colors.
+In terminals supporting SGR mouse reporting, left-click positions the cursor and dragging
+selects text, including across lines. Holding the pointer at the top or bottom while dragging
+scrolls the file and extends the selection. Backspace/Delete removes the selection; typing replaces
+it. The mouse wheel scrolls without changing the editing position; Ctrl+Up/Down also scrolls.
+Ctrl+C copies selected text to the system clipboard, and Ctrl+V pastes clipboard text at the
+cursor or replaces the selection. Ctrl+Q or Esc exits the editor. The editor disables mouse
+reporting again when it exits. Keyboard editing remains available in terminals without mouse
+support.
+Clipboard access uses the system clipboard on Windows, `pbcopy`/`pbpaste` on macOS, and
+`wl-clipboard` (Wayland), `xclip` or `xsel` (X11) on Linux. Linux requires one of those tools
+and access to a graphical session. The editor reports when no clipboard is available; terminal
+paste shortcuts can still insert text directly when supported by the terminal.
+On Termux, editor clipboard shortcuts use `termux-clipboard-set`/`termux-clipboard-get`
+when the Termux:API app and `termux-api` package are installed.
+
+Use `veo config edit --external` to use `VISUAL`, then `EDITOR`, then Notepad on Windows
+or `vi` elsewhere. `veo config edit --terminal` explicitly selects the built-in editor.
+Set `VEO_CONFIG_EDITOR=external` to disable the built-in editor by default (`auto` restores
+automatic selection, `terminal` forces it). For a persistent Windows preference:
+
+```powershell
+[Environment]::SetEnvironmentVariable('VEO_CONFIG_EDITOR', 'external', 'User')
+$env:VEO_CONFIG_EDITOR = 'external'
+```
+
+Non-interactive sessions use the external editor unless `--terminal` is explicitly selected,
+in which case an interactive-terminal error is reported. The wizard also offers configured profiles.
+Generated guides and app messages are in English. Existing comments, profile names and
+settings are preserved when opening the editor.
+
+### Terminal output
+
+- During a download, the terminal/tab title shows `veo | 50% | My Video` (original title or
+  your `-r` name), plus setup/processing status. It ends with `Done`, `Failed`, or
+  `Cancelled`; the shell may replace it at the next prompt. This uses the native console
+  title on Windows (including PowerShell/Windows Terminal) and OSC title sequences on
+  compatible Linux/macOS terminals. Titles are not changed when stderr is redirected or
+  `TERM=dumb`. Terminal settings that enforce a fixed tab title can override this feature.
+- Progress shows percentage, speed, downloaded/total size and ETA on stderr; unknown values
+  appear as `?`. Separate audio/video streams each have their own progress. Non-interactive
+  output is throttled.
+- Progress labels include the current item (`[3/12]`), source title, video/audio/media stream,
+  postprocessing (merging, conversion, subtitles or metadata) and saving. Stream percentages
+  describe that stream, not the entire multi-step job. Sources without codec metadata use
+  the neutral `Media` label.
+- `--open` launches the completed file in your default app, including renamed files and
+  audio. With several URLs, the primary file of each URL is opened. Uses `explorer.exe` on
+  Windows, `open` on macOS, and `xdg-open` on Linux (requires a graphical desktop,
+  xdg-utils and a file association). The CLI does not wait for the player to close. If the
+  opener cannot be launched, a warning is printed and the successful download still exits
+  with `0`; later errors inside the detached opener/player are not monitored.
+- After each successful command, veo checks the npm registry at most once per day for a
+  newer version and prints a one-line notice on stderr (`Update available: veo X
+  (you have Y). Run: veo up`). Help, version and the update commands themselves
+  stay quiet. Disable it with `VEO_NO_UPDATE_CHECK=1`;
+  `VEO_REGISTRY`/`npm_config_registry` are respected.
+- Exit status is `0` on success, `1` on errors, and `130` on cancellation. With several
+  URLs, `1` means at least one URL failed.
+
+## Commands
+
+```bash
+veo version           # installed version (also: veo --version or veo -v)
+veo                   # interactive download wizard (terminal only)
+veo config edit       # create/open config; F3 offers the optional guide
+veo config guide      # print the current option guide
+veo config reset      # confirm with y; back up config and restore the current template
+veo config profiles   # list available profiles
+veo profile            # show the currently selected profile
+veo profile list       # list all profiles and mark the active one
+veo profile music      # use music as the default for future commands
+veo profile reset      # return to default (or global settings if absent)
+veo config path       # show the config file location
+veo doctor            # diagnose the local setup; exit 1 if a check fails
+veo doctor fix        # restore missing or damaged managed tools
+veo doctor --offline  # skip the network checks
+veo stats             # persistent download totals; --json for scripting
+veo history           # the last 5 downloads; --json for scripting
+veo history --failed --limit 20  # recent failed/cancelled attempts
+veo changes           # released versions, newest first; the installed one is marked
+veo changes 1.10.1    # notes of one release (also: --version 1.10.1)
+veo changes --since 1.10.1  # everything newer than a version
+veo changes --latest --json  # newest release as JSON
+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
+veo flush --stats     # the same, and reset the statistics
+veo update            # install the latest veo with npm
+veo update --check    # only check for a newer veo
+veo up                # short alias for veo update (also: veo up --check)
+veo upgrade           # alias for veo update
+veo check update      # alias for veo update --check
+veo backend update    # install the newest yt-dlp release
+veo backend reset     # back to the release pinned in this veo version
+veo alias list        # shipped (veo, veodl) plus custom wrappers
+veo alias add veo-dl  # create veo-dl as a wrapper that calls veo
+veo alias remove veo-dl  # delete a custom wrapper
+veo uninstall -p veodl   # delete one alias (veo itself stays installed)
+veo uninstall            # plan the full removal (aliases, package, cache, config)
+veo uninstall --yes      # remove everything
+```
+
+`veo update` runs `npm install -g veodl@latest` and then removes yt-dlp backend
+caches from older pinned releases, keeping an explicitly installed backend release. It
+never uses a shell on Linux/macOS, passes fixed arguments only, and prints the manual npm
+command on any failure. The registry can be overridden with `VEO_REGISTRY` (or npm's
+`npm_config_registry`) for mirrors and proxies.
+
+### `veo alias` and `veo uninstall`
+
+The npm package is `veodl`; a global install ships the commands `veo`
+and `veodl`. `veo alias` manages extra command names without reinstalling:
+
+```bash
+veo alias list
+veo alias add veo-dl
+veo alias remove veo-dl
+veo uninstall -p veodl
+```
+
+`add` creates a small wrapper next to the `veo` command found on `PATH` that
+forwards to `veo`, so it survives `veo update`. Names use 2-31 lowercase
+letters, digits or hyphens. `remove` (also `veo alias rm`) deletes the wrapper
+files; `veo` itself can never be removed this way. Removing a shipped name such
+as `veodl` only deletes that shortcut — the next `veo update` recreates it.
+
+`veo uninstall -p <name>` is a shortcut for `veo alias remove <name>`. Bare
+`veo uninstall` removes everything: without flags it only prints the plan
+(package `veodl` with commands veo, veodl, plus custom wrappers, cache
+and config paths); `veo uninstall --yes` deletes all of it — custom wrappers,
+the package with `npm uninstall -g veodl`, veo's cache directory (downloads,
+jobs, backend tools, history, statistics) and the config file. Use
+`--keep-aliases`, `--keep-cache` or `--keep-config` to preserve one part.
+The plan shows the active config path, including a `VEO_CONFIG` override.
+Add `--json` for scripting.
+
+### `veo flush`
+
+Run `veo flush` to stop active veo runs started with this version, then remove
+temporary local downloads, including the 15-minute retained files and unfinished
+resume data, and cached retry job JSON files. Those jobs can no longer be retried.
+Saved media, output history, config/profiles, the `veo history` list, finished-run
+records and backend binaries are kept.
+Cleanup waits for cancellation; if a run cannot stop, it fails without deleting
+download or job files. Locked folders from older or interrupted processes are
+skipped and reported. Only veo's own per-user cache is cleaned. Statistics are
+preserved unless `--stats` is given: `veo flush --stats` resets them too.
+To end runs without removing their downloads and jobs, use `veo stop [id]` instead.
+
+### `veo stats`
+
+Shows saved videos/audio, failed attempts, skips, cancellations and total time spent
+on download requests (including preparation, processing and saving). Parallel run
+times are added together. Playlist entries count individually; retries are new
+attempts. Active requests are recorded when they finish. Tracking starts with this
+version; previous downloads are not imported. `veo stats --json` returns the totals
+as JSON. Statistics contain counters and timestamps, not URLs or filenames.
+
+### `veo history`
+
+Shows the **last 5 download attempts** by default, newest first, with title, status, media type,
+date, duration, URL and the saved files. Saved, skipped, failed and cancelled items are
+recorded, including the reason a failure was reported; playlist entries and retried
+attempts count individually. Active downloads appear once they finish. Long file lists
+are summarized in the text view.
+
+Use `veo history --limit N` to show 1-1000 attempts, or `veo history --failed` to
+show only failed and cancelled attempts; the flags can be combined. Failed attempts
+include their exact retry-job command when one was recorded. New attempts also show
+their persistent run ID for `veo inspect run <id>`. `veo history --json`
+prints `{"count":N,"entries":[…]}` for scripting. Each entry has
+`at`, `url`, `title`, `status`, `media` (`video`/`audio`), `quality`, `format`, the
+complete `files` list, `error`, `elapsedMs` and an optional `job` path. Titles and paths are stored without
+terminal control characters.
+
+History is one small JSON file per attempt in the per-user veo cache's `history`
+directory, so parallel runs cannot overwrite each other and each record stays small. The
+directory keeps one file per attempt and contains URLs, titles and local file paths;
+delete it to remove those records. `veo flush` keeps the list (only `veo flush --stats`
+resets statistics, not history).
+
+### `veo changes`
+
+Lists every **released version**, newest first, and marks the installed one. `veo changelog`
+is an alias. The notes are parsed from the `CHANGELOG.md` that ships inside the package, so
+they always belong to the installed code and the command needs no network access.
+
+```bash
+veo changes                       # all versions with their Added/Changed/Fixed counts
+veo changes 1.10.1                # the notes of one release
+veo changes --version 1.10.1      # the same, spelled out
+veo changes 1.10                  # newest release starting with 1.10
+veo changes --latest              # only the newest release
+veo changes --since 1.10.0        # everything newer than 1.10.0, up to the newest release
+veo changes --range 1.9.0..1.11.0 # a closed range, newest first
+veo changes --json                # machine-readable
+```
+
+An unknown version fails with the known versions listed. Long entries wrap to the terminal
+width, and `--json` returns the complete text. Because the list already names the released
+versions, `veo changes` prints no automatic update hint.
+
+`veo changes --json` prints `{"current":…,"count":N,"versions":[…]}`, where each entry has
+`version`, `date` (currently `null`, since the changelog headings carry no date), `installed`,
+`counts` and `summary`. One version adds `"version"`, `"installed"` and `"sections"`; a range
+adds `"from"` and `"to"` and keeps the per-release `sections`. Sections are
+`{"type":"Added","items":[{"text":"…","items":[…]}]}`, and nested items are preserved.
+
+### `veo runs` and `veo stop`
+
+Every run registers itself while it works, under a **6-character id**, and removes that
+record when it ends:
+
+```bash
+veo runs            # active runs: id, PID, state, start time, progress, output directory
+veo runs k3f9qa     # one run in detail: URLs, settings, job file, per-item state
+veo stop k3f9qa     # ask that run to stop and wait until it exits
+veo stop            # stop every active run
+```
+
+`veo runs` lists the runs of this user, including those started in another terminal, and a
+run disappears from the list as soon as it finishes. Progress such as
+`1/3 done, 1 running` is read from the run's job file, which is created before the first
+download starts, so a run that is still preparing the backend shows `starting`. `veo stop
+<id>` writes a stop request that the run itself polls, so it needs no signals or PIDs and
+works the same on every platform. A stopped run exits like Ctrl+C (`130`) and keeps its
+partial data and retry job, so the printed `veo --retry-failed` command still works —
+unlike `veo flush`, which also removes that data. If a run does not stop within 15 seconds,
+`veo stop` reports it and exits with `1`.
+
+A run that crashed without cleaning up leaves its record behind: `veo runs` marks it
+`stale` and `veo stop` removes it, with or without its id. Records contain the id, process
+id, start time, URLs, output directory and job path — never cookie files, browser sessions
+or other credentials. Unknown or damaged record files are ignored instead of breaking veo,
+because a single stray file in the cache must never stop later runs.
+
+### `veo doctor`
+
+Prints one line per check: `ok`, `warn` or `fail`. It inspects the JavaScript runtime used by
+yt-dlp, the platform, the
+output directory, the backend cache, yt-dlp (including the SHA-256 of the cached binary and
+the version it reports), FFmpeg/FFprobe, a system FFmpeg fallback, the config file, leftover
+partial downloads, stale duplicate-detection records, the npm registry and the yt-dlp release host. It downloads no backend and
+only creates its own probe files plus the backend cache directory. Exit status is `1` when
+at least one check fails.
+
+Run `veo doctor fix` to restore missing or damaged managed tools and check again.
+It stages bundled FFmpeg/FFprobe and downloads verified yt-dlp when needed. Missing
+desktop media tools are downloaded into veo's cache from the pinned media releases and
+verified before use. On Termux it installs missing native tools with the package manager.
+With `--offline`, it only uses local binaries; missing tools are reported for an online retry.
+Use `-o PATH` to create and check an output directory. Config errors and invalid overrides
+are reported for manual correction; PATH and config values are never rewritten.
+A missing system FFmpeg is not a warning when the selected media tools work.
+
+## Supported sites and backend
+
+YouTube, X/Twitter, TikTok, Vimeo, Reddit, Instagram, and [many other yt-dlp sites](https://github.com/yt-dlp/yt-dlp/blob/master/supportedsites.md) are supported **when publicly accessible and technically available**. Support changes with websites, regions, rate limits, and backend versions; it is not a guarantee that every URL will work.
+
+Official standalone yt-dlp is acquired on first download and cached outside the package directory; help, version and plain doctor never download the backend. The release is pinned and SHA-256 verified against hashes shipped with this package. The npm package runs no installation scripts; its only dependencies are the optional per-platform packages that carry the veo binary.
+
+When no trusted local FFmpeg/FFprobe pair is available, veo downloads both tools directly from the upstream [ffmpeg-static binary releases](https://github.com/eugeneware/ffmpeg-static/releases/tag/b6.1.1). Release URLs, compressed and executable SHA-256 hashes, and byte counts are pinned in the package. The complete pair and its license and README must pass verification before either executable is started. Later uses verify the cached pair again; legacy or damaged cached binaries are not accepted merely because they are executable. Most targets use FFmpeg 6.1.1; Windows ia32 uses the last available pair, FFmpeg 6.0. Old `FFMPEG_BINARIES_URL`, `FFMPEG_BINARY_RELEASE` and `FFMPEG_BIN` variables do not change these downloads. Use `VEO_FFMPEG_PATH` to choose a trusted installed pair explicitly.
+
+The downloaded binaries retain their separate upstream licenses. `FFmpeg.LICENSE` and `FFmpeg.README` are saved next to the cached tools, including upstream source and build information. veo itself is MIT licensed. No Python installation is needed on supported standalone platforms.
+
+An installed Node.js, Deno or Bun (found on PATH, in that order) is passed to yt-dlp as its JavaScript runtime for YouTube; `VEO_JS_RUNTIME=deno:/path/to/deno` selects one explicitly. Without one, yt-dlp uses its own default. Local yt-dlp configuration and plugins are disabled for predictable execution. Arguments are passed without a shell.
+
+Windows ARM64 uses an FFmpeg/FFprobe pair found on `PATH`, including the usual
+WinGet, Chocolatey and `C:\ffmpeg\bin` locations, or automatically downloads x64
+media tools for Windows 11's x64 emulation.
+
+### Android / Termux
+
+With npm installed in Termux (`pkg install nodejs`), npm fetches the native
+Android binary:
+
+```sh
+npm install -g veodl
+veo "URL"
+```
+
+On Android, veo automatically finds `yt-dlp`, `ffmpeg` and `ffprobe` on PATH
+(also checking `$PREFIX/bin`). If tools or the `yt-dlp-ejs` Python module are
+missing, it runs `pkg install -y python-yt-dlp yt-dlp-ejs ffmpeg` automatically,
+then checks the installed programs before continuing the download. Python is
+installed as a dependency. Termux with the pacman package manager uses
+`--noconfirm` instead. This needs a working Termux repository and internet access.
+No root access is needed. Later runs reuse the installed tools.
+
+The npm installation does not pull in desktop FFmpeg packages.
+The system yt-dlp is maintained by Termux and is
+not pinned or hash-verified by veo. Explicit `VEO_YT_DLP_PATH` and
+`VEO_FFMPEG_PATH` overrides still take precedence.
+
+`veo doctor fix` also performs this automatic setup; `veo doctor fix --offline`
+never invokes a package manager. Update Termux packages with `pkg upgrade`;
+`veo backend update` prints this platform's update instructions.
+
+To save files in Android's shared Downloads folder, run `termux-setup-storage`,
+grant the storage permission, then use `veo "URL" -o ~/storage/downloads`.
+Keep veo and its tools in Termux's private storage.
+
+For existing published veo 1.6.1 installations (before this automatic setup), run:
+
+```sh
+pkg install python-yt-dlp yt-dlp-ejs ffmpeg
+export VEO_YT_DLP_PATH="$(command -v yt-dlp)"
+export VEO_FFMPEG_PATH="$PREFIX/bin"
+veo doctor
+```
+
+These exports apply to the current shell; add them to your shell startup file
+if you need them on subsequent launches of 1.6.1.
+
+### Advanced overrides
+
+- `VEO_YT_DLP_PATH`: absolute path to a trusted, current yt-dlp executable. It always takes
+  precedence over the managed backend, including one installed by `veo backend update`.
+- `VEO_FFMPEG_PATH`: directory containing both `ffmpeg` and `ffprobe` executables (with
+  `.exe` on Windows).
+- `VEO_CONFIG`: path to the config file.
+- `VEO_JS_RUNTIME`: `name:path` of the JavaScript runtime passed to yt-dlp, for example
+  `deno:/usr/local/bin/deno` (`node`, `deno`, `bun` or `quickjs`).
+- `VEO_BINARY`: path to a veo executable the npm launcher should start instead of the
+  installed platform package (for testing a local build).
+
+Automatic setup covers Windows x64/ia32/ARM64, macOS x64/ARM64, Linux x64/ARM64,
+and Android through Termux. Windows ARM64 media tools require x64 emulation.
+`--open` uses `termux-open` in Termux; another Android app must be available to view the file.
+Other systems should supply trusted native binaries. Internet
+access, executable private storage and working OS libraries are prerequisites;
+network blocks or unavailable repositories can still prevent setup. Android's
+shared-storage permission must be granted by the user. Maintainers should update
+the pinned yt-dlp release and hashes as websites change,
+or users can install a newer release themselves.
+
+### Installing a newer backend
+
+```bash
+veo backend update --check   # is a newer yt-dlp release available?
+veo backend update           # install it
+veo backend reset            # forget it, use the pinned release again
+```
+
+The pinned backend is hash-verified against values compiled into this veo version. That
+guarantee cannot cover a release that did not exist when this version was built, so
+`veo backend update` verifies the download against the `SHA2-256SUMS` file published with
+that release over HTTPS: the trust anchor becomes HTTPS and GitHub instead of the npm
+package. It is opt-in, it says so on stderr when it runs, and `veo backend reset` (plus the
+next `veo update`) returns to the pinned release. An installed release is used only while it
+is newer than the pinned one and its bytes still match the recorded hash; anything else
+silently falls back to the pinned release.
+
+## Develop and publish
+
+veo is a Rust crate (Rust 1.85+). The npm package `veodl` contains only a small launcher
+(`bin/veo.js`); the binaries ship in `veodl-<platform>-<arch>` packages generated from
+`Cargo.toml` by `scripts/npm-packages.mjs`.
+
+```bash
+cargo build --release                  # target/release/veo
+cargo test                             # unit tests and offline CLI tests, no network
+cargo test --test smoke -- --ignored   # real downloads: local HTTP server, real yt-dlp, real FFmpeg
+cargo clippy --all-targets -- -D warnings
+node scripts/npm-packages.mjs          # sync npm package versions after a version bump
+npm pack && node scripts/check-package.js
+```
+
+The offline tests (`tests/cli.rs`) run the real binary against `tests/fake-backend`, a
+small stand-in for yt-dlp, ffmpeg and ffprobe, in isolated cache and config directories.
+They cover downloads, duplicate names, skip-existing, playlists and entry selection,
+audio, subtitles, naming templates, dry runs and listings, incognito mode, retries by run
+ID, transient-failure back-off, profiles and release notes.
+
+The smoke test prepares the pinned tools with `veo doctor fix`, generates a two-second
+synthetic video with FFmpeg, serves it on loopback and runs real yt-dlp downloads. It checks
+default output, the quality cap, duplicate names, audio extraction, conversion, remuxing,
+dry-run, format listing, JSON output, audio inspection, batch failures, profiles with URL
+lists, retry by run ID from another directory, playlist selection, and that a finished
+download whose destination was unavailable is transferred later without contacting the
+source again. It downloads no third-party video.
+
+Continuous integration runs formatting, Clippy, the unit and offline tests, and the smoke
+test on Windows, macOS and Linux, and verifies the npm package. Pushing a tag `vX.Y.Z`
+(matching `Cargo.toml`) builds the binaries for Windows x64/ARM64, macOS x64/ARM64,
+static Linux x64/ARM64 (musl) and Android ARM64 and uploads the eight npm tarballs
+as an Actions artifact. The `rust-port` branch also triggers this build.
+
+GitHub builds all seven native targets and bundles them into the single veodl npm
+package. Branch pushes and manual workflow runs build and upload the npm-package
+artifact without publishing. Pushing a matching version tag (for example,
+v2.0.1) additionally publishes the verified tarball using npm trusted publishing
+with OIDC. Configure Mailo037/veodl and release.yml as the npm trusted publisher,
+with direct npm publishing allowed; no npm token or GitHub environment is needed.
+The publish job alone has id-token: write permission and uses Node 24 and npm 11.
+
+After committing and pushing the intended release changes, create and push the tag:
+
+```sh
+git tag -a v2.0.1 -m "Release v2.0.1"
+git push origin v2.0.1
+```
+
+Wait for the complete workflow, including the publish job, and check npm's latest
+tag before announcing the release. An already published version cannot be reused.
+For a local fallback, download the npm-package artifact and publish its verified
+tarball with npm publish; users always install with npm install -g veodl.
+
+Modules mirror the commands and stay small (larger ones are directories of focused
+submodules): argument parsing and dispatch (`src/cli/`), configuration (`src/config*.rs`,
+`src/config_editor/`), backend setup and updates (`src/backend/`, `src/tool_setup.rs`,
+`src/backend_update.rs`), downloads (`src/downloader/`, `src/download_cache.rs`,
+`src/jobs/`, `src/playlist.rs`), records (`src/runs/`, `src/history.rs`, `src/stats.rs`,
+`src/run_archive.rs`, `src/flush.rs`), diagnostics (`src/doctor.rs`,
+`src/inspect_media.rs`), source discovery over the Chrome DevTools Protocol
+(`src/source_discovery/`), terminal output (`src/output.rs`, `src/progress/`,
+`src/terminal.rs`) and helpers.
+
+## License
+
+MIT for this CLI. yt-dlp and FFmpeg/FFprobe retain their respective upstream licenses.
+# Clickable paths
+
+In supported terminals (Windows Terminal, iTerm2, WezTerm, Kitty, VS Code and recent VTE terminals), the `Saved:` path, `veo config path` and the config editor's header link to the containing folder. Use the terminal's link gesture, usually Ctrl+click or Cmd+click. The terminal and operating system decide whether file links open the file manager; unsupported terminals and redirected output show plain paths. Missing paths are not linked. JSON output remains plain.