From 25c60352128c9bd882eec3e770b933ca6046646c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Miguel=20=C3=81ngel?= Date: Mon, 16 Nov 2026 05:52:09 +0000 Subject: [PATCH] fix(media-use): carve runs its own copy of core's analysis, never the project's (#7926) * fix(media-use): carve runs its own copy of core's analysis, never the project's carve.mjs loaded @hyperframes/core from the composition's own node_modules, so carving a project ran whatever that project shipped under that name. It now imports a bundle of core's carve and audio-fx functions generated beside it, with a test that fails when the bundle drifts from core's source. * fix(media-use): lint and format skip the carve bundle on the CLI path too --- .oxlintrc.json | 4 +- .prettierignore | 3 + package.json | 2 +- ...k-media-use-audio-carve-generated.test.mjs | 21 +++++ scripts/generate-media-use-audio-carve.mjs | 60 ++++++++++++ skills-manifest.json | 4 +- skills/media-use/audio/scripts/carve.mjs | 92 ++----------------- skills/media-use/audio/scripts/carve.test.mjs | 53 ++++++----- .../audio/scripts/lib/audio-carve.mjs | 4 + skills/media-use/references/mixing.md | 2 +- 10 files changed, 136 insertions(+), 109 deletions(-) create mode 100644 scripts/check-media-use-audio-carve-generated.test.mjs create mode 100644 scripts/generate-media-use-audio-carve.mjs create mode 100644 skills/media-use/audio/scripts/lib/audio-carve.mjs diff --git a/.oxlintrc.json b/.oxlintrc.json index 3f9314a4ba..7c4d560f32 100644 --- a/.oxlintrc.json +++ b/.oxlintrc.json @@ -17,7 +17,9 @@ "registry/blocks/frost-sequence-camera-orbit/source/**", "registry/examples/path-traced-3d/assets/vendor/*.min.js", "chrome/", - "packages/cli/src/media-use/lib/svg-sanitize.mjs" + "packages/cli/src/media-use/lib/svg-sanitize.mjs", + "skills/media-use/audio/scripts/lib/audio-carve.mjs", + "packages/cli/src/audio/scripts/lib/audio-carve.mjs" ], "overrides": [ { diff --git a/.prettierignore b/.prettierignore index aad5f080f6..ac2d650fd5 100644 --- a/.prettierignore +++ b/.prettierignore @@ -59,3 +59,6 @@ skills/slideshow/SKILL.md skills/remotion-to-hyperframes/SKILL.md skills/reverse-any-video/SKILL.md skills/style-sampling/SKILL.md +# scripts/generate-media-use-audio-carve.mjs — never hand-edit or reformat. +skills/media-use/audio/scripts/lib/audio-carve.mjs +packages/cli/src/audio/scripts/lib/audio-carve.mjs diff --git a/package.json b/package.json index 718c680065..ab8705ba45 100644 --- a/package.json +++ b/package.json @@ -57,7 +57,7 @@ "player:perf": "bun run --filter @hyperframes/player perf", "format:check": "oxfmt --check .", "knip": "knip", - "test:scripts": "node --import tsx --test scripts/animejs-v4-guidance.test.mjs scripts/check-tracked-artifacts.test.mjs scripts/check-committed-keys.test.mjs scripts/check-symlinks.test.mjs scripts/upload-docs-images.test.mjs scripts/check-registry-set-delta.test.mjs scripts/check-no-main-deletions.test.mjs scripts/check-pr-captures.test.mjs scripts/check-comment-citations.test.mjs scripts/comments-workflow.test.mjs scripts/comment-ratchet.test.mjs scripts/check-docs-snippet-motion.test.mjs scripts/registry-target-paths.test.mjs scripts/check-workspace-contracts.test.mjs scripts/check-media-use-copy-parity.test.mjs scripts/check-svg-sanitize-parity.test.mjs scripts/check-media-use-svg-sanitize-generated.test.mjs scripts/check-package-cycles.test.mjs scripts/check-cli-process-ownership.test.mjs scripts/check-cli-lazy-deps.test.mjs scripts/file-url-paths.test.mjs scripts/check-studio-copy-dashes.test.mjs scripts/check-large-files.test.mjs scripts/check-registry-innerhtml.test.mjs scripts/package-subpaths.test.mjs scripts/validate-release-channel.test.mjs scripts/clawhub-sync.test.mjs scripts/clawhub-unlist-retired.test.mjs scripts/publish-workflow.test.mjs scripts/release-lambda-assets.test.mjs scripts/publish-main-only-workflows.test.mjs scripts/pr-edit-concurrency.test.mjs scripts/merge-queue-workflows.test.mjs scripts/ci-cache-workflows.test.mjs scripts/install-workspace-dependencies.test.mjs scripts/check-edit-accuracy-filter.test.mjs scripts/edit-accuracy-retry.test.mjs scripts/draft-changelog.test.ts scripts/set-version.test.ts scripts/release-prepare.test.ts scripts/cli-options.test.ts scripts/changelog-weekly.test.ts scripts/claude-plugin-compression.test.ts scripts/catalog-payload-assets.test.ts scripts/host-registry-assets.test.ts scripts/catalog-preview-temp.test.ts scripts/backfill-block-previews.test.ts scripts/catalog-hosted-files.test.ts scripts/player-cdn-pin.test.ts scripts/registry-cdn-pins.test.ts scripts/studio-runtime-smoke.test.mjs scripts/verify-packed-manifests.test.mjs scripts/rewrite-relative-import-extensions.test.mjs scripts/lint-skills.test.mjs scripts/check-core-skills.test.mjs scripts/creator-editing-recipes.test.mjs packages/gcp-cloud-run/check-dockerfile-workspaces.test.mjs packages/core/scripts/writeGeneratedFile.test.ts scripts/catalog-publication.test.mjs scripts/ci/resolve-workflow-pr.test.mjs scripts/lefthook-order.test.mjs scripts/inline-gsap.test.mjs scripts/ci/flake-gate.test.mjs scripts/ci/motion-blur-nightly-report.test.mjs scripts/ci/base-file.test.mjs scripts/ci/release-only-diff.test.mjs scripts/check-catalog-source-pr.test.mjs scripts/generate-registry-items.test.ts scripts/catalog-drift.test.ts scripts/catalog-fetch-mirror.test.ts scripts/catalog-script-inlining.test.ts scripts/catalog-detail.test.ts scripts/generate-catalog-pages.test.ts scripts/verify-catalog-payloads.test.ts scripts/registry-theme-fallbacks.test.ts scripts/registry-skill-files.test.ts scripts/creator-editing-capabilities.test.mjs scripts/generate-catalog-previews.test.ts scripts/registry-primitive-payloads.test.ts registry/components/pan-stations/pan-stations.test.mjs registry/components/filmed-screen/filmed-screen.test.mjs registry/components/echo-smear/echo-smear.test.mjs registry/examples/path-traced-3d/source/path-traced-3d.test.mjs && vitest run scripts/catalog/ scripts/contrastRatchet.test.ts scripts/generate-catalog-payloads.test.ts", + "test:scripts": "node --import tsx --test scripts/animejs-v4-guidance.test.mjs scripts/check-tracked-artifacts.test.mjs scripts/check-committed-keys.test.mjs scripts/check-symlinks.test.mjs scripts/upload-docs-images.test.mjs scripts/check-registry-set-delta.test.mjs scripts/check-no-main-deletions.test.mjs scripts/check-pr-captures.test.mjs scripts/check-comment-citations.test.mjs scripts/comments-workflow.test.mjs scripts/comment-ratchet.test.mjs scripts/check-docs-snippet-motion.test.mjs scripts/registry-target-paths.test.mjs scripts/check-workspace-contracts.test.mjs scripts/check-media-use-copy-parity.test.mjs scripts/check-svg-sanitize-parity.test.mjs scripts/check-media-use-svg-sanitize-generated.test.mjs scripts/check-media-use-audio-carve-generated.test.mjs scripts/check-package-cycles.test.mjs scripts/check-cli-process-ownership.test.mjs scripts/check-cli-lazy-deps.test.mjs scripts/file-url-paths.test.mjs scripts/check-studio-copy-dashes.test.mjs scripts/check-large-files.test.mjs scripts/check-registry-innerhtml.test.mjs scripts/package-subpaths.test.mjs scripts/validate-release-channel.test.mjs scripts/clawhub-sync.test.mjs scripts/clawhub-unlist-retired.test.mjs scripts/publish-workflow.test.mjs scripts/release-lambda-assets.test.mjs scripts/publish-main-only-workflows.test.mjs scripts/pr-edit-concurrency.test.mjs scripts/merge-queue-workflows.test.mjs scripts/ci-cache-workflows.test.mjs scripts/install-workspace-dependencies.test.mjs scripts/check-edit-accuracy-filter.test.mjs scripts/edit-accuracy-retry.test.mjs scripts/draft-changelog.test.ts scripts/set-version.test.ts scripts/release-prepare.test.ts scripts/cli-options.test.ts scripts/changelog-weekly.test.ts scripts/claude-plugin-compression.test.ts scripts/catalog-payload-assets.test.ts scripts/host-registry-assets.test.ts scripts/catalog-preview-temp.test.ts scripts/backfill-block-previews.test.ts scripts/catalog-hosted-files.test.ts scripts/player-cdn-pin.test.ts scripts/registry-cdn-pins.test.ts scripts/studio-runtime-smoke.test.mjs scripts/verify-packed-manifests.test.mjs scripts/rewrite-relative-import-extensions.test.mjs scripts/lint-skills.test.mjs scripts/check-core-skills.test.mjs scripts/creator-editing-recipes.test.mjs packages/gcp-cloud-run/check-dockerfile-workspaces.test.mjs packages/core/scripts/writeGeneratedFile.test.ts scripts/catalog-publication.test.mjs scripts/ci/resolve-workflow-pr.test.mjs scripts/lefthook-order.test.mjs scripts/inline-gsap.test.mjs scripts/ci/flake-gate.test.mjs scripts/ci/motion-blur-nightly-report.test.mjs scripts/ci/base-file.test.mjs scripts/ci/release-only-diff.test.mjs scripts/check-catalog-source-pr.test.mjs scripts/generate-registry-items.test.ts scripts/catalog-drift.test.ts scripts/catalog-fetch-mirror.test.ts scripts/catalog-script-inlining.test.ts scripts/catalog-detail.test.ts scripts/generate-catalog-pages.test.ts scripts/verify-catalog-payloads.test.ts scripts/registry-theme-fallbacks.test.ts scripts/registry-skill-files.test.ts scripts/creator-editing-capabilities.test.mjs scripts/generate-catalog-previews.test.ts scripts/registry-primitive-payloads.test.ts registry/components/pan-stations/pan-stations.test.mjs registry/components/filmed-screen/filmed-screen.test.mjs registry/components/echo-smear/echo-smear.test.mjs registry/examples/path-traced-3d/source/path-traced-3d.test.mjs && vitest run scripts/catalog/ scripts/contrastRatchet.test.ts scripts/generate-catalog-payloads.test.ts", "typecheck:scripts": "tsc --noEmit -p scripts/tsconfig.json", "test:skills": "HYPERFRAMES_MEDIA_HOME_REQUIRED=1 node --import ./packages/cli/scripts/test-home.mjs --test 'skills/**/*.test.mjs' 'packages/cli/src/media-use/**/*.test.mjs'", "generate:previews": "tsx scripts/generate-template-previews.ts", diff --git a/scripts/check-media-use-audio-carve-generated.test.mjs b/scripts/check-media-use-audio-carve-generated.test.mjs new file mode 100644 index 0000000000..9c9747e24a --- /dev/null +++ b/scripts/check-media-use-audio-carve-generated.test.mjs @@ -0,0 +1,21 @@ +import assert from "node:assert/strict"; +import { readFileSync } from "node:fs"; +import { resolve } from "node:path"; +import { describe, it } from "node:test"; +import { generate } from "./generate-media-use-audio-carve.mjs"; + +// The carve analysis lives in packages/core/src/audioCarve.ts and audioFx.ts; the skill's copy is a generated +// bundle. This trips on a hand edit of the bundle or a source change that was not regenerated. +describe("media-use audio-carve.mjs matches a fresh regeneration", () => { + it("is byte-identical to `node scripts/generate-media-use-audio-carve.mjs`", async () => { + const committed = readFileSync( + resolve(import.meta.dirname, "../skills/media-use/audio/scripts/lib/audio-carve.mjs"), + "utf8", + ); + assert.equal( + committed, + await generate(), + "skills/media-use/audio/scripts/lib/audio-carve.mjs is stale. Run: node scripts/generate-media-use-audio-carve.mjs", + ); + }); +}); diff --git a/scripts/generate-media-use-audio-carve.mjs b/scripts/generate-media-use-audio-carve.mjs new file mode 100644 index 0000000000..98bf3d23c1 --- /dev/null +++ b/scripts/generate-media-use-audio-carve.mjs @@ -0,0 +1,60 @@ +#!/usr/bin/env node +// Bundles the carve analysis carve.mjs uses (packages/core/src/audioCarve.ts and audioFx.ts) into a single +// import-free .mjs beside the skill, so the skill never loads @hyperframes/core from the project it edits. +// Regenerate after editing the source: node scripts/generate-media-use-audio-carve.mjs +import { writeFileSync } from "node:fs"; +import { fileURLToPath } from "node:url"; +import { dirname, resolve } from "node:path"; + +const here = dirname(fileURLToPath(import.meta.url)); +const CORE_SRC = resolve(here, "../packages/core/src"); +const OUTFILE = resolve(here, "../skills/media-use/audio/scripts/lib/audio-carve.mjs"); +// scripts/ has no node_modules of its own (bun's per-consumer linking); reach into the one +// package that already depends on esbuild rather than adding a root-level dependency. +const { build } = await import(resolve(here, "../packages/core/node_modules/esbuild/lib/main.js")); + +const ENTRY = `export { + analyseCarveBands, + analyseCarveDuck, + carveBandsToChain, + carveProfile, + classifyAudioName, + clipsOverlap, + mixCarveSources, +} from "./audioCarve.ts"; +export { + defaultAudioFxParams, + mintAudioFxNodeId, + parseAudioFxChain, + serializeAudioFxChain, +} from "./audioFx.ts"; +`; + +const HEADER = `// GENERATED: do not hand-edit. Source: packages/core/src/audioCarve.ts and audioFx.ts, bundled by +// scripts/generate-media-use-audio-carve.mjs so carve.mjs runs the same analysis as Studio without +// loading @hyperframes/core from the project. Regenerate: node scripts/generate-media-use-audio-carve.mjs +`; + +export async function generate() { + const result = await build({ + stdin: { + contents: ENTRY, + resolveDir: CORE_SRC, + loader: "ts", + sourcefile: "audio-carve-entry.ts", + }, + bundle: true, + format: "esm", + platform: "node", + write: false, + minify: true, + legalComments: "none", + }); + return HEADER + result.outputFiles[0].text; +} + +if (import.meta.url === `file://${process.argv[1]}`) { + const code = await generate(); + writeFileSync(OUTFILE, code); + console.log(`wrote ${OUTFILE} (${code.length} bytes)`); +} diff --git a/skills-manifest.json b/skills-manifest.json index beaeb4a947..3df3068823 100644 --- a/skills-manifest.json +++ b/skills-manifest.json @@ -18,8 +18,8 @@ "files": 13 }, "media-use": { - "hash": "71ce3fd61360ec79", - "files": 127 + "hash": "bffe3f288782b86a", + "files": 128 }, "remotion-to-hyperframes": { "hash": "e7982839c333759e", diff --git a/skills/media-use/audio/scripts/carve.mjs b/skills/media-use/audio/scripts/carve.mjs index c672f27880..ee2832019f 100644 --- a/skills/media-use/audio/scripts/carve.mjs +++ b/skills/media-use/audio/scripts/carve.mjs @@ -18,18 +18,16 @@ * voice is analysed together, so a bed running under a narrator and an answer makes * room for both. * - * Needs `ffmpeg` on PATH (to decode the audio) and `@hyperframes/core` resolvable - * from the composition's project (`npm i -D @hyperframes/core`) — the CLI bundles - * core inline rather than shipping it as a package, so it cannot be borrowed from - * there. + * Needs `ffmpeg` on PATH (to decode the audio). The analysis ships beside this + * script (`lib/audio-carve.mjs`, generated from core), so nothing in the + * composition's project is loaded. */ import "../../scripts/lib/windows-exe-search.mjs"; import { execFileSync } from "node:child_process"; -import { createRequire } from "node:module"; import { readFileSync, writeFileSync } from "node:fs"; import { dirname, resolve } from "node:path"; -import { pathToFileURL } from "node:url"; +import * as carveApi from "./lib/audio-carve.mjs"; import { isMainModule } from "./lib/main-module.mjs"; /** Sample rate the analysis runs at. Matches Studio's own decode rate, so the @@ -40,13 +38,12 @@ const SAMPLE_RATE = 48000; export const DEFAULT_STRENGTH = 0.8; const usage = `carve.mjs --comp [--bed ] [--voice ...] - [--strength 0..1] [--dry-run] [--core ] + [--strength 0..1] [--dry-run] --bed id of the music track that gets carved (detected if omitted) --voice id of a voice to make room for; repeatable (detected if omitted) --strength how hard to carve, 0..1 (default ${DEFAULT_STRENGTH}) - --dry-run report what it would write, touch nothing - --core directory to resolve @hyperframes/core from (default: the comp's)`; + --dry-run report what it would write, touch nothing`; export function parseArgs(argv) { const args = { strength: DEFAULT_STRENGTH, dryRun: false, voices: [] }; @@ -62,7 +59,6 @@ export function parseArgs(argv) { else if (flag === "--bed") args.bed = next(); else if (flag === "--voice") args.voices.push(next()); else if (flag === "--strength") args.strength = Number(next()); - else if (flag === "--core") args.core = next(); else if (flag === "--dry-run") args.dryRun = true; else if (flag === "-h" || flag === "--help") fail(usage, 0); else fail(`unknown flag: ${flag}\n\n${usage}`); @@ -79,73 +75,6 @@ function fail(message, code = 1) { process.exit(code); } -/** - * Load the carve analysis out of `@hyperframes/core`. - * - * Resolved from the project rather than from this script, which lives wherever - * the skill was installed — a sibling of the composition is what has the - * dependency. - */ -export async function loadCore(fromDir) { - const require = createRequire(pathToFileURL(resolve(fromDir, "package.json"))); - - /* - * Two constraints at once, and satisfying either alone is broken: - * - * 1. Anchored at the PROJECT, not at this script. This file lives wherever - * the skill was installed, which has no @hyperframes/core; the - * composition's project is what holds the dependency. So a bare - * `import("@hyperframes/core/audio-carve")` from here cannot work — bare - * specifiers resolve relative to the importing module. - * 2. Honouring the package's export CONDITIONS. `require.resolve` asks for - * "require"/"node". The workspace manifest declares `node`, so this - * resolved fine inside the monorepo — but the PUBLISHED manifest carries - * only `import` + `types`, so every consumer of the released package got - * ERR_PACKAGE_PATH_NOT_EXPORTED for a package that ships the file. That - * is the audience this skill is shipped to, so the script was broken - * everywhere except where it was developed. - * - * Keep the project anchor; fall back to the package's declared `import` - * target when no require-resolvable condition exists. - */ - const load = async (subpath) => { - const spec = `@hyperframes/core/${subpath}`; - try { - return await import(pathToFileURL(require.resolve(spec)).href); - } catch (error) { - if (error?.code !== "ERR_PACKAGE_PATH_NOT_EXPORTED") throw error; - // `./package.json` is exported by every manifest, so this always resolves - // and gives us the package root without guessing at node_modules layout. - const pkgPath = require.resolve("@hyperframes/core/package.json"); - const pkg = JSON.parse(readFileSync(pkgPath, "utf-8")); - const entry = pkg.exports?.[`./${subpath}`]; - const target = typeof entry === "string" ? entry : (entry?.import ?? entry?.default ?? null); - if (!target) { - fail( - `@hyperframes/core does not export ./${subpath}\n` + - ` found at: ${pkgPath} (version ${pkg.version})\n` + - ` update it: npm i -D @hyperframes/core`, - ); - } - return import(pathToFileURL(resolve(dirname(pkgPath), target)).href); - } - }; - - try { - return { - carve: await load("audio-carve"), - fx: await load("audio-fx"), - }; - } catch (error) { - fail( - `cannot load @hyperframes/core from ${fromDir}\n` + - ` is it installed there? npm i -D @hyperframes/core\n` + - ` or point at one: --core \n` + - ` (${error.code ?? "error"}: ${error.message.split("\n")[0]})`, - ); - } -} - /** * The `sources` a carve should record for these voices, on this bed. * @@ -383,7 +312,6 @@ async function main() { const args = parseArgs(process.argv.slice(2)); const compPath = resolve(args.comp); const compDir = dirname(compPath); - const { carve: carveApi, fx: fxApi } = await loadCore(args.core ? resolve(args.core) : compDir); const html = readFileSync(compPath, "utf-8"); const { @@ -433,7 +361,7 @@ async function main() { // carve's own nodes are replaced. That is what `fromCarve` is for. const existingChain = attrOf(bedTag, "data-fx-chain"); const existingNodes = existingChain - ? fxApi.parseAudioFxChain(unescapeAttr(existingChain)).nodes + ? carveApi.parseAudioFxChain(unescapeAttr(existingChain)).nodes : []; const kept = existingNodes.filter((n) => !n.fromCarve); // Lanes belonging to the carve being replaced, addressed by the ids the OLD @@ -444,7 +372,7 @@ async function main() { let claimed = { version: 1, nodes: kept }; const mint = (node) => { - const withId = { ...node, id: fxApi.mintAudioFxNodeId(claimed), fromCarve: true }; + const withId = { ...node, id: carveApi.mintAudioFxNodeId(claimed), fromCarve: true }; claimed = { version: 1, nodes: [...claimed.nodes, withId] }; return withId; }; @@ -456,7 +384,7 @@ async function main() { type: "gain", enabled: true, params: { - ...fxApi.defaultAudioFxParams("gain"), + ...carveApi.defaultAudioFxParams("gain"), gain: 0, }, }) @@ -522,7 +450,7 @@ async function main() { } const written = ` data-fx-carve="${escapeAttr(JSON.stringify(settings))}"` + - ` data-fx-chain="${escapeAttr(fxApi.serializeAudioFxChain(chain))}"` + + ` data-fx-chain="${escapeAttr(carveApi.serializeAudioFxChain(chain))}"` + (lanes.length > 0 ? ` data-automation="${escapeAttr(JSON.stringify({ version: 1, lanes }))}"` : ""); diff --git a/skills/media-use/audio/scripts/carve.test.mjs b/skills/media-use/audio/scripts/carve.test.mjs index bb85137d23..338d1f1928 100644 --- a/skills/media-use/audio/scripts/carve.test.mjs +++ b/skills/media-use/audio/scripts/carve.test.mjs @@ -1,17 +1,11 @@ import assert from "node:assert/strict"; import test from "node:test"; import { execFileSync } from "node:child_process"; -import { mkdirSync, mkdtempSync, rmSync, symlinkSync, writeFileSync } from "node:fs"; +import { existsSync, mkdirSync, mkdtempSync, rmSync, symlinkSync, writeFileSync } from "node:fs"; import { tmpdir } from "node:os"; import { dirname, join } from "node:path"; import { fileURLToPath } from "node:url"; -import { - DEFAULT_STRENGTH, - carveSources, - groupSourceRefusal, - loadCore, - parseArgs, -} from "./carve.mjs"; +import { DEFAULT_STRENGTH, carveSources, groupSourceRefusal, parseArgs } from "./carve.mjs"; const SCRIPTS_DIR = dirname(fileURLToPath(import.meta.url)); @@ -202,33 +196,48 @@ test("the CLI still runs when invoked through a symlinked path", () => { }); }); -test("loadCore honours an import-only export map, as the published core has", () => { - // The published manifest carries only `import` + `types` for these subpaths, so - // `require.resolve` cannot resolve them at all and the fallback has to read the - // export map itself. A fixture pins that without depending on npm. +test("carve never loads @hyperframes/core from the composition's project", () => { + // A received project is untrusted: a core planted in its node_modules must not run. return inTempDir(async (dir) => { const pkgDir = join(dir, "node_modules", "@hyperframes", "core"); - mkdirSync(join(pkgDir, "dist"), { recursive: true }); - writeFileSync(join(dir, "package.json"), JSON.stringify({ name: "fixture-project" })); + mkdirSync(pkgDir, { recursive: true }); + writeFileSync(join(dir, "package.json"), JSON.stringify({ name: "received-project" })); + const planted = + 'import { writeFileSync } from "node:fs";\nwriteFileSync(new URL("./RAN", import.meta.url), "");\n'; + writeFileSync(join(pkgDir, "planted.mjs"), planted); writeFileSync( join(pkgDir, "package.json"), JSON.stringify({ name: "@hyperframes/core", - version: "0.0.0-fixture", type: "module", exports: { "./package.json": "./package.json", - "./audio-carve": { import: "./dist/audioCarve.js" }, - "./audio-fx": { import: "./dist/audioFx.js" }, + "./audio-carve": "./planted.mjs", + "./audio-fx": "./planted.mjs", }, }), ); - writeFileSync(join(pkgDir, "dist", "audioCarve.js"), 'export const marker = "carve";\n'); - writeFileSync(join(pkgDir, "dist", "audioFx.js"), 'export const marker = "fx";\n'); + writeFileSync(join(dir, "index.html"), ""); - const core = await loadCore(dir); - assert.equal(core.carve.marker, "carve"); - assert.equal(core.fx.marker, "fx"); + let stderr = ""; + try { + execFileSync( + process.execPath, + [join(SCRIPTS_DIR, "carve.mjs"), "--comp", "index.html", "--dry-run"], + { + cwd: dir, + stdio: "pipe", + }, + ); + } catch (error) { + stderr = String(error.stderr); + } + assert.equal(existsSync(join(pkgDir, "RAN")), false, "the project's @hyperframes/core ran"); + assert.match( + stderr, + /media in the composition/, + "carve stopped before it read the composition", + ); }); }); diff --git a/skills/media-use/audio/scripts/lib/audio-carve.mjs b/skills/media-use/audio/scripts/lib/audio-carve.mjs new file mode 100644 index 0000000000..4a33b32bc3 --- /dev/null +++ b/skills/media-use/audio/scripts/lib/audio-carve.mjs @@ -0,0 +1,4 @@ +// GENERATED: do not hand-edit. Source: packages/core/src/audioCarve.ts and audioFx.ts, bundled by +// scripts/generate-media-use-audio-carve.mjs so carve.mjs runs the same analysis as Studio without +// loading @hyperframes/core from the project. Regenerate: node scripts/generate-media-use-audio-carve.mjs +var K="data-fx-chain",Fe=K.slice(5),A=1,y=(e="frequency",n="Frequency",t=1e3,a=20,r=2e4)=>({kind:"number",key:e,label:n,unit:"Hz",min:a,max:r,step:1,default:t,scale:"log",automatable:!0}),C=(e=.707,n="Bandwidth: higher is narrower.")=>({kind:"number",key:"q",label:"Q",unit:"",min:.1,max:20,step:.01,default:e,scale:"log",automatable:!0,hint:n}),F=(e=-40,n=40,t=0)=>({kind:"number",key:"gain",label:"Gain",unit:"dB",min:e,max:n,step:.1,default:t,automatable:!0}),T={kind:"enum",key:"poles",label:"Slope",options:[{value:"1",label:"6 dB/oct"},{value:"2",label:"12 dB/oct"}],default:"2",hint:"Two poles is the usual biquad; one pole is gentler."},B=[{id:"gain",label:"Gain",group:"dynamics",description:"Raise or lower the whole signal. Automate it to duck under something else.",params:[F(-60,12,0)],web:"gain-node"},{id:"peaking",label:"Peaking EQ",group:"filter",description:"Boost or cut a band, leaving everything either side alone.",params:[y("frequency","Frequency",1e3),F(-40,40,0),C(1)],web:"biquad-peaking"},{id:"lowshelf",label:"Low Shelf",group:"filter",description:"Lift or drop everything below the corner frequency.",params:[y("frequency","Frequency",200,20,2e3),F(-40,40,0)],web:"biquad-lowshelf"},{id:"highshelf",label:"High Shelf",group:"filter",description:"Lift or drop everything above the corner frequency.",params:[y("frequency","Frequency",4e3,500,2e4),F(-40,40,0)],web:"biquad-highshelf"},{id:"highpass",label:"High-pass",group:"filter",description:"Remove low frequencies: the usual fix for rumble on a voice.",params:[y("frequency","Cutoff",300,20,2e4),C(.707),T],web:"biquad-highpass"},{id:"lowpass",label:"Low-pass",group:"filter",description:"Remove high frequencies, which darkens or muffles a track.",params:[y("frequency","Cutoff",8e3,100,2e4),C(.707),T],web:"biquad-lowpass"},{id:"compressor",label:"Compressor",group:"dynamics",description:"Pull loud parts down so the quiet ones can come up.",params:[{kind:"number",key:"threshold",label:"Threshold",unit:"dB",min:-60,max:0,step:.5,default:-24,hint:"Level above which the compressor starts working."},{kind:"number",key:"ratio",label:"Ratio",unit:":1",min:1,max:20,step:.1,default:4},{kind:"number",key:"attack",label:"Attack",unit:"ms",min:.01,max:2e3,step:.1,default:20,scale:"log"},{kind:"number",key:"release",label:"Release",unit:"ms",min:.01,max:9e3,step:1,default:250,scale:"log"},{kind:"number",key:"knee",label:"Knee",unit:"",min:1,max:8,step:.01,default:2.83,hint:"1 is a hard corner; higher eases into it."},{kind:"number",key:"makeup",label:"Makeup",unit:"dB",min:0,max:36,step:.1,default:0},{kind:"number",key:"mix",label:"Mix",unit:"",min:0,max:1,step:.01,default:1,hint:"Below 1 blends the dry signal back in."}],web:"worklet-compressor"},{id:"limiter",label:"Limiter",group:"dynamics",description:"Peak limiter that follows the signal's level. It has no lookahead, so a fast peak or an inter-sample peak can pass the ceiling; use the true-peak limiter for a delivery limit.",params:[{kind:"number",key:"limit",label:"Ceiling",unit:"dB",min:-24,max:0,step:.1,default:-1},{kind:"number",key:"attack",label:"Attack",unit:"ms",min:.1,max:80,step:.1,default:5},{kind:"number",key:"release",label:"Release",unit:"ms",min:1,max:8e3,step:1,default:50,scale:"log"},{kind:"number",key:"level_out",label:"Output",unit:"dB",min:-24,max:24,step:.1,default:0}],web:"worklet-limiter"},{id:"truepeak",label:"True-peak limiter",group:"dynamics",description:"Lookahead limiter that holds a 4x estimate of the inter-sample peak at a dBTP ceiling; full-band noise can land up to about 1.7 dB above it. Adds lookahead plus about 0.3 ms of latency.",params:[{kind:"number",key:"ceiling",label:"Ceiling",unit:"dBTP",min:-24,max:0,step:.1,default:-1,hint:"Target true peak, measured on a 4x oversampled signal. Dense full-band sound can end up to about 1.7 dB above it."},{kind:"number",key:"lookahead",label:"Lookahead",unit:"ms",min:.5,max:10,step:.1,default:3,hint:"How far ahead the gain starts falling. Longer is smoother and adds the same latency."},{kind:"number",key:"release",label:"Release",unit:"ms",min:10,max:2e3,step:1,default:80,scale:"log"}],web:"worklet-truepeak"},{id:"gate",label:"Noise Gate",group:"dynamics",description:"Silence the track when it drops below the threshold.",params:[{kind:"number",key:"threshold",label:"Threshold",unit:"dB",min:-80,max:0,step:.5,default:-35},{kind:"number",key:"range",label:"Range",unit:"dB",min:-80,max:0,step:.5,default:-24,hint:"How far down the gate pulls when closed."},{kind:"number",key:"ratio",label:"Ratio",unit:":1",min:1,max:20,step:.1,default:10},{kind:"number",key:"attack",label:"Attack",unit:"ms",min:.01,max:9e3,step:.1,default:1,scale:"log"},{kind:"number",key:"release",label:"Release",unit:"ms",min:.01,max:9e3,step:1,default:100,scale:"log"},{kind:"number",key:"knee",label:"Knee",unit:"",min:1,max:8,step:.01,default:2.83}],web:"worklet-gate"},{id:"saturate",label:"Saturation",group:"nonlinear",description:"Soft-clip the waveform for warmth or outright distortion.",params:[{kind:"enum",key:"type",label:"Curve",options:[{value:"tanh",label:"Tanh"},{value:"atan",label:"Arctan"},{value:"cubic",label:"Cubic"},{value:"exp",label:"Exponential"},{value:"alg",label:"Algebraic"},{value:"quintic",label:"Quintic"},{value:"sin",label:"Sine"},{value:"erf",label:"Error function"},{value:"hard",label:"Hard clip"}],default:"tanh"},{kind:"number",key:"threshold",label:"Threshold",unit:"dB",min:-40,max:0,step:.1,default:-6},{kind:"number",key:"output",automatable:!0,label:"Output",unit:"dB",min:-24,max:24,step:.1,default:0},{kind:"number",key:"oversample",label:"Oversample",unit:"x",min:1,max:8,step:1,default:4,hint:"Higher costs more but keeps aliasing down."}],web:"waveshaper"},{id:"bitcrush",label:"Bitcrush",group:"nonlinear",description:"Drop bit depth and sample rate for a lo-fi, digital sound.",params:[{kind:"number",key:"bits",label:"Bit depth",unit:"bit",min:1,max:32,step:.1,default:8},{kind:"number",key:"samples",label:"Sample hold",unit:"x",min:1,max:250,step:1,default:1,hint:"Repeats each sample N times, a crude downsample."},{kind:"number",key:"mix",label:"Mix",unit:"",min:0,max:1,step:.01,default:1}],web:"worklet-bitcrush"},{id:"pitchshift",label:"Pitch shift",group:"time",description:"Shifts pitch up or down without changing playback speed. Adds ~50 ms of latency.",params:[{kind:"number",key:"semitones",label:"Semitones",unit:"st",min:-12,max:12,step:1,default:0},{kind:"number",key:"mix",label:"Mix",unit:"",min:0,max:1,step:.01,default:1}],web:"worklet-pitchshift"},{id:"delay",label:"Delay",group:"time",description:"Repeating echoes behind the dry signal.",params:[{kind:"number",key:"time",automatable:!0,label:"Time",unit:"ms",min:1,max:5e3,step:1,default:250,scale:"log"},{kind:"number",key:"feedback",automatable:!0,label:"Feedback",unit:"",min:.01,max:.95,step:.01,default:.35},{kind:"number",key:"mix",automatable:!0,label:"Mix",unit:"",min:0,max:1,step:.01,default:.4}],web:"delay-feedback"},{id:"chorus",label:"Chorus",group:"time",description:"Detuned copies of the signal for width and thickness.",params:[{kind:"number",key:"delay",automatable:!0,label:"Delay",unit:"ms",min:1,max:100,step:.1,default:7},{kind:"number",key:"depth",automatable:!0,label:"Depth",unit:"ms",min:0,max:10,step:.01,default:2},{kind:"number",key:"speed",automatable:!0,label:"Rate",unit:"Hz",min:.01,max:10,step:.01,default:1},{kind:"number",key:"mix",automatable:!0,label:"Mix",unit:"",min:0,max:1,step:.01,default:.5}],web:"chorus-lfo"},{id:"phaser",label:"Phaser",group:"time",description:"Sweeping notches moving through the spectrum.",params:[{kind:"number",key:"in_gain",automatable:!0,label:"Input",unit:"",min:0,max:1,step:.01,default:.4},{kind:"number",key:"out_gain",automatable:!0,label:"Output",unit:"",min:0,max:2,step:.01,default:.74},{kind:"number",key:"delay",label:"Delay",unit:"ms",min:.1,max:5,step:.1,default:3},{kind:"number",key:"decay",label:"Decay",unit:"",min:0,max:.99,step:.01,default:.4},{kind:"number",key:"speed",automatable:!0,label:"Rate",unit:"Hz",min:.1,max:2,step:.01,default:.5},{kind:"enum",key:"type",label:"Waveform",options:[{value:"0",label:"Triangular"},{value:"1",label:"Sinusoidal"}],default:"0"}],web:"allpass-phaser"},{id:"reverb",label:"Reverb",group:"time",description:"Room tail. Both ends convolve the same generated impulse, so preview matches render.",params:[{kind:"number",key:"size",label:"Room size",unit:"",min:.05,max:1,step:.01,default:.7},{kind:"number",key:"damping",label:"Damping",unit:"",min:0,max:1,step:.01,default:.5,hint:"Higher rolls the top off the tail faster."},{kind:"number",key:"wet",automatable:!0,label:"Wet",unit:"",min:0,max:1,step:.01,default:.35},{kind:"number",key:"dry",automatable:!0,label:"Dry",unit:"",min:0,max:1,step:.01,default:.7}],web:"convolver"}],D=new Map(B.map(e=>[e.id,e]));var ve=B.map(e=>e.id);function M(e){let n=D.get(e);if(!n)return{};let t={};for(let a of n.params)t[a.key]=a.default;return t}function O(e,n){let t=D.get(e);if(!t)return{};let a={};for(let r of t.params){let o=n?.[r.key];if(r.kind==="enum"){let i=r.options.some(u=>u.value===o);a[r.key]=i?o:r.default;continue}let s=typeof o=="number"?o:typeof o=="string"&&o.trim()!==""?Number(o):Number.NaN;a[r.key]=Number.isFinite(s)?Math.min(r.max,Math.max(r.min,s)):r.default}return a}var x=class extends Error{constructor(n){super(n),this.name="AudioFxChainError"}};function X(e){let n;try{n=JSON.parse(e)}catch(r){throw new x(`Chain file is not valid JSON: ${r.message}`)}if(typeof n!="object"||n===null)throw new x("Chain file must be a JSON object.");let t=n;if(t.version!==A)throw new x(`Unsupported chain version: ${String(t.version)}`);if(!Array.isArray(t.nodes))throw new x("Chain file is missing a `nodes` array.");let a=t.nodes.map(W);return{version:A,nodes:a}}function j(e){return JSON.stringify({version:A,nodes:e.nodes.map(Q)})}function J(e){let n=new Set(e.nodes.map(t=>t.id).filter(Boolean));for(let t=1;;t+=1){let a=`n${t}`;if(!n.has(a))return a}}function W(e,n){if(typeof e!="object"||e===null)throw new x(`Node ${n} is not an object.`);let t=e;if(typeof t.type!="string"||!D.has(t.type))throw new x(`Node ${n} has unknown effect type: ${String(t.type)}`);return L({type:t.type,id:k(t.id),fromCarve:v(t.fromCarve),fromPreset:k(t.fromPreset),label:k(t.label),fromEq:k(t.fromEq),fromLeveller:v(t.fromLeveller),presetAmount:R(t.presetAmount),enabled:t.enabled!==!1,params:O(t.type,t.params??void 0)})}function Q(e){return L({type:e.type,id:k(e.id),fromCarve:v(e.fromCarve),fromPreset:k(e.fromPreset),label:k(e.label),fromEq:k(e.fromEq),fromLeveller:v(e.fromLeveller),presetAmount:e.presetAmount===1?void 0:R(e.presetAmount),enabled:e.enabled===!1?!1:void 0,params:O(e.type,e.params)})}function k(e){return typeof e=="string"&&e?e:void 0}function v(e){return e===!0?!0:void 0}function R(e){if(!(typeof e!="number"||!Number.isFinite(e)))return Math.min(1,Math.max(0,e))}function L(e){for(let n of Object.keys(e))e[n]===void 0&&delete e[n];return e}function V(e,n){let t=e.length;for(let a=1,r=0;a>1;for(;r&o;o>>=1)r^=o;r^=o,a`${ne}${e}${ae}`,re=new RegExp(`music|bgm|${w("bed")}|soundtrack|score|${w("song")}|theme|instrumental|track\\d`,"i"),oe=new RegExp(`voice|${w("vo")}|${w("vox")}|narrat|speech|dialog|monolog|announce|${w("tts")}|talk|interview|podcast|recap|script`,"i");function ie(...e){let n=e.filter(Boolean).join(" ");return oe.test(n)?"voice":te.test(n)?"sfx":re.test(n)?"music":"unknown"}function se(e,n){let t=a=>typeof a.duration=="number"&&Number.isFinite(a.duration)?a.start+Math.max(0,a.duration):Number.POSITIVE_INFINITY;return e.start({samples:o.samples,at:Math.round(o.offsetSeconds*n)})),a=t.reduce((o,s)=>Math.max(o,s.at+s.samples.length),0);if(a<=0)return new Float32Array(0);let r=new Float32Array(a);for(let{samples:o,at:s}of t){let i=s<0?-s:0;for(let u=i;u=a||(r[l]=(r[l]??0)+(o[u]??0))}}return r}function me(e,n){let t=Math.max(e.length,c),a=e.length>=c?e:(()=>{let m=new Float32Array(c);return m.set(e),m})(),r=new Float32Array(c);for(let m=0;m=a&&e[i]0?o/s:0}var fe=30;function ce(e,n){let t=Math.log2(e/2e3),a=Math.exp(-(t*t)/2);return n*fe*(1-a)}function be(e,n,t){if(e.length===0)return[];let{freqs:a,power:r}=me(e,n),s=Z.map(u=>{let l=de(a,r,u);return{center:u,hasEnergy:l>0,scoreDb:l>0?10*Math.log10(l)-ce(u,t.intelligibilityBias):Number.NEGATIVE_INFINITY}}).sort((u,l)=>l.scoreDb-u.scoreDb).slice(0,Math.max(1,t.bands)).filter(u=>u.hasEnergy);if(s.length===0)return[];let i=s[0].scoreDb;return s.map(({center:u,scoreDb:l})=>{let f=Math.pow(10,(l-i)/10),p=Math.min(t.maxCutDb,Math.max(t.maxCutDb/2,t.maxCutDb*f));return{freq:u,gainDb:-Number(p.toFixed(2)),q:t.q}}).sort((u,l)=>u.freq-l.freq)}var pe=30,he=.05;var xe=2.4,ke=400,P=.2,ge=.5;function ye(e,n){let t=[{t:0,v:0}],a=0,r=-1;return e.forEach((o,s)=>{s!==e.length-1&&Math.abs(o.v-a)0&&r!==s-1&&t.push(e[s-1]),t.push(o),a=o.v,r=s)}),t}function U(e,n,t){let a=0,r=0;for(let s=n;s0?20*Math.log10(o):Number.NEGATIVE_INFINITY}function Ae(e,n,t,a,r){if(e.length===0||a.duckDb<=0)return[];let o=Math.max(c,Math.ceil(e.length/ke)),s=Math.round(r*t),i=[],u=[],l=[];for(let h=0;h{let q=u[_]??Number.NEGATIVE_INFINITY,G=h>p&&Number.isFinite(q)?q-(h-a.headroomDb):0,I=Math.min(a.duckDb,Math.max(0,G));b+=(I>b?m:d)*(I-b);let Y=b=P;)b+=d*-b,E+=$,g.push({t:Number(E.toFixed(3)),v:b=S||N.push({t:S,v:0}),N}function we(e){let n=e.map(t=>({type:"peaking",enabled:!0,params:{...M("peaking"),frequency:t.freq,gain:t.gainDb,q:t.q}}));return{version:A,nodes:n}}export{be as analyseCarveBands,Ae as analyseCarveDuck,we as carveBandsToChain,ue as carveProfile,ie as classifyAudioName,se as clipsOverlap,M as defaultAudioFxParams,J as mintAudioFxNodeId,le as mixCarveSources,X as parseAudioFxChain,j as serializeAudioFxChain}; diff --git a/skills/media-use/references/mixing.md b/skills/media-use/references/mixing.md index 8215001560..8557eca386 100644 --- a/skills/media-use/references/mixing.md +++ b/skills/media-use/references/mixing.md @@ -65,7 +65,7 @@ A crossfade is two clips on different tracks that overlap, each with a fade. ## Music under a voice -Duck the bed with a `volume` lane on the music: full level before the voice, down to about 0.3–0.4 while anyone speaks (word timings from `npx hyperframes transcribe` or the voiceover give the times), back up after. Then carve the bed, which dips only the bands the voice uses: `node /audio/scripts/carve.mjs --comp index.html` (needs `ffmpeg` and `@hyperframes/core` in the project; `--dry-run` to see the plan). It is the same analysis as Studio's carve panel. It reads only double-quoted attributes (JSON quotes as `"`), so write the bed's chain and lanes that way or it overwrites them. Never put a carve on a voice track. +Duck the bed with a `volume` lane on the music: full level before the voice, down to about 0.3–0.4 while anyone speaks (word timings from `npx hyperframes transcribe` or the voiceover give the times), back up after. Then carve the bed, which dips only the bands the voice uses: `node /audio/scripts/carve.mjs --comp index.html` (needs `ffmpeg`; `--dry-run` to see the plan). It is the same analysis as Studio's carve panel. It reads only double-quoted attributes (JSON quotes as `"`), so write the bed's chain and lanes that way or it overwrites them. Never put a carve on a voice track. ## Group buses