easycaptionkit 0.1.2 → 0.1.4

package/LICENSE

@@ -1,6 +1,7 @@
 MIT License
 
 Copyright (c) 2026 Emin Budak
+Copyright (c) 2026 Wiro AI Inc.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -37,25 +37,36 @@ easycaptionkit-demo/
 - The captions run as long as the video's sound where the sound runs on past its picture, in the subtitle files too, and as long as its frames where it states no length, as a WebM a browser recorded does. A file whose frames and sound all end well before the length it states, as an interrupted download leaves it, is captioned as far as its frames go, and CAPTIONS.md says so.
 - CAPTIONS.md carries the license facts easyfontkit read for the font that was burned in, and the closest free font when it is not open. Whether to use it is your call. When the font has none of the letters, as a Latin font has no Japanese, CAPTIONS.md says that no letter of it is in the video and names the fonts of the machine that drew them.
 
+## Requirements
+
+- Node.js 22 or newer.
+- ffmpeg and ffprobe 4.4 or newer, Ubuntu 22.04's 4.4.2 included. To burn the captions, ffmpeg needs an H.264 encoder: libx264, the one every test has used, or VideoToolbox, OpenH264 or Media Foundation, which no test has run with. `--libass` needs it built with libass as well, which Homebrew's default ffmpeg is not; `subtitles` needs neither, and with `--video` it uses ffprobe alone. Apart from libass's ass filter, the filters it uses are ffmpeg's own, and so is the AAC encoder. `brew install ffmpeg` and `winget install ffmpeg` give a new enough one, and so does `sudo apt install ffmpeg` on Ubuntu 22.04, Debian 12 or newer. Set `FFMPEG_PATH` to use another build, as a path or a name on your PATH, and `FFPROBE_PATH` for an ffprobe that is not next to ffmpeg or on your PATH. Before any work, a run checks that ffmpeg and ffprobe start and answer as ffmpeg and ffprobe, ffprobe alone in `subtitles --video`; one that does not stops the run with what the system or the program said, and how to get one. When the system is short of open files, processes or memory to start one, the run says so and what to do. Then, before it draws anything, a run that burns captions checks ffmpeg's version number, its H.264 encoder and, for `--libass`, libass, and says what is missing; an ffmpeg that fails or is stopped when asked for its encoders or its filters stops the run with how it ended. An ffmpeg or ffprobe that gives no answer in two minutes when asked, as on a machine short of memory, stops the run too, and the message says to run it again. It checks no version number of ffprobe's.
+- Google Chrome or Chromium, which draws the captions; `subtitles` starts none. Chrome runs in its sandbox unless easycaptionkit runs as root, where the sandbox does not start: on Linux, Google Chrome's own package sets the sandbox up, and a container has to let it start, as Docker does with `--security-opt seccomp=unconfined`. It has been tested with Google Chrome only: 155 on Ubuntu 26.04, 157 on Ubuntu 22.04 and the ones GitHub's ubuntu-22.04, ubuntu-24.04 and ubuntu-latest runners come with. No test has run with Chromium, or with Edge or Brave, which easycaptionkit also takes. It looks for all four on your PATH and where macOS installs them; on Windows it looks only where Chrome and Edge install themselves. Set `CHROME_PATH` to use another build, as a path or a name on your PATH. Before any work, a run that draws with Chrome checks that it starts and gives a version number when asked with `--version`, except on Windows, where Chrome prints none, and one that does not stops the run in the same way. With `--libass` ffmpeg draws the captions instead, and a run with no browser, or with one that does not start or gives no version number, makes plainer sheet.png and safe-zones.png.
+- A font that has the letters of your captions, on the machine or in `--fonts`. A letter no font has is drawn as a box, as Japanese is on a server with no Japanese font; `fonts-noto-cjk` gives Debian and Ubuntu one.
+- Linux, where it is tested: on Ubuntu 22.04 with its ffmpeg 4.4.2, on Ubuntu 24.04 with its ffmpeg 6.1 and on GitHub's ubuntu-latest runner, on every push and before every release. This release has also run on Ubuntu 26.04 with ffmpeg 8.0. It is written for macOS and Windows as well, but it has not been run on either.
+- Room on the disk for the files of a run and those of the run before it, as the earlier files stay until the new ones are in place. captioned.mp4 is a new encode of the whole video and can come out larger than the video given. Until a run ends, it also keeps the pictures Chrome drew of the captions, a PNG of each state and an animated PNG of them all, in its hidden folder in the out folder. In the karaoke style, at the default letter size and two lines, they take about 75 KB a word on a 1080x1920 video, 150 KB on a 1920x1080 one and 360 KB on a 3840x2160 one, some 1.5 GB for an hour of speech at 1920x1080. With the largest letters and the most lines the options allow, `--size 20` and `--lines 3`, they take about twice as much, and in the line and word styles and with `--box` less. Each Chrome that easycaptionkit starts keeps a profile of 3 to 7 MB in the temp folder.
+- Memory for ffmpeg's encode, more for a video of more pixels, more again for an HDR one, which stays in 10 bits, and on a machine with more cores. For a 1920x1080 or 1080x1920 video, ffmpeg took about 0.6 GB on 2 cores and 1.5 GB on 24, as much for ten minutes of video as for 30 seconds, and 1 GB and 2.4 GB for one in HDR. For a 3840x2160 video it took about 2 GB on 2 cores and 5 GB on 24, and 3.6 GB and 8.6 GB for one in HDR. The cores are the ones ffmpeg may run on, and a CPU quota does not lower their count: in a systemd scope held to 2 CPUs by CPUQuota=200% on a 24 core machine, where `nproc` said 2, the encode of a 1920x1080 video took as much as on all 24 cores, and 0.6 GB once `taskset` held it to 2 cores. A container held to 2 CPUs by `docker run --cpus=2` or by a Kubernetes CPU limit is held by such a quota, while `docker run --cpuset-cpus` holds it to cores, as taskset does. Ubuntu 22.04's ffmpeg 4.4.2 counts every core of the machine for its own decoding, whatever it is held to, and only x264 follows taskset and cpuset there. Chrome takes about 0.3 GB while it draws, before the encode and after it, and Node.js about 0.1 GB.
+- A run needs no network access and no API key: easycaptionkit reads files on your disk, the browser runs offline with the font files there, and nothing leaves your machine. Installing it needs the network, and `npx easycaptionkit@latest` asks npm for the newest version each time it runs. There are no npm dependencies, and `subtitles` without `--video` needs Node.js alone.
+
 ## Use it with your agent
 
 easycaptionkit ships as an [Agent Skill](https://agentskills.io). Install it once and your agent runs it by itself when a video needs captions:
 
 ```bash
-npx skills add EminBudak/easycaptionkit
+npx skills add MakersMCP/easycaptionkit
 ```
 
 That covers Claude Code, Codex, Cursor and the other agents the [`skills`](https://github.com/vercel-labs/skills) CLI supports. In Claude Code you can add it as a plugin instead:
 
 ```
-/plugin marketplace add EminBudak/easycaptionkit
+/plugin marketplace add MakersMCP/easycaptionkit
 /plugin install easycaptionkit@easycaptionkit
 ```
 
 In GitHub Copilot CLI it takes the same two steps:
 
 ```bash
-copilot plugin marketplace add EminBudak/easycaptionkit
+copilot plugin marketplace add MakersMCP/easycaptionkit
 copilot plugin install easycaptionkit@easycaptionkit
 ```
 
@@ -111,8 +122,6 @@ npx easycaptionkit@latest subtitles transcript.json --video film.mp4
 
 Installed globally (`npm install -g easycaptionkit`), the command is `easycaptionkit`. npx keeps the copy an earlier run fetched, so `npx easycaptionkit@latest` is how you get a newer version.
 
-It needs Node 22 or newer, ffmpeg 4.4 or newer and Chrome, Chromium, Edge or Brave. `brew install ffmpeg` and `winget install ffmpeg` give a new enough ffmpeg, and so does `sudo apt install ffmpeg` on Ubuntu 22.04, Debian 12 or newer; the tests run on Ubuntu 22.04's ffmpeg 4.4 and on the latest Ubuntu's, before every release too. Set `FFMPEG_PATH` and `CHROME_PATH` to pick them, as a path or a name on your PATH, and `FFPROBE_PATH` for an ffprobe that is not next to ffmpeg or on your PATH. There are no npm dependencies, and nothing leaves your machine: the browser runs offline with the font files on your disk.
-
 ## Where the words come from
 
 `--words` takes the words with their times from any of these, told apart by what is in the file, saved as UTF-8 or UTF-16:
@@ -165,11 +174,11 @@ With `--libass`, ffmpeg draws the captions itself from captions.ass with its ass
 
 ## See also
 
-- [easyfontkit](https://github.com/EminBudak/easyfontkit) saves the fonts a website really uses, with their licenses.
-- [easybrandkit](https://github.com/EminBudak/easybrandkit) saves a site's real logo files, colors and fonts as a brand kit.
-- [easyscreenshotkit](https://github.com/EminBudak/easyscreenshotkit) records a demo video of a site, with the steps.json captions can follow.
-- [launch-film](https://github.com/EminBudak/launch-film) turns a site into a short launch film, and its `check` measures any video.
-- [musicfit](https://github.com/EminBudak/musicfit) fits a music track to a video cut and ducks it under a voice.
+- [easyfontkit](https://github.com/MakersMCP/easyfontkit) saves the fonts a website really uses, with their licenses.
+- [easybrandkit](https://github.com/MakersMCP/easybrandkit) saves a site's real logo files, colors and fonts as a brand kit.
+- [easyscreenshotkit](https://github.com/MakersMCP/easyscreenshotkit) records a demo video of a site, with the steps.json captions can follow.
+- [launch-film](https://github.com/MakersMCP/launch-film) turns a site into a short launch film, and its `check` measures any video.
+- [musicfit](https://github.com/MakersMCP/musicfit) fits a music track to a video cut and ducks it under a voice.
 
 ## License
 

package/package.json

@@ -1,15 +1,15 @@
 {
   "name": "easycaptionkit",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Burn captions into a video in the product's own fonts and colors, word by word or line by line, kept clear of each app's buttons, with the SRT, VTT and ASS files to go with it.",
   "license": "MIT",
   "author": "Emin Budak",
-  "homepage": "https://github.com/EminBudak/easycaptionkit#readme",
+  "homepage": "https://github.com/MakersMCP/easycaptionkit#readme",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/EminBudak/easycaptionkit.git"
+    "url": "git+https://github.com/MakersMCP/easycaptionkit.git"
   },
-  "bugs": "https://github.com/EminBudak/easycaptionkit/issues",
+  "bugs": "https://github.com/MakersMCP/easycaptionkit/issues",
   "bin": {
     "easycaptionkit": "skills/easycaptionkit/scripts/easycaptionkit.js"
   },

package/skills/easycaptionkit/SKILL.md

@@ -53,6 +53,10 @@ node <skill>/scripts/easycaptionkit.js subtitles transcript.json --video video.m
 - With `--libass`, CAPTIONS.md can say the video shows boxes for some emoji: libass draws no color emoji. Run again without `--libass` to have Chrome draw them.
 - CAPTIONS.md says Chrome found no font for some letters, or that no font libass can use has them: the video shows a box for each, as it does for Japanese on a server with no Japanese font. Install a font that has them, such as Noto Sans CJK (`fonts-noto-cjk` on Debian and Ubuntu), or give `--fonts` an easyfontkit folder whose font has them, and run again. Do not hand over a video with boxes in its captions.
 - No Chrome on the machine: the run stops. `--libass` draws the captions with ffmpeg's libass instead, which needs an ffmpeg built with libass (Homebrew's default ffmpeg is not).
+- "easycaptionkit needs ffmpeg", "easycaptionkit needs ffprobe" or "easycaptionkit needs Chrome": the run stopped before any work, as it found none, or the one it found or the variable names could not be started, did not answer as one when asked its version or, for ffmpeg, failed when asked its encoders or its filters. The message names that file, by `FFMPEG_PATH`, `FFPROBE_PATH`, `CHROME_PATH` or PATH, and gives what is at its path, as a folder, or what the system said, or the first line the program printed and how it ended: tell the user, and ask them to install the program or to point the variable at one that runs, and never guess a path. Where it is Chrome, `--libass` draws the captions without it.
+- "easycaptionkit could not start ffmpeg:", or ffprobe or Chrome, and what the system is short of: the system could not start a program then, as when too many files are open, and the message says what to do, such as raising the limit on open files or running it again once fewer processes run. The program is not at fault, so do not ask the user to install another.
+- "easycaptionkit could not start ffmpeg, <its path>, again", or ffprobe or Chrome: the program answered when the run began, and the system could not start it later in the run, as when it was taken away or changed in the meantime. Tell the user what the system said, and run again: a program that is still wrong then stops the run before any work, with what is wrong with it.
+- "easycaptionkit could not check ffmpeg", or ffprobe or Chrome: the program gave no answer in two minutes when asked its version or, for ffmpeg, its encoders or its filters, as on a machine short of memory. Run again, and if it gives no answer again, tell the user, with the path the message names.
 - "Chrome could not start its sandbox here", or another reason Chrome stopped as it started (in a container, or on a CI runner without user namespaces): the run stops before the encode. `--libass` draws the captions without Chrome, and ffmpeg makes plainer sheet.png and safe-zones.png, which CAPTIONS.md notes.
 - A run killed outright (`kill -9`, or the system when memory runs out) cannot tidy up: its hidden `.easycaptionkit-work-` folder stays in the out folder, where an ffmpeg it started can go on writing captioned.mp4, and its Chrome profile stays in the temporary folder. The captioned.mp4 in that folder is no result to hand over: run again. The next run into the folder removes the work folder, and a later run of the same user that starts Chrome removes the profile once no process names it and it has not changed for a day, except on Windows, where it stays in the temporary folder until Windows or the user clears it.
 - The safe zones are the apps' ad guides or estimates, each with its source and date. Tell the user to check one post on a phone.

package/skills/easycaptionkit/scripts/lib/caption.js

@@ -18,7 +18,7 @@ const { captionLayout, charsThatFit, defaultPlaces, shapeOf } = require("./place
 const { chooseLook, variableFace, machineFont, fallbackFont } = require("./look");
 const { fontLike } = require("./fontfile");
 const ffmpeg = require("./ffmpeg");
-const { findChrome, missingChrome, chromeNamedNothing, tempProblem } = require("./chrome");
+const { chromeReady, chromeProblem, tempProblem } = require("./chrome");
 const { renderStates } = require("./render");
 const { safeZonesPng, sheetPng, plainPictures, shotOf } = require("./draw");
 const { captionsMarkdown, captionsJson, subtitlesMarkdown, arg, subtitlesCommand, shown, captionsOf, lettersOf, boxesText, installText } = require("./report");
@@ -945,15 +945,22 @@ async function captionVideo(videoFile, options) {
   writable(dir);
   const notes = recover(path.resolve(dir), dir);
   const view = guard(dir, { video: videoFile, timeline: timelineOf(videoFile), words: options.words, brand: options.brand, fonts: options.fonts });
-  const bins = ffmpeg.tools();
   const useLibass = Boolean(options.libass);
-  if (!useLibass && !findChrome()) throw new Error(missingChrome());
   // Chrome keeps its profile in the temporary folder.
   const temp = useLibass ? "" : tempProblem();
   if (temp) throw new Error(`${temp}. Set it to a folder, or unset it`);
-  const [video, caps] = await Promise.all([ffmpeg.readVideo(videoFile, bins), ffmpeg.capabilities(bins)]);
+  // Each program the run uses is asked its version before the video is
+  // read, Chrome while ffmpeg is: one that cannot be started or does not
+  // answer as itself stops the run with what the system or the program
+  // said, ffmpeg's first.
+  const chrome = useLibass ? null : chromeReady();
+  if (chrome) chrome.catch(() => {});
+  const tools = await ffmpeg.ready();
+  if (chrome) await chrome;
+  const bins = { ffmpeg: tools.ffmpeg, ffprobe: tools.ffprobe, places: tools.places };
+  const [video, caps] = await Promise.all([ffmpeg.readVideo(videoFile, bins), ffmpeg.capabilities(bins, tools.version)]);
   notStill(video, videoFile);
-  if (!caps.encoder) throw new Error("This ffmpeg has no H.264 encoder (libx264, VideoToolbox or OpenH264), so it cannot write the captioned MP4");
+  if (!caps.encoder) throw new Error("This ffmpeg has no H.264 encoder (libx264, VideoToolbox, OpenH264 or Media Foundation), so it cannot write the captioned MP4");
   if (useLibass && !caps.libass) throw new Error("This ffmpeg has no libass (its ass filter), so --libass cannot draw the captions. Leave out --libass to draw them with Chrome, or install an ffmpeg built with libass");
   if (!useLibass && !caps.overlay) throw new Error("This ffmpeg has no overlay filter, so it cannot lay the captions over the video");
   const read = await loadWords(options.words);
@@ -1077,9 +1084,11 @@ async function captionVideo(videoFile, options) {
         // A Chrome that cannot start here (no usable sandbox, as in a
         // container) stops the run before the encode; libass needs none. A
         // Chrome the system stopped as memory ran out can draw with fewer
-        // jobs at once, or a smaller video.
-        if (err.chrome && err.signal === "SIGKILL") err.message += ". Run again with fewer jobs at once or with a smaller video, or pass --libass to have ffmpeg draw the captions without Chrome";
-        else if (err.chrome && err.start) err.message += ". Pass --libass to have ffmpeg draw the captions without Chrome";
+        // jobs at once, or a smaller video. A message that ends with a full
+        // stop, as one of what to do does, keeps only that one.
+        const said = err.message.replace(/\.$/, "");
+        if (err.chrome && err.signal === "SIGKILL") err.message = `${said}. Run again with fewer jobs at once or with a smaller video, or pass --libass to have ffmpeg draw the captions without Chrome`;
+        else if (err.chrome && err.start) err.message = `${said}. Pass --libass to have ffmpeg draw the captions without Chrome`;
         throw err;
       }
       fs.writeFileSync(path.join(run.work, "captions.ass"), assFile(drawn.scales));
@@ -1126,8 +1135,10 @@ async function captionVideo(videoFile, options) {
     const sheetFile = path.join(run.work, "sheet.png");
     // Chrome lays the pictures out. Where there is none, or it cannot start
     // or stops, ffmpeg makes plainer ones: the captions are in the video
-    // by now, and the pictures only show them.
-    let plain = findChrome() ? tempProblem() : chromeNamedNothing() || "no Chrome was found";
+    // by now, and the pictures only show them. A run that drew them with
+    // libass asks Chrome its version here, which a run that drew them with
+    // Chrome did before any work, with the temporary folder.
+    let plain = useLibass ? (await chromeProblem()) || tempProblem() : "";
     if (!plain) {
       try {
         await safeZonesPng({ bins, video, output: out, zones: place.zones, cue: widest, times, file: zonesFile, dir: run.work, frameTags });
@@ -1321,6 +1332,9 @@ async function makeSubtitles(wordsFile, options) {
   writable(dir);
   const notes = recover(path.resolve(dir), dir);
   const view = guard(dir, { words: wordsFile, video: options.video, brand: options.brand, fonts: options.fonts }, { subtitles: true, options });
+  // The video is read with ffprobe alone, which is asked its version first;
+  // no ffmpeg is started, so nothing at ffmpeg's path stops the run.
+  const bins = options.video ? await ffmpeg.readyProbe() : null;
   const read = await loadWords(wordsFile);
   const first = firstFormat(read, origin);
   const look = chooseLook({ ...options, ...scriptsOf(read.words) });
@@ -1328,7 +1342,7 @@ async function makeSubtitles(wordsFile, options) {
   notes.push(...read.notes, ...look.notes);
   let video = null;
   if (options.video) {
-    video = await ffmpeg.readVideo(options.video, ffmpeg.tools());
+    video = await ffmpeg.readVideo(options.video, bins);
     notStill(video, options.video);
     notes.push(...video.notes);
   }

package/skills/easycaptionkit/scripts/lib/chrome.js

@@ -12,49 +12,86 @@ const fs = require("node:fs");
 const os = require("node:os");
 const path = require("node:path");
 const { spawn, spawnSync } = require("node:child_process");
-const { onPath, given, namedNothing } = require("./ffmpeg");
+const programs = require("./programs");
 const { track, trackFolder, untrackFolder, kill, sleep } = require("./running");
 
-// A Chrome named in the environment is found as FFMPEG_PATH is: a bare
-// name on PATH, a path from the folder the run starts in.
-function findChrome() {
-  const named = process.env.CHROME_PATH;
-  if (named) return given(named);
-  const mac = [
-    "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
-    "/Applications/Chromium.app/Contents/MacOS/Chromium",
-    "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge",
-    "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
-    path.join(os.homedir(), "Applications/Google Chrome.app/Contents/MacOS/Google Chrome"),
-  ];
-  const win = [
-    path.join(process.env.PROGRAMFILES || "C:\\Program Files", "Google\\Chrome\\Application\\chrome.exe"),
-    path.join(process.env["PROGRAMFILES(X86)"] || "C:\\Program Files (x86)", "Google\\Chrome\\Application\\chrome.exe"),
-    path.join(process.env.LOCALAPPDATA || "", "Google\\Chrome\\Application\\chrome.exe"),
-    path.join(process.env["PROGRAMFILES(X86)"] || "C:\\Program Files (x86)", "Microsoft\\Edge\\Application\\msedge.exe"),
-  ];
-  const listed = process.platform === "darwin" ? mac : process.platform === "win32" ? win : [];
-  for (const file of listed) if (file && fs.existsSync(file)) return file;
-  for (const name of ["google-chrome", "google-chrome-stable", "chromium", "chromium-browser", "chrome", "microsoft-edge", "brave-browser"]) {
-    const found = onPath(name);
-    if (found) return found;
-  }
-  return "";
-}
+const LIBASS = "--libass has ffmpeg draw the captions without Chrome.";
 
-const MISSING = "No Chrome was found to draw the captions with. Install Google Chrome or Chromium, set CHROME_PATH to it, or pass --libass to have ffmpeg draw them.";
+// Chrome as a run looks for it and asks it its version (see
+// programs.find()): the path CHROME_PATH gives, or a name on PATH, as
+// FFMPEG_PATH is read; else where macOS and Windows install it, and on
+// PATH by each of its names. It answers with a version number, as "Google
+// Chrome 155.0.8059.84". On Windows, where Chrome prints no version, it is
+// not asked, and taken once nothing keeps it from running.
+const CHROME = {
+  name: "Chrome",
+  variable: "CHROME_PATH",
+  args: ["--version"],
+  answers: (stdout) => /\d+\.\d+/.test(stdout),
+  names: ["google-chrome", "google-chrome-stable", "chromium", "chromium-browser", "chrome", "microsoft-edge", "brave-browser"],
+  first: () => {
+    const mac = [
+      "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+      "/Applications/Chromium.app/Contents/MacOS/Chromium",
+      "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge",
+      "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
+      path.join(os.homedir(), "Applications/Google Chrome.app/Contents/MacOS/Google Chrome"),
+    ];
+    const win = [
+      path.join(process.env.PROGRAMFILES || "C:\\Program Files", "Google\\Chrome\\Application\\chrome.exe"),
+      path.join(process.env["PROGRAMFILES(X86)"] || "C:\\Program Files (x86)", "Google\\Chrome\\Application\\chrome.exe"),
+      path.join(process.env.LOCALAPPDATA || "", "Google\\Chrome\\Application\\chrome.exe"),
+      path.join(process.env["PROGRAMFILES(X86)"] || "C:\\Program Files (x86)", "Microsoft\\Edge\\Application\\msedge.exe"),
+    ];
+    const listed = process.platform === "darwin" ? mac : process.platform === "win32" ? win : [];
+    return listed.filter(Boolean).map((file) => ({ file, name: "Chrome", where: "installed on this machine" }));
+  },
+  ask: process.platform !== "win32",
+  none: `easycaptionkit needs Chrome to draw the captions, and none was found. Install Google Chrome or Chromium, or set CHROME_PATH to one. ${LIBASS}`,
+  advice: {
+    variable: `Set CHROME_PATH to a Chrome that runs, or unset it and install Google Chrome or Chromium. ${LIBASS}`,
+    found: `Install Google Chrome or Chromium, or set CHROME_PATH to a Chrome that runs. ${LIBASS}`,
+    late: `Run easycaptionkit again. ${LIBASS}`,
+  },
+};
 
-// The variable that names this run's Chrome, when it names no program:
-// what it names, as a sentence without its end. Empty otherwise.
-function chromeNamedNothing() {
-  return namedNothing("CHROME_PATH");
+// The Chrome a run would take, by what is at its place alone, not run, or
+// "" where there is none.
+const findChrome = () => programs.locate(CHROME);
+
+// The Chrome that answered, for the CHROME_PATH, the PATH and the folder
+// the run works with now: a run asks it once, and every Chrome it starts
+// to draw is that one. A failure is not kept, so a later call asks again.
+let checked = null;
+
+// The Chrome a run draws with, found and asked its version before any work,
+// so one that cannot be started or does not answer as Chrome stops the run
+// with what the system or the program said, not once it begins to draw.
+async function chromeReady(limit = programs.LIMIT) {
+  let here = "";
+  try {
+    here = process.cwd();
+  } catch {
+    // A folder taken away since: only PATH's relative entries read from it.
+  }
+  const key = JSON.stringify([process.env.CHROME_PATH, process.env.PATH, here]);
+  if (checked && checked.key === key) return checked.file;
+  const { file } = await programs.find(CHROME, limit);
+  checked = { key, file };
+  return file;
 }
 
-// Why there is no Chrome: what the variable names, or that none is on the
-// machine.
-function missingChrome() {
-  const nothing = chromeNamedNothing();
-  return nothing ? `${nothing}. Set it to the path of Chrome or Chromium, or pass --libass to have ffmpeg draw the captions.` : MISSING;
+// For a run that draws without Chrome and uses it for its pictures alone:
+// why there is no Chrome to use, as words that follow "since", or "" when
+// it answers.
+async function chromeProblem() {
+  try {
+    await chromeReady();
+    return "";
+  } catch (err) {
+    if (!err.unusable) throw err;
+    return err.why;
+  }
 }
 
 // An error of Chrome's own, not of a file or of ffmpeg: `start` when Chrome
@@ -225,9 +262,17 @@ function whyStopped(stderr, temp) {
   return text;
 }
 
+// Starts the Chrome a run checked before any work (see chromeReady()),
+// asking it first where it was not. A start the system refuses says what
+// the system said, never its code alone.
 async function launch({ width = 1920, height = 1080 } = {}) {
-  const chrome = findChrome();
-  if (!chrome) throw failed(missingChrome(), { start: true });
+  let chrome;
+  try {
+    chrome = await chromeReady();
+  } catch (err) {
+    throw failed(err.message, { start: true });
+  }
+  const refused = (err) => failed(programs.startFailure(chrome, err, "Chrome").message, { start: true });
   const temp = chromeTemp();
   clearOldProfiles();
   // A profile Chrome cannot have is a Chrome that cannot start.
@@ -271,13 +316,20 @@ async function launch({ width = 1920, height = 1080 } = {}) {
     child = track(spawn(chrome, args, { stdio: ["ignore", "ignore", "pipe", "pipe", "pipe"], env: { ...process.env, TMPDIR: temp, CHROME_CONFIG_HOME: path.join(profile, "config") } }), stop);
   } catch (err) {
     drop();
-    throw failed(`Chrome could not start: ${err.message}`, { start: true });
+    throw refused(err);
   }
   // Settles when Chrome is gone, whether it exited or never started.
   const gone = new Promise((resolve) => {
     child.once("exit", resolve);
     child.once("error", resolve);
   });
+  // With no file descriptor left for them Node makes no pipes, and says
+  // why a moment later.
+  if (!child.stdio || !child.stderr || !child.stdio[3] || !child.stdio[4]) {
+    const err = await new Promise((resolve) => child.once("error", resolve));
+    drop();
+    throw refused(err);
+  }
   let stderr = "";
   child.stderr.on("data", (d) => (stderr = (stderr + d).slice(-8000)));
   const told = new Promise((resolve) => child.stderr.once("close", resolve));
@@ -312,7 +364,7 @@ async function launch({ width = 1920, height = 1080 } = {}) {
     fall(dead);
   });
   child.on("error", (err) => {
-    dead = failed(`Chrome could not start: ${err.message}`, { start: true });
+    dead = refused(err);
     for (const waiting of pending.values()) waiting.reject(dead);
     pending.clear();
     fall(dead);
@@ -421,4 +473,4 @@ async function openPage(browser, file, { width, height, transparent = false }) {
   return page;
 }
 
-module.exports = { findChrome, missingChrome, chromeNamedNothing, tempProblem, launch, evaluate, openPage, whyStopped, chromeTemp, clearOldProfiles, MISSING };
+module.exports = { CHROME, findChrome, chromeReady, chromeProblem, tempProblem, launch, evaluate, openPage, whyStopped, chromeTemp, clearOldProfiles };

package/skills/easycaptionkit/scripts/lib/ffmpeg.js

@@ -8,82 +8,69 @@ const fs = require("node:fs");
 const path = require("node:path");
 const { spawn } = require("node:child_process");
 const { track } = require("./running");
+const programs = require("./programs");
+
+const { exe } = programs;
 
 // Where package managers put it, for an agent or app whose PATH is short.
 const KNOWN = ["/opt/homebrew/bin", "/usr/local/bin", "/usr/bin", "/snap/bin"];
 
-// The first program by a name on PATH, in a folder `skip` does not pass
-// over.
-function onPath(name, { skip = () => false } = {}) {
-  for (const dir of String(process.env.PATH || "").split(path.delimiter)) {
-    if (!dir || skip(dir)) continue;
-    const file = path.join(dir, name);
-    try {
-      fs.accessSync(file, fs.constants.X_OK);
-      if (fs.statSync(file).isFile()) return file;
-    } catch {
-      // Not here.
-    }
-  }
-  return "";
-}
-
-const exe = (name) => (process.platform === "win32" ? `${name}.exe` : name);
+const INSTALL = "brew install ffmpeg, sudo apt install ffmpeg or winget install ffmpeg";
 
-const bare = (value) => !(value.includes("/") || (process.platform === "win32" && value.includes("\\")));
-const isFile = (file) => {
-  try {
-    return fs.statSync(file).isFile();
-  } catch {
-    return false;
-  }
+// ffmpeg as a run looks for it and asks it its version (see programs.find()).
+const FFMPEG = {
+  name: "ffmpeg",
+  variable: "FFMPEG_PATH",
+  args: ["-version"],
+  answers: (stdout) => /^ffmpeg version\b/m.test(stdout),
+  names: [exe("ffmpeg")],
+  known: KNOWN,
+  none: `easycaptionkit needs ffmpeg, and none was found. Install it (${INSTALL}) or set FFMPEG_PATH to one.`,
+  advice: {
+    variable: `Set FFMPEG_PATH to an ffmpeg that runs, or unset it and install one (${INSTALL}).`,
+    found: `Install ffmpeg (${INSTALL}) or set FFMPEG_PATH to an ffmpeg that runs.`,
+    late: "Run easycaptionkit again.",
+  },
 };
 
-// A program named in the environment, as a whole path: a path is taken
-// from the folder the run started in, so a program run in another folder
-// (the encode runs in its work folder) still finds it, and a bare name is
-// looked up on PATH, as a shell would. Empty when it is not there.
-function given(value) {
-  if (bare(value)) return onPath(value) || onPath(exe(value));
-  const file = path.resolve(value);
-  return isFile(file) ? file : "";
-}
-
-// What an environment variable that names a program names, when that is
-// no program: "FFMPEG_PATH is /opt/ffmpeg, and there is no file there".
-// Empty when it is not set or names one.
-function namedNothing(variable) {
-  const value = process.env[variable];
-  if (!value || given(value)) return "";
-  const what = bare(value) ? "and no program by that name is on PATH" : fs.existsSync(path.resolve(value)) ? "a folder, not a program" : "and there is no file there";
-  return `${variable} is ${value}, ${what}`;
-}
-
-function findFfmpeg() {
-  if (process.env.FFMPEG_PATH) return given(process.env.FFMPEG_PATH);
-  return onPath(exe("ffmpeg")) || (process.platform === "win32" ? "" : KNOWN.map((d) => path.join(d, "ffmpeg")).find((f) => fs.existsSync(f)) || "");
-}
+// ffprobe, which sits next to ffmpeg in every package: the one next to the
+// ffmpeg at `ffmpeg`, when that is not ffmpeg's own file, else as ffmpeg is
+// looked for.
+const FFPROBE = (ffmpeg) => ({
+  name: "ffprobe",
+  variable: "FFPROBE_PATH",
+  args: ["-version"],
+  answers: (stdout) => /^ffprobe version\b/m.test(stdout),
+  names: [exe("ffprobe")],
+  known: KNOWN,
+  first: () => (ffmpeg ? [{ file: path.join(path.dirname(ffmpeg), exe("ffprobe")), name: "ffprobe", where: `next to ${ffmpeg}`, next: true }].filter((place) => place.file !== ffmpeg) : []),
+  none: `easycaptionkit needs ffprobe, and none was found${ffmpeg ? ` next to ${ffmpeg} or` : ""} on PATH. Install ffmpeg, which comes with ffprobe (${INSTALL}), or set FFPROBE_PATH to one.`,
+  advice: {
+    variable: `Set FFPROBE_PATH to an ffprobe that runs, or unset it and install ffmpeg, which comes with ffprobe (${INSTALL}).`,
+    next: "Set FFPROBE_PATH to an ffprobe that runs.",
+    found: `Install ffmpeg, which comes with ffprobe (${INSTALL}), or set FFPROBE_PATH to an ffprobe that runs.`,
+    late: "Run easycaptionkit again.",
+  },
+});
 
-// ffprobe sits next to ffmpeg in every package.
-function findFfprobe(ffmpeg) {
-  if (process.env.FFPROBE_PATH) return given(process.env.FFPROBE_PATH);
-  const next = ffmpeg ? path.join(path.dirname(ffmpeg), exe("ffprobe")) : "";
-  if (next && fs.existsSync(next)) return next;
-  return onPath(exe("ffprobe")) || (process.platform === "win32" ? "" : KNOWN.map((d) => path.join(d, "ffprobe")).find((f) => fs.existsSync(f)) || "");
+// ffmpeg and ffprobe, each found and asked its version before any work,
+// as { ffmpeg, ffprobe, version, places }: their files, what ffmpeg said,
+// which capabilities() reads, and where each was found, for the words of
+// a later failure. ffprobe is looked for next to the ffmpeg that answered.
+// A program that cannot be started or does not answer as itself stops the
+// run there, as programs.find() says, ffmpeg's first.
+async function ready(limit = programs.LIMIT) {
+  const ffmpeg = await programs.find(FFMPEG, limit);
+  const ffprobe = await programs.find(FFPROBE(ffmpeg.file), limit);
+  return { ffmpeg: ffmpeg.file, ffprobe: ffprobe.file, version: ffmpeg.stdout, places: { ffmpeg: ffmpeg.place, ffprobe: ffprobe.place } };
 }
 
-const MISSING = "ffmpeg and ffprobe were not found. Install them (brew install ffmpeg, sudo apt install ffmpeg or winget install ffmpeg) or set FFMPEG_PATH and FFPROBE_PATH to them.";
-
-function tools() {
-  for (const [variable, name] of [["FFMPEG_PATH", "ffmpeg"], ["FFPROBE_PATH", "ffprobe"]]) {
-    const nothing = namedNothing(variable);
-    if (nothing) throw new Error(`${nothing}. Set it to the path of ${name}, or unset it to use the one on PATH.`);
-  }
-  const ffmpeg = findFfmpeg();
-  const ffprobe = findFfprobe(ffmpeg);
-  if (!ffmpeg) throw new Error(MISSING);
-  if (!ffprobe) throw new Error(`ffprobe was not found next to ${ffmpeg} or on PATH. It comes with ffmpeg: install it, or set FFPROBE_PATH to it.`);
-  return { ffmpeg, ffprobe };
+// ffprobe alone, for a run that reads a video and starts no ffmpeg: found
+// and asked as ready() does, next to the ffmpeg the run would take, which
+// is not run, so nothing at ffmpeg's path stops it.
+async function readyProbe(limit = programs.LIMIT) {
+  const ffprobe = await programs.find(FFPROBE(programs.locate(FFMPEG)), limit);
+  return { ffprobe: ffprobe.file, places: { ffprobe: ffprobe.place } };
 }
 
 // What ffmpeg prints once it has given up, after the lines that say why:
@@ -92,7 +79,9 @@ function tools() {
 // ffmpeg 7 and newer with the others, and ffmpeg 8 says last that its
 // encoder never opened and that it wrote nothing, after a filter that
 // could not start, or that filtering failed, after the scaler said which
-// frame it could not convert.
+// frame it could not convert. ffmpeg 6.1 says it could not start a simple
+// filtergraph, the one -vf gives, after the line that names the option
+// its filter refused.
 const CLOSING = [
   /^Could not open encoder before EOF/,
   /^Error while filtering\b/,
@@ -104,6 +93,7 @@ const CLOSING = [
   /^Error initializing complex filters\.?$/,
   /^Error opening filters!?$/,
   /^Exiting normally/,
+  /^Error initializing a simple filtergraph$/,
   /^(?:Invalid argument|Operation not permitted|Cannot allocate memory|Invalid data found when processing input|Unknown error occurred)$/,
   /^Error opening (?:input|output) files?\b/,
   /^Error selecting an encoder$/,
@@ -149,20 +139,42 @@ function whyFailed({ code, signal, stderr }, who = "it") {
 // error, not a hang, unless what `busy` gives, as the size and the time of
 // the file it writes, changed in that time: ffmpeg prints nothing while it
 // writes a whole MP4 again to move its index to the front. With `binary`,
-// stdout is the bytes it wrote, not text.
+// stdout is the bytes it wrote, not text. The programs are the ones a run
+// checked before any work, so one that cannot be started now says what
+// the system said, or that the folder it was to run in is gone, never the
+// system's code alone: Node throws some of those errors at once and gives
+// the others a moment later.
 function run(binary, args, { quiet = 120_000, onStdout = null, cwd = undefined, busy = null, binary: bytes = false } = {}) {
   return new Promise((resolve, reject) => {
+    const failed = (err) => {
+      if (!/^spawn\b/.test(err.syscall || "")) return err;
+      // A start that fails for want of the folder it runs in is no fault of
+      // the program's.
+      if (cwd && !programs.enterable(cwd)) return new Error(`${path.basename(binary)} could not be started in ${cwd}, a folder that is not there any more or may not be entered`);
+      return programs.startFailure(binary, err);
+    };
     let child;
     try {
       child = track(spawn(binary, args, { stdio: ["ignore", "pipe", "pipe"], cwd }));
     } catch (err) {
-      reject(err);
+      reject(failed(err));
       return;
     }
     let stdout = "";
     const chunks = [];
     let stderr = "";
     let timer = null;
+    child.on("error", (err) => {
+      clearTimeout(timer);
+      reject(failed(err));
+    });
+    child.on("close", (code, signal) => {
+      clearTimeout(timer);
+      resolve({ code, signal, stdout: bytes ? Buffer.concat(chunks) : stdout, stderr });
+    });
+    // With no file descriptor left for them Node makes no pipes, and says
+    // why a moment later.
+    if (!child.stdout || !child.stderr) return;
     const arm = () => {
       clearTimeout(timer);
       const before = busy ? busy() : null;
@@ -184,14 +196,6 @@ function run(binary, args, { quiet = 120_000, onStdout = null, cwd = undefined,
       arm();
       stderr = (stderr + d).slice(-40_000);
     });
-    child.on("error", (err) => {
-      clearTimeout(timer);
-      reject(err.code === "ENOENT" ? new Error(MISSING) : err);
-    });
-    child.on("close", (code, signal) => {
-      clearTimeout(timer);
-      resolve({ code, signal, stdout: bytes ? Buffer.concat(chunks) : stdout, stderr });
-    });
   });
 }
 
@@ -564,15 +568,21 @@ const round3 = (value) => Math.round(value * 1000) / 1000;
 
 // ─── what this ffmpeg can do ──────────────────────────────────────────────
 
-async function capabilities(bins) {
-  const [about, filters, encoders] = await Promise.all([run(bins.ffmpeg, ["-hide_banner", "-version"], { quiet: 20_000 }), run(bins.ffmpeg, ["-hide_banner", "-filters"], { quiet: 20_000 }), run(bins.ffmpeg, ["-hide_banner", "-encoders"], { quiet: 20_000 })]);
+// What this ffmpeg can do: its version number, from what it said when
+// ready() asked it, and its filters and encoders, each asked of it and
+// read only once it ended well (see programs.probe()), so an ffmpeg that
+// fails or is stopped when asked is said to, not taken for one with no
+// H.264 encoder, no overlay filter or no libass.
+async function capabilities(bins, version) {
+  const asked = (args, what) => programs.probe(FFMPEG, bins.places.ffmpeg, ["-hide_banner", ...args], what);
+  const [filters, encoders] = await Promise.all([asked(["-filters"], "its filters"), asked(["-encoders"], "its encoders")]);
   // 4.4 is the oldest ffmpeg the kit is tried on: Ubuntu 22.04's. A build
   // from git says no number and is newer.
-  const v = /ffmpeg version n?(\d+)\.(\d+)/.exec(about.stdout);
+  const v = /ffmpeg version n?(\d+)\.(\d+)/.exec(version);
   const atLeast = (major, minor) => !v || Number(v[1]) > major || (Number(v[1]) === major && Number(v[2]) >= minor);
   if (!atLeast(4, 4)) throw new Error(`ffmpeg 4.4 or newer is needed, and this one is ${v[1]}.${v[2]}. Install a newer one (brew install ffmpeg, or a static build) or set FFMPEG_PATH to it.`);
-  const hasFilter = (name) => new RegExp(`^\\s*\\S+\\s+${name}\\s`, "m").test(filters.stdout);
-  const hasEncoder = (name) => new RegExp(`^\\s*V\\S*\\s+${name}\\s`, "m").test(encoders.stdout);
+  const hasFilter = (name) => new RegExp(`^\\s*\\S+\\s+${name}\\s`, "m").test(filters);
+  const hasEncoder = (name) => new RegExp(`^\\s*V\\S*\\s+${name}\\s`, "m").test(encoders);
   let encoder = null;
   // No B-frames: with them the file starts behind an edit list, and a tool
   // that reads frames without it is two frames off the captions' times.
@@ -581,11 +591,7 @@ async function capabilities(bins) {
   else if (hasEncoder("libopenh264")) encoder = { name: "libopenh264", args: ["-c:v", "libopenh264", "-b:v", "12M"] };
   else if (hasEncoder("h264_mf")) encoder = { name: "h264_mf", args: ["-c:v", "h264_mf", "-b:v", "12M"] };
   // Whether x264 here writes 10 bits, which an HDR video needs to stay HDR.
-  let tenBit = false;
-  if (encoder && encoder.name === "libx264") {
-    const help = await run(bins.ffmpeg, ["-hide_banner", "-h", "encoder=libx264"], { quiet: 20_000 });
-    tenBit = /yuv420p10le/.test(help.stdout);
-  }
+  const tenBit = Boolean(encoder && encoder.name === "libx264" && /yuv420p10le/.test(await asked(["-h", "encoder=libx264"], "about its libx264")));
   const setparams = hasFilter("setparams");
   return {
     // -fps_mode came in 5.1, in the place of -vsync.
@@ -594,10 +600,10 @@ async function capabilities(bins) {
     libass: hasFilter("ass"),
     setparams,
     // The names setparams takes for each of its options.
-    colorNames: setparams ? optionNames((await run(bins.ffmpeg, ["-hide_banner", "-h", "filter=setparams"], { quiet: 20_000 })).stdout) : {},
+    colorNames: setparams ? optionNames(await asked(["-h", "filter=setparams"], "about its setparams filter")) : {},
     encoder,
     tenBit,
-    aac: /^\s*A\S*\s+aac\s/m.test(encoders.stdout),
+    aac: /^\s*A\S*\s+aac\s/m.test(encoders),
   };
 }
 
@@ -925,7 +931,7 @@ const rateBase = (rate) => {
 // The captions show on the video's own frames. Where it has too few for
 // them, as fillFor says, `fill` gives it frames at a steady rate first.
 async function burn({ bins, caps, video: v, output, overlay = null, ass = null, assMatrix = "", assFull = false, fontsDir = "", fill = null, onProgress = null, quiet = 180_000 }) {
-  if (!caps.encoder) throw new Error("This ffmpeg has no H.264 encoder (libx264, VideoToolbox or OpenH264), so it cannot write the captioned MP4");
+  if (!caps.encoder) throw new Error("This ffmpeg has no H.264 encoder (libx264, VideoToolbox, OpenH264 or Media Foundation), so it cannot write the captioned MP4");
   const color = colorOf(v, caps.colorNames);
   // An HDR video stays HDR where x264 writes 10 bits.
   const deep = v.hdr && caps.tenBit;
@@ -1029,4 +1035,4 @@ async function frameAt(bins, file, t, output, { width = 0, retag = "", untag = "
   return output;
 }
 
-module.exports = { tools, findFfmpeg, findFfprobe, given, namedNothing, probe, readVideo, packetsOf, frameTimes, rateOf, steadyRate, fillFor, capabilities, burn, frameAt, run, whyFailed, optionNames, onPath, MISSING, colorOf, prepareChain, filterPath, libassFilter, hdrLevel, fineBase, matrixLine, as601, libassFollows, assColors, pixelFormat };
+module.exports = { FFMPEG, FFPROBE, ready, readyProbe, onPath: programs.onPath, probe, readVideo, packetsOf, frameTimes, rateOf, steadyRate, fillFor, capabilities, burn, frameAt, run, whyFailed, optionNames, colorOf, prepareChain, filterPath, libassFilter, hdrLevel, fineBase, matrixLine, as601, libassFollows, assColors, pixelFormat };

package/skills/easycaptionkit/scripts/lib/programs.js

@@ -0,0 +1,478 @@
+"use strict";
+
+// The programs a run starts, ffmpeg, ffprobe and Chrome: where each one
+// is, and whether it starts and answers as itself, asked before any work.
+// Of one that does not, a run says only what is certain: what is at its
+// path, as a folder or a file this user may not run, else what the system
+// said when it could not start it, the first line the program printed and
+// how it ended, or that it gave no answer in time. That line is the
+// program's own, and says in its words what is at fault: nothing here
+// guesses which file of a chain it is.
+
+const fs = require("node:fs");
+const path = require("node:path");
+const { spawn } = require("node:child_process");
+const { getSystemErrorMap } = require("node:util");
+const { track } = require("./running");
+
+const WINDOWS = process.platform === "win32";
+
+const exe = (name) => (WINDOWS ? `${name}.exe` : name);
+
+// A name with no folder in it, which is looked up on PATH.
+const bare = (value) => !(value.includes("/") || (WINDOWS && value.includes("\\")));
+
+// The errors a start can fail with that libuv has no name for, and Node
+// calls "Unknown system error -86": each one's name and the system's
+// words, by system and number. Linux's numbers are those of every
+// processor Node.js runs on but MIPS.
+const UNNAMED = {
+  linux: { 80: ["ELIBBAD", "accessing a corrupted shared library"], 116: ["ESTALE", "stale file handle"] },
+  darwin: { 70: ["ESTALE", "stale NFS file handle"], 85: ["EBADEXEC", "bad executable (or shared library)"], 86: ["EBADARCH", "bad CPU type in executable"], 87: ["ESHLIBVERS", "shared library version mismatch"], 88: ["EBADMACHO", "malformed Mach-o file"] },
+};
+
+// An error's name and the system's words for it, as ["EACCES",
+// "permission denied"], or [] when neither is known.
+const known = (err) => getSystemErrorMap().get(err.errno) || (!/^mips/.test(process.arch) && (UNNAMED[process.platform] || {})[-err.errno]) || [];
+
+// The system's name for an error, as EACCES, else Node's.
+const codeOf = (err) => known(err)[0] || err.code;
+
+// The system's words for an error, as "permission denied", else its code.
+const worded = (err) => known(err)[1] || err.code || String(err.message || err);
+
+// How long a program may take to answer, in milliseconds: on a machine
+// short of memory, with its swap full, ffmpeg 4.4 took more than 30
+// seconds to say its version.
+const LIMIT = 120_000;
+
+// ─── where a program is ───────────────────────────────────────────────────
+
+// A file this user may run, as a shell takes one: a file, not a folder,
+// with the permission to run it. On Windows that permission is not looked
+// at, and any file passes.
+function runnable(file) {
+  try {
+    fs.accessSync(file, fs.constants.X_OK);
+    return fs.statSync(file).isFile();
+  } catch {
+    return false;
+  }
+}
+
+// Whether a folder is there and this user may enter it, as a program run
+// in it needs.
+function enterable(folder) {
+  try {
+    fs.accessSync(folder, fs.constants.X_OK);
+    return fs.statSync(folder).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+// The folders of PATH in order, each as a whole path: one given from the
+// current folder is taken from the folder the run started in, so a
+// program found there is found when it runs in another folder. An empty
+// entry is passed over.
+const folders = () =>
+  String(process.env.PATH || "")
+    .split(path.delimiter)
+    .filter(Boolean)
+    .map((dir) => path.resolve(dir));
+
+// The first program by a name on PATH that this user may run, in a folder
+// `skip` does not pass over, or "".
+function onPath(name, { skip = () => false } = {}) {
+  for (const dir of String(process.env.PATH || "").split(path.delimiter)) {
+    if (!dir || skip(dir)) continue;
+    const file = path.resolve(dir, name);
+    if (runnable(file)) return file;
+  }
+  return "";
+}
+
+// Whether a file, not a folder, is at a path, as Windows looks for one.
+function there(file) {
+  try {
+    return !fs.statSync(file).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+// Whether Windows runs a file by its own name: one whose name has an
+// extension. It runs a name with none only as that name with .com or .exe
+// added, which libuv looks for next to it.
+function runsAsNamed(file) {
+  const name = path.basename(file);
+  const dot = name.indexOf(".");
+  return dot >= 0 && dot < name.length - 1;
+}
+
+// The file a path goes through as if it were a folder, as notes.txt in
+// notes.txt/ffmpeg, or "".
+function fileOnTheWay(file) {
+  const parts = file.split(path.sep);
+  for (let i = 2; i < parts.length; i++) {
+    const part = parts.slice(0, i).join(path.sep);
+    try {
+      if (!fs.statSync(part).isDirectory()) return part;
+    } catch {
+      return "";
+    }
+  }
+  return "";
+}
+
+// What keeps the system from running the file at a path, as far as can be
+// told for certain before it runs: null when nothing does, else the words
+// for it, and in `on` what the system does with such a file as it looks
+// for a program on PATH. It "passes" over a folder, a named pipe, a
+// socket and a device, none of which it runs, a link to nothing and a
+// file this user may not run, to look in the next folder, and these are
+// named when no program comes after them; it passes over nothing there
+// and a folder this user may not enter "quietly", as these may hold no
+// such program at all; and it "stops" at a path it cannot follow, as a
+// loop of links. On Windows, where no permission to run a file is looked
+// at, a file whose name has no extension passes, as Windows does not run
+// it, unless a .com or an .exe by that name is next to it, which it runs.
+function barred(file) {
+  let stat;
+  try {
+    stat = fs.statSync(file);
+  } catch (err) {
+    if (err.code === "ENOENT" || err.code === "ENOTDIR") {
+      let link = false;
+      try {
+        link = fs.lstatSync(file).isSymbolicLink();
+      } catch {
+        // Nothing there at all.
+      }
+      if (link) return { on: "passes", words: "is a link to a file that is not there" };
+      const through = err.code === "ENOTDIR" ? fileOnTheWay(file) : "";
+      return { on: "quietly", words: through ? `where there is none, as ${through} is a file, not a folder` : "where there is none" };
+    }
+    if (err.code === "EACCES" || err.code === "EPERM") return { on: "quietly", words: "may not be run: permission denied" };
+    if (err.code === "ELOOP") return { on: "stops", words: "goes through a loop of links" };
+    return { on: "stops", words: `cannot be looked at: ${worded(err)}` };
+  }
+  if (stat.isDirectory()) return { on: "passes", words: "is a folder" };
+  if (WINDOWS) return runsAsNamed(file) || there(`${file}.com`) || there(`${file}.exe`) ? null : { on: "passes", words: "has no .exe in its name, so Windows does not run it" };
+  if (!stat.isFile()) return { on: "passes", words: stat.isFIFO() ? "is a named pipe" : stat.isSocket() ? "is a socket" : "is a device" };
+  try {
+    fs.accessSync(file, fs.constants.X_OK);
+  } catch {
+    return { on: "passes", words: (stat.mode & 0o111) === 0 ? "is not executable" : "may not be run: permission denied" };
+  }
+  return null;
+}
+
+// ─── what a program said ──────────────────────────────────────────────────
+
+// What `file` did when run with `args`, given `limit` milliseconds: { code,
+// signal, stdout, stderr }, { late: true } when it gave no answer in that
+// time and was stopped (see late()), or { err } when the system did not
+// start it. What it printed is kept up to `cap` bytes.
+function ask(file, args, { limit = LIMIT, cap = 1 << 20 } = {}) {
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = track(spawn(file, args, { stdio: ["ignore", "pipe", "pipe"] }));
+    } catch (err) {
+      resolve({ err });
+      return;
+    }
+    let timer = null;
+    let done = false;
+    const end = (result) => {
+      if (done) return;
+      done = true;
+      clearTimeout(timer);
+      resolve(result);
+    };
+    // A start that fails gives its error before the close.
+    child.on("error", (err) => end({ err }));
+    // With no file descriptor left Node makes no pipes, and says why a
+    // moment later.
+    if (!child.stdout || !child.stderr) return;
+    const said = { stdout: [], stderr: [] };
+    let size = 0;
+    for (const name of ["stdout", "stderr"]) {
+      child[name].on("data", (chunk) => {
+        if (size >= cap) return;
+        said[name].push(chunk);
+        size += chunk.length;
+      });
+    }
+    // A program that hands its output on to one that goes on running may
+    // never close it, so the answer is not waited for past the limit.
+    timer = setTimeout(() => {
+      try {
+        child.kill("SIGKILL");
+      } catch {
+        // Gone already.
+      }
+      child.stdout.destroy();
+      child.stderr.destroy();
+      end({ late: true });
+    }, limit);
+    child.on("close", (code, signal) => end({ code, signal, stdout: Buffer.concat(said.stdout).toString("utf8"), stderr: Buffer.concat(said.stderr).toString("utf8") }));
+  });
+}
+
+// A line a program printed, in quotes, as it printed it, with its control
+// characters written out, as \r or \x1b. A line longer than 200 characters
+// keeps its first 120 and its last 80, as its end most often says why.
+function quoted(line) {
+  const chars = Array.from(String(line)).map((c) => {
+    if (c === "\t") return "\\t";
+    if (c === "\r") return "\\r";
+    if (!/[\p{Cc}\p{Cf}]/u.test(c)) return c;
+    const n = c.codePointAt(0);
+    return n < 0x100 ? `\\x${n.toString(16).padStart(2, "0")}` : `\\u${n.toString(16).padStart(4, "0")}`;
+  });
+  const shown = chars.length > 200 ? [...chars.slice(0, 120), "...", ...chars.slice(-80)] : chars;
+  return `"${shown.join("")}"`;
+}
+
+// The first line with anything in it of what a program printed, or null.
+const firstLine = (text) =>
+  String(text || "")
+    .split(/\r?\n/)
+    .find((line) => line.trim()) || null;
+
+// What a program that ran did, where it did not answer: the first line it
+// printed on its error output, where a program says what is wrong, else on
+// its output, and how it ended. ffmpeg, ffprobe and Chrome give their
+// versions on their output, so a program that ended well and printed on
+// its error output alone is said to.
+function happened(r) {
+  const line = firstLine(r.stderr);
+  if (line && r.code === 0 && !firstLine(r.stdout)) return `it printed ${quoted(line)} on its error output, nothing on its output, and exited with 0`;
+  const ended = r.signal ? `was stopped by ${r.signal}` : `exited with ${r.code}`;
+  const said = line || firstLine(r.stdout);
+  if (said) return `it printed ${quoted(said)} and ${ended}`;
+  return r.signal ? `it was stopped by ${r.signal}` : `it printed nothing and exited with ${r.code}`;
+}
+
+// The first line of a file that starts with #!, which names the program
+// the system starts the file with, or null. It is opened without waiting,
+// as a named pipe put in the file's place since it was looked at would
+// wait for a writer for good, and read only when it is a file.
+function bangLine(file) {
+  let fd;
+  try {
+    fd = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NONBLOCK || 0));
+    if (!fs.fstatSync(fd).isFile()) return null;
+    const bytes = Buffer.alloc(256);
+    const got = bytes.subarray(0, fs.readSync(fd, bytes, 0, bytes.length, 0));
+    if (got.indexOf("#!") !== 0) return null;
+    const end = got.indexOf(10);
+    return got.subarray(0, end < 0 ? got.length : end).toString("utf8");
+  } catch {
+    return null;
+  } finally {
+    if (fd !== undefined) fs.closeSync(fd);
+  }
+}
+
+// What the system said when it did not start a file the checks found
+// nothing wrong with. Off Windows it says ENOENT of a file that is there
+// when an interpreter or a loader the file needs is not, so a script's
+// first line, which names its interpreter, is shown with it. Windows runs
+// no interpreter a first line names.
+function unstartable(file, err) {
+  if (["ENOEXEC", "EFTYPE", "EBADARCH", "EBADMACHO"].includes(codeOf(err))) return "it is not a program this system can run";
+  const line = WINDOWS ? null : bangLine(file);
+  const first = line === null ? "" : `; its first line is ${quoted(line)}`;
+  if (codeOf(err) === "ENOENT" && !WINDOWS) return `the system could not start it, as an interpreter or a loader it needs is not there${first}`;
+  return `the system could not start it: ${worded(err)}${first}`;
+}
+
+// The errors that say the system is short of something to start a program
+// with, not that the program is wrong: what it is short of, and what to do.
+const SHORT = {
+  EMFILE: "too many open files. Raise the limit on open files (ulimit -n) and run it again",
+  ENFILE: "the system has too many files open. Run it again once fewer are",
+  EAGAIN: "the system starts no more processes for now. Run it again once fewer are running",
+  ENOMEM: "not enough memory. Free some and run it again",
+  E2BIG: "its environment is too large. Run it with fewer or shorter environment variables",
+};
+
+// The errors a start fails with that the system passes over, as glibc's
+// execvp does, to try the next folder of PATH: a file that is not there or
+// may not be run, or one whose interpreter or loader is not there.
+const PASSED = new Set(["ENOENT", "EACCES", "ENOTDIR", "ESTALE", "ENODEV", "ETIMEDOUT"]);
+
+// The error for a program the system could not start for want of something
+// it is short of, as open files: no fault of the program's.
+const short = (name, err) => Object.assign(new Error(`easycaptionkit could not start ${name}: ${SHORT[err.code]}.`), { unusable: true, why: `the system could not start ${name}: ${SHORT[err.code].replace(/\. .*$/, "")}` });
+
+// The error for a program that gave no answer in `limit` ms when asked
+// `what`, as "its version": ffmpeg on a machine short of memory can be
+// that slow as well as a program that is not ffmpeg, so only that is said,
+// and to run again, with no advice to install another.
+function late(spec, place, what, limit) {
+  const words = `gave no answer in ${limit / 1000} s when asked ${what}`;
+  return Object.assign(new Error(`easycaptionkit could not check ${spec.name}, ${place.file}: it ${words}, as on a machine short of memory. ${spec.advice.late}`), { unusable: true, why: placed(place, words) });
+}
+
+// The error for a program a run checked before any work that the system
+// did not start during the work, `name` being what messages call it: what
+// the system is short of, else the system's words, never its code alone,
+// and what to check, as a program that answered when the run began can
+// have been taken away or changed since.
+function startFailure(file, err, name = path.basename(file)) {
+  if (Object.hasOwn(SHORT, err.code)) return short(name, err);
+  return new Error(`easycaptionkit could not start ${name}, ${file}, again: ${worded(err)}. Check that it is still there and may be run, and run easycaptionkit again.`);
+}
+
+// ─── finding a program and asking it ──────────────────────────────────────
+
+// A program a run looks for, as ffmpeg.js and chrome.js give it: { name,
+// variable, args, answers, names, first, known, ask, none, advice }.
+// `name` is what messages call it, `variable` the one that names it,
+// `args` what asks its version and `answers(stdout)` whether what it
+// printed then answers as it does, after it exited with 0. `names` are its
+// names on PATH. Where the variable is not set, `first()` gives places
+// looked at before PATH, each { file, name, where, next }, of which the
+// first that is there is taken, and `known` folders looked in where PATH
+// has nothing by its names, as package managers put it there for an agent
+// or an app whose PATH is short. With `ask` false, a program is taken once
+// nothing is in the way of running it, as Chrome on Windows, which prints
+// no version. `none` is the message when there is none, and `advice` the
+// sentence that ends one about a program the run cannot use: `variable`
+// for one the variable names, `next` for ffprobe next to ffmpeg, `found`
+// for the others, and `late` for one that gave no answer in time.
+
+// Where a run found a program, in words that name its place and say what
+// happened there.
+function placed(place, words) {
+  if (place.variable && !bare(place.value)) return `${place.variable} points to ${place.file}, ${words.startsWith("where ") ? words : `which ${words}`}`;
+  if (place.variable) return `${place.variable} names ${place.value}, found on PATH at ${place.file}, which ${words}`;
+  return `the ${place.name} ${place.where}, ${place.file}, ${words}`;
+}
+
+// The error for a program a run cannot use: the message, and in `why` the
+// words that name its place and what happened, as a note gives them.
+function unusable(spec, place, words) {
+  const why = placed(place, words);
+  const advice = place.variable ? spec.advice.variable : place.next ? spec.advice.next : spec.advice.found;
+  return Object.assign(new Error(`easycaptionkit needs ${spec.name}, and ${why}. ${advice}`), { unusable: true, why });
+}
+
+// Whether what a program did when asked its version answers as `spec`.
+const answered = (spec, r) => !r.err && !r.late && r.code === 0 && !r.signal && spec.answers(r.stdout);
+
+// The places in turn: what keeps each from running, then, unless `spec`
+// says not to, what it did when asked its version. The first that answers
+// is { found: place, stdout }. A place `alone`, the one a variable or a
+// place before PATH gives, is the only one, and what is wrong with it is
+// said. Of places on PATH, the system's search passes over some (see
+// barred() and PASSED), and the first of those is given as `passed`; at
+// any other the search stops, with what is wrong there.
+async function walk(spec, places, limit, { alone = false } = {}) {
+  let passed = null;
+  for (const place of places) {
+    let seen = barred(place.file);
+    if (!seen) {
+      if (spec.ask === false) return { found: place, stdout: "" };
+      const r = await ask(place.file, spec.args, { limit, cap: 1 << 16 });
+      if (r.err && Object.hasOwn(SHORT, r.err.code)) throw short(spec.name, r.err);
+      if (r.late) throw late(spec, place, "its version", limit);
+      if (answered(spec, r)) return { found: place, stdout: r.stdout };
+      // A file taken away or changed since it was looked at is said to be
+      // what it is now.
+      if (r.err) seen = barred(place.file) || { on: PASSED.has(codeOf(r.err)) ? "passes" : "stops", words: `did not run as ${spec.name}: ${unstartable(place.file, r.err)}` };
+      else seen = { on: "stops", words: `did not run as ${spec.name}: ${happened(r)}` };
+    }
+    if (alone || seen.on === "stops") throw unusable(spec, place, seen.words);
+    if (seen.on === "passes" && !passed) passed = { place, words: seen.words };
+  }
+  return { passed };
+}
+
+// The places a program is looked for on PATH, by each of its names, and
+// in the folders `known` where PATH has nothing by them.
+function onPathPlaces(spec, value) {
+  const names = value ? [value, ...(WINDOWS ? [exe(value)] : [])] : spec.names;
+  const named = value ? { variable: spec.variable, value } : {};
+  return names.flatMap((name) => folders().map((dir) => ({ file: path.join(dir, name), name, where: "on PATH", ...named })));
+}
+
+const knownPlaces = (spec) => (WINDOWS ? [] : (spec.known || []).flatMap((dir) => spec.names.map((name) => ({ file: path.join(dir, name), name, where: `in ${dir}` }))));
+
+// The program a run uses, found and asked its version before any work, as
+// { file, stdout, place }: the path its variable gives, as it is, or the
+// first program by its name on PATH the system would start; with the
+// variable unset, the first of the places before PATH that is there, else
+// the first on PATH, else one in the known folders. It is taken only when
+// it exits with 0 and its answer is one `spec` takes; otherwise the run
+// stops before any work, with what is wrong with it, what the system said
+// or what it printed (see unusable()), and when there is none, with
+// `spec.none`. Every run checks the programs it uses with this first.
+async function find(spec, limit = LIMIT) {
+  const value = process.env[spec.variable] || "";
+  const through = async (places, options) => {
+    const { found, stdout, passed } = await walk(spec, places, limit, options);
+    return found ? { file: found.file, stdout, place: found } : { passed };
+  };
+  if (value && !bare(value)) return through([{ file: path.resolve(value), variable: spec.variable, value }], { alone: true });
+  if (!value) {
+    const first = (spec.first ? spec.first() : []).find((place) => fs.existsSync(place.file));
+    if (first) return through([first], { alone: true });
+  }
+  let result = await through(onPathPlaces(spec, value));
+  if (!result.file && !result.passed && !value) result = await through(knownPlaces(spec));
+  if (result.file) return result;
+  if (result.passed) throw unusable(spec, result.passed.place, result.passed.words);
+  if (value) throw Object.assign(new Error(`easycaptionkit needs ${spec.name}, and ${spec.variable} names ${value}, which is not on PATH. ${spec.advice.variable}`), { unusable: true, why: `${spec.variable} names ${value}, which is not on PATH` });
+  throw Object.assign(new Error(spec.none), { unusable: true, why: `no ${spec.name} was found` });
+}
+
+// The file a run would take for a program by what is at each place alone,
+// not run, or "": the path its variable gives, as it is, else as find()
+// looks, where nothing keeps a file from running. ffprobe is looked for
+// next to it, where a run uses ffprobe alone.
+function locate(spec) {
+  const value = process.env[spec.variable] || "";
+  if (value && !bare(value)) return path.resolve(value);
+  if (!value) {
+    const first = (spec.first ? spec.first() : []).find((place) => fs.existsSync(place.file));
+    if (first) return first.file;
+  }
+  // The first place nothing keeps from running, as { file }, else whether
+  // the search stopped at one or passed over one.
+  const look = (places) => {
+    let passed = false;
+    for (const place of places) {
+      const seen = barred(place.file);
+      if (!seen) return { file: place.file };
+      if (seen.on === "stops") return { stopped: true };
+      if (seen.on === "passes") passed = true;
+    }
+    return { passed };
+  };
+  const onPath = look(onPathPlaces(spec, value));
+  if (onPath.file) return onPath.file;
+  if (onPath.stopped || onPath.passed || value) return "";
+  return look(knownPlaces(spec)).file || "";
+}
+
+// What the program found at `place` printed when run with `args` after it
+// answered its version, as asked about `what` ("its encoders"): its
+// output, read only once it ended well. One that fails or is stopped
+// stops the run with how it ended, so a program that cannot answer is not
+// taken for one without the encoder or the filter asked for, and one that
+// gives no answer in time stops it as late() says.
+async function probe(spec, place, args, what, limit = LIMIT) {
+  const r = await ask(place.file, args, { limit });
+  const asked = args.filter((arg) => arg !== "-hide_banner").join(" ");
+  if (r.err && Object.hasOwn(SHORT, r.err.code)) throw short(spec.name, r.err);
+  if (r.late) throw late(spec, place, `${what} (${asked})`, limit);
+  if (!r.err && r.code === 0 && !r.signal) return r.stdout;
+  throw unusable(spec, place, `failed when asked ${what} (${asked}): ${r.err ? unstartable(place.file, r.err) : happened(r)}`);
+}
+
+module.exports = { exe, enterable, onPath, quoted, happened, unstartable, find, locate, probe, startFailure, LIMIT };

package/skills/easycaptionkit/scripts/lib/version.js

@@ -2,4 +2,4 @@
 
 // Kept here, not read from package.json: a skill install copies this folder
 // alone.
-module.exports = "0.1.2";
+module.exports = "0.1.4";