Add Video thumbnail tile option (#47)

* Add video thumbnail tile option

* Changesets

Author: 11bit

.changeset/moody-coins-wink.md

@@ -0,0 +1,5 @@
+---
+"@imgproxy/imgproxy-js-core": minor
+---
+
+Add [Video thumbnail tile](https://docs.imgproxy.net/usage/processing#video-thumbnail-tile) option

src/options/index.ts

@@ -62,6 +62,7 @@ export * as trim from "./trim";
 export * as unsharpMasking from "./unsharpMasking";
 export * as videoThumbnailSecond from "../optionsShared/videoThumbnailSecond";
 export * as videoThumbnailAnimation from "./videoThumbnailAnimation";
+export * as videoThumbnailTile from "./videoThumbnailTile";
 export * as watermark from "./watermark";
 export * as watermarkShadow from "./watermarkShadow";
 export * as watermarkSize from "./watermarkSize";

src/options/videoThumbnailTile.ts

@@ -0,0 +1,49 @@
+import { VideoThumbnailTileOptionsPartial } from "../types/videoThumbnailTile";
+import { guardIsNotNum, guardIsUndef, normalizeBoolean } from "../utils";
+
+function getOpts(options: VideoThumbnailTileOptionsPartial) {
+  return options.video_thumbnail_tile || options.vtt;
+}
+
+function test(options: VideoThumbnailTileOptionsPartial) {
+  return Boolean(getOpts(options));
+}
+
+function build(options: VideoThumbnailTileOptionsPartial) {
+  const vtt = getOpts(options);
+  guardIsUndef(vtt, "video_thumbnail_tile");
+
+  guardIsNotNum(vtt.step, "video_thumbnail_tile.step");
+  guardIsNotNum(vtt.columns, "video_thumbnail_tile.columns");
+  guardIsNotNum(vtt.rows, "video_thumbnail_tile.rows");
+  guardIsNotNum(vtt.tile_width, "video_thumbnail_tile.tile_width");
+  guardIsNotNum(vtt.tile_height, "video_thumbnail_tile.tile_height");
+
+  const parts = [];
+
+  // Add boolean flags with proper normalization
+  const extend_tile =
+    vtt.extend_tile !== undefined
+      ? normalizeBoolean(vtt.extend_tile)
+      : undefined;
+  const trim = vtt.trim !== undefined ? normalizeBoolean(vtt.trim) : undefined;
+  const fill = vtt.fill !== undefined ? normalizeBoolean(vtt.fill) : undefined;
+
+  parts.push(extend_tile, trim, fill);
+
+  // Add focus coordinates if fill is true and coordinates are defined
+  if (fill === "t") {
+    parts.push(vtt.focus_x, vtt.focus_y);
+  }
+
+  // Remove trailing undefined values
+  while (parts.length > 0 && parts[parts.length - 1] === undefined) {
+    parts.pop();
+  }
+
+  const optionsPart = parts.length > 0 ? `:${parts.join(":")}` : "";
+
+  return `vtt:${vtt.step}:${vtt.columns}:${vtt.rows}:${vtt.tile_width}:${vtt.tile_height}${optionsPart}`;
+}
+
+export { test, build };

src/types/index.ts

@@ -61,6 +61,7 @@ import type { StyleOptionsPartial } from "./style";
 import type { TrimOptionsPartial } from "./trim";
 import type { UnsharpMaskingOptionsPartial } from "./unsharpMasking";
 import type { VideoThumbnailAnimationOptionsPartial } from "./videoThumbnailAnimation";
+import type { VideoThumbnailTileOptionsPartial } from "./videoThumbnailTile";
 import type { VideoThumbnailSecondOptionsPartial } from "../typesShared/videoThumbnailSecond";
 import type { WatermarkOptionsPartial } from "./watermark";
 import type { WatermarkRotateOptionsPartial } from "./watermarkRotate";
@@ -136,6 +137,7 @@ export type Options = AdjustOptionsPartial &
   TrimOptionsPartial &
   UnsharpMaskingOptionsPartial &
   VideoThumbnailAnimationOptionsPartial &
+  VideoThumbnailTileOptionsPartial &
   VideoThumbnailSecondOptionsPartial &
   WatermarkOptionsPartial &
   WatermarkShadowOptionsPartial &

src/types/videoThumbnailTile.ts

@@ -0,0 +1,66 @@
+/**
+ * *Video thumbnail tile option*. **PRO feature**
+ *
+ * Generate a tiled sprite using the source video frames.
+ */
+interface VideoThumbnailTile {
+  /**
+   * step: the step of timestamp (in seconds) between video frames that should be used for the sprite generation:
+   *     When step value is positive, imgproxy will use it as an absolute value
+   *     When step value is negative, imgproxy will calculate the actual step as video_duration / (columns * rows)
+   */
+  step: number;
+
+  /**
+   * the number of columns in the sprite
+   */
+  columns: number;
+
+  /**
+   * the number of rows in the sprite
+   */
+  rows: number;
+
+  /**
+   * the width and height of tiles. imgproxy will resize each used frame to fit the provided size
+   */
+  tile_width: number;
+  tile_height: number;
+
+  /**
+   * when set to 1, t or true, imgproxy will extend each tile to the requested size using a black background
+   */
+  extend_tile?: boolean | 1 | string;
+
+  /**
+   * when set to 1, t or true, imgproxy will trim the unused sprite space
+   */
+  trim?: boolean | 1 | string;
+
+  /**
+   * when set to 1, t or true, imgproxy will use the fill resizing type for the tiles
+   */
+  fill?: boolean | 1 | string;
+
+  /**
+   * floating point numbers between 0 and 1 that define the coordinates of the center of the resulting tile
+   * (as in the fp gravity type). Treat 0 and 1 as right/left for x and top/bottom for y.
+   * Applicable only when fill is set. Default: 0.5:0.5
+   */
+  focus_x?: number;
+  focus_y?: number;
+}
+
+/**
+ * *Video thumbnail tile option*. **PRO feature**
+ *
+ * Allows generating a tiled sprite using the source video frames.
+ *
+ * @see https://docs.imgproxy.net/usage/processing#video-thumbnail-tile
+ */
+interface VideoThumbnailTileOptionsPartial {
+  video_thumbnail_tile?: VideoThumbnailTile;
+  vtt?: VideoThumbnailTile;
+}
+
+export { VideoThumbnailTile, VideoThumbnailTileOptionsPartial };

tests/optionsBasic/videoThumbnailTile.test.ts

@@ -0,0 +1,172 @@
+import { assertType, describe, expect, expectTypeOf, it } from "vitest";
+import { test, build } from "../../src/options/videoThumbnailTile";
+import { VideoThumbnailTile } from "../../src/types/videoThumbnailTile";
+import { Options } from "../../src/types";
+
+describe("videoThumbnailTile", () => {
+  describe("test", () => {
+    it("should return true if video_thumbnail_tile option is defined", () => {
+      const vtt: VideoThumbnailTile = {
+        step: 1,
+        columns: 3,
+        rows: 3,
+        tile_width: 320,
+        tile_height: 240,
+      };
+      expect(test({ video_thumbnail_tile: vtt })).toEqual(true);
+    });
+
+    it("should return true if vtt option is defined", () => {
+      const vtt: VideoThumbnailTile = {
+        step: 2,
+        columns: 4,
+        rows: 3,
+        tile_width: 320,
+        tile_height: 240,
+      };
+      expect(test({ vtt })).toEqual(true);
+    });
+
+    it("should return false if video_thumbnail_tile option is undefined", () => {
+      expect(test({})).toEqual(false);
+    });
+  });
+
+  describe("build", () => {
+    it("should throw an error if video_thumbnail_tile option is undefined", () => {
+      expect(() => build({})).toThrow(
+        "video_thumbnail_tile option is undefined"
+      );
+    });
+
+    it("should build basic vtt option with required parameters", () => {
+      const vtt: VideoThumbnailTile = {
+        step: 1.5,
+        columns: 3,
+        rows: 3,
+        tile_width: 320,
+        tile_height: 240,
+      };
+      expect(build({ video_thumbnail_tile: vtt })).toEqual(
+        "vtt:1.5:3:3:320:240"
+      );
+    });
+
+    it("should build vtt option with extend_tile as boolean", () => {
+      const vtt: VideoThumbnailTile = {
+        step: 1,
+        columns: 3,
+        rows: 3,
+        tile_width: 320,
+        tile_height: 240,
+        extend_tile: true,
+      };
+      expect(build({ vtt })).toEqual("vtt:1:3:3:320:240:t");
+    });
+
+    it("should build vtt option with extend_tile as number", () => {
+      const vtt: VideoThumbnailTile = {
+        step: 1,
+        columns: 3,
+        rows: 3,
+        tile_width: 320,
+        tile_height: 240,
+        extend_tile: 1,
+      };
+      expect(build({ vtt })).toEqual("vtt:1:3:3:320:240:t");
+    });
+
+    it("should build vtt option with trim flag", () => {
+      const vtt: VideoThumbnailTile = {
+        step: 1,
+        columns: 3,
+        rows: 3,
+        tile_width: 320,
+        tile_height: 240,
+        trim: true,
+      };
+      expect(build({ vtt })).toEqual("vtt:1:3:3:320:240::t");
+    });
+
+    it("should build vtt option with fill flag", () => {
+      const vtt: VideoThumbnailTile = {
+        step: 1,
+        columns: 3,
+        rows: 3,
+        tile_width: 320,
+        tile_height: 240,
+        fill: true,
+      };
+      expect(build({ vtt })).toEqual("vtt:1:3:3:320:240:::t");
+    });
+
+    it("should build vtt option with focus coordinates", () => {
+      const vtt: VideoThumbnailTile = {
+        step: 1,
+        columns: 3,
+        rows: 3,
+        tile_width: 320,
+        tile_height: 240,
+        fill: true,
+        focus_x: 0.3,
+        focus_y: 0.7,
+      };
+      expect(build({ vtt })).toEqual("vtt:1:3:3:320:240:::t:0.3:0.7");
+    });
+
+    it("should build vtt option with all parameters", () => {
+      const vtt: VideoThumbnailTile = {
+        step: -1,
+        columns: 4,
+        rows: 3,
+        tile_width: 640,
+        tile_height: 480,
+        extend_tile: true,
+        trim: true,
+        fill: true,
+        focus_x: 0.5,
+        focus_y: 0.5,
+      };
+      expect(build({ video_thumbnail_tile: vtt })).toEqual(
+        "vtt:-1:4:3:640:480:t:t:t:0.5:0.5"
+      );
+    });
+  });
+});
+
+describe("Check `video_thumbnail_tile` type declarations", () => {
+  it("video_thumbnail_tile option should have correct type", () => {
+    expectTypeOf(build).parameter(0).toEqualTypeOf<{
+      video_thumbnail_tile?: VideoThumbnailTile;
+      vtt?: VideoThumbnailTile;
+    }>();
+    expectTypeOf(build).returns.toEqualTypeOf<string>();
+  });
+
+  it("check TS type declaration", () => {
+    assertType<Options>({
+      video_thumbnail_tile: {
+        step: 1,
+        columns: 3,
+        rows: 3,
+        tile_width: 320,
+        tile_height: 240,
+      },
+    });
+
+    assertType<Options>({
+      vtt: {
+        step: 1,
+        columns: 3,
+        rows: 3,
+        tile_width: 320,
+        tile_height: 240,
+        extend_tile: true,
+        trim: true,
+        fill: true,
+        focus_x: 0.5,
+        focus_y: 0.5,
+      },
+    });
+  });
+});