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.

Balance caption phrases so no phrase is one lonely word (#18)

Vincent Schmalbach00a6e1230047
diff --git a/engine/captions.js b/engine/captions.js
index 6ed71af..96c85dd 100644
--- a/engine/captions.js
+++ b/engine/captions.js
@@ -6,24 +6,20 @@ import { clamp, ease } from './util.js';
export function buildPhrases(timeline, maxChars) {
const phrases = [];
for (const sc of timeline.scenes) {
- let cur = null;
+ // A sentence (or a run of words between long pauses) is split into as few
+ // phrases as fit, balanced in length, so no phrase is one lonely word.
+ let run = [];
const flush = () => {
- if (cur && cur.words.length) phrases.push(cur);
- cur = null;
+ for (const words of balancePhrases(run, maxChars)) phrases.push({ words, start: words[0].start, end: words[words.length - 1].end });
+ run = [];
};
- sc.words.forEach((w, i) => {
+ for (const w of sc.words) {
const g = { text: w.text, start: sc.start + w.start, end: sc.start + w.end };
- if (cur) {
- const len = cur.words.reduce((n, x) => n + x.text.length + 1, 0) + g.text.length;
- const gapBefore = g.start - cur.words[cur.words.length - 1].end;
- if (len > maxChars || gapBefore > 0.55) flush();
- }
- if (!cur) cur = { words: [], start: g.start };
- cur.words.push(g);
- cur.end = g.end;
- if (/[.!?;:।]["'’)]*$/.test(g.text) || (/,$/.test(g.text) && cur.words.length >= 4)) flush();
- });
- flush();
+ if (run.length && g.start - run[run.length - 1].end > 0.55) flush();
+ run.push(g);
+ if (/[.!?;:।]["'’)]*$/.test(g.text)) flush();
+ }
+ if (run.length) flush();
}
phrases.forEach((p, i) => {
const next = phrases[i + 1];
@@ -32,6 +28,30 @@ export function buildPhrases(timeline, maxChars) {
return phrases;
}
+// Splits words into the fewest phrases of at most maxChars characters, with
+// lengths as even as possible and breaks after commas where they fit.
+export function balancePhrases(words, maxChars) {
+ if (!words.length) return [];
+ const len = (a, b) => words.slice(a, b).reduce((n, w) => n + w.text.length + 1, -1);
+ if (len(0, words.length) <= maxChars) return [words];
+ const n = words.length;
+ const best = [{ parts: 0, cost: 0, from: -1 }];
+ for (let b = 1; b <= n; b++) {
+ best[b] = null;
+ for (let a = b - 1; a >= 0; a--) {
+ const l = len(a, b);
+ if (l > maxChars && b - a > 1) break;
+ if (!best[a]) continue;
+ const comma = b < n && /[,;:–—]["'’)]*$/.test(words[b - 1].text) ? 150 : 0;
+ const c = { parts: best[a].parts + 1, cost: best[a].cost + (maxChars - l) ** 2 - comma, from: a };
+ if (!best[b] || c.parts < best[b].parts || (c.parts === best[b].parts && c.cost < best[b].cost)) best[b] = c;
+ }
+ }
+ const out = [];
+ for (let b = n; b > 0; b = best[b].from) out.unshift(words.slice(best[b].from, b));
+ return out;
+}
+
// `area` ({ cx, bottom, maxWidth }) places the captions inside a platform's
// safe area, right above the band the app covers with its own text.
export function drawCaptions(ctx, phrases, T, theme, W, H, area = null) {
diff --git a/test/caption-phrases.test.js b/test/caption-phrases.test.js
new file mode 100644
index 0000000..4a09240
--- /dev/null
+++ b/test/caption-phrases.test.js
@@ -0,0 +1,35 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { buildPhrases, balancePhrases } from '../engine/captions.js';
+
+const words = (text, step = 0.3) => text.split(' ').map((t, i) => ({ text: t, start: i * step, end: i * step + 0.2 }));
+const texts = (phrases) => phrases.map((p) => p.words.map((w) => w.text).join(' '));
+
+test('a sentence that just overflows splits into balanced phrases, not a lonely last word', () => {
+ const phrases = buildPhrases({ scenes: [{ start: 0, words: words('La respuesta está en la luz del Sol y en el aire.') }] }, 46);
+ assert.equal(phrases.length, 2);
+ assert.ok(texts(phrases).every((t) => t.split(' ').length >= 3), texts(phrases).join(' | '));
+});
+
+test('phrases prefer a break after a comma and never exceed the limit', () => {
+ const out = balancePhrases(words('When the user arrives, its callback starts fetching the orders.'), 46);
+ assert.deepEqual(out.map((p) => p.map((w) => w.text).join(' ')), ['When the user arrives,', 'its callback starts fetching the orders.']);
+ const long = balancePhrases(words('Every phrase here stays within twenty eight characters on a phone screen.'), 28);
+ assert.ok(long.every((p) => p.map((w) => w.text).join(' ').length <= 28));
+});
+
+test('short sentences stay whole, sentences and long pauses start new phrases', () => {
+ const sc = { start: 1, words: [...words('One short line.'), { text: 'Next', start: 2, end: 2.2 }, { text: 'idea.', start: 2.3, end: 2.5 }] };
+ assert.deepEqual(texts(buildPhrases({ scenes: [sc] }, 46)), ['One short line.', 'Next idea.']);
+ const paused = { start: 0, words: [{ text: 'before', start: 0, end: 0.3 }, { text: 'after', start: 1.2, end: 1.5 }] };
+ assert.deepEqual(texts(buildPhrases({ scenes: [paused] }, 46)), ['before', 'after']);
+});
+
+test('a single word longer than the limit is its own phrase', () => {
+ assert.equal(balancePhrases(words('a supercalifragilisticexpialidocious word'), 10).length, 3);
+});
+
+test('a comma does not leave a lonely word behind', () => {
+ const out = balancePhrases(words('Yes, the browser asks a resolver for the address first.'), 46);
+ assert.ok(out.every((p) => p.length >= 3), out.map((p) => p.map((w) => w.text).join(' ')).join(' | '));
+});