Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
import { spawn } from "node:child_process";
import {
existsSync,
writeFileSync,
mkdirSync,
lstatSync,
mkdtempSync,
renameSync,
rmSync,
statSync,
} from "node:fs";
import { dirname, join } from "node:path";
import { findFfBinary } from "@hyperframes/parsers/ff-binaries";
const SAMPLE_RATE = 4000;
const PEAK_COUNT = 4000;
const WAVEFORM_CACHE_VERSION = "v2";
/**
* Cache filename for one asset's peaks, keyed on its content as well as its name.
*
* The path alone is not an identity. An asset rebuilt in place — a bed
* re-encoded without its ducking, a plate swapped for the right one — keeps its
* name and gets new samples, and a path-keyed entry then served the old peaks
* for the rest of the project's life: the timeline drew a duck that was no
* longer in the file, which reads as the render having done it. Size and mtime
* are what a rebuild always changes, and both are already on the stat the route
* takes to check the file exists.
*
* Without a fingerprint it falls back to the old path-only key, so a caller that
* cannot stat still gets caching rather than an error.
*/
export function buildWaveformCacheKey(
assetPath: string,
fingerprint?: { size: number; mtimeMs: number },
): string {
const name = assetPath.replace(/[/\\]/g, "_");
if (!fingerprint) return `${WAVEFORM_CACHE_VERSION}_${name}.json`;
const stamp = `${fingerprint.size}-${Math.round(fingerprint.mtimeMs)}`;
return `${WAVEFORM_CACHE_VERSION}_${name}_${stamp}.json`;
}
function computePeaks(floats: Float32Array, count: number): number[] {
const step = floats.length / count;
const peaks: number[] = [];
for (let i = 0; i < count; i++) {
const start = Math.floor(i * step);
const end = Math.min(Math.floor((i + 1) * step), floats.length);
let max = 0;
for (let j = start; j < end; j++) {
// fallow-ignore-next-line code-duplication
const abs = Math.abs(floats[j] ?? 0);
if (abs > max) max = abs;
}
peaks.push(max);
}
const maxPeak = Math.max(...peaks, 0.001);
return peaks.map((p) => p / maxPeak);
}
export function decodeAudioPeaks(audioPath: string): Promise<number[]> {
return new Promise((resolvePromise, reject) => {
const proc = spawn(
findFfBinary("ffmpeg") ?? "ffmpeg",
[
"-i",
audioPath,
"-af",
"atrim=start_sample=1152",
"-f",
"f32le",
"-ac",
"1",
"-ar",
String(SAMPLE_RATE),
"-vn",
"pipe:1",
],
{ stdio: ["ignore", "pipe", "ignore"], windowsHide: true },
);
const chunks: Buffer[] = [];
proc.stdout?.on("data", (chunk: Buffer) => chunks.push(chunk));
proc.on("close", (code) => {
if (code !== 0 && chunks.length === 0) {
reject(new Error(`ffmpeg exited with code ${code}`));
return;
}
const buf = Buffer.concat(chunks);
const numSamples = Math.floor(buf.length / 4);
if (numSamples === 0) {
reject(new Error("ffmpeg produced no audio samples"));
return;
}
const ab = buf.buffer.slice(buf.byteOffset, buf.byteOffset + numSamples * 4);
resolvePromise(computePeaks(new Float32Array(ab), PEAK_COUNT));
});
proc.on("error", reject);
});
}
export async function generateWaveformCache(projectDir: string, assetPath: string): Promise<void> {
const audioPath = join(projectDir, assetPath);
if (!existsSync(audioPath)) return;
const stats = statSync(audioPath);
const cacheDir = join(projectDir, ".waveform-cache");
const cachePath = join(cacheDir, buildWaveformCacheKey(assetPath, stats));
if (isWaveformCacheDirectory(cacheDir) && existsSync(cachePath)) return;
const peaks = await decodeAudioPeaks(audioPath);
writeWaveformCache(cachePath, peaks);
}
export function isWaveformCacheDirectory(cacheDir: string): boolean {
return lstatSync(cacheDir, { throwIfNoEntry: false })?.isDirectory() ?? false;
}
/** Publish complete peaks without following a replaced cache-file symlink. */
export function writeWaveformCache(cachePath: string, peaks: number[]): void {
const cacheDir = dirname(cachePath);
try {
mkdirSync(cacheDir, { mode: 0o700 });
} catch (error) {
if (!(error instanceof Error && "code" in error && error.code === "EEXIST")) throw error;
}
if (!isWaveformCacheDirectory(cacheDir)) {
throw new Error("Waveform cache must be a directory, not a symlink");
}
const stagingDir = mkdtempSync(join(cacheDir, ".waveform-"));
try {
const stagingPath = join(stagingDir, "peaks.json");
writeFileSync(stagingPath, JSON.stringify(peaks), { flag: "wx" });
renameSync(stagingPath, cachePath);
} finally {
try {
rmSync(stagingDir, { recursive: true, force: true });
} catch {
// Cleanup must not mask a write error or fail an already published cache.
}
}
}