musicfit 0.2.0 → 0.2.2

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

@@ -12,6 +12,15 @@ AI music models ignore the length you ask for. Ask for 30 seconds and you may ge
 
 The track can come from any music model, and [Wiro](https://wiro.ai/explore/music-generation) has several.
 
+## Requirements
+
+- Node.js 22 or newer.
+- ffmpeg 4.4 or newer, Ubuntu 22.04's 4.4.2 included. musicfit does not use ffprobe, and needs no H.264 encoder, as `--video` copies the picture as it is. 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. Before any work, a run checks that ffmpeg starts and answers as ffmpeg; one that does not stops the run with what the system or the program said, and how to get one. One that gives no answer in two minutes, as on a machine short of memory, stops the run too, and the message says to run it again. It does not check the version number ffmpeg gives, so an ffmpeg older than 4.4 goes ahead, though no test has run on one. When the system is short of open files, processes or memory to start ffmpeg, the run says so and what to do.
+- 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. `fitted.wav` and `mix.wav` take 17 MB each for every minute of the fit, and `video.mp4` as much as the video's picture and about 2 MB a minute of sound. Until a run with `--video` ends, it also keeps up to four AAC encodings of that sound, about 2 MB a minute each, in its hidden folder in the out folder, or next to it when the out folder is not there yet.
+- Memory that grows with the length of the fit and of the track, and with that of a voice or of the video's own sound, which are read to their end even where they run on past the fit: a 10 minute fit of a 10 minute track took 0.9 to 1.7 GB, and a 20 second fit with a voice took 0.2 GB, or 0.8 GB when the voice ran on 10 minutes past it (see [Limits](#limits)).
+- A run needs no network access, no browser and no API key: musicfit reads files on your disk, and nothing leaves your machine. Installing it needs the network, and `npx musicfit@latest` asks npm for the newest version each time it runs. There are no npm dependencies: the beat tracking is plain JavaScript.
+
 ## What you get
 
 ```
@@ -93,20 +102,20 @@ When another program holds a file open so that it cannot be moved, the run says
 musicfit ships as an [Agent Skill](https://agentskills.io). Install it once and your agent runs it by itself when a video needs music that fits:
 
 ```bash
-npx skills add EminBudak/musicfit
+npx skills add MakersMCP/musicfit
 ```
 
 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/musicfit
+/plugin marketplace add MakersMCP/musicfit
 /plugin install musicfit@musicfit
 ```
 
 In GitHub Copilot CLI it takes the same two steps:
 
 ```bash
-copilot plugin marketplace add EminBudak/musicfit
+copilot plugin marketplace add MakersMCP/musicfit
 copilot plugin install musicfit@musicfit
 ```
 
@@ -172,9 +181,7 @@ npx musicfit@latest track.mp3 --length 32 --video talk.mp4 --video-sound voice
 npx musicfit@latest track.mp3 --analyze
 ```
 
-Installed globally (`npm install -g musicfit`), the command is `musicfit`. npx keeps the copy an earlier run fetched, so `npx musicfit@latest` is how you get a newer version.
-
-It needs Node 22 or newer and ffmpeg 4.4 or newer (`brew install ffmpeg`, `sudo apt install ffmpeg` or `winget install ffmpeg`); the tests run on Ubuntu 22.04's ffmpeg 4.4 and on the latest Ubuntu's, before every release too. Set `FFMPEG_PATH` to pick the ffmpeg. There are no npm dependencies; the beat tracking is plain JavaScript and nothing leaves your machine.
+Installed globally (`npm install -g musicfit`), the command is `musicfit`. npx keeps the copy an earlier run fetched, so `npx musicfit@latest` is how you get a newer version. What a run needs is under [Requirements](#requirements).
 
 ## How it works
 
@@ -197,15 +204,15 @@ It needs Node 22 or newer and ffmpeg 4.4 or newer (`brew install ffmpeg`, `sudo
 - Seams follow bars and sound, not words: in a song with singing a cut can fall in the middle of a line. An instrumental fits best.
 - Lengthening loops bars the track already has, so a 30 second track stretched to 3 minutes repeats, and so does the intro when the drop is asked for much later than the track has it (musicfit says how many times). Ask the music model for a little more than you need.
 - `--video` copies the picture as it is, so a picture an MP4 cannot hold that way (ProRes, DNxHD, VP8) is refused rather than encoded again. Only the picture and the new sound go into `video.mp4`: subtitles and other streams of the video are left out, a note says so of subtitles, and of several sound streams only the first is read.
-- A fit holds its sound in memory a few times over, so memory grows with `--length` and with the length of the track itself: a 10 minute fit of a 10 minute track took 0.9 to 1 GB, 1.2 GB with `--video` and its own sound kept, 1.4 to 1.5 GB with `--voice` and 1.7 GB with a voice and the video's own sound as well, on a desktop with ffmpeg 8 and in a 2 GB container with ffmpeg 4.4. A run takes a few seconds, and with `--video` of a long film a minute or more, most of it spent encoding the sound as AAC.
+- A fit holds its sound in memory a few times over, so memory grows with `--length` and with the length of the track itself: a 10 minute fit of a 10 minute track took 0.9 to 1 GB, 1.2 GB with `--video` and its own sound kept, 1.4 to 1.5 GB with `--voice` and 1.7 GB with a voice and the video's own sound as well, on a desktop with ffmpeg 8 and in a 2 GB container with ffmpeg 4.4. A voice and the video's own sound are read to their end before they are cut to the fit, so memory grows with their length too: a 20 second fit took 0.2 GB with a voice as long as itself, 0.8 GB with one that ran on 10 minutes past it, and 0.6 GB with a video whose own sound ran on 10 minutes past its picture, on the desktop and in the container alike. A run takes a few seconds, and with `--video` of a long film a minute or more, most of it spent encoding the sound as AAC.
 - musicfit cannot tell speech from sound effects or from music, which is why it asks for `--video-sound`. With `voice` the music dips under anything in that sound that stands out, a cough or a door as much as a word, and a hiss or a hum under a quiet voice comes up with it. With `keep` each place is set on its own, so a soft effect and a loud one over the same music come out alike, and a hiss or a hum between them comes up with the places around it.
 - It does not change the tempo or the pitch, and it does not check whether you may use the track.
 
 ## See also
 
-- [launch-film](https://github.com/EminBudak/launch-film) turns a site into a short launch film, rendered on your machine.
-- [easyscreenshotkit](https://github.com/EminBudak/easyscreenshotkit) saves clean screenshots of a website's pages.
-- [easybrandkit](https://github.com/EminBudak/easybrandkit) saves a site's real logo files, colors and fonts as a brand kit.
+- [launch-film](https://github.com/MakersMCP/launch-film) turns a site into a short launch film, rendered on your machine.
+- [easyscreenshotkit](https://github.com/MakersMCP/easyscreenshotkit) saves clean screenshots of a website's pages.
+- [easybrandkit](https://github.com/MakersMCP/easybrandkit) saves a site's real logo files, colors and fonts as a brand kit.
 
 ## License
 

package/package.json

@@ -1,15 +1,15 @@
 {
   "name": "musicfit",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Fit a music track to a video cut: exactly the length you need, cut and looped on bar lines, the drop on the second you pick, a fade that ends on a beat, ducked under a voice, at the right loudness, and laid under the video when you give it.",
   "license": "MIT",
   "author": "Emin Budak",
-  "homepage": "https://github.com/EminBudak/musicfit#readme",
+  "homepage": "https://github.com/MakersMCP/musicfit#readme",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/EminBudak/musicfit.git"
+    "url": "git+https://github.com/MakersMCP/musicfit.git"
   },
-  "bugs": "https://github.com/EminBudak/musicfit/issues",
+  "bugs": "https://github.com/MakersMCP/musicfit/issues",
   "bin": {
     "musicfit": "skills/musicfit/scripts/musicfit.js"
   },

package/skills/musicfit/SKILL.md

@@ -13,7 +13,7 @@ Music models ignore the length you ask for, and a track cut at the video's last
 node <skill>/scripts/musicfit.js track.mp3 --length 32 --hit 27.5 --fps 30 --out audio/fit
 ```
 
-`<skill>` is this skill's folder. The script needs Node 22 or newer and ffmpeg 4.4 or newer on the machine; it installs nothing and needs no API key. A run takes a few seconds, and with a long `--video` a minute or more. A long fit needs memory, more the longer the fit and the longer the track: a 10 minute fit of a 10 minute track took 0.9 to 1 GB, 1.2 GB with `--video`, 1.4 to 1.5 GB with `--voice` and 1.7 GB with a voice and the video's own sound.
+`<skill>` is this skill's folder. The script needs Node 22 or newer and ffmpeg 4.4 or newer on the machine; it installs nothing and needs no API key. A run takes a few seconds, and with a long `--video` a minute or more. A run needs memory, more the longer the fit and the track, and the longer a voice or the video's own sound, which are read to their end even where they run on past the fit: a 10 minute fit of a 10 minute track took 0.9 to 1 GB, 1.2 GB with `--video`, 1.4 to 1.5 GB with `--voice` and 1.7 GB with a voice and the video's own sound, and a 20 second fit took 0.8 GB with a voice that ran on 10 minutes past it.
 
 - `--length` is the video's length: seconds (`32`), frames (`960f`, at `--fps`) or minutes (`1:05`).
 - `--hit` is the second the drop should land on, for example the logo reveal. Leave it out and the track keeps its own ending; a short fit can then start later in the track, so its drop may not play (FIT.md says where it starts). Give `--hit` when the drop has to be heard.
@@ -59,4 +59,5 @@ A voice the video already holds goes with `--video-sound voice`, not as a copy g
 - A run is refused before any work when its out folder holds, under a name the run writes, a file that is not as an earlier musicfit run wrote it there, such as the user's own `video.mp4` beside a copied `cues.json` for a run with `--video`, or a `FIT.md` or `cues.json` the user changed (move it, with the files it lists for a `cues.json`, or give another `--out`); a run that does not write that name leaves the file alone. It is refused too when the track, the voice or the video is one of the files the run would replace or remove.
 - A run that fails or is stopped (Ctrl-C, or a signal such as SIGTERM) leaves its folder as it was, so a fit that worked is never lost to one that did not. As the earlier files stay until the new ones are in place, a run needs room on the disk for both, and a full disk says so. A run that ends well removes the earlier files it does not make again, and a note names them: tell the user when one was a fit's `video.mp4` or `fitted.wav`. A run killed outright after it began writing can leave a hidden `.musicfit-part-` folder, inside the out folder or next to it when the out folder was not there yet, which a later run that ends well in the same place removes once the killed run's process is gone and 15 minutes have passed (one it may not look into stays, and does not fail that run); a run killed in the moment it moved its files in is undone by the next run there, which puts the earlier files back first, and no other run removes its hidden folder. When a failed or stopped run could not remove its hidden folder, its message names it, and a later run removes it the same way. When another program held a file open so that a run could not put every earlier file back, the message names the folder they are in, and its `musicfit-kept.txt` says where each one belongs: tell the user.
 - musicfit reads files: a track, a voice or a video given as an address is refused. Download it first.
+- "musicfit needs ffmpeg" means the run stopped before any work, as it found no ffmpeg, or the one it found or `FFMPEG_PATH` names could not be started or did not answer as ffmpeg when asked its version. The message names that file and gives what the system said, or the first line the program printed and how it ended: tell the user, and ask them to install ffmpeg or to set `FFMPEG_PATH` to one that runs. "musicfit could not start ffmpeg" means the system could not start a program then, as when too many files are open, and "musicfit could not check ffmpeg" that ffmpeg gave no answer in two minutes when asked its version, as on a machine short of memory; the message says what to do.
 - Never say a track is cleared for use; musicfit does not check rights.

package/skills/musicfit/scripts/lib/audio.js

@@ -7,7 +7,9 @@
 // floats, or as stereo { L, R }, which is interleaved a block at a time on
 // its way, so no interleaved copy of a long sound is ever held whole.
 
+const fs = require("node:fs");
 const path = require("node:path");
+const { getSystemErrorMap } = require("node:util");
 const { spawn } = require("node:child_process");
 const { CHUNK, breathe } = require("./breathe");
 
@@ -30,20 +32,30 @@ function ffmpegPath() {
   return path.basename(named) === named ? named : whole(named);
 }
 
+// The variable that holds PATH and its entries, as the system reads them.
+// Windows takes the variable's name in any case, and an entry in quotes,
+// which may hold a ; of its own. No entries when there is no PATH.
+function pathEntries() {
+  const windows = process.platform === "win32";
+  const key = windows ? Object.keys(process.env).find((name) => name.toUpperCase() === "PATH") : "PATH";
+  if (!key || process.env[key] === undefined) return { key, entries: null };
+  return { key, entries: windows ? process.env[key].match(/(?<=^|;)("[^"]*"?|'[^']*'?)?[^;]*/g) : process.env[key].split(path.posix.delimiter) };
+}
+
+// The bare folder of an entry of PATH written in quotes on Windows.
+const unquoted = (entry) => entry.replace(/^["']|["']$/g, "");
+
 // The environment for a call run in another folder: a relative entry of PATH
 // reads from that folder when ffmpeg is looked up, so that entry is written
 // from where musicfit was started, and the others stay as they are. An empty
-// entry is the current folder too. Windows passes over an empty entry, takes
-// one in quotes, which may hold a ; of its own, and the variable's name in
-// any case.
+// entry is the current folder too. Windows passes over an empty entry.
 function fromHere() {
   const windows = process.platform === "win32";
   const { delimiter, isAbsolute } = windows ? path.win32 : path.posix;
-  const key = windows ? Object.keys(process.env).find((name) => name.toUpperCase() === "PATH") : "PATH";
-  if (!key || process.env[key] === undefined) return process.env;
-  const entries = windows ? process.env[key].match(/(?<=^|;)("[^"]*"?|'[^']*'?)?[^;]*/g) : process.env[key].split(delimiter);
+  const { key, entries } = pathEntries();
+  if (!entries) return process.env;
   const written = entries.map((entry) => {
-    const bare = windows ? entry.replace(/^["']|["']$/g, "") : entry;
+    const bare = windows ? unquoted(entry) : entry;
     return isAbsolute(bare) || (windows && !bare) ? entry : whole(bare);
   });
   return { ...process.env, [key]: written.join(delimiter) };
@@ -54,6 +66,318 @@ function fromHere() {
 // protocol, and never a full path.
 const where = (file) => whole(file);
 
+// Whether a file the run looked at before any work is not there now, as
+// when it was taken away since: only then is a "No such file" that ffmpeg
+// says while it reads it about that file. ffmpeg 7 and newer say it on a
+// line that does not name the file.
+function gone(file) {
+  try {
+    fs.statSync(where(file));
+    return false;
+  } catch (err) {
+    return err.code === "ENOENT" || err.code === "ENOTDIR";
+  }
+}
+
+// How each message that asks for an ffmpeg says to get one.
+const INSTALL = "brew install ffmpeg, sudo apt install ffmpeg or winget install ffmpeg";
+
+// Where the system looks for a program when there is no PATH: glibc in
+// /bin, then /usr/bin, musl in /usr/local/bin first, and Node on macOS, as
+// the BSDs do, in /usr/bin, then /bin.
+function defaultFolders() {
+  if (process.platform !== "linux") return ["/usr/bin", "/bin"];
+  return process.report.getReport().header.glibcVersionRuntime ? ["/bin", "/usr/bin"] : ["/usr/local/bin", "/bin", "/usr/bin"];
+}
+
+// The files the system tries, in its order, for the program FFMPEG_PATH
+// names, or ffmpeg: that path when it has a folder in it, else that name in
+// each folder of PATH, an empty or a relative one read from where musicfit
+// was started, or with no PATH at all in the system's own folders. Windows
+// looks in the current folder first and adds .com and .exe to the name,
+// which it tries as it is only when it has an extension. A path with a
+// folder in it comes first as it is all the same, so a file there with no
+// extension is named for what it is (see barred()).
+function places(program) {
+  const windows = process.platform === "win32";
+  if (path.basename(program) !== program) return [program, ...(windows ? [`${program}.com`, `${program}.exe`] : [])];
+  const { entries } = pathEntries();
+  const folders = windows ? ["", ...(entries || []).map(unquoted).filter(Boolean)] : entries || defaultFolders();
+  const names = windows ? [...(path.extname(program) ? [program] : []), `${program}.com`, `${program}.exe`] : [program];
+  return folders.flatMap((folder) => {
+    const at = whole(folder || ".");
+    return names.map((name) => `${at}${at.endsWith(path.sep) ? "" : path.sep}${name}`);
+  });
+}
+
+// The system's words for an error, such as "permission denied", else its code.
+const worded = (err) => (getSystemErrorMap().get(err.errno) || [])[1] || err.code;
+
+// The file a path goes through as if it were a folder, as notes.txt in
+// notes.txt/ffmpeg, or null.
+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 null;
+    }
+  }
+  return null;
+}
+
+// What keeps the system from running the file at a place, 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 it when it looks for a
+// program on PATH. It "passes" over a folder, a file this user may not run
+// and a link to nothing, and looks in the next folder; 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. Windows passes over a file whose name has no
+// extension too, as it tries that name with .com and .exe added (see
+// places()).
+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 (process.platform === "win32" && !path.extname(file)) return { on: "passes", words: "has no .exe in its name, so Windows does not run it" };
+  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;
+}
+
+// The errors that say the system is short of something to start a program
+// with, not that ffmpeg 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"]);
+
+// How long ffmpeg -version may take, in milliseconds: on a machine short
+// of memory, with its swap full, ffmpeg 4.4 took more than 30 seconds.
+const LIMIT = 120000;
+
+// 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(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.
+function firstLine(text) {
+  return (
+    String(text || "")
+      .split(/\r?\n/)
+      .find((l) => l.trim()) || null
+  );
+}
+
+// The first line of a file that starts with #!, as the system reads it to
+// find the program that runs the file, or null.
+function bangLine(file) {
+  let fd;
+  try {
+    fd = fs.openSync(file, "r");
+    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 happened to a file the system did not start with `err`, after the
+// certain checks found nothing wrong with the file itself. The system says
+// ENOENT of a file that is there when an interpreter or a loader it needs
+// is not, so a script's first line, which names its interpreter, is shown.
+function unstartable(file, err) {
+  if (["ENOEXEC", "EFTYPE", "EBADARCH"].includes(err.code)) return "it is not a program this system can run";
+  const line = bangLine(file);
+  const first = line === null ? "" : `; its first line is ${quoted(line)}`;
+  if (err.code === "ENOENT") 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}`;
+}
+
+// What a file that ran with -version and did not answer as ffmpeg did:
+// the first line it printed, on its error output, where a program says
+// what is wrong, else on its output, then how it ended. ffmpeg prints its
+// version on its output, so a program that ended well printing only on its
+// error output is said to.
+function answered(r) {
+  const ended = r.signal ? `was stopped by ${r.signal}` : `exited with ${r.code}`;
+  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`;
+  if (line || firstLine(r.stdout)) return `it printed ${quoted(line || firstLine(r.stdout))} and ${ended}`;
+  return r.signal ? `it was stopped by ${r.signal}` : `it printed nothing and exited with ${r.code}`;
+}
+
+// An error for an ffmpeg that could not be used, marked, so what reads
+// ffmpeg's words of a failure leaves it as it is.
+const unusable = (message, more) => Object.assign(new Error(message), { unstarted: true }, more);
+
+// The error for the ffmpeg at `file`, with `words` that say what happened
+// there: by FFMPEG_PATH when it gives a path, else as the one on PATH, and
+// how to get an ffmpeg or point to one.
+function needs(file, words) {
+  const program = ffmpegPath();
+  const how = process.env.FFMPEG_PATH ? `Set FFMPEG_PATH to an ffmpeg, or unset it and install one (${INSTALL}).` : `Install ffmpeg (${INSTALL}) or set FFMPEG_PATH to one.`;
+  if (path.basename(program) !== program) return `musicfit needs ffmpeg, and FFMPEG_PATH points to ${file}, ${words.startsWith("where ") ? words : `which ${words}`}. ${how}`;
+  return `musicfit needs ffmpeg, and the ${program} on PATH, ${file}, ${words}. ${how}`;
+}
+
+// What `file` did when run with -version, as { code, signal, stdout,
+// stderr }; { late: true } when it gave no answer in `limit` milliseconds
+// and was stopped; { err } when the system did not start it.
+function version(file, limit) {
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = spawn(file, ["-version"], { stdio: ["ignore", "pipe", "pipe"] });
+    } catch (err) {
+      resolve({ err });
+      return;
+    }
+    running.add(child);
+    let timer = null;
+    const end = (result) => {
+      clearTimeout(timer);
+      running.delete(child);
+      resolve(result);
+    };
+    child.on("error", (err) => end({ err }));
+    // With no file descriptor left Node makes no pipes, and says so 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 >= 1 << 16) 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(() => {
+      child.kill("SIGKILL");
+      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") }));
+  });
+}
+
+// The ffmpeg every call runs, as a path, found before any work as the
+// system finds it: the path FFMPEG_PATH gives, or the first file on PATH
+// the system would start (see places()), past what it passes over (see
+// barred() and PASSED), and run once with -version. It is taken only when
+// it exits with 0 and prints a line that starts with "ffmpeg version";
+// else the run stops, with what the system said or the first line the
+// program printed (see needs()). When the system finds none after a file
+// it passed over, the first such file is named. One that gives no answer
+// in time may be ffmpeg on a machine short of memory as well as a program
+// that is not, so nothing more is said of it.
+async function find(limit) {
+  const program = ffmpegPath();
+  let passed = null;
+  let none = null;
+  for (const file of places(program)) {
+    let seen = barred(file);
+    if (!seen) {
+      const r = await version(file, limit);
+      if (r.err && Object.hasOwn(SHORT, r.err.code)) throw unusable(`musicfit could not start ffmpeg: ${SHORT[r.err.code]}.`);
+      if (r.late) throw unusable(`musicfit could not check ffmpeg, ${file}: it gave no answer in ${limit / 1000} s when asked its version, as on a machine short of memory. Run it again.`);
+      if (!r.err && r.code === 0 && /^ffmpeg version\b/m.test(r.stdout)) return file;
+      seen = { on: r.err && PASSED.has(r.err.code) ? "passes" : "stops", words: `did not run as ffmpeg: ${r.err ? unstartable(file, r.err) : answered(r)}`, signal: r.signal };
+    }
+    if (seen.on === "stops") throw unusable(needs(file, seen.words), { stopped: Boolean(seen.signal) });
+    if (seen.on === "quietly") none = none || seen;
+    else passed = passed || { file, words: seen.words };
+  }
+  if (passed) throw unusable(needs(passed.file, passed.words));
+  if (path.basename(program) !== program) throw unusable(needs(program, none ? none.words : "where there is none"));
+  if (process.env.FFMPEG_PATH) throw unusable(`musicfit needs ffmpeg, and FFMPEG_PATH names ${program}, which is not on PATH. Set FFMPEG_PATH to an ffmpeg, or unset it and install one (${INSTALL}).`);
+  throw unusable(`musicfit needs ffmpeg. Install it (${INSTALL}) or set FFMPEG_PATH to it.`);
+}
+
+// The ffmpeg found for the FFMPEG_PATH, the PATH and the folder musicfit
+// runs with now, found once for them (see find()). A failure is not kept,
+// so a later call looks again.
+let found = null;
+
+function ready(limit = 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.FFMPEG_PATH, pathEntries().entries, here]);
+  if (found && found.key === key) return found.file;
+  const file = find(limit);
+  found = { key, file };
+  file.catch(() => {
+    if (found && found.file === file) found = null;
+  });
+  return file;
+}
+
+// Whether a call can run in a folder: a start that fails there for want of
+// the folder is no fault of ffmpeg's.
+function enterable(folder) {
+  try {
+    fs.accessSync(folder, fs.constants.X_OK);
+    return fs.statSync(folder).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
 // What ffmpeg prints once it has given up, after the line that says why:
 // how it stopped, which says nothing of the cause. ffmpeg 4.4 ends with the
 // first five, newer ones with the others.
@@ -70,6 +394,11 @@ const CLOSING = [
   /^Error muxing a packet$/,
   /^Task finished with error code/,
   /^Terminating thread with return code/,
+  // The report of what it wrote, which ffmpeg prints at -v info at the end
+  // of a run, a failed one too: "video:0kB audio:0kB ..." in 4.4 and
+  // "video:0KiB audio:0KiB ..." in newer ones. Its "muxing overhead:
+  // unknown" is no cause.
+  /^video:\S+ audio:\S+ /,
 ];
 // The words of a line that says what went wrong.
 const WRONG = /error|\b(invalid|unable|cannot|can't|could not|couldn't|failed|not found|no such|unknown|unrecognized|not supported|denied|no space|refused|not opened|is not|does not)\b/i;
@@ -134,25 +463,42 @@ function stopChildren() {
 
 // Runs ffmpeg with `args`, and `input` on its stdin. `writes` is the file
 // the call writes, if any, and `cwd` the folder to run it in, if not this one.
-function run(args, input, { writes = null, cwd } = {}) {
+// The ffmpeg it runs is found and asked its version before the first call
+// (see ready()), so one that cannot be used stops the run before any work.
+function run(args, input, options = {}) {
+  return ready().then((file) => call(file, args, input, options));
+}
+
+function call(file, args, input, { writes = null, cwd } = {}) {
   return new Promise((resolve, reject) => {
+    // The system short of something to start it with, the folder of the
+    // call gone, which is no fault of ffmpeg's, or an ffmpeg that ran when
+    // the run began and cannot be started now, as when it was removed or
+    // changed since.
+    const failed = (error) => {
+      if (Object.hasOwn(SHORT, error.code)) reject(unusable(`musicfit could not start ffmpeg: ${SHORT[error.code]}.`));
+      else if (cwd && !enterable(cwd)) reject(error);
+      else reject(unusable(`musicfit could not start ffmpeg, ${file}, again: ${worded(error)}. Check that it is still there and may be run, and run musicfit again.`));
+    };
     let child;
     try {
-      child = spawn(ffmpegPath(), ["-hide_banner", ...(input ? [] : ["-nostdin"]), ...args], { cwd, env: cwd ? fromHere() : process.env, stdio: [input ? "pipe" : "ignore", "pipe", "pipe"] });
+      child = spawn(file, ["-hide_banner", ...(input ? [] : ["-nostdin"]), ...args], { cwd, env: cwd ? fromHere() : process.env, stdio: [input ? "pipe" : "ignore", "pipe", "pipe"] });
     } catch (err) {
-      reject(err);
+      failed(err);
       return;
     }
     running.add(child);
+    child.on("error", (error) => {
+      running.delete(child);
+      failed(error);
+    });
+    // With no file descriptor left Node makes no pipes, and says so a moment
+    // later.
+    if (!child.stdout || !child.stderr) return;
     const out = [];
     const err = [];
     child.stdout.on("data", (chunk) => out.push(chunk));
     child.stderr.on("data", (chunk) => err.push(chunk));
-    child.on("error", (error) => {
-      running.delete(child);
-      if (error.code === "ENOENT" && !cwd) reject(new Error("musicfit needs ffmpeg. Install it (brew install ffmpeg, sudo apt install ffmpeg or winget install ffmpeg) or set FFMPEG_PATH to it."));
-      else reject(error);
-    });
     child.on("close", (code, signal) => {
       running.delete(child);
       const stderr = Buffer.concat(err).toString("utf8");
@@ -232,10 +578,11 @@ async function decode(file, { rate = RATE, channels = 2, from = null, stream = 0
     if (!samples.length) throw new Error(`${file} has no audio`);
     return samples;
   } catch (err) {
+    if (err.unstarted) throw err;
     // ffmpeg says why early and sums up last, so all it said is searched.
     const said = err.stderr || err.message;
     if (/matches no streams/.test(said)) throw new Error(`${file} has no audio stream`);
-    if (/No such file|does not exist/.test(said)) throw new Error(`Cannot read ${file}: no such file`);
+    if (/No such file|does not exist/.test(said) && gone(file)) throw new Error(`Cannot read ${file}: no such file`);
     if (/Invalid data found/.test(said)) throw new Error(`Cannot read ${file}: ffmpeg does not know this format`);
     throw err;
   }
@@ -280,4 +627,4 @@ async function measureFile(file) {
   return summary(stderr);
 }
 
-module.exports = { RATE, decode, encodeWav, fromHere, measure, measureFile, run, reason, stopChildren, where };
+module.exports = { RATE, decode, encodeWav, fromHere, gone, measure, measureFile, quoted, ready, run, reason, stopChildren, where };

package/skills/musicfit/scripts/lib/fit.js

@@ -8,7 +8,7 @@
 const fs = require("node:fs");
 const path = require("node:path");
 const crypto = require("node:crypto");
-const { RATE, decode, encodeWav, measure, measureFile } = require("./audio");
+const { RATE, decode, encodeWav, measure, measureFile, ready } = require("./audio");
 const { probe, fits, ownSound, encodeAac, mux, mark, fpsText } = require("./video");
 const { RATE: ANALYSIS_RATE } = require("./analyze");
 const { analyzeInThread } = require("./thread");
@@ -110,6 +110,9 @@ async function fit(track, options) {
   // Begun first, so a stop while it waits for another run in that folder is said.
   const run = begin(dir);
   try {
+    // An ffmpeg that cannot be used stops the run before it looks at the
+    // out folder.
+    await ready();
     await claim(dir, writes, [track, options.voice, options.video]);
     const o = { ...options, warnings: [...(options.warnings || [])] };
     // The video is read before any work, so one that cannot take this fit

package/skills/musicfit/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.2.0";
+module.exports = "0.2.2";

package/skills/musicfit/scripts/lib/video.js

@@ -13,7 +13,7 @@
 
 const fs = require("node:fs");
 const path = require("node:path");
-const { RATE, run, decode, where } = require("./audio");
+const { RATE, run, decode, gone, where } = require("./audio");
 const { blocks } = require("./breathe");
 
 const num = (x, digits) => String(Number(x.toFixed(digits)));
@@ -90,8 +90,9 @@ async function probe(file) {
     crc = Buffer.concat(chunks).toString("utf8");
     said = stderr;
   } catch (err) {
+    if (err.unstarted) throw err;
     const why = err.stderr || err.message;
-    if (/No such file|does not exist/.test(why)) throw new Error(`Cannot read ${file}: no such file`);
+    if (/No such file|does not exist/.test(why) && gone(file)) throw new Error(`Cannot read ${file}: no such file`);
     // An MP4 or a MOV that stops before its index or inside it, as one whose
     // recording or download was cut off; a file ffmpeg only guessed was one
     // is not.
@@ -279,7 +280,7 @@ async function mux(file, sound, out, { picture, comment, start }) {
     const { stderr } = await run(["-v", "error", "-i", name, "-map", "0", "-c", "copy", "-f", "null", "-"], null, { cwd: path.dirname(out) });
     if (DAMAGED.some((line) => line.test(stderr))) why = "it is cut short";
   } catch (err) {
-    if (err.stopped) throw err;
+    if (err.stopped || err.unstarted) throw err;
     why = err.message.replace(/^ffmpeg: /, "").split(`${name}: `).join("");
   }
   if (why) throw new Error(`The video.mp4 this run wrote cannot be read back (${why}), so it was not put in place`);