feat(cli): info --media lists every clip the render hears, on the film's clock (#7235)

* feat(cli): info --media lists every clip the render hears, on the film's clock

* fix(cli): info --media leaves out a clip that starts past its media's end

* fix(cli): keep the heard-clips doc line within 120 characters
This commit is contained in:
Miguel Ángel
2026-11-05 14:09:22 +00:00
committed by GitHub
parent 80e02e74a0
commit df54f380cb
5 changed files with 149 additions and 2 deletions
+3
View File
@@ -2088,6 +2088,9 @@ files, the browser download and models are never touched.
duration, element counts by type, track count, and total size.
`npx hyperframes compositions` lists every composition in the project with its
ID, duration, resolution, and element count. Both take `--json`.
`npx hyperframes info --media --json` adds `heard`: every clip the render mixes, scenes included, on the film's clock,
each with `src`, `start`, `end` (where it stops, or where its media runs out if sooner; `0` runs to the media's end),
`mediaStart`, `playbackRate`, `volume` and `type`.
### `update`
+2 -2
View File
@@ -69,7 +69,7 @@ describe("info", () => {
const log = vi.spyOn(console, "log").mockImplementation(() => {});
try {
writeFileSync(join(dir, "index.html"), html);
await info.run?.({ args: { _: [], dir, json: true }, rawArgs: [], cmd: info });
await info.run?.({ args: { _: [], dir, json: true, media: false }, rawArgs: [], cmd: info });
expect(JSON.parse(String(log.mock.calls[0]?.[0]))).toMatchObject({
resolution: "portrait",
@@ -93,7 +93,7 @@ describe("info", () => {
<div class="clip" data-start="1" data-duration="2"></div>
</div></body></html>`,
);
await info.run?.({ args: { _: [], dir, json: true }, rawArgs: [], cmd: info });
await info.run?.({ args: { _: [], dir, json: true, media: false }, rawArgs: [], cmd: info });
expect(JSON.parse(String(log.mock.calls[0]?.[0]))).toMatchObject({
resolution: "landscape",
+14
View File
@@ -5,6 +5,7 @@ import { readFileSync, readdirSync, statSync } from "node:fs";
export const examples: Example[] = [
["Show project metadata", "hyperframes info"],
["Output as JSON", "hyperframes info --json"],
["List the clips the render hears, on the film's clock", "hyperframes info --media --json"],
];
import { join } from "node:path";
import { parseHtml, CANVAS_DIMENSIONS } from "@hyperframes/core";
@@ -13,6 +14,7 @@ import {
readCompositionSize,
} from "@hyperframes/core/runtime/composition-length";
import { readDataDurationSeconds } from "@hyperframes/parsers/media-duration";
import { heardClips } from "../utils/projectMedia.js";
import { c } from "../ui/colors.js";
import { formatBytes, label } from "../ui/format.js";
import { ensureDOMParser } from "../utils/dom.js";
@@ -61,6 +63,11 @@ export default defineCommand({
args: {
dir: { type: "positional", description: "Project directory", required: false },
json: { type: "boolean", description: "Output as JSON", default: false },
media: {
type: "boolean",
description: "Also list every clip the render hears, scenes included, on the film's clock",
default: false,
},
},
async run({ args }) {
const project = resolveProject(args.dir);
@@ -90,6 +97,8 @@ export default defineCommand({
.map(([t, count]) => `${count} ${t}`)
.join(", ");
const heard = args.media ? await heardClips(project.dir) : undefined;
if (args.json) {
console.log(
JSON.stringify(
@@ -103,6 +112,7 @@ export default defineCommand({
tracks: tracks.size,
types: typeCounts,
size,
...(heard ? { heard } : {}),
}),
null,
2,
@@ -117,5 +127,9 @@ export default defineCommand({
console.log(label("Elements", `${parsed.elements.length}${typeStr ? ` (${typeStr})` : ""}`));
console.log(label("Tracks", `${tracks.size}`));
console.log(label("Size", formatBytes(size)));
for (const clip of heard ?? []) {
const until = clip.end > 0 ? `${clip.end.toFixed(2)}s` : "its end";
console.log(label("Heard", `${clip.src} ${clip.start.toFixed(2)}s to ${until}`));
}
},
});
@@ -0,0 +1,82 @@
import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { afterEach, describe, expect, it } from "vitest";
import { heardClips } from "./projectMedia.js";
let dir = "";
afterEach(() => rmSync(dir, { recursive: true, force: true }));
function project(scene: string): string {
dir = mkdtempSync(join(tmpdir(), "hf-heard-"));
mkdirSync(join(dir, "compositions"));
writeFileSync(
join(dir, "index.html"),
`<!doctype html><html><body>
<div id="root" data-composition-id="main" data-start="0" data-duration="30" data-width="1080" data-height="1920">
<div id="talk-host" data-composition-id="talk" data-composition-src="compositions/talk.html"
data-start="10" data-duration="20" data-width="1080" data-height="1920"></div>
</div></body></html>`,
);
writeFileSync(
join(dir, "compositions", "talk.html"),
`<template id="talk-template"><div data-composition-id="talk" data-start="0" data-duration="20" data-width="1080" data-height="1920">
${scene}
</div></template>`,
);
return dir;
}
const probe = { seconds: async () => 6 };
describe("heardClips", () => {
it("hears a speaking video inside a timed wrapper in a scene, where the render plays it", async () => {
const clips = await heardClips(
project(`<div id="wrap" class="clip" data-start="1" data-duration="8">
<video id="talk" src="../assets/talk.mp4" data-has-audio="true" data-start="0" data-duration="5"></video>
</div>`),
probe,
);
expect(clips.map(({ src, start, end }) => ({ src, start, end }))).toEqual([
{ src: "assets/talk.mp4", start: 10, end: 15 },
]);
});
it("ends a speaking clip with no set length where its media runs out, not where its scene ends", async () => {
const clips = await heardClips(
project(
`<video id="talk" src="../assets/talk.mp4" data-has-audio="true" data-start="2" data-media-start="1"></video>`,
),
probe,
);
expect(clips.map(({ src, start, end }) => ({ src, start, end }))).toEqual([
{ src: "assets/talk.mp4", start: 12, end: 17 },
]);
});
it("leaves out a clip that starts past its media's end, and reads each file's length once", async () => {
const probed: string[] = [];
const counting = { seconds: async (path: string) => (probed.push(path), 6) };
const clips = await heardClips(
project(`<video id="late" src="../assets/talk.mp4" data-has-audio="true" data-start="0" data-media-start="7"></video>
<video id="talk" src="../assets/talk.mp4" data-has-audio="true" data-start="8" data-duration="3"></video>`),
counting,
);
expect(clips.map(({ id, start, end }) => ({ id, start, end }))).toEqual([
{ id: "talk-audio", start: 18, end: 21 },
]);
expect(probed).toHaveLength(1);
});
it("hears a video only when it says data-has-audio and is not muted, as the render does", async () => {
const clips = await heardClips(
project(`<video id="broll" src="../assets/broll.mp4" data-start="0" data-duration="3"></video>
<video id="quiet" src="../assets/quiet.mp4" data-has-audio="true" data-start="4" data-duration="3" muted></video>
<video id="talk" src="../assets/talk.mp4" data-has-audio="true" data-start="8" data-duration="3"></video>`),
probe,
);
expect(clips.map(({ src, start, end }) => ({ src, start, end }))).toEqual([
{ src: "assets/talk.mp4", start: 18, end: 21 },
]);
});
});
+48
View File
@@ -1,4 +1,5 @@
import {
extractAudioMetadata,
resolveProjectRelativeSrc,
type AudioElement,
type VideoElement,
@@ -29,3 +30,50 @@ export async function collectProjectMedia(projectDir: string): Promise<ProjectMe
export function mediaPath(src: string, projectDir: string): string {
return /^https?:\/\//i.test(src) ? src : resolveProjectRelativeSrc(src, projectDir, projectDir);
}
/** A clip the render mixes into the film, on the film's clock; `end` 0 means it runs to its media's end. */
export type HeardClip = Pick<
AudioElement,
"id" | "src" | "start" | "end" | "mediaStart" | "playbackRate" | "volume" | "type"
>;
export interface HeardProbe {
seconds(path: string): Promise<number>;
}
const PROBE: HeardProbe = {
seconds: async (path) => (await extractAudioMetadata(path)).durationSeconds,
};
/** Every clip the render mixes, read as the render reads them (scenes inlined, on the film's clock), each ended where
* its media runs out if sooner, and left out if it starts past that; a ramped rate or a loop keeps its end. */
export async function heardClips(
projectDir: string,
probe: HeardProbe = PROBE,
): Promise<HeardClip[]> {
const { audios } = await collectProjectMedia(projectDir);
const lengths = new Map<string, Promise<number | null>>();
const length = (src: string): Promise<number | null> => {
const path = mediaPath(src, projectDir);
const known = lengths.get(path) ?? probe.seconds(path).catch(() => null);
lengths.set(path, known);
return known;
};
const clips = await Promise.all(audios.map((clip) => endedClip(clip, length)));
return clips.filter((clip) => clip !== null);
}
async function endedClip(
clip: AudioElement,
length: (src: string) => Promise<number | null>,
): Promise<HeardClip | null> {
const { id, src, start, mediaStart, playbackRate, volume, type } = clip;
const heard = { id, src, start, end: clip.end, mediaStart, playbackRate, volume, type };
const rate = playbackRate === undefined ? 1 : playbackRate;
if (clip.loop || typeof rate !== "number" || !(rate > 0)) return heard;
const seconds = await length(src);
if (seconds === null) return heard;
if (seconds <= mediaStart) return null;
const runsOut = start + (seconds - mediaStart) / rate;
return { ...heard, end: clip.end > 0 ? Math.min(clip.end, runsOut) : runsOut };
}