Expose keepDuplicateFrames GIF output parameter

docs/src/content/docs/api-output.md

@@ -496,6 +496,7 @@ The palette of the input image will be re-used if possible.
 | [options.dither] | <code>number</code> | <code>1.0</code> | level of Floyd-Steinberg error diffusion, between 0 (least) and 1 (most) |
 | [options.interFrameMaxError] | <code>number</code> | <code>0</code> | maximum inter-frame error for transparency, between 0 (lossless) and 32 |
 | [options.interPaletteMaxError] | <code>number</code> | <code>3</code> | maximum inter-palette error for palette reuse, between 0 and 256 |
+| [options.keepDuplicateFrames] | <code>boolean</code> | <code>false</code> | keep duplicate frames in the output instead of combining them |
 | [options.loop] | <code>number</code> | <code>0</code> | number of animation iterations, use 0 for infinite animation |
 | [options.delay] | <code>number</code> \| <code>Array.&lt;number&gt;</code> |  | delay(s) between animation frames (in milliseconds) |
 | [options.force] | <code>boolean</code> | <code>true</code> | force GIF output, otherwise attempt to use input format |

docs/src/content/docs/changelog.md

@@ -12,6 +12,8 @@ Requires libvips v8.17.0
 
 * Add "Magic Kernel Sharp" (no relation) to resizing kernels.
 
+* Expose `keepDuplicateFrames` GIF output parameter.
+
 * Expose JPEG 2000 `oneshot` decoder option.
   [#4262](https://github.com/lovell/sharp/pull/4262)
   [@mbklein](https://github.com/mbklein)

lib/constructor.js

@@ -338,6 +338,7 @@ const Sharp = function (input, options) {
     gifDither: 1,
     gifInterFrameMaxError: 0,
     gifInterPaletteMaxError: 3,
+    gifKeepDuplicateFrames: false,
     gifReuse: true,
     gifProgressive: false,
     tiffQuality: 80,

lib/index.d.ts

@@ -1392,9 +1392,11 @@ declare namespace sharp {
         /** Level of Floyd-Steinberg error diffusion, between 0 (least) and 1 (most) (optional, default 1.0) */
         dither?: number | undefined;
         /** Maximum inter-frame error for transparency, between 0 (lossless) and 32 (optional, default 0) */
-        interFrameMaxError?: number;
+        interFrameMaxError?: number | undefined;
         /** Maximum inter-palette error for palette reuse, between 0 and 256 (optional, default 3) */
-        interPaletteMaxError?: number;
+        interPaletteMaxError?: number | undefined;
+        /** Keep duplicate frames in the output instead of combining them (optional, default false) */
+        keepDuplicateFrames?: boolean | undefined;
     }
 
     interface TiffOptions extends OutputOptions {

lib/output.js

@@ -729,6 +729,7 @@ function webp (options) {
  * @param {number} [options.dither=1.0] - level of Floyd-Steinberg error diffusion, between 0 (least) and 1 (most)
  * @param {number} [options.interFrameMaxError=0] - maximum inter-frame error for transparency, between 0 (lossless) and 32
  * @param {number} [options.interPaletteMaxError=3] - maximum inter-palette error for palette reuse, between 0 and 256
+ * @param {boolean} [options.keepDuplicateFrames=false] - keep duplicate frames in the output instead of combining them
  * @param {number} [options.loop=0] - number of animation iterations, use 0 for infinite animation
  * @param {number|number[]} [options.delay] - delay(s) between animation frames (in milliseconds)
  * @param {boolean} [options.force=true] - force GIF output, otherwise attempt to use input format
@@ -779,6 +780,13 @@ function gif (options) {
         throw is.invalidParameterError('interPaletteMaxError', 'number between 0.0 and 256.0', options.interPaletteMaxError);
       }
     }
+    if (is.defined(options.keepDuplicateFrames)) {
+      if (is.bool(options.keepDuplicateFrames)) {
+        this._setBooleanOption('gifKeepDuplicateFrames', options.keepDuplicateFrames);
+      } else {
+        throw is.invalidParameterError('keepDuplicateFrames', 'boolean', options.keepDuplicateFrames);
+      }
+    }
   }
   trySetAnimationOptions(options, this.options);
   return this._updateFormatOut('gif', options);

src/pipeline.cc

@@ -1006,6 +1006,7 @@ class PipelineWorker : public Napi::AsyncWorker {
             ->set("interlace", baton->gifProgressive)
             ->set("interframe_maxerror", baton->gifInterFrameMaxError)
             ->set("interpalette_maxerror", baton->gifInterPaletteMaxError)
+            ->set("keep_duplicate_frames", baton->gifKeepDuplicateFrames)
             ->set("dither", baton->gifDither)));
           baton->bufferOut = static_cast<char*>(area->data);
           baton->bufferOutLength = area->length;
@@ -1209,6 +1210,9 @@ class PipelineWorker : public Napi::AsyncWorker {
             ->set("effort", baton->gifEffort)
             ->set("reuse", baton->gifReuse)
             ->set("interlace", baton->gifProgressive)
+            ->set("interframe_maxerror", baton->gifInterFrameMaxError)
+            ->set("interpalette_maxerror", baton->gifInterPaletteMaxError)
+            ->set("keep_duplicate_frames", baton->gifKeepDuplicateFrames)
             ->set("dither", baton->gifDither));
           baton->formatOut = "gif";
         } else if (baton->formatOut == "tiff" || (mightMatchInput && isTiff) ||
@@ -1761,6 +1765,7 @@ Napi::Value pipeline(const Napi::CallbackInfo& info) {
   baton->gifDither = sharp::AttrAsDouble(options, "gifDither");
   baton->gifInterFrameMaxError = sharp::AttrAsDouble(options, "gifInterFrameMaxError");
   baton->gifInterPaletteMaxError = sharp::AttrAsDouble(options, "gifInterPaletteMaxError");
+  baton->gifKeepDuplicateFrames = sharp::AttrAsBool(options, "gifKeepDuplicateFrames");
   baton->gifReuse = sharp::AttrAsBool(options, "gifReuse");
   baton->gifProgressive = sharp::AttrAsBool(options, "gifProgressive");
   baton->tiffQuality = sharp::AttrAsUint32(options, "tiffQuality");

src/pipeline.h

@@ -169,6 +169,7 @@ struct PipelineBaton {
   double gifDither;
   double gifInterFrameMaxError;
   double gifInterPaletteMaxError;
+  bool gifKeepDuplicateFrames;
   bool gifReuse;
   bool gifProgressive;
   int tiffQuality;
@@ -342,6 +343,7 @@ struct PipelineBaton {
     gifDither(1.0),
     gifInterFrameMaxError(0.0),
     gifInterPaletteMaxError(3.0),
+    gifKeepDuplicateFrames(false),
     gifReuse(true),
     gifProgressive(false),
     tiffQuality(80),

test/types/sharp.test-d.ts

@@ -375,6 +375,8 @@ sharp(input)
   .gif({ reuse: false })
   .gif({ progressive: true })
   .gif({ progressive: false })
+  .gif({ keepDuplicateFrames: true })
+  .gif({ keepDuplicateFrames: false })
   .toBuffer({ resolveWithObject: true })
   .then(({ data, info }) => {
     console.log(data);

test/unit/gif.js

@@ -187,6 +187,17 @@ describe('GIF input', () => {
     );
   });
 
+  it('invalid keepDuplicateFrames throws', () => {
+    assert.throws(
+      () => sharp().gif({ keepDuplicateFrames: -1 }),
+      /Expected boolean for keepDuplicateFrames but received -1 of type number/
+    );
+    assert.throws(
+      () => sharp().gif({ keepDuplicateFrames: 'fail' }),
+      /Expected boolean for keepDuplicateFrames but received fail of type string/
+    );
+  });
+
   it('should work with streams when only animated is set', function (done) {
     fs.createReadStream(fixtures.inputGifAnimated)
       .pipe(sharp({ animated: true }))
@@ -225,6 +236,20 @@ describe('GIF input', () => {
     assert.strict(before.length > after.length);
   });
 
+  it('should keep duplicate frames via keepDuplicateFrames', async () => {
+    const create = { width: 8, height: 8, channels: 4, background: 'blue' };
+    const input = sharp([{ create }, { create }], { join: { animated: true } });
+
+    const before = await input.gif({ keepDuplicateFrames: false }).toBuffer();
+    const after = await input.gif({ keepDuplicateFrames: true }).toBuffer();
+    assert.strict(before.length < after.length);
+
+    const beforeMeta = await sharp(before).metadata();
+    const afterMeta = await sharp(after).metadata();
+    assert.strictEqual(beforeMeta.pages, 1);
+    assert.strictEqual(afterMeta.pages, 2);
+  });
+
   it('non-animated input defaults to no-loop', async () => {
     for (const input of [fixtures.inputGif, fixtures.inputPng]) {
       const data = await sharp(input)