Skip to content

Write HTML. Render video. Built for agents.

fix(media-use): honour HYPERFRAMES_PYTHON in the audio engine (#4614) (#4723)

Poetry Of Codef1b79d8e7bdb
diff --git a/skills-manifest.json b/skills-manifest.json
index 27cc9fe3c6..83d6b79b6c 100644
--- a/skills-manifest.json
+++ b/skills-manifest.json
@@ -54,7 +54,7 @@
"files": 1
},
"media-use": {
- "hash": "0744050e3114e60a",
+ "hash": "bf88c1a47da67cfa",
"files": 104
},
"motion-graphics": {
diff --git a/skills/media-use/audio/scripts/lib/python.mjs b/skills/media-use/audio/scripts/lib/python.mjs
index a11c0151ce..f5cd7fe6c7 100644
--- a/skills/media-use/audio/scripts/lib/python.mjs
+++ b/skills/media-use/audio/scripts/lib/python.mjs
@@ -11,12 +11,20 @@
// Resolve once, per process: probe the platform's candidates in order and take
// the first that actually runs. `py` is the launcher, so it needs a `-3` arg to
// select Python 3 — hence candidates are argv PREFIXES, not bare names.
+//
+// `HYPERFRAMES_PYTHON` (the documented PEP 668 venv setup) wins over the PATH probe, matching
+// the CLI's `findPython()`; ignoring it made BGM silently disable itself (#4614).
import { spawnSync } from "node:child_process";
-function defaultProbe(cmd, args) {
+// Accept only an interpreter whose `--version` reports Python 3, as the CLI's
+// `validatePythonOverride()` does. Exit status alone would take a Python 2
+// `python` (or any executable that exits 0) that `doctor` rejects. Python 2
+// prints its version to stderr, so read both streams.
+export function defaultProbe(cmd, args) {
try {
- return spawnSync(cmd, args, { stdio: "ignore" }).status === 0;
+ const result = spawnSync(cmd, args, { encoding: "utf-8", timeout: 5000 });
+ return result.status === 0 && /Python 3/.test(`${result.stdout}${result.stderr}`);
} catch {
return false;
}
@@ -26,12 +34,18 @@ function defaultProbe(cmd, args) {
* Pick the argv prefix that launches Python 3 on this platform.
* Returns e.g. `["python3"]`, `["python"]`, or `["py", "-3"]`.
*
- * Pure except for `probe` (which runs `<cmd> … --version`); both `platform`
- * and `probe` are injectable so every branch is unit-testable without spawning.
+ * Pure except for `probe` (which runs `<cmd> … --version`); `platform`, `probe`
+ * and `env` are injectable so every branch is unit-testable without spawning.
* If nothing probes OK, falls back to the canonical name for the platform so
* the eventual spawn fails loudly exactly as it did before — never worse.
*/
-export function resolvePythonCommand(platform = process.platform, probe = defaultProbe) {
+export function resolvePythonCommand(
+ platform = process.platform,
+ probe = defaultProbe,
+ env = process.env,
+) {
+ const override = env.HYPERFRAMES_PYTHON;
+ if (override && probe(override, ["--version"])) return [override];
const candidates =
platform === "win32" ? [["python3"], ["python"], ["py", "-3"]] : [["python3"], ["python"]];
for (const prefix of candidates) {
diff --git a/skills/media-use/audio/scripts/lib/python.test.mjs b/skills/media-use/audio/scripts/lib/python.test.mjs
index 4598d02e03..babea4efc6 100644
--- a/skills/media-use/audio/scripts/lib/python.test.mjs
+++ b/skills/media-use/audio/scripts/lib/python.test.mjs
@@ -1,6 +1,9 @@
import { test } from "node:test";
import assert from "node:assert/strict";
-import { resolvePythonCommand, pythonInvocation } from "./python.mjs";
+import { chmodSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { defaultProbe, resolvePythonCommand, pythonInvocation } from "./python.mjs";
// Regression: on Windows a standard python.org install has no `python3.exe`
// (only `python.exe` + the `py` launcher), so `spawn("python3", …)` ENOENTs and
@@ -55,6 +58,71 @@ test("falls back to the canonical name (loud failure, unchanged) when nothing ru
);
});
+// Regression (#4614): on PEP 668 systems the documented setup is a venv named
+// by HYPERFRAMES_PYTHON; the audio engine ignored it and probed the bare
+// system python3, so MusicGen BGM was skipped while `doctor` said installed.
+const VENV = "/home/u/.venvs/hf/bin/python";
+
+test("HYPERFRAMES_PYTHON wins over python3 on PATH when it runs", () => {
+ const env = { HYPERFRAMES_PYTHON: VENV };
+ assert.deepEqual(resolvePythonCommand("darwin", probeFor(VENV, "python3"), env), [VENV]);
+ assert.deepEqual(resolvePythonCommand("win32", probeFor(VENV, "python", "py"), env), [VENV]);
+});
+
+test("a HYPERFRAMES_PYTHON that doesn't run falls through to the PATH probe", () => {
+ const env = { HYPERFRAMES_PYTHON: "/nope/python" };
+ assert.deepEqual(resolvePythonCommand("linux", probeFor("python3"), env), ["python3"]);
+});
+
+test("an empty HYPERFRAMES_PYTHON is ignored without being probed", () => {
+ const seen = [];
+ const probe = (cmd) => {
+ seen.push(cmd);
+ return cmd === "python3";
+ };
+ assert.deepEqual(resolvePythonCommand("linux", probe, { HYPERFRAMES_PYTHON: "" }), ["python3"]);
+ assert.deepEqual(seen, ["python3"]);
+});
+
+// defaultProbe must match the CLI's validatePythonOverride(): exiting 0 is not
+// enough, `--version` has to report Python 3. Stubs are shell scripts, so
+// these run on POSIX only.
+function withStub(script, fn) {
+ const dir = mkdtempSync(join(tmpdir(), "hf-python-probe-"));
+ try {
+ const stub = join(dir, "python");
+ writeFileSync(stub, `#!/bin/sh\n${script}\n`);
+ chmodSync(stub, 0o755);
+ fn(stub);
+ } finally {
+ rmSync(dir, { recursive: true, force: true });
+ }
+}
+
+const posixOnly = { skip: process.platform === "win32" && "stub scripts need a POSIX shell" };
+
+test("defaultProbe accepts an interpreter reporting Python 3", posixOnly, () => {
+ withStub('echo "Python 3.12.4"', (stub) => assert.equal(defaultProbe(stub, ["--version"]), true));
+});
+
+test("defaultProbe rejects Python 2, which prints its version to stderr", posixOnly, () => {
+ withStub('echo "Python 2.7.18" >&2', (stub) =>
+ assert.equal(defaultProbe(stub, ["--version"]), false),
+ );
+});
+
+test(
+ "defaultProbe rejects an executable that exits 0 without a Python 3 version",
+ posixOnly,
+ () => {
+ withStub("exit 0", (stub) => assert.equal(defaultProbe(stub, ["--version"]), false));
+ },
+);
+
+test("defaultProbe rejects a command that doesn't exist", () => {
+ assert.equal(defaultProbe("/nonexistent/hf-python", ["--version"]), false);
+});
+
test("pythonInvocation prepends the resolved prefix ahead of caller args", () => {
assert.deepEqual(pythonInvocation(["-c", "import x"], ["python"]), {
cmd: "python",