Skip to content

Explainer videos and product demos made by your AI agent. Free and open source: a local voice (Kokoro), word timing (Whisper) and a canvas renderer turn a script into a narrated MP4.

Upload long soundtracks in pieces, so long videos render (#2)

MrThommasoe7e66c83acc1
diff --git a/engine/frame.html b/engine/frame.html
index c3cfc0a..2698aea 100644
--- a/engine/frame.html
+++ b/engine/frame.html
@@ -9,15 +9,11 @@
<canvas id="c"></canvas>
<script type="module">
import { boot, renderAudio } from '/engine/runtime.js';
+import { upload } from '/engine/upload.js';
const canvas = document.getElementById('c');
const scale = Number(new URLSearchParams(location.search).get('scale') || 1);
-async function upload(path, body) {
- const res = await fetch('/__upload?path=' + encodeURIComponent(path), { method: 'PUT', body });
- if (!res.ok) throw new Error(`upload ${path} failed: ${await res.text()}`);
-}
-
function describe(e) {
const where = e.scene ? ` (scene "${e.scene}" at ${Number(e.sceneTime).toFixed(2)}s)` : '';
return (e.message || String(e)) + where;
diff --git a/engine/upload.js b/engine/upload.js
new file mode 100644
index 0000000..943f404
--- /dev/null
+++ b/engine/upload.js
@@ -0,0 +1,32 @@
+// Uploads from engine pages (render, still, sheet) to the local server.
+//
+// Two things keep large uploads such as a long soundtrack WAV working:
+//
+// - The body is always sent as a Blob. When a page sends an ArrayBuffer, Chrome
+// copies the whole body into the DevTools Network.requestWillBeSent event,
+// and Playwright reads that event as one string (about four characters per
+// byte). A 16-bit stereo 48 kHz soundtrack is about 192 KB per second, so
+// around ten minutes of audio passed Node's maximum string length and the
+// render stopped with ERR_STRING_TOO_LONG before the first frame. Blob bodies
+// are not copied into the event.
+// - The body goes up in pieces of at most UPLOAD_CHUNK_BYTES, each with its
+// byte offset, so no single request or server-side buffer grows with the
+// length of the video. The server assembles the pieces of one upload (its
+// random id) in order and moves the file into place when the last piece
+// arrives (see /__upload in server.js).
+export const UPLOAD_CHUNK_BYTES = 8 * 1024 * 1024;
+
+export async function upload(path, body, { chunkBytes = UPLOAD_CHUNK_BYTES } = {}) {
+ if (!(chunkBytes > 0)) throw new Error(`upload ${path}: chunkBytes must be positive`);
+ const blob = body instanceof Blob ? body : new Blob([body]);
+ const id = crypto.randomUUID().replaceAll('-', '');
+ const base = `/__upload?path=${encodeURIComponent(path)}&upload=${id}`;
+ let offset = 0;
+ do {
+ const part = blob.slice(offset, offset + chunkBytes);
+ const last = offset + part.size >= blob.size;
+ const res = await fetch(`${base}&offset=${offset}${last ? '&last=1' : ''}`, { method: 'PUT', body: part });
+ if (!res.ok) throw new Error(`upload ${path} failed at byte ${offset}: ${await res.text()}`);
+ offset += part.size;
+ } while (offset < blob.size);
+}
diff --git a/src/server.js b/src/server.js
index 9eb97d6..d004d8d 100644
--- a/src/server.js
+++ b/src/server.js
@@ -84,14 +84,16 @@ function uploadFile(projectDir, rel) {
if (realProbe !== realProject && !underRoot(realProbe)) return null;
fs.mkdirSync(path.dirname(dest), { recursive: true });
if (!underRoot(fs.realpathSync(path.dirname(dest)))) return null;
- // lstat, not existsSync: a symlink to a missing file must be refused too.
- let link = false;
+ return isSymlink(dest) ? null : dest;
+}
+
+// lstat, not existsSync: a symlink to a missing file must be refused too.
+function isSymlink(p) {
try {
- link = fs.lstatSync(dest).isSymbolicLink();
+ return fs.lstatSync(p).isSymbolicLink();
} catch {
- link = false;
+ return false;
}
- return link ? null : dest;
}
export function startServer({ projectDir, getState, port = 0 }) {
@@ -114,7 +116,38 @@ export function startServer({ projectDir, getState, port = 0 }) {
if (!dest) return send(res, 400, 'uploads go to build/ or out/');
const chunks = [];
for await (const c of req) chunks.push(c);
- fs.writeFileSync(dest, Buffer.concat(chunks));
+ const body = Buffer.concat(chunks);
+ // Chunked upload (engine/upload.js): the pieces of one upload carry its
+ // random id and their byte offset, and are assembled in
+ // "<dest>.<id>.part" next to the target, which replaces the target only
+ // when the last piece has arrived. A piece at the wrong offset is
+ // refused, an interrupted upload never leaves a half-written file under
+ // the real name, and a new upload of the same file (offset 0) removes
+ // older partial uploads, so a stale or competing upload fails instead
+ // of mixing bytes into the result.
+ if (url.searchParams.has('offset')) {
+ const rawOffset = url.searchParams.get('offset');
+ const offset = Number(rawOffset);
+ if (!/^\d+$/.test(rawOffset) || !Number.isSafeInteger(offset)) return send(res, 400, 'offset must be a non-negative integer');
+ const id = url.searchParams.get('upload') || '';
+ if (!/^[0-9a-f]{16,64}$/.test(id)) return send(res, 400, 'upload must be a hexadecimal upload id');
+ const part = `${dest}.${id}.part`;
+ if (isSymlink(part)) return send(res, 400, 'uploads go to build/ or out/');
+ if (offset === 0) {
+ const stale = new RegExp(`^${path.basename(dest).replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\.[0-9a-f]{16,64}\\.part$`);
+ for (const name of fs.readdirSync(path.dirname(dest))) {
+ if (stale.test(name)) fs.rmSync(path.join(path.dirname(dest), name), { force: true });
+ }
+ fs.writeFileSync(part, body);
+ } else {
+ const have = fs.existsSync(part) ? fs.statSync(part).size : null;
+ if (have !== offset) return send(res, 409, `upload piece out of order: expected offset ${have ?? 0}, got ${offset}`);
+ fs.appendFileSync(part, body);
+ }
+ if (url.searchParams.get('last') === '1') fs.renameSync(part, dest);
+ return send(res, 200, 'ok');
+ }
+ fs.writeFileSync(dest, body);
return send(res, 200, 'ok');
}
if (req.method !== 'GET' && req.method !== 'HEAD') return send(res, 405, 'method not allowed');
diff --git a/test/server.test.js b/test/server.test.js
index caa0c59..a168161 100644
--- a/test/server.test.js
+++ b/test/server.test.js
@@ -20,6 +20,82 @@ function request(port, { method = 'GET', path: p, host = `127.0.0.1:${port}`, or
});
}
+test('chunked uploads are assembled in order and appear only when complete', async () => {
+ const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'explainroo-chunks-'));
+ fs.writeFileSync(path.join(dir, 'scenes.js'), 'export default {};');
+ const server = await startServer({ projectDir: dir, getState: () => ({}) });
+ try {
+ const port = server.port;
+ const put = (p, query, body) => request(port, { method: 'PUT', path: `/__upload?path=${encodeURIComponent(p)}${query}`, body });
+ const piece = (p, id, offset, body, last = false) => put(p, `&upload=${id}&offset=${offset}${last ? '&last=1' : ''}`, body);
+ const A = 'a'.repeat(32);
+ const B = 'b'.repeat(32);
+ const build = path.join(dir, 'build');
+ const mix = path.join(build, 'mix.wav');
+ const parts = () => fs.readdirSync(build).filter((n) => n.endsWith('.part'));
+ fs.mkdirSync(build, { recursive: true });
+ fs.writeFileSync(mix, 'old');
+
+ // pieces in order; the existing file is replaced only by the last piece
+ assert.equal((await piece('build/mix.wav', A, 0, 'aaa')).status, 200);
+ assert.equal((await piece('build/mix.wav', A, 3, 'bbb')).status, 200);
+ assert.equal(fs.readFileSync(mix, 'utf8'), 'old');
+ // a piece at the wrong offset is refused and changes nothing
+ assert.equal((await piece('build/mix.wav', A, 99, 'zzz')).status, 409);
+ assert.equal((await piece('build/mix.wav', A, 6, 'cc', true)).status, 200);
+ assert.equal(fs.readFileSync(mix, 'utf8'), 'aaabbbcc');
+ assert.deepEqual(parts(), []);
+
+ // uploading the same file again replaces the completed destination
+ assert.equal((await piece('build/mix.wav', B, 0, 'second', true)).status, 200);
+ assert.equal(fs.readFileSync(mix, 'utf8'), 'second');
+
+ // an interrupted upload leaves only its part file; a new upload starts clean
+ assert.equal((await piece('build/mix.wav', A, 0, 'xxxx')).status, 200);
+ assert.equal((await piece('build/mix.wav', A, 4, 'yyyy')).status, 200);
+ assert.equal(fs.readFileSync(mix, 'utf8'), 'second');
+ assert.equal((await piece('build/mix.wav', B, 0, 'fresh')).status, 200);
+ assert.equal((await piece('build/mix.wav', B, 5, '!', true)).status, 200);
+ assert.equal(fs.readFileSync(mix, 'utf8'), 'fresh!');
+ assert.deepEqual(parts(), []);
+
+ // a competing upload never mixes bytes: the older one fails, the newer one wins
+ assert.equal((await piece('build/mix.wav', A, 0, '1111')).status, 200);
+ assert.equal((await piece('build/mix.wav', B, 0, '2222')).status, 200);
+ assert.equal((await piece('build/mix.wav', A, 4, '1111', true)).status, 409);
+ assert.equal(fs.readFileSync(mix, 'utf8'), 'fresh!');
+ assert.equal((await piece('build/mix.wav', B, 4, '2222', true)).status, 200);
+ assert.equal(fs.readFileSync(mix, 'utf8'), '22222222');
+
+ // a continuation without a started upload is refused
+ assert.equal((await piece('build/other.wav', A, 5, 'x', true)).status, 409);
+ assert.ok(!fs.existsSync(path.join(build, 'other.wav')));
+ // malformed offsets and upload ids are refused
+ for (const bad of ['-1', '1.5', 'abc', '']) assert.equal((await put('build/mix.wav', `&upload=${A}&offset=${bad}`, 'x')).status, 400);
+ for (const bad of ['', 'short', '../../scenes', 'A'.repeat(32), 'g'.repeat(32)]) assert.equal((await put('build/mix.wav', `&upload=${bad}&offset=0`, 'x')).status, 400);
+ // an empty upload is one last piece at offset 0
+ assert.equal((await piece('out/empty.bin', A, 0, '', true)).status, 200);
+ assert.equal(fs.statSync(path.join(dir, 'out', 'empty.bin')).size, 0);
+ // the single-request form keeps working, under the same path rules
+ assert.equal((await put('out/single.txt', '', 'one')).status, 200);
+ assert.equal(fs.readFileSync(path.join(dir, 'out', 'single.txt'), 'utf8'), 'one');
+
+ // chunked uploads obey the same path rules, and the part file cannot be a symlink
+ assert.equal((await piece('build/../scenes.js', A, 0, 'x', true)).status, 400);
+ assert.equal((await piece('assets/x.png', A, 0, 'x', true)).status, 400);
+ assert.equal(fs.readFileSync(path.join(dir, 'scenes.js'), 'utf8'), 'export default {};');
+ fs.symlinkSync(path.join(dir, 'scenes.js'), path.join(build, `trap.wav.${A}.part`));
+ assert.equal((await piece('build/trap.wav', A, 0, 'x', true)).status, 400);
+ assert.equal(fs.readFileSync(path.join(dir, 'scenes.js'), 'utf8'), 'export default {};');
+ // removing a stale part never follows a symlink to its target
+ assert.equal((await piece('build/trap.wav', B, 0, 'x', true)).status, 200);
+ assert.equal(fs.readFileSync(path.join(dir, 'scenes.js'), 'utf8'), 'export default {};');
+ } finally {
+ await server.close();
+ fs.rmSync(dir, { recursive: true, force: true });
+ }
+});
+
test('the preview server keeps secrets and sources safe', async () => {
const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'explainroo-server-'));
fs.writeFileSync(path.join(dir, '.env'), 'OPENROUTER_API_KEY=secret');
diff --git a/test/upload-browser.test.js b/test/upload-browser.test.js
new file mode 100644
index 0000000..42d6f28
--- /dev/null
+++ b/test/upload-browser.test.js
@@ -0,0 +1,55 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { findChrome } from '../src/browser.js';
+import { loadProject } from '../src/project.js';
+import { withEngine } from '../src/pipeline.js';
+
+// Regression test for long renders failing with ERR_STRING_TOO_LONG while the
+// soundtrack was uploaded: an ArrayBuffer request body is copied into the
+// DevTools event that Playwright reads as one string. The upload must arrive
+// intact, in bounded pieces, without its bytes travelling through the driver.
+let chrome;
+try { chrome = findChrome(); } catch {}
+test('engine uploads go up in bounded pieces that never pass through the driver', { skip: !chrome }, async () => {
+ const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'explainroo-upload-'));
+ try {
+ fs.writeFileSync(path.join(dir, 'video.json'), JSON.stringify({ theme: 'clean', captions: false, music: false, sfx: false }));
+ fs.writeFileSync(path.join(dir, 'script.md'), '## demo\nA sound.');
+ fs.writeFileSync(path.join(dir, 'scenes.js'), 'export default { demo(s) { s.text("demo", { at: 0 }); } };');
+ const project = loadProject(dir);
+ const timeline = { pace: 1, duration: 1, frames: 30, fps: 30, width: 1920, height: 1080, transitionSeconds: 0,
+ scenes: [{ id: 'demo', index: 0, start: 0, dur: 1, words: [], marks: {}, voice: null, lead: 0, transition: 'none' }] };
+ await withEngine(project, timeline, { scale: 0.25 }, async (page) => {
+ const puts = [];
+ page.on('request', (r) => {
+ if (r.method() === 'PUT') puts.push({ url: r.url(), driverBytes: r.postDataBuffer()?.length ?? 0 });
+ });
+ // 5 MB of pseudo-random bytes as an ArrayBuffer, like an encoded WAV, in 1 MB pieces
+ const size = 5 * 1024 * 1024 + 123;
+ const digest = await page.evaluate(async ({ size }) => {
+ const { upload } = await import('/engine/upload.js');
+ const bytes = new Uint8Array(size);
+ let x = 2463534242;
+ for (let i = 0; i < size; i++) { x ^= x << 13; x ^= x >>> 17; x ^= x << 5; bytes[i] = x & 255; }
+ await upload('build/big.bin', bytes.buffer, { chunkBytes: 1024 * 1024 });
+ const hash = await crypto.subtle.digest('SHA-256', bytes);
+ return [...new Uint8Array(hash)].map((b) => b.toString(16).padStart(2, '0')).join('');
+ }, { size });
+ const written = fs.readFileSync(path.join(dir, 'build', 'big.bin'));
+ assert.equal(written.length, size);
+ assert.equal(crypto.createHash('sha256').update(written).digest('hex'), digest);
+ assert.equal(puts.length, 6);
+ assert.deepEqual(puts.map((p) => Number(new URL(p.url).searchParams.get('offset'))), [0, 1, 2, 3, 4, 5].map((k) => k * 1024 * 1024));
+ assert.equal(new URL(puts.at(-1).url).searchParams.get('last'), '1');
+ const ids = new Set(puts.map((p) => new URL(p.url).searchParams.get('upload')));
+ assert.equal(ids.size, 1);
+ assert.match([...ids][0], /^[0-9a-f]{32}$/);
+ assert.ok(puts.every((p) => p.driverBytes === 0), 'request bodies must not be copied into the driver protocol');
+ assert.deepEqual(fs.readdirSync(path.join(dir, 'build')).filter((n) => n.endsWith('.part')), []);
+ });
+ } finally { fs.rmSync(dir, { recursive: true, force: true }); }
+});