flipbook 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4c21569bdedb373e7209ca4931199bfaa3039c62e606e3a09c5f49b708d2f3da
-  data.tar.gz: f0f977372a0d76697924494e6b9fc63ebbf535d23a01a4b9e80858649855cf0a
+  metadata.gz: ed6c3ae7ae41a6819cbd15890ebe7002b9637c2a2afb51e1f185ac7cf4c4b39c
+  data.tar.gz: 59c4fcbf5f6fce4baa22c359a54334d873403bf2ee6904ab483770cca41a5ab1
 SHA512:
-  metadata.gz: b814f5fbb5d1a743bb406e409b82317ddc3506acf7a8abde3f6317d2ffbba5fc1f2f9721e183fa09fb94113915a98deff2c6915983880ccf31da3002d4bf99de
-  data.tar.gz: 32f5830b2b7a5584d8e2b21af6727a550717e888f4d8b57c0631738695a10d35feba4084a357878794b18ce4233055b8d68f118aa705b449cab7f4f78c123c40
+  metadata.gz: 3047e42608ce4f1d5653fa4573fc2d9c210e5b732557bb65cf2f41f8087aa8f6b81c1a3e895f4cadc3e03c8c83b532bfaa8ea51a47bd557bcf890bd0fb42e949
+  data.tar.gz: 44abccb00089ba9fe0d6b16657c36c2967d506a69e923e42d31971260b09461d405f755e3d195f6fd5a50aadea68971686b0ba101217d1b74bf524887183f375

data/CHANGELOG.md

@@ -1,5 +1,7 @@
 # Changelog
 
-## [0.1.0] - 2026-09-25
+## [0.3.0] - 2026-09-24
 
-Initial release
+- Add GIF89a encoding, animated PNG encoding, and GIF decoding.
+- Add streaming writers, cumulative frame timing, palette quantization, transparency, and frame-difference output.
+- Add the `Flipbook.write` and `Flipbook.read` APIs.

data/README.md

@@ -1,6 +1,6 @@
 <h1 align="center">Flipbook</h1>
 
-<p align="center">Turn a sequence of RGBA images into animated GIF files.</p>
+<p align="center">Turn a sequence of RGBA images into animated GIF or APNG files.</p>
 
 <p align="center">
   <a href="https://rubygems.org/gems/flipbook"><img src="https://badge.fury.io/rb/flipbook.svg" alt="Gem version"></a>
@@ -12,15 +12,16 @@
 
 ---
 
-Flipbook writes animated GIFs from [`Tessel::Image`](https://github.com/rbgfx/tessel) frames. GIF palettes use Tessel's shared quantizer. The library has no runtime dependency beyond Tessel and Ruby's standard library.
+Flipbook writes animated GIF and APNG from [`Tessel::Image`](https://github.com/rbgfx/tessel) frames. GIF palettes use Tessel's shared quantizer. The library has no runtime dependency beyond Tessel and Ruby's standard library.
 
 ## Formats
 
-| Format | Colors | Transparency | Encoding |
+| Format | Color | Transparency | Reading |
 | --- | --- | --- | --- |
-| GIF | Up to 256 palette entries | One transparent palette index | GIF89a output with global or per-frame palettes |
+| GIF | Up to 256 palette entries | One transparent palette index | GIF87a/GIF89a frames, local and global palettes, interlace, and disposal methods |
+| APNG | RGBA8 | Full alpha | First frame through Tessel's PNG reader |
 
-GIF uses a single global palette by default so colors stay stable across frames. Use `palette: :per_frame` when streaming frames with different color ranges.
+GIF uses a single global palette by default so colors stay stable across frames. Animated frames with transparent pixels are written as full frames with background disposal so pixels can become transparent correctly. Opaque animations use difference rectangles by default.
 
 ## Installation
 
@@ -42,6 +43,9 @@ frames = 60.times.map do |index|
 end
 
 Flipbook.write("animation.gif", frames, fps: 30, loop: true)
+Flipbook.write("animation.png", frames, fps: 30, loop: true)
+
+decoded_frames = Flipbook.read("animation.gif")
 ~~~
 
 Use `delay:` in seconds instead of `fps:`. It accepts one duration or one duration per frame; `Rational(1, 30)` avoids floating-point timing drift. GIF delays use cumulative centisecond rounding. Viewers may lengthen delays below 1/50 second.
@@ -54,11 +58,15 @@ Flipbook::GIF::Writer.open("recording.gif", width: 320, height: 240, palette: :p
 end
 ~~~
 
+APNG also supports streaming output and patches its frame count when the destination can seek. Otherwise it buffers the animation until close.
+
 ### API contracts
 
-- `Flipbook.write(path, frames, fps: or delay:)` requires one or more same-sized `Tessel::Image` objects and a `.gif` output path.
-- `GIF::Writer#add` raises `TypeError` for non-image frames and `ArgumentError` for invalid dimensions or timing.
+- `Flipbook.write(path, frames, fps: or delay:)` requires one or more same-sized `Tessel::Image` objects. The `.gif` extension selects GIF; `.png` and `.apng` select APNG.
+- `Flipbook.read(path)` returns composited GIF frames as `Tessel::Image` objects. `Flipbook::GIF::Reader#delays` returns each frame delay as a `Rational` in seconds.
+- `GIF::Writer#add` and `APNG::Writer#add` raise `TypeError` for non-image frames and `ArgumentError` for invalid dimensions or timing.
 - GIF palette colors are RGB triples of integer channels from 0 to 255. GIF transparency is binary; partial alpha is encoded as an opaque palette color.
+- APNG chunks use RGBA8 pixels. The first frame is also a valid static PNG image.
 
 GIF format acknowledgement: The Graphics Interchange Format© is the Copyright property of CompuServe Incorporated. GIF® is a Service Mark property of CompuServe Incorporated.
 

data/docs/verification.md

@@ -1,12 +1,13 @@
 # File verification
 
-The test suite checks GIF LZW code-width growth and dictionary resets, frame timing, and transparent palette entries.
+The test suite checks GIF LZW code-width growth and dictionary resets, decodes generated animations, and validates APNG chunk ordering and sequence numbers.
 
 For an independent local check, install ImageMagick or gifsicle and inspect sample output:
 
 ~~~sh
-identify animation.gif
+identify animation.gif animation.png
 magick animation.gif -coalesce /tmp/flipbook-gif-%02d.png
+magick animation.png -coalesce /tmp/flipbook-apng-%02d.png
 gifsicle --info animation.gif
 ~~~
 

data/lib/flipbook/apng/writer.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require "stringio"
+
+module Flipbook
+  module APNG
+    class Writer
+      def self.open(path, **options)
+        io = File.open(path, "wb+")
+        writer = new(io, **options)
+        writer.instance_variable_set(:@owns_io, true)
+        return writer unless block_given?
+
+        begin
+          yield writer
+        ensure
+          writer.close
+        end
+        path
+      rescue StandardError
+        io&.close unless io&.closed?
+        raise
+      end
+
+      def initialize(io, width:, height:, loop: true, optimize: true, level: Zlib::DEFAULT_COMPRESSION, filter: :none)
+        @io = io
+        @width = Integer(width)
+        @height = Integer(height)
+        raise ArgumentError, "APNG dimensions must be positive" unless @width.positive? && @height.positive?
+        raise ArgumentError, "unknown PNG filter: #{filter}" unless %i[none sub up average paeth adaptive].include?(filter)
+
+        @loop = plays(loop)
+        @optimize = optimize
+        @level = level
+        @filter = filter
+        @seekable = io.respond_to?(:pos) && io.respond_to?(:seek)
+        @storage = @seekable ? io : StringIO.new("".b)
+        @frames = 0
+        @sequence = 0
+        @previous = nil
+        @closed = false
+        @storage << Tessel::SIGNATURE
+        Tessel::PNG::Chunk.write(@storage, "IHDR", [@width, @height, 8, 6, 0, 0, 0].pack("N2C5"))
+        @animation_offset = @storage.pos
+        write_chunk("acTL", [0, @loop].pack("N2"))
+      end
+
+      def add(image, delay:)
+        raise IOError, "APNG writer is closed" if @closed
+        raise TypeError, "frame must be a Tessel::Image" unless image.is_a?(Tessel::Image)
+        raise ArgumentError, "frame dimensions must match the animation" unless image.width == @width && image.height == @height
+
+        seconds = Timing.duration(delay)
+        left, top, width, height = @optimize ? Diff.bounds(@previous, image) : [0, 0, @width, @height]
+        frame = image.crop(left, top, width, height)
+        numerator, denominator = Timing.apng_fraction(seconds)
+        compressed = idat_data(frame)
+        raise Error, "APNG frame count exceeds the format limit" if @frames >= 0xFFFF_FFFF
+        control = [@sequence, width, height, left, top, numerator, denominator, 0, 0].pack("N5n2C2")
+        write_chunk("fcTL", control)
+        @sequence += 1
+        if @frames.zero?
+          write_chunk("IDAT", compressed)
+        else
+          write_chunk("fdAT", [@sequence].pack("N") + compressed)
+          @sequence += 1
+        end
+        @frames += 1
+        @previous = image.dup
+        self
+      end
+
+      def close
+        return if @closed
+        raise Error, "APNG contains no frames" if @frames.zero?
+
+        write_chunk("IEND", "".b)
+        finish_animation_control
+        @io << @storage.string if @storage != @io
+        @closed = true
+        @io.close if @owns_io && !@io.closed?
+        self
+      end
+
+      private
+
+      def plays(value)
+        return 0 if value == true
+        return 1 if value == false
+        return value if value.is_a?(Integer) && value.between?(0, 0xFFFF_FFFF)
+
+        raise ArgumentError, "loop must be true, false, or an integer from 0 to 4294967295"
+      end
+
+      def write_chunk(type, data)
+        Tessel::PNG::Chunk.write(@storage, type, data)
+      end
+
+      def idat_data(image)
+        png = Tessel::PNG.encode(image, color_type: :rgba, filter: @filter, level: @level, metadata: {})
+        output = "".b
+        cursor = Tessel::SIGNATURE.bytesize
+        while cursor + 12 <= png.bytesize
+          length = png.byteslice(cursor, 4).unpack1("N")
+          type = png.byteslice(cursor + 4, 4)
+          output << png.byteslice(cursor + 8, length) if type == "IDAT"
+          cursor += length + 12
+          break if type == "IEND"
+        end
+        raise Error, "Tessel produced a PNG without image data" if output.empty?
+
+        output
+      end
+
+      def finish_animation_control
+        control = [@frames, @loop].pack("N2")
+        ending = @storage.pos
+        @storage.seek(@animation_offset)
+        write_chunk("acTL", control)
+        @storage.seek(ending)
+      end
+    end
+  end
+end

data/lib/flipbook/diff.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Flipbook
+  module Diff
+    module_function
+
+    def bounds(previous, current)
+      raise TypeError, "current must be a Tessel::Image" unless current.is_a?(Tessel::Image)
+      return [0, 0, current.width, current.height] unless previous
+      raise TypeError, "previous must be a Tessel::Image" unless previous.is_a?(Tessel::Image)
+      raise ArgumentError, "image dimensions must match" unless previous.width == current.width && previous.height == current.height
+
+      old_bytes = previous.bytes
+      new_bytes = current.bytes
+      left, top, right, bottom = current.width, current.height, -1, -1
+      (0...(current.width * current.height)).each do |index|
+        offset = index * 4
+        next if old_bytes.byteslice(offset, 4) == new_bytes.byteslice(offset, 4)
+
+        x = index % current.width
+        y = index / current.width
+        left = x if x < left
+        top = y if y < top
+        right = x if x > right
+        bottom = y if y > bottom
+      end
+      right.negative? ? [0, 0, 1, 1] : [left, top, right - left + 1, bottom - top + 1]
+    end
+  end
+end

data/lib/flipbook/gif/lzw.rb

@@ -46,6 +46,72 @@ module Flipbook
         writer.sub_blocks
       end
 
+      def decode(bytes, minimum_code_size, expected_size: nil)
+        raise ArgumentError, "minimum code size must be between 2 and 8" unless minimum_code_size.is_a?(Integer) && minimum_code_size.between?(2, 8)
+
+        bytes = String(bytes).b
+        clear_code = 1 << minimum_code_size
+        end_code = clear_code + 1
+        dictionary = initial_dictionary(clear_code)
+        next_code = end_code + 1
+        code_width = minimum_code_size + 1
+        bit_offset = 0
+        previous = nil
+        output = "".b
+        ended = false
+        loop do
+          code = read_code(bytes, bit_offset, code_width)
+          break if code.nil?
+          bit_offset += code_width
+          if code == clear_code
+            dictionary = initial_dictionary(clear_code)
+            next_code = end_code + 1
+            code_width = minimum_code_size + 1
+            previous = nil
+            next
+          end
+          if code == end_code
+            ended = true
+            break
+          end
+
+          entry = if code < dictionary.length && dictionary[code]
+            dictionary[code]
+          elsif code == next_code && previous
+            previous + [previous.first]
+          else
+            raise Error, "invalid GIF LZW code"
+          end
+          output << entry.pack("C*")
+          raise Error, "GIF frame expands beyond its dimensions" if expected_size && output.bytesize > expected_size
+
+          if previous && next_code < 4096
+            dictionary[next_code] = previous + [entry.first]
+            next_code += 1
+            code_width += 1 if next_code == (1 << code_width) && code_width < 12
+          end
+          previous = entry
+        end
+        raise Error, "GIF LZW data is truncated" unless ended && (!expected_size || output.bytesize == expected_size)
+
+        output
+      end
+
+      def initial_dictionary(clear_code)
+        Array.new(clear_code) { |index| [index] } + [nil, nil]
+      end
+      private_class_method :initial_dictionary
+
+      def read_code(bytes, bit_offset, width)
+        return nil if bit_offset + width > bytes.bytesize * 8
+
+        value = 0
+        width.times do |bit|
+          value |= ((bytes.getbyte((bit_offset + bit) / 8) >> ((bit_offset + bit) % 8)) & 1) << bit
+        end
+        value
+      end
+      private_class_method :read_code
     end
   end
 end

data/lib/flipbook/gif/reader.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+module Flipbook
+  module GIF
+    class Reader
+      attr_reader :width, :height
+
+      def self.read(path)
+        new(File.binread(path)).frames
+      end
+
+      def initialize(data, max_pixels: 16_777_216, max_frames: 10_000, max_total_pixels: 67_108_864)
+        @data = String(data).b
+        @cursor = 0
+        @max_pixels = max_pixels
+        @max_frames = max_frames
+        @max_total_pixels = max_total_pixels
+        @decoded_pixels = 0
+        @frames = []
+        @delays = []
+        decode
+      end
+
+      def frames
+        @frames.map(&:dup).freeze
+      end
+
+      def delays
+        @delays.dup.freeze
+      end
+
+      def each(&block)
+        return enum_for(:each) unless block
+
+        @frames.each(&block)
+      end
+
+      private
+
+      def decode
+        raise Error, "invalid GIF signature" unless take(6).match?(/\AGIF8[79]a\z/)
+
+        @width, @height, packed, @background_index, = take(7).unpack("v2C3")
+        raise Error, "invalid GIF dimensions" unless @width.positive? && @height.positive?
+        raise Error, "GIF exceeds pixel limit" if @width * @height > @max_pixels
+
+        global = (packed & 0x80).zero? ? nil : read_palette(1 << ((packed & 7) + 1))
+        background = global && global[@background_index]
+        canvas = Tessel::Image.new(@width, @height)
+        @current_control = { disposal: 1, delay: 0, transparent: nil }
+        previous = nil
+        previous_disposal = 0
+        restore = nil
+        control = { disposal: 1, delay: 0, transparent: nil }
+
+        until @cursor >= @data.bytesize
+          marker = byte
+          case marker
+          when 0x3B then break
+          when 0x21 then read_extension(control)
+          when 0x2C
+            raise Error, "GIF exceeds frame limit" if @frames.length >= @max_frames
+            @current_control = control
+            frame = read_frame(global)
+            if previous
+              if previous_disposal == 2
+                color = control_background(global, background, previous[:control][:transparent])
+                canvas.fill_rect(previous[:left], previous[:top], previous[:width], previous[:height], color)
+              elsif previous_disposal == 3 && restore
+                canvas = restore.dup
+              end
+            elsif background && frame[:control][:transparent] != @background_index
+              canvas.clear([*background, 255])
+            end
+            restore = canvas.dup if frame[:control][:disposal] == 3
+            composite(canvas, frame)
+            @frames << canvas.dup
+            @delays << Rational(frame[:control][:delay], 100)
+            previous = frame
+            previous_disposal = frame[:control][:disposal]
+            control = { disposal: 1, delay: 0, transparent: nil }
+            @current_control = control
+          else
+            raise Error, "invalid GIF block marker"
+          end
+        end
+        raise Error, "GIF contains no frames" if @frames.empty?
+      end
+
+      def read_extension(control)
+        label = byte
+        if label == 0xF9
+          raise Error, "invalid GIF control extension" unless byte == 4
+          packed, delay, transparent = take(4).unpack("CvC")
+          raise Error, "invalid GIF control terminator" unless byte.zero?
+          control.replace(disposal: (packed >> 2) & 7, delay: delay, transparent: (packed & 1).zero? ? nil : transparent)
+        else
+          skip_sub_blocks
+        end
+      end
+
+      def read_frame(global)
+        left, top, width, height, packed = take(9).unpack("v4C")
+        raise Error, "invalid GIF frame dimensions" unless width.positive? && height.positive?
+        raise Error, "GIF frame exceeds pixel limit" if width * height > @max_pixels
+        raise Error, "GIF exceeds total decoded pixel limit" if @decoded_pixels + width * height > @max_total_pixels
+        raise Error, "GIF frame lies outside the logical screen" if left + width > @width || top + height > @height
+
+        local = (packed & 0x80).zero? ? nil : read_palette(1 << ((packed & 7) + 1))
+        palette = local || global
+        raise Error, "GIF frame has no color table" unless palette
+        minimum = byte
+        compressed = read_sub_blocks
+        indices = LZW.decode(compressed, minimum, expected_size: width * height)
+        indices = deinterlace(indices, width, height) unless (packed & 0x40).zero?
+        @decoded_pixels += width * height
+        { left:, top:, width:, height:, palette:, indices:, control: @current_control.dup }
+      end
+
+      def composite(canvas, frame)
+        frame[:height].times do |row|
+          frame[:width].times do |column|
+            index = frame[:indices].getbyte(row * frame[:width] + column)
+            next if index == frame[:control][:transparent]
+
+            color = frame[:palette][index]
+            raise Error, "GIF color index out of range" unless color
+            canvas[frame[:left] + column, frame[:top] + row] = [*color, 255]
+          end
+        end
+      end
+
+      def control_background(global, background, transparent)
+        return [0, 0, 0, 0] if transparent == @background_index
+        return [0, 0, 0, 0] unless global && background
+
+        [*background, 255]
+      end
+
+      def deinterlace(indices, width, height)
+        rows = [0, 4, 2, 1].flat_map do |start|
+          step = { 0 => 8, 4 => 8, 2 => 4, 1 => 2 }.fetch(start)
+          (start...height).step(step).to_a
+        end
+        output = "\0".b * indices.bytesize
+        rows.each_with_index do |row, source_row|
+          output[row * width, width] = indices.byteslice(source_row * width, width)
+        end
+        output
+      end
+
+      def read_palette(count)
+        take(count * 3).bytes.each_slice(3).map(&:freeze)
+      end
+
+      def skip_sub_blocks
+        read_sub_blocks
+      end
+
+      def read_sub_blocks
+        output = "".b
+        loop do
+          length = byte
+          break if length.zero?
+          raise Error, "GIF sub-block exceeds input" if @cursor + length > @data.bytesize
+
+          output << take(length)
+        end
+        output
+      end
+
+      def byte
+        raise Error, "truncated GIF" if @cursor >= @data.bytesize
+
+        value = @data.getbyte(@cursor)
+        @cursor += 1
+        value
+      end
+
+      def take(length)
+        raise Error, "truncated GIF" if length.negative? || @cursor + length > @data.bytesize
+
+        value = @data.byteslice(@cursor, length)
+        @cursor += length
+        value
+      end
+    end
+  end
+end

data/lib/flipbook/gif/writer.rb

@@ -20,7 +20,7 @@ module Flipbook
         raise
       end
 
-      def initialize(io, width:, height:, loop: true, palette: :per_frame, colors: 256, dither: :floyd_steinberg, transparent_index: nil)
+      def initialize(io, width:, height:, loop: true, palette: :per_frame, colors: 256, dither: :floyd_steinberg, optimize: true, transparent_index: nil, clear_background: false)
         @io = io
         @width = Integer(width)
         @height = Integer(height)
@@ -31,6 +31,9 @@ module Flipbook
         @loop = loop_value(loop)
         @colors = colors
         @dither = dither
+        @clear_background = clear_background
+        @optimize = optimize && !clear_background
+        @previous = nil
         @elapsed = Rational(0)
         @rounded_delay = 0
         @closed = false
@@ -38,11 +41,17 @@ module Flipbook
         @frame_count = 0
         @palette_mode = palette
         if palette == :per_frame
+          raise ArgumentError, "clear_background requires a global palette" if clear_background
           raise ArgumentError, "transparent_index is only valid with a global palette" unless transparent_index.nil?
           @global_palette = nil
         else
           raise TypeError, "palette must be :per_frame or an RGB array" unless palette.is_a?(Array)
           @global_palette = validate_palette(palette)
+          if (@optimize || clear_background) && transparent_index.nil?
+            raise ArgumentError, "global palettes need room for a transparent color when optimize is enabled" if @global_palette.length == 256
+            @global_palette = @global_palette + [[0, 0, 0]]
+            transparent_index = @global_palette.length - 1
+          end
           if transparent_index
             raise ArgumentError, "transparent_index must be the last palette entry" unless transparent_index == @global_palette.length - 1
             raise ArgumentError, "transparent_index is out of range" unless transparent_index.between?(0, @global_palette.length - 1)
@@ -64,7 +73,9 @@ module Flipbook
           @warned_short_delay = true
         end
         transparent_pixels = image.bytes.bytes.each_slice(4).any? { |_, _, _, alpha| alpha.zero? }
-        raise ArgumentError, "transparent frames require a global palette" if @palette_mode == :per_frame && transparent_pixels
+        if @palette_mode == :per_frame && @frame_count.positive? && (@previous_transparency || transparent_pixels)
+          raise ArgumentError, "transparent multi-frame GIFs require a global palette"
+        end
         elapsed = @elapsed + seconds
         target_delay = (elapsed * 100).floor
         frame_delay = target_delay - @rounded_delay
@@ -78,11 +89,25 @@ module Flipbook
           end
         end
 
+        left, top, width, height = @optimize ? Diff.bounds(@previous, image) : [0, 0, @width, @height]
+        if @previous && @optimize && transparent_index
+          image_bytes = image.bytes
+          old_bytes = @previous.bytes
+          (top...(top + height)).each do |y|
+            (left...(left + width)).each do |x|
+              offset = (y * @width + x) * 4
+              indices.setbyte(y * @width + x, transparent_index) if image_bytes.byteslice(offset, 4) == old_bytes.byteslice(offset, 4)
+            end
+          end
+        end
+        frame_indices = crop_indices(indices, left, top, width, height)
         write_control(frame_delay, transparent_index)
-        write_image(0, 0, @width, @height, indices, palette)
+        write_image(left, top, width, height, frame_indices, palette)
         @elapsed = elapsed
         @rounded_delay = target_delay
         @frame_count += 1
+        @previous_transparency = transparent_pixels
+        @previous = image.dup
         self
       end
 
@@ -123,7 +148,7 @@ module Flipbook
           return [@global_palette, opaque, @global_transparent_index]
         end
 
-        reserve = transparent_pixels
+        reserve = @optimize || transparent_pixels
         opaque_count = reserve ? [@colors - 1, 1].max : @colors
         opaque = Tessel::Quantize.palette_for(image, colors: [opaque_count, 2].max).first(opaque_count)
         palette = reserve ? opaque + [[0, 0, 0]] : opaque
@@ -134,7 +159,8 @@ module Flipbook
         @io << "GIF89a".b << [@width, @height].pack("v2")
         if @global_palette
           bits, size = table_size(@global_palette.length)
-          @io << [0x80 | 0x70 | (bits - 1), 0, 0].pack("C3")
+          background = @clear_background ? @global_transparent_index : 0
+          @io << [0x80 | 0x70 | (bits - 1), background, 0].pack("C3")
           write_palette(@global_palette, size)
         else
           @io << "\0\0\0".b
@@ -145,7 +171,7 @@ module Flipbook
       end
 
       def write_control(delay, transparent_index)
-        packed = 0
+        packed = @clear_background ? 0x08 : (@optimize ? 0x04 : 0)
         packed |= 0x01 if transparent_index
         @io << "!\xF9\x04".b << [packed, delay, transparent_index || 0, 0].pack("CvCC")
       end
@@ -170,6 +196,13 @@ module Flipbook
         (size - palette.length).times { @io << "\0\0\0".b }
       end
 
+      def crop_indices(indices, left, top, width, height)
+        output = String.new(capacity: width * height, encoding: Encoding::BINARY)
+        height.times do |row|
+          output << indices.byteslice((top + row) * @width + left, width)
+        end
+        output
+      end
     end
   end
 end

data/lib/flipbook/timing.rb

@@ -39,6 +39,17 @@ module Flipbook
       end
     end
 
+    def apng_fraction(delay)
+      value = rational(delay)
+      raise ArgumentError, "APNG delays cannot exceed 65535 seconds" if value > 65_535
+      max_denominator = value > 1 ? (65_535 / value).floor : 65_535
+      denominator = [value.denominator, max_denominator, 65_535].min
+      denominator = 1 if denominator.zero?
+      numerator = [(value * denominator).round, 1].max
+      divisor = numerator.gcd(denominator)
+      [numerator / divisor, denominator / divisor]
+    end
+
     def rational(value)
       raise TypeError, "delay and fps must be numeric" unless value.is_a?(Numeric)
 

data/lib/flipbook/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Flipbook
-  VERSION = "0.1.0"
+  VERSION = "0.3.0"
 end

data/lib/flipbook.rb

@@ -1,32 +1,51 @@
 # frozen_string_literal: true
 
 require "tessel"
+require "zlib"
 
 require_relative "flipbook/version"
 require_relative "flipbook/timing"
+require_relative "flipbook/diff"
 require_relative "flipbook/gif/bit_writer"
 require_relative "flipbook/gif/lzw"
 require_relative "flipbook/gif/writer"
+require_relative "flipbook/gif/reader"
+require_relative "flipbook/apng/writer"
 
 module Flipbook
   class Error < StandardError; end
 
   module_function
 
-  def write(path, frames, fps: nil, delay: nil, loop: true, colors: 256, palette: :global, dither: :floyd_steinberg)
+  def write(path, frames, fps: nil, delay: nil, loop: true, format: nil, colors: 256, palette: :global, dither: :floyd_steinberg, optimize: true, **options)
     raise TypeError, "frames must be an array of Tessel::Image values" unless frames.is_a?(Array) && frames.all? { |frame| frame.is_a?(Tessel::Image) }
     raise ArgumentError, "at least one frame is required" if frames.empty?
     raise ArgumentError, "frame dimensions must match" unless frames.all? { |frame| frame.width == frames.first.width && frame.height == frames.first.height }
 
     delays = Timing.delays(frames.length, fps:, delay:)
-    raise ArgumentError, "output path must end in .gif" unless File.extname(String(path)).casecmp?(".gif")
+    extension = format&.to_s&.downcase || File.extname(String(path)).delete_prefix(".").downcase
+    case extension
+    when "gif"
+      write_gif(path, frames, delays, loop:, colors:, palette:, dither:, optimize:)
+    when "png", "apng"
+      APNG::Writer.open(path, width: frames.first.width, height: frames.first.height, loop:, optimize:, **options) do |writer|
+        frames.zip(delays).each { |frame, frame_delay| writer.add(frame, delay: frame_delay) }
+      end
+    else
+      raise ArgumentError, "format must be GIF or APNG"
+    end
+  end
+
+  def read(path)
+    bytes = File.binread(path)
+    raise Error, "not a GIF file" unless bytes.start_with?("GIF87a", "GIF89a")
 
-    write_gif(path, frames, delays, loop:, colors:, palette:, dither:)
+    GIF::Reader.new(bytes).frames
   end
 
-  def write_gif(path, frames, delays, loop:, colors:, palette:, dither:)
+  def write_gif(path, frames, delays, loop:, colors:, palette:, dither:, optimize:)
     has_transparency = frames.any? { |frame| frame.bytes.bytes.each_slice(4).any? { |_, _, _, alpha| alpha.zero? } }
-    transparent = has_transparency
+    transparent = optimize || has_transparency
     global_palette = if palette == :per_frame
       raise ArgumentError, "per-frame palettes cannot preserve transparency across frames" if has_transparency
       :per_frame
@@ -46,7 +65,7 @@ module Flipbook
     end
     transparent_index = global_palette.is_a?(Array) && transparent ? global_palette.length - 1 : nil
 
-    GIF::Writer.open(path, width: frames.first.width, height: frames.first.height, loop:, palette: global_palette, colors:, dither:, transparent_index:) do |writer|
+    GIF::Writer.open(path, width: frames.first.width, height: frames.first.height, loop:, palette: global_palette, colors:, dither:, optimize:, transparent_index:, clear_background: has_transparency) do |writer|
       frames.zip(delays).each { |frame, frame_delay| writer.add(frame, delay: frame_delay) }
     end
   end

data/sig/flipbook.rbs

@@ -1,10 +1,12 @@
 module Flipbook
   VERSION: String
 
-  def self.write: (String path, Array[Tessel::Image] frames, ?fps: Numeric?, ?delay: Numeric | Array[Numeric]?, ?loop: bool | Integer, ?colors: Integer, ?palette: Symbol | Array[[Integer, Integer, Integer]], ?dither: Symbol) -> String
+  def self.write: (String path, Array[Tessel::Image] frames, ?fps: Numeric?, ?delay: Numeric | Array[Numeric]?, ?loop: bool | Integer, ?format: String?, ?colors: Integer, ?palette: Symbol | Array[[Integer, Integer, Integer]], ?dither: Symbol, ?optimize: bool, **untyped) -> String
+  def self.read: (String path) -> Array[Tessel::Image]
 
   module Timing
     def self.delays: (Integer count, ?fps: Numeric?, ?delay: Numeric | Array[Numeric]?) -> Array[Rational]
     def self.centiseconds: (Array[Numeric] delays) -> Array[Integer]
+    def self.apng_fraction: (Numeric delay) -> [Integer, Integer]
   end
 end

metadata

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: flipbook
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Yudai Takada
+autorequire:
 bindir: bin
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-09-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: tessel
@@ -57,7 +58,7 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.6'
-description: Flipbook encodes animated GIF files from Tessel RGBA images.
+description: Flipbook encodes animated GIF and APNG files from Tessel RGBA images.
 email:
 - t.yudai92@gmail.com
 executables: []
@@ -70,8 +71,11 @@ files:
 - Rakefile
 - docs/verification.md
 - lib/flipbook.rb
+- lib/flipbook/apng/writer.rb
+- lib/flipbook/diff.rb
 - lib/flipbook/gif/bit_writer.rb
 - lib/flipbook/gif/lzw.rb
+- lib/flipbook/gif/reader.rb
 - lib/flipbook/gif/writer.rb
 - lib/flipbook/timing.rb
 - lib/flipbook/version.rb
@@ -82,6 +86,7 @@ licenses:
 metadata:
   source_code_uri: https://github.com/rbgfx/flipbook
   changelog_uri: https://github.com/rbgfx/flipbook/blob/main/CHANGELOG.md
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -96,7 +101,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.16
+rubygems_version: 3.4.19
+signing_key:
 specification_version: 4
-summary: Write animated GIFs in Ruby
+summary: Write and read GIF and APNG animations in Ruby
 test_files: []