keepitreel 0.1.0 → 0.1.1

package/README.md

@@ -196,26 +196,28 @@ Renders `start` to `end` of a clip as a 9:16 segment: the landscape picture sits
 |---|---|---|---|
 | `clipPath` | `string` | required | The source video |
 | `start`, `end` | `number` | required | Seconds into the clip |
-| `workDir` | `string` | required | Where the output and the text files ffmpeg reads go |
+| `workDir` | `string` | required | Where the output and the files ffmpeg reads go: the text, and the filter graph (`<name>.filter`), which keeps clips with hundreds of subtitle words within Windows' command-line limit |
 | `name` | `string` | required | The output's base name |
 | `subtitles` | `SubtitleChunk[]` | `[]` | From [`.subtitleChunks()`](#subtitlechunksoptions) |
 | `hook` | `{ band: { y, h, opacity }, lines, outSeconds }` | | A full-width ink band with text, up from the first frame, fading out `outSeconds` before the end |
 | `tag` | `{ box: { x, y, w, h, opacity }, lines, delay?, outSeconds?, fade? }` | | An ink box with text that fades in after `delay` and out before the end. With `fade: false` it is up for the whole clip |
 | `hold` | `number` | `0` | Seconds the first frame is held, silent, before the clip plays. Subtitles and mute windows move with it |
 | `mute` | `[number, number][]` | `[]` | Clip-relative windows where the sound is replaced by a beep |
+| `loudness` | `number` | | Target loudness in LUFS, e.g. `-14`. The clip's sound is normalized to it before beeps are mixed in. Without it the sound is left as it is |
 
 `lines` are [text lines](#text-lines).
 
 #### .subtitleChunks(options)
 
-Splits clip-relative words into one-line, centered chunks, breaking at sentence ends. A sentence longer than `maxWords` is cut into the fewest pieces that fit, differing by at most one word ("I heard you / were in town."): seven words become 4 + 3, and twenty-one become 5 + 4 + 4 + 4 + 4 rather than leaving one word over. A piece is split further while it is wider than `maxWidth`, so a word too wide to share a line gets one to itself. Returns an array of `{ start, end, words }`, where each word is placed with its `x`, `font`, `color` and `size`.
+Splits clip-relative words into one-line, centered chunks, breaking at sentence ends. A sentence longer than `maxWords` is cut into the fewest pieces that fit, differing by at most one word ("I heard you / were in town."): seven words become 4 + 3, and twenty-one become 5 + 4 + 4 + 4 + 4 rather than leaving one word over. A piece is split further while it is wider than `maxWidth`, so a word too wide to share a line gets one to itself. Returns an array of `{ start, end, words }`, where each word is placed with its `x`, `font`, `color` and `size`, plus `active: { start, end, color }` when `activeColor` is given.
 
 | Option | Type | Default | |
 |---|---|---|---|
 | `words` | `{ text, start, end }[]` | required | Clip-relative seconds |
 | `duration` | `number` | required | Length of the clip. No chunk stays up past it |
 | `font`, `color` | `string` | required | A font key and an ffmpeg color |
-| `style` | `(word) => { font?, color?, text? }` | | Per-word font, color or text, for a highlighted or blanked-out word |
+| `style` | `(word) => { font?, color?, text?, activeColor? }` | | Per-word font, color or text, for a highlighted or blanked-out word. Its `activeColor` overrides the option for that word, and `null` keeps the word's own color while it is spoken |
+| `activeColor` | `string` | | Karaoke style: each word takes this color while it is spoken, from its start to the next word's start (the line's end for the last word), so Whisper's early end times leave no gap. Without it words keep their color the whole line |
 | `size` | `number` | `56` | |
 | `baseline` | `number` | `1445` | Below the picture of a 4:3 film and above the apps' bottom UI zone |
 | `maxWords` | `number` | `5` | |

package/dist/video/index.cjs

@@ -135,7 +135,7 @@ ${stderr.slice(-1500)}`);
    * further while it is wider than `maxWidth`.
    */
   subtitleChunks(options) {
-    const { words, duration, font, color, style, size = 56, baseline = 1445, maxWords = 5, hold = 0.6, maxWidth = TEXT_WIDTH } = options;
+    const { words, duration, font, color, style, activeColor, size = 56, baseline = 1445, maxWords = 5, hold = 0.6, maxWidth = TEXT_WIDTH } = options;
     const styled = words.map((w) => ({ ...w, font, color, ...style?.(w) }));
     const space = this.textWidth(" ", font, size);
     const width = (ws) => ws.reduce((sum, w) => sum + this.textWidth(w.text, w.font, size), 0) + (ws.length - 1) * space;
@@ -172,39 +172,55 @@ ${stderr.slice(-1500)}`);
       const next = groups[i + 1]?.[0];
       const holdEnd = Math.min(duration, last.end + hold);
       const end = next ? Math.min(next.start, holdEnd) : holdEnd;
+      const start = Math.max(0, first.start);
+      const lineEnd = Math.max(end, first.start + 0.1);
       let x = (WIDTH - width(group)) / 2;
-      const placed = group.map((w) => {
+      const placed = group.map((w, j) => {
         const word = { text: w.text, font: w.font, color: w.color, size, baseline, x };
+        const spokenColor = w.activeColor === void 0 ? activeColor : w.activeColor;
+        if (spokenColor) {
+          const from = Math.max(start, w.start);
+          const to = j < group.length - 1 ? group[j + 1].start : lineEnd;
+          word.active = { start: from, end: Math.max(from, to), color: spokenColor };
+        }
         x += this.textWidth(w.text, w.font, size) + space;
         return word;
       });
-      return { start: Math.max(0, first.start), end: Math.max(end, first.start + 0.1), words: placed };
+      return { start, end: lineEnd, words: placed };
     });
   }
   // Each word is its own drawtext so a word can take another color.
   drawSubtitles(chunks, workDir, name) {
     return chunks.flatMap(
-      (chunk, c) => chunk.words.map(
-        (word, w) => this.drawtext(
-          workDir,
-          `${name}-sub${c}-${w}.txt`,
-          word,
-          `y=${word.baseline}-ascent:borderw=3:bordercolor=${this.ink}@0.85:enable='between(t,${chunk.start.toFixed(3)},${chunk.end.toFixed(3)})'`
-        )
-      )
+      (chunk, c) => chunk.words.flatMap((word, w) => {
+        const file = `${name}-sub${c}-${w}.txt`;
+        const look = `y=${word.baseline}-ascent:borderw=3:bordercolor=${this.ink}@0.85`;
+        const shown = `between(t,${chunk.start.toFixed(3)},${chunk.end.toFixed(3)})`;
+        if (!word.active) return [this.drawtext(workDir, file, word, `${look}:enable='${shown}'`)];
+        const spoken = `gte(t,${word.active.start.toFixed(3)})*lt(t,${word.active.end.toFixed(3)})`;
+        return [
+          this.drawtext(workDir, file, word, `${look}:enable='${shown}*not(${spoken})'`),
+          this.drawtext(workDir, file, { ...word, color: word.active.color }, `${look}:enable='${spoken}'`)
+        ];
+      })
     );
   }
   /**
    * Renders `start` to `end` of a clip as a 9:16 segment, with optional tag, hook, subtitles
    * and beeps. Returns the file name in `workDir`.
    */
-  async renderClip({ clipPath, start, end, tag, hook, hold = 0, subtitles = [], mute = [], workDir, name }) {
+  async renderClip({ clipPath, start, end, tag, hook, hold = 0, subtitles = [], mute = [], loudness, workDir, name }) {
     const duration = end - start + hold;
-    const subs = this.drawSubtitles(subtitles.map((c) => ({ ...c, start: c.start + hold, end: c.end + hold })), workDir, name);
+    const held = subtitles.map((c) => ({
+      start: c.start + hold,
+      end: c.end + hold,
+      words: c.words.map((w) => w.active ? { ...w, active: { ...w.active, start: w.active.start + hold, end: w.active.end + hold } } : w)
+    }));
+    const subs = this.drawSubtitles(held, workDir, name);
     const withSubs = (chain) => subs.length ? `${chain},${subs.join(",")}` : chain;
     const out = hook ? "[pre]" : "[v]";
     const input = `[0:v]${hold ? `tpad=start_duration=${hold.toFixed(3)}:start_mode=clone,` : ""}${FILL_9_16}`;
-    const sound = `[0:a]aresample=${SAMPLE_RATE}${hold ? `,adelay=${Math.round(hold * 1e3)}:all=1` : ""}`;
+    const sound = `[0:a]${loudness == null ? "" : `loudnorm=I=${loudness}:TP=-1.5:LRA=11,`}aresample=${SAMPLE_RATE}${hold ? `,adelay=${Math.round(hold * 1e3)}:all=1` : ""}`;
     let video = `${withSubs(input)}${out}`;
     if (tag) {
       const { box, lines, delay = 0, outSeconds = 0, fade = true } = tag;
@@ -236,9 +252,11 @@ ${stderr.slice(-1500)}`);
       const muted = `gt(${mute.map(([a, b]) => `between(t,${(a + hold).toFixed(3)},${(b + hold).toFixed(3)})`).join("+")},0)`;
       audio = `${sound},aformat=channel_layouts=stereo,volume=volume=0:enable='${muted}'[dry];aevalsrc='${BEEP_LEVEL}*sin(2*PI*${BEEP_HZ}*t)*${muted}':c=stereo:s=${SAMPLE_RATE}:d=${duration.toFixed(3)}[beep];[dry][beep]amix=inputs=2:normalize=0:duration=first[a]`;
     }
+    const graph = `${name}.filter`;
+    fs.writeFileSync(path.join(workDir, graph), `${video};${audio}`);
     const output = `${name}.mp4`;
     await this.run(
-      ["-ss", String(start), "-to", String(end), "-i", path.resolve(clipPath), "-filter_complex", `${video};${audio}`, "-map", "[v]", "-map", "[a]", ...OUTPUT_ARGS, output],
+      ["-ss", String(start), "-to", String(end), "-i", path.resolve(clipPath), "-filter_complex_script", graph, "-map", "[v]", "-map", "[a]", ...OUTPUT_ARGS, output],
       workDir
     );
     return output;

package/dist/video/index.d.cts

@@ -79,6 +79,12 @@ interface PlacedWord {
     size: number;
     baseline: number;
     x: number;
+    /** While the word is spoken (clip-relative seconds), it is drawn in `color` instead. */
+    active?: {
+        start: number;
+        end: number;
+        color: string;
+    };
 }
 /** One line of subtitles, shown from `start` to `end` (clip-relative seconds). */
 interface SubtitleChunk {
@@ -92,12 +98,21 @@ interface SubtitleOptions {
     duration: number;
     font: string;
     color: string;
-    /** Per-word font, color or text, such as a highlighted or blanked-out word. */
+    /**
+     * Per-word font, color or text, such as a highlighted or blanked-out word, and its own
+     * `activeColor` (`null` keeps the word's color while it is spoken).
+     */
     style?: (word: TimedWord) => {
         font?: string;
         color?: string;
         text?: string;
+        activeColor?: string | null;
     };
+    /**
+     * Color of each word while it is spoken, karaoke style: from its start to the next word's
+     * start, so early end times leave no gap, and to the line's end for its last word.
+     */
+    activeColor?: string;
     /** @default 56 */
     size?: number;
     /**
@@ -160,6 +175,11 @@ interface ClipOptions {
     subtitles?: SubtitleChunk[];
     /** [start, end] windows (clip-relative seconds) where the sound is replaced by a beep. */
     mute?: [number, number][];
+    /**
+     * Target integrated loudness in LUFS (e.g. -14). The clip's sound is normalized to it
+     * before any beep is mixed in, so beeps stay at the same level in every clip.
+     */
+    loudness?: number;
 }
 /** Renders 1080x1920 reel segments with ffmpeg and joins them. */
 declare class Renderer {
@@ -198,7 +218,7 @@ declare class Renderer {
      * Renders `start` to `end` of a clip as a 9:16 segment, with optional tag, hook, subtitles
      * and beeps. Returns the file name in `workDir`.
      */
-    renderClip({ clipPath, start, end, tag, hook, hold, subtitles, mute, workDir, name }: ClipOptions): Promise<string>;
+    renderClip({ clipPath, start, end, tag, hook, hold, subtitles, mute, loudness, workDir, name }: ClipOptions): Promise<string>;
     /**
      * 16 kHz mono 16-bit WAV of `input`, the format keepitreel/transcribe reads. Without
      * `start`/`end`, the whole file.

package/dist/video/index.d.ts

@@ -79,6 +79,12 @@ interface PlacedWord {
     size: number;
     baseline: number;
     x: number;
+    /** While the word is spoken (clip-relative seconds), it is drawn in `color` instead. */
+    active?: {
+        start: number;
+        end: number;
+        color: string;
+    };
 }
 /** One line of subtitles, shown from `start` to `end` (clip-relative seconds). */
 interface SubtitleChunk {
@@ -92,12 +98,21 @@ interface SubtitleOptions {
     duration: number;
     font: string;
     color: string;
-    /** Per-word font, color or text, such as a highlighted or blanked-out word. */
+    /**
+     * Per-word font, color or text, such as a highlighted or blanked-out word, and its own
+     * `activeColor` (`null` keeps the word's color while it is spoken).
+     */
     style?: (word: TimedWord) => {
         font?: string;
         color?: string;
         text?: string;
+        activeColor?: string | null;
     };
+    /**
+     * Color of each word while it is spoken, karaoke style: from its start to the next word's
+     * start, so early end times leave no gap, and to the line's end for its last word.
+     */
+    activeColor?: string;
     /** @default 56 */
     size?: number;
     /**
@@ -160,6 +175,11 @@ interface ClipOptions {
     subtitles?: SubtitleChunk[];
     /** [start, end] windows (clip-relative seconds) where the sound is replaced by a beep. */
     mute?: [number, number][];
+    /**
+     * Target integrated loudness in LUFS (e.g. -14). The clip's sound is normalized to it
+     * before any beep is mixed in, so beeps stay at the same level in every clip.
+     */
+    loudness?: number;
 }
 /** Renders 1080x1920 reel segments with ffmpeg and joins them. */
 declare class Renderer {
@@ -198,7 +218,7 @@ declare class Renderer {
      * Renders `start` to `end` of a clip as a 9:16 segment, with optional tag, hook, subtitles
      * and beeps. Returns the file name in `workDir`.
      */
-    renderClip({ clipPath, start, end, tag, hook, hold, subtitles, mute, workDir, name }: ClipOptions): Promise<string>;
+    renderClip({ clipPath, start, end, tag, hook, hold, subtitles, mute, loudness, workDir, name }: ClipOptions): Promise<string>;
     /**
      * 16 kHz mono 16-bit WAV of `input`, the format keepitreel/transcribe reads. Without
      * `start`/`end`, the whole file.

package/dist/video/index.js

@@ -131,7 +131,7 @@ ${stderr.slice(-1500)}`);
    * further while it is wider than `maxWidth`.
    */
   subtitleChunks(options) {
-    const { words, duration, font, color, style, size = 56, baseline = 1445, maxWords = 5, hold = 0.6, maxWidth = TEXT_WIDTH } = options;
+    const { words, duration, font, color, style, activeColor, size = 56, baseline = 1445, maxWords = 5, hold = 0.6, maxWidth = TEXT_WIDTH } = options;
     const styled = words.map((w) => ({ ...w, font, color, ...style?.(w) }));
     const space = this.textWidth(" ", font, size);
     const width = (ws) => ws.reduce((sum, w) => sum + this.textWidth(w.text, w.font, size), 0) + (ws.length - 1) * space;
@@ -168,39 +168,55 @@ ${stderr.slice(-1500)}`);
       const next = groups[i + 1]?.[0];
       const holdEnd = Math.min(duration, last.end + hold);
       const end = next ? Math.min(next.start, holdEnd) : holdEnd;
+      const start = Math.max(0, first.start);
+      const lineEnd = Math.max(end, first.start + 0.1);
       let x = (WIDTH - width(group)) / 2;
-      const placed = group.map((w) => {
+      const placed = group.map((w, j) => {
         const word = { text: w.text, font: w.font, color: w.color, size, baseline, x };
+        const spokenColor = w.activeColor === void 0 ? activeColor : w.activeColor;
+        if (spokenColor) {
+          const from = Math.max(start, w.start);
+          const to = j < group.length - 1 ? group[j + 1].start : lineEnd;
+          word.active = { start: from, end: Math.max(from, to), color: spokenColor };
+        }
         x += this.textWidth(w.text, w.font, size) + space;
         return word;
       });
-      return { start: Math.max(0, first.start), end: Math.max(end, first.start + 0.1), words: placed };
+      return { start, end: lineEnd, words: placed };
     });
   }
   // Each word is its own drawtext so a word can take another color.
   drawSubtitles(chunks, workDir, name) {
     return chunks.flatMap(
-      (chunk, c) => chunk.words.map(
-        (word, w) => this.drawtext(
-          workDir,
-          `${name}-sub${c}-${w}.txt`,
-          word,
-          `y=${word.baseline}-ascent:borderw=3:bordercolor=${this.ink}@0.85:enable='between(t,${chunk.start.toFixed(3)},${chunk.end.toFixed(3)})'`
-        )
-      )
+      (chunk, c) => chunk.words.flatMap((word, w) => {
+        const file = `${name}-sub${c}-${w}.txt`;
+        const look = `y=${word.baseline}-ascent:borderw=3:bordercolor=${this.ink}@0.85`;
+        const shown = `between(t,${chunk.start.toFixed(3)},${chunk.end.toFixed(3)})`;
+        if (!word.active) return [this.drawtext(workDir, file, word, `${look}:enable='${shown}'`)];
+        const spoken = `gte(t,${word.active.start.toFixed(3)})*lt(t,${word.active.end.toFixed(3)})`;
+        return [
+          this.drawtext(workDir, file, word, `${look}:enable='${shown}*not(${spoken})'`),
+          this.drawtext(workDir, file, { ...word, color: word.active.color }, `${look}:enable='${spoken}'`)
+        ];
+      })
     );
   }
   /**
    * Renders `start` to `end` of a clip as a 9:16 segment, with optional tag, hook, subtitles
    * and beeps. Returns the file name in `workDir`.
    */
-  async renderClip({ clipPath, start, end, tag, hook, hold = 0, subtitles = [], mute = [], workDir, name }) {
+  async renderClip({ clipPath, start, end, tag, hook, hold = 0, subtitles = [], mute = [], loudness, workDir, name }) {
     const duration = end - start + hold;
-    const subs = this.drawSubtitles(subtitles.map((c) => ({ ...c, start: c.start + hold, end: c.end + hold })), workDir, name);
+    const held = subtitles.map((c) => ({
+      start: c.start + hold,
+      end: c.end + hold,
+      words: c.words.map((w) => w.active ? { ...w, active: { ...w.active, start: w.active.start + hold, end: w.active.end + hold } } : w)
+    }));
+    const subs = this.drawSubtitles(held, workDir, name);
     const withSubs = (chain) => subs.length ? `${chain},${subs.join(",")}` : chain;
     const out = hook ? "[pre]" : "[v]";
     const input = `[0:v]${hold ? `tpad=start_duration=${hold.toFixed(3)}:start_mode=clone,` : ""}${FILL_9_16}`;
-    const sound = `[0:a]aresample=${SAMPLE_RATE}${hold ? `,adelay=${Math.round(hold * 1e3)}:all=1` : ""}`;
+    const sound = `[0:a]${loudness == null ? "" : `loudnorm=I=${loudness}:TP=-1.5:LRA=11,`}aresample=${SAMPLE_RATE}${hold ? `,adelay=${Math.round(hold * 1e3)}:all=1` : ""}`;
     let video = `${withSubs(input)}${out}`;
     if (tag) {
       const { box, lines, delay = 0, outSeconds = 0, fade = true } = tag;
@@ -232,9 +248,11 @@ ${stderr.slice(-1500)}`);
       const muted = `gt(${mute.map(([a, b]) => `between(t,${(a + hold).toFixed(3)},${(b + hold).toFixed(3)})`).join("+")},0)`;
       audio = `${sound},aformat=channel_layouts=stereo,volume=volume=0:enable='${muted}'[dry];aevalsrc='${BEEP_LEVEL}*sin(2*PI*${BEEP_HZ}*t)*${muted}':c=stereo:s=${SAMPLE_RATE}:d=${duration.toFixed(3)}[beep];[dry][beep]amix=inputs=2:normalize=0:duration=first[a]`;
     }
+    const graph = `${name}.filter`;
+    writeFileSync(join(workDir, graph), `${video};${audio}`);
     const output = `${name}.mp4`;
     await this.run(
-      ["-ss", String(start), "-to", String(end), "-i", resolve(clipPath), "-filter_complex", `${video};${audio}`, "-map", "[v]", "-map", "[a]", ...OUTPUT_ARGS, output],
+      ["-ss", String(start), "-to", String(end), "-i", resolve(clipPath), "-filter_complex_script", graph, "-map", "[v]", "-map", "[a]", ...OUTPUT_ARGS, output],
       workDir
     );
     return output;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "keepitreel",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Building blocks for automated short-form video: Whisper transcription, ffmpeg reel rendering, and publishing to YouTube Shorts, Facebook, Instagram and TikTok.",
   "type": "module",
   "exports": {