captions.js 0.3.1 → 0.4.1

package/README.md

@@ -7,7 +7,7 @@ Star or watch the repo on GitHub to get updates!
 
 # Captions.js
 
-A modern JavaScript library for adding captions to HTML5 videos with ease.
+Render styled animated captions on canvas — works both on client and server side using Node.js and FFmpeg.
 
 [**Live Demo**](https://maskin25.github.io/captions.js/)
 

package/dist/index.d.mts

@@ -138,6 +138,8 @@ type CaptionsOptions = {
     captions?: Caption[] | null;
     /** When false, caller must invoke {@link Captions.enable} manually. */
     autoEnable?: boolean;
+    /** Show debug bounding boxes around lines/blocks. */
+    debug?: boolean;
 };
 /**
  * Imperative controller that owns the Konva stage lifecycle for a single video element.
@@ -158,6 +160,7 @@ declare class Captions {
     private animationFrameId;
     private videoWidth;
     private videoHeight;
+    private readonly debug;
     private readonly handleResize;
     private readonly handleMetadata;
     private readonly animationLoop;

package/dist/index.d.ts

@@ -138,6 +138,8 @@ type CaptionsOptions = {
     captions?: Caption[] | null;
     /** When false, caller must invoke {@link Captions.enable} manually. */
     autoEnable?: boolean;
+    /** Show debug bounding boxes around lines/blocks. */
+    debug?: boolean;
 };
 /**
  * Imperative controller that owns the Konva stage lifecycle for a single video element.
@@ -158,6 +160,7 @@ declare class Captions {
     private animationFrameId;
     private videoWidth;
     private videoHeight;
+    private readonly debug;
     private readonly handleResize;
     private readonly handleMetadata;
     private readonly animationLoop;

package/dist/index.js

@@ -1229,13 +1229,14 @@ var splitCaptionsBytotalWordsToDisplay = (captions, totalWordsToDisplay, linesPe
   let currentLine = 1;
   const maxWordGapSec = 1;
   const isValidBlockGap = (currentBlock2, caption) => {
+    return true;
     return currentBlock2.length > 0 && caption.startTime - currentBlock2[currentBlock2.length - 1].endTime < maxWordGapSec || currentBlock2.length === 0;
   };
   while (currentCaptionIndex < captions.length) {
     const caption = captions[currentCaptionIndex];
-    if (currentSymbolsLength + caption.word.length <= totalWordsToDisplay && isValidBlockGap(currentBlock, caption)) {
+    if (currentSymbolsLength + caption.word.length + 1 <= totalWordsToDisplay && isValidBlockGap(currentBlock, caption)) {
       currentBlock.push(caption);
-      currentSymbolsLength += caption.word.length;
+      currentSymbolsLength += caption.word.length + 1;
       currentCaptionIndex++;
     } else if (linesPerPage > currentLine && isValidBlockGap(currentBlock, caption)) {
       currentBlock.push(caption);
@@ -1304,14 +1305,23 @@ var getCaptionsGroupY = (groupHeight, canvasWidth, canvasHeight, position, offse
   }
 };
 var alignLinesInGroup = (group, maxGroupWidth, xOffset) => {
-  group.children.forEach((line, i) => {
+  return group.children.map((line) => {
     const lineWords = line.children;
     const lineWordsWidth = lineWords.reduce(
       (acc, word, currentIndex) => acc + word.width() + (currentIndex > 0 ? xOffset : 0),
       0
     );
+    const lineHeight = lineWords.reduce(
+      (acc, word) => Math.max(acc, word.height()),
+      0
+    );
     const lineX = (maxGroupWidth - lineWordsWidth) / 2;
     line.x(lineX);
+    return {
+      line,
+      width: lineWordsWidth,
+      height: lineHeight
+    };
   });
 };
 var alphabetEN = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ";
@@ -1359,10 +1369,24 @@ function isArabic(text) {
 // src/canvas-captions/index.ts
 var import_object_hash = __toESM(require("object-hash"));
 var memo = {};
-var renderFrame = (captionsSettings, layoutSettings, captions, currentTime, targetSize, layer, toCoef, position) => {
-  const style = captionsSettings.style.name;
+var drawDebugBoundingBox = (parent, width, height, stroke, dash = [6, 4]) => {
+  const rect = new import_konva4.default.Rect({
+    x: 0,
+    y: 0,
+    width,
+    height,
+    stroke,
+    strokeWidth: 4,
+    dash,
+    listening: false
+  });
+  parent.add(rect);
+  rect.moveToTop();
+};
+var renderFrame = (captionsSettings, layoutSettings, captions, currentTime, targetSize, layer, toCoef, debug) => {
   const [width, height] = targetSize;
   const targetFontSize = captionsSettings.style.font.fontSize * (toCoef ?? 1);
+  const showDebugBoundingBoxes = Boolean(debug);
   let totalSymbolInLine = 0;
   const hash = (0, import_object_hash.default)({ captionsSettings });
   if (memo[hash]) {
@@ -1397,24 +1421,28 @@ var renderFrame = (captionsSettings, layoutSettings, captions, currentTime, targ
   }
   const chunks = splitCaptionsBytotalWordsToDisplay(
     captions,
-    totalSymbolInLine - 6,
+    totalSymbolInLine,
     captionsSettings.linesPerPage
   );
   const currentChunk = chunks.find(
     (chunk) => chunk[0].startTime <= currentTime && chunk[chunk.length - 1].endTime >= currentTime
   );
   const xOffset = targetFontSize * 0.1;
+  const wordSpacing = xOffset + (captionsSettings.animation === "bounce" ? 8 : 0) + (captionsSettings.style.font.fontCapitalize ? 2 : 0);
   const yOffset = captionsSettings.lineSpacing ?? 4;
   if (currentChunk) {
-    var group = new import_konva4.default.Group();
+    const group = new import_konva4.default.Group({
+      drawBorder: true
+    });
     let x = 0;
     let y = 0;
     let maxGroupWidth = 0;
     let groupWidth = 0;
     let groupHeight = 0;
-    let line = new import_konva4.default.Group();
+    let line = new import_konva4.default.Group({
+      drawBorder: true
+    });
     let currentSymbolsLength = 0;
-    let box = new import_konva4.default.Group();
     let current = void 0;
     currentChunk.forEach((caption, index) => {
       const isCurrentCaption = caption.startTime <= currentTime && caption.endTime >= currentTime;
@@ -1449,7 +1477,9 @@ var renderFrame = (captionsSettings, layoutSettings, captions, currentTime, targ
           shadowOffset: captionsSettings2.style.font.shadow ? {
             x: captionsSettings2.style.font.shadow?.fontShadowOffsetX ?? 0,
             y: captionsSettings2.style.font.shadow?.fontShadowOffsetY ?? 0
-          } : void 0
+          } : void 0,
+          listening: false,
+          perfectDrawEnabled: false
         });
       };
       const text = createKonvaText(
@@ -1478,8 +1508,8 @@ var renderFrame = (captionsSettings, layoutSettings, captions, currentTime, targ
           //progress: Math.min(1, (currentTime - caption.start_time) / 0.5),
         };
       }
-      x += text.width() + xOffset + (captionsSettings.animation === "bounce" ? 8 : 0) + (captionsSettings.style.font.fontCapitalize ? 2 : 0);
-      groupWidth += text.width() + (isLastWordInLine ? 0 : xOffset);
+      x += text.width() + wordSpacing;
+      groupWidth += text.width() + (isLastWordInLine ? 0 : wordSpacing);
       line.y(y);
       line.add(text);
       if (isLastWordInLine) {
@@ -1492,13 +1522,15 @@ var renderFrame = (captionsSettings, layoutSettings, captions, currentTime, targ
           maxGroupWidth = groupWidth;
         }
         groupWidth = 0;
-        line = new import_konva4.default.Group();
+        line = new import_konva4.default.Group({
+          drawBorder: true
+        });
         currentSymbolsLength = 0;
       } else {
-        currentSymbolsLength += caption.word.length;
+        currentSymbolsLength += caption.word.length + 1;
       }
     });
-    alignLinesInGroup(group, maxGroupWidth, xOffset);
+    const lineMetrics = alignLinesInGroup(group, maxGroupWidth, wordSpacing);
     const progress = Math.min(
       1,
       (currentTime - currentChunk[0].startTime) / 0.2
@@ -1511,8 +1543,8 @@ var renderFrame = (captionsSettings, layoutSettings, captions, currentTime, targ
         groupHeight,
         width,
         height,
-        position?.type ?? captionsSettings.position,
-        position?.positionTopOffset ?? captionsSettings.positionTopOffset ?? 0,
+        captionsSettings.position,
+        captionsSettings.positionTopOffset ?? 0,
         toCoef ?? 1
       )
     );
@@ -1526,6 +1558,12 @@ var renderFrame = (captionsSettings, layoutSettings, captions, currentTime, targ
       },
       current
     );
+    if (showDebugBoundingBoxes) {
+      drawDebugBoundingBox(group, maxGroupWidth, groupHeight, "#ff4081");
+      lineMetrics.forEach(({ line: line2, width: width2, height: height2 }) => {
+        drawDebugBoundingBox(line2, width2, height2, "#2196f3", [4, 3]);
+      });
+    }
     if (current?.text && captionsSettings.animation === "box-word") {
       current.text?.zIndex(10);
     }
@@ -1566,6 +1604,7 @@ var Captions = class {
     this.providedContainer = options.container;
     this.presetState = options.preset;
     this.captionsState = options.captions ?? null;
+    this.debug = options.debug ?? false;
     if (options.autoEnable ?? true) {
       this.enable();
     }
@@ -1582,7 +1621,7 @@ var Captions = class {
     this.stage = new import_konva5.default.Stage({
       container: this.containerElement
     });
-    this.layer = new import_konva5.default.Layer();
+    this.layer = new import_konva5.default.Layer({ listening: false });
     this.stage.add(this.layer);
     this.videoWidth = this.video.videoWidth;
     this.videoHeight = this.video.videoHeight;
@@ -1681,19 +1720,15 @@ var Captions = class {
       return;
     }
     this.layer.destroyChildren();
-    const captionsSettings = this.presetState.captionsSettings;
     renderFrame(
-      captionsSettings,
+      this.presetState.captionsSettings,
       void 0,
       this.captionsState || [],
       this.video.currentTime,
       [this.videoWidth, this.videoHeight],
       this.layer,
       2,
-      {
-        type: captionsSettings.position ?? "bottom",
-        positionTopOffset: captionsSettings.positionTopOffset ?? 0
-      }
+      this.debug
     );
   }
   syncStageDimensions() {
@@ -1734,7 +1769,11 @@ var Captions = class {
     container.style.width = "100%";
     container.style.height = "100%";
     container.style.pointerEvents = "none";
-    this.video.parentElement?.appendChild(container);
+    const parent = this.video.parentElement;
+    parent?.appendChild(container);
+    if (parent) {
+      parent.style.position = "relative";
+    }
     return container;
   }
 };

package/dist/index.mjs

@@ -1187,13 +1187,14 @@ var splitCaptionsBytotalWordsToDisplay = (captions, totalWordsToDisplay, linesPe
   let currentLine = 1;
   const maxWordGapSec = 1;
   const isValidBlockGap = (currentBlock2, caption) => {
+    return true;
     return currentBlock2.length > 0 && caption.startTime - currentBlock2[currentBlock2.length - 1].endTime < maxWordGapSec || currentBlock2.length === 0;
   };
   while (currentCaptionIndex < captions.length) {
     const caption = captions[currentCaptionIndex];
-    if (currentSymbolsLength + caption.word.length <= totalWordsToDisplay && isValidBlockGap(currentBlock, caption)) {
+    if (currentSymbolsLength + caption.word.length + 1 <= totalWordsToDisplay && isValidBlockGap(currentBlock, caption)) {
       currentBlock.push(caption);
-      currentSymbolsLength += caption.word.length;
+      currentSymbolsLength += caption.word.length + 1;
       currentCaptionIndex++;
     } else if (linesPerPage > currentLine && isValidBlockGap(currentBlock, caption)) {
       currentBlock.push(caption);
@@ -1262,14 +1263,23 @@ var getCaptionsGroupY = (groupHeight, canvasWidth, canvasHeight, position, offse
   }
 };
 var alignLinesInGroup = (group, maxGroupWidth, xOffset) => {
-  group.children.forEach((line, i) => {
+  return group.children.map((line) => {
     const lineWords = line.children;
     const lineWordsWidth = lineWords.reduce(
       (acc, word, currentIndex) => acc + word.width() + (currentIndex > 0 ? xOffset : 0),
       0
     );
+    const lineHeight = lineWords.reduce(
+      (acc, word) => Math.max(acc, word.height()),
+      0
+    );
     const lineX = (maxGroupWidth - lineWordsWidth) / 2;
     line.x(lineX);
+    return {
+      line,
+      width: lineWordsWidth,
+      height: lineHeight
+    };
   });
 };
 var alphabetEN = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ";
@@ -1317,10 +1327,24 @@ function isArabic(text) {
 // src/canvas-captions/index.ts
 import objectHash from "object-hash";
 var memo = {};
-var renderFrame = (captionsSettings, layoutSettings, captions, currentTime, targetSize, layer, toCoef, position) => {
-  const style = captionsSettings.style.name;
+var drawDebugBoundingBox = (parent, width, height, stroke, dash = [6, 4]) => {
+  const rect = new Konva4.Rect({
+    x: 0,
+    y: 0,
+    width,
+    height,
+    stroke,
+    strokeWidth: 4,
+    dash,
+    listening: false
+  });
+  parent.add(rect);
+  rect.moveToTop();
+};
+var renderFrame = (captionsSettings, layoutSettings, captions, currentTime, targetSize, layer, toCoef, debug) => {
   const [width, height] = targetSize;
   const targetFontSize = captionsSettings.style.font.fontSize * (toCoef ?? 1);
+  const showDebugBoundingBoxes = Boolean(debug);
   let totalSymbolInLine = 0;
   const hash = objectHash({ captionsSettings });
   if (memo[hash]) {
@@ -1355,24 +1379,28 @@ var renderFrame = (captionsSettings, layoutSettings, captions, currentTime, targ
   }
   const chunks = splitCaptionsBytotalWordsToDisplay(
     captions,
-    totalSymbolInLine - 6,
+    totalSymbolInLine,
     captionsSettings.linesPerPage
   );
   const currentChunk = chunks.find(
     (chunk) => chunk[0].startTime <= currentTime && chunk[chunk.length - 1].endTime >= currentTime
   );
   const xOffset = targetFontSize * 0.1;
+  const wordSpacing = xOffset + (captionsSettings.animation === "bounce" ? 8 : 0) + (captionsSettings.style.font.fontCapitalize ? 2 : 0);
   const yOffset = captionsSettings.lineSpacing ?? 4;
   if (currentChunk) {
-    var group = new Konva4.Group();
+    const group = new Konva4.Group({
+      drawBorder: true
+    });
     let x = 0;
     let y = 0;
     let maxGroupWidth = 0;
     let groupWidth = 0;
     let groupHeight = 0;
-    let line = new Konva4.Group();
+    let line = new Konva4.Group({
+      drawBorder: true
+    });
     let currentSymbolsLength = 0;
-    let box = new Konva4.Group();
     let current = void 0;
     currentChunk.forEach((caption, index) => {
       const isCurrentCaption = caption.startTime <= currentTime && caption.endTime >= currentTime;
@@ -1407,7 +1435,9 @@ var renderFrame = (captionsSettings, layoutSettings, captions, currentTime, targ
           shadowOffset: captionsSettings2.style.font.shadow ? {
             x: captionsSettings2.style.font.shadow?.fontShadowOffsetX ?? 0,
             y: captionsSettings2.style.font.shadow?.fontShadowOffsetY ?? 0
-          } : void 0
+          } : void 0,
+          listening: false,
+          perfectDrawEnabled: false
         });
       };
       const text = createKonvaText(
@@ -1436,8 +1466,8 @@ var renderFrame = (captionsSettings, layoutSettings, captions, currentTime, targ
           //progress: Math.min(1, (currentTime - caption.start_time) / 0.5),
         };
       }
-      x += text.width() + xOffset + (captionsSettings.animation === "bounce" ? 8 : 0) + (captionsSettings.style.font.fontCapitalize ? 2 : 0);
-      groupWidth += text.width() + (isLastWordInLine ? 0 : xOffset);
+      x += text.width() + wordSpacing;
+      groupWidth += text.width() + (isLastWordInLine ? 0 : wordSpacing);
       line.y(y);
       line.add(text);
       if (isLastWordInLine) {
@@ -1450,13 +1480,15 @@ var renderFrame = (captionsSettings, layoutSettings, captions, currentTime, targ
           maxGroupWidth = groupWidth;
         }
         groupWidth = 0;
-        line = new Konva4.Group();
+        line = new Konva4.Group({
+          drawBorder: true
+        });
         currentSymbolsLength = 0;
       } else {
-        currentSymbolsLength += caption.word.length;
+        currentSymbolsLength += caption.word.length + 1;
       }
     });
-    alignLinesInGroup(group, maxGroupWidth, xOffset);
+    const lineMetrics = alignLinesInGroup(group, maxGroupWidth, wordSpacing);
     const progress = Math.min(
       1,
       (currentTime - currentChunk[0].startTime) / 0.2
@@ -1469,8 +1501,8 @@ var renderFrame = (captionsSettings, layoutSettings, captions, currentTime, targ
         groupHeight,
         width,
         height,
-        position?.type ?? captionsSettings.position,
-        position?.positionTopOffset ?? captionsSettings.positionTopOffset ?? 0,
+        captionsSettings.position,
+        captionsSettings.positionTopOffset ?? 0,
         toCoef ?? 1
       )
     );
@@ -1484,6 +1516,12 @@ var renderFrame = (captionsSettings, layoutSettings, captions, currentTime, targ
       },
       current
     );
+    if (showDebugBoundingBoxes) {
+      drawDebugBoundingBox(group, maxGroupWidth, groupHeight, "#ff4081");
+      lineMetrics.forEach(({ line: line2, width: width2, height: height2 }) => {
+        drawDebugBoundingBox(line2, width2, height2, "#2196f3", [4, 3]);
+      });
+    }
     if (current?.text && captionsSettings.animation === "box-word") {
       current.text?.zIndex(10);
     }
@@ -1524,6 +1562,7 @@ var Captions = class {
     this.providedContainer = options.container;
     this.presetState = options.preset;
     this.captionsState = options.captions ?? null;
+    this.debug = options.debug ?? false;
     if (options.autoEnable ?? true) {
       this.enable();
     }
@@ -1540,7 +1579,7 @@ var Captions = class {
     this.stage = new Konva5.Stage({
       container: this.containerElement
     });
-    this.layer = new Konva5.Layer();
+    this.layer = new Konva5.Layer({ listening: false });
     this.stage.add(this.layer);
     this.videoWidth = this.video.videoWidth;
     this.videoHeight = this.video.videoHeight;
@@ -1639,19 +1678,15 @@ var Captions = class {
       return;
     }
     this.layer.destroyChildren();
-    const captionsSettings = this.presetState.captionsSettings;
     renderFrame(
-      captionsSettings,
+      this.presetState.captionsSettings,
       void 0,
       this.captionsState || [],
       this.video.currentTime,
       [this.videoWidth, this.videoHeight],
       this.layer,
       2,
-      {
-        type: captionsSettings.position ?? "bottom",
-        positionTopOffset: captionsSettings.positionTopOffset ?? 0
-      }
+      this.debug
     );
   }
   syncStageDimensions() {
@@ -1692,7 +1727,11 @@ var Captions = class {
     container.style.width = "100%";
     container.style.height = "100%";
     container.style.pointerEvents = "none";
-    this.video.parentElement?.appendChild(container);
+    const parent = this.video.parentElement;
+    parent?.appendChild(container);
+    if (parent) {
+      parent.style.position = "relative";
+    }
     return container;
   }
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "captions.js",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "private": false,
   "license": "MIT",
   "repository": {