Skip to content

Commit df54f38

Browse files
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
1 parent 80e02e7 commit df54f38

5 files changed

Lines changed: 149 additions & 2 deletions

File tree

‎docs/packages/cli.mdx‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2088,6 +2088,9 @@ files, the browser download and models are never touched.
20882088
duration, element counts by type, track count, and total size.
20892089
`npx hyperframes compositions` lists every composition in the project with its
20902090
ID, duration, resolution, and element count. Both take `--json`.
2091+
`npx hyperframes info --media --json` adds `heard`: every clip the render mixes, scenes included, on the film's clock,
2092+
each with `src`, `start`, `end` (where it stops, or where its media runs out if sooner; `0` runs to the media's end),
2093+
`mediaStart`, `playbackRate`, `volume` and `type`.
20912094

20922095
### `update`
20932096

‎packages/cli/src/commands/info.test.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -69,7 +69,7 @@ describe("info", () => {
6969
const log = vi.spyOn(console, "log").mockImplementation(() => {});
7070
try {
7171
writeFileSync(join(dir, "index.html"), html);
72-
await info.run?.({ args: { _: [], dir, json: true }, rawArgs: [], cmd: info });
72+
await info.run?.({ args: { _: [], dir, json: true, media: false }, rawArgs: [], cmd: info });
7373

7474
expect(JSON.parse(String(log.mock.calls[0]?.[0]))).toMatchObject({
7575
resolution: "portrait",
@@ -93,7 +93,7 @@ describe("info", () => {
9393
<div class="clip" data-start="1" data-duration="2"></div>
9494
</div></body></html>`,
9595
);
96-
await info.run?.({ args: { _: [], dir, json: true }, rawArgs: [], cmd: info });
96+
await info.run?.({ args: { _: [], dir, json: true, media: false }, rawArgs: [], cmd: info });
9797

9898
expect(JSON.parse(String(log.mock.calls[0]?.[0]))).toMatchObject({
9999
resolution: "landscape",

‎packages/cli/src/commands/info.ts‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ import { readFileSync, readdirSync, statSync } from "node:fs";
55
export const examples: Example[] = [
66
["Show project metadata", "hyperframes info"],
77
["Output as JSON", "hyperframes info --json"],
8+
["List the clips the render hears, on the film's clock", "hyperframes info --media --json"],
89
];
910
import { join } from "node:path";
1011
import { parseHtml, CANVAS_DIMENSIONS } from "@hyperframes/core";
@@ -13,6 +14,7 @@ import {
1314
readCompositionSize,
1415
} from "@hyperframes/core/runtime/composition-length";
1516
import { readDataDurationSeconds } from "@hyperframes/parsers/media-duration";
17+
import { heardClips } from "../utils/projectMedia.js";
1618
import { c } from "../ui/colors.js";
1719
import { formatBytes, label } from "../ui/format.js";
1820
import { ensureDOMParser } from "../utils/dom.js";
@@ -61,6 +63,11 @@ export default defineCommand({
6163
args: {
6264
dir: { type: "positional", description: "Project directory", required: false },
6365
json: { type: "boolean", description: "Output as JSON", default: false },
66+
media: {
67+
type: "boolean",
68+
description: "Also list every clip the render hears, scenes included, on the film's clock",
69+
default: false,
70+
},
6471
},
6572
async run({ args }) {
6673
const project = resolveProject(args.dir);
@@ -90,6 +97,8 @@ export default defineCommand({
9097
.map(([t, count]) => `${count} ${t}`)
9198
.join(", ");
9299

100+
const heard = args.media ? await heardClips(project.dir) : undefined;
101+
93102
if (args.json) {
94103
console.log(
95104
JSON.stringify(
@@ -103,6 +112,7 @@ export default defineCommand({
103112
tracks: tracks.size,
104113
types: typeCounts,
105114
size,
115+
...(heard ? { heard } : {}),
106116
}),
107117
null,
108118
2,
@@ -117,5 +127,9 @@ export default defineCommand({
117127
console.log(label("Elements", `${parsed.elements.length}${typeStr ? ` (${typeStr})` : ""}`));
118128
console.log(label("Tracks", `${tracks.size}`));
119129
console.log(label("Size", formatBytes(size)));
130+
for (const clip of heard ?? []) {
131+
const until = clip.end > 0 ? `${clip.end.toFixed(2)}s` : "its end";
132+
console.log(label("Heard", `${clip.src} ${clip.start.toFixed(2)}s to ${until}`));
133+
}
120134
},
121135
});
Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
2+
import { tmpdir } from "node:os";
3+
import { join } from "node:path";
4+
import { afterEach, describe, expect, it } from "vitest";
5+
import { heardClips } from "./projectMedia.js";
6+
7+
let dir = "";
8+
afterEach(() => rmSync(dir, { recursive: true, force: true }));
9+
10+
function project(scene: string): string {
11+
dir = mkdtempSync(join(tmpdir(), "hf-heard-"));
12+
mkdirSync(join(dir, "compositions"));
13+
writeFileSync(
14+
join(dir, "index.html"),
15+
`<!doctype html><html><body>
16+
<div id="root" data-composition-id="main" data-start="0" data-duration="30" data-width="1080" data-height="1920">
17+
<div id="talk-host" data-composition-id="talk" data-composition-src="compositions/talk.html"
18+
data-start="10" data-duration="20" data-width="1080" data-height="1920"></div>
19+
</div></body></html>`,
20+
);
21+
writeFileSync(
22+
join(dir, "compositions", "talk.html"),
23+
`<template id="talk-template"><div data-composition-id="talk" data-start="0" data-duration="20" data-width="1080" data-height="1920">
24+
${scene}
25+
</div></template>`,
26+
);
27+
return dir;
28+
}
29+
30+
const probe = { seconds: async () => 6 };
31+
32+
describe("heardClips", () => {
33+
it("hears a speaking video inside a timed wrapper in a scene, where the render plays it", async () => {
34+
const clips = await heardClips(
35+
project(`<div id="wrap" class="clip" data-start="1" data-duration="8">
36+
<video id="talk" src="../assets/talk.mp4" data-has-audio="true" data-start="0" data-duration="5"></video>
37+
</div>`),
38+
probe,
39+
);
40+
expect(clips.map(({ src, start, end }) => ({ src, start, end }))).toEqual([
41+
{ src: "assets/talk.mp4", start: 10, end: 15 },
42+
]);
43+
});
44+
45+
it("ends a speaking clip with no set length where its media runs out, not where its scene ends", async () => {
46+
const clips = await heardClips(
47+
project(
48+
`<video id="talk" src="../assets/talk.mp4" data-has-audio="true" data-start="2" data-media-start="1"></video>`,
49+
),
50+
probe,
51+
);
52+
expect(clips.map(({ src, start, end }) => ({ src, start, end }))).toEqual([
53+
{ src: "assets/talk.mp4", start: 12, end: 17 },
54+
]);
55+
});
56+
57+
it("leaves out a clip that starts past its media's end, and reads each file's length once", async () => {
58+
const probed: string[] = [];
59+
const counting = { seconds: async (path: string) => (probed.push(path), 6) };
60+
const clips = await heardClips(
61+
project(`<video id="late" src="../assets/talk.mp4" data-has-audio="true" data-start="0" data-media-start="7"></video>
62+
<video id="talk" src="../assets/talk.mp4" data-has-audio="true" data-start="8" data-duration="3"></video>`),
63+
counting,
64+
);
65+
expect(clips.map(({ id, start, end }) => ({ id, start, end }))).toEqual([
66+
{ id: "talk-audio", start: 18, end: 21 },
67+
]);
68+
expect(probed).toHaveLength(1);
69+
});
70+
71+
it("hears a video only when it says data-has-audio and is not muted, as the render does", async () => {
72+
const clips = await heardClips(
73+
project(`<video id="broll" src="../assets/broll.mp4" data-start="0" data-duration="3"></video>
74+
<video id="quiet" src="../assets/quiet.mp4" data-has-audio="true" data-start="4" data-duration="3" muted></video>
75+
<video id="talk" src="../assets/talk.mp4" data-has-audio="true" data-start="8" data-duration="3"></video>`),
76+
probe,
77+
);
78+
expect(clips.map(({ src, start, end }) => ({ src, start, end }))).toEqual([
79+
{ src: "assets/talk.mp4", start: 18, end: 21 },
80+
]);
81+
});
82+
});

‎packages/cli/src/utils/projectMedia.ts‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
import {
2+
extractAudioMetadata,
23
resolveProjectRelativeSrc,
34
type AudioElement,
45
type VideoElement,
@@ -29,3 +30,50 @@ export async function collectProjectMedia(projectDir: string): Promise<ProjectMe
2930
export function mediaPath(src: string, projectDir: string): string {
3031
return /^https?:\/\//i.test(src) ? src : resolveProjectRelativeSrc(src, projectDir, projectDir);
3132
}
33+
34+
/** A clip the render mixes into the film, on the film's clock; `end` 0 means it runs to its media's end. */
35+
export type HeardClip = Pick<
36+
AudioElement,
37+
"id" | "src" | "start" | "end" | "mediaStart" | "playbackRate" | "volume" | "type"
38+
>;
39+
40+
export interface HeardProbe {
41+
seconds(path: string): Promise<number>;
42+
}
43+
44+
const PROBE: HeardProbe = {
45+
seconds: async (path) => (await extractAudioMetadata(path)).durationSeconds,
46+
};
47+
48+
/** Every clip the render mixes, read as the render reads them (scenes inlined, on the film's clock), each ended where
49+
* its media runs out if sooner, and left out if it starts past that; a ramped rate or a loop keeps its end. */
50+
export async function heardClips(
51+
projectDir: string,
52+
probe: HeardProbe = PROBE,
53+
): Promise<HeardClip[]> {
54+
const { audios } = await collectProjectMedia(projectDir);
55+
const lengths = new Map<string, Promise<number | null>>();
56+
const length = (src: string): Promise<number | null> => {
57+
const path = mediaPath(src, projectDir);
58+
const known = lengths.get(path) ?? probe.seconds(path).catch(() => null);
59+
lengths.set(path, known);
60+
return known;
61+
};
62+
const clips = await Promise.all(audios.map((clip) => endedClip(clip, length)));
63+
return clips.filter((clip) => clip !== null);
64+
}
65+
66+
async function endedClip(
67+
clip: AudioElement,
68+
length: (src: string) => Promise<number | null>,
69+
): Promise<HeardClip | null> {
70+
const { id, src, start, mediaStart, playbackRate, volume, type } = clip;
71+
const heard = { id, src, start, end: clip.end, mediaStart, playbackRate, volume, type };
72+
const rate = playbackRate === undefined ? 1 : playbackRate;
73+
if (clip.loop || typeof rate !== "number" || !(rate > 0)) return heard;
74+
const seconds = await length(src);
75+
if (seconds === null) return heard;
76+
if (seconds <= mediaStart) return null;
77+
const runsOut = start + (seconds - mediaStart) / rate;
78+
return { ...heard, end: clip.end > 0 ? Math.min(clip.end, runsOut) : runsOut };
79+
}

0 commit comments

Comments
 (0)