diff --git a/src/Titano.Core/Codecs/Apng/ApngEncoder.cs b/src/Titano.Core/Codecs/Apng/ApngEncoder.cs
new file mode 100644
index 00000000..5047d90a
--- /dev/null
+++ b/src/Titano.Core/Codecs/Apng/ApngEncoder.cs
@@ -0,0 +1,246 @@
+using System.Buffers.Binary;
+using System.IO.Compression;
+using Titano.Core.Codecs.Png;
+using Titano.Core.Imaging;
+
+namespace Titano.Core.Codecs.Apng;
+
+/// Options of .
+public sealed record ApngEncoderOptions
+{
+ /// Write RGBA (alpha taken from 4-channel buffers); otherwise RGB.
+ public bool Alpha { get; init; }
+
+ /// acTL num_plays: 0 loops forever.
+ public int LoopCount { get; init; }
+
+ /// Crop frames to the changed area (blend OVER with transparent unchanged pixels when possible).
+ public bool FrameDifferencing { get; init; } = true;
+
+ public CompressionLevel CompressionLevel { get; init; } = CompressionLevel.Optimal;
+}
+
+///
+/// Animated PNG encoder (8-bit RGB/RGBA): acTL/fcTL/IDAT/fdAT with one shared sequence counter; the first frame is
+/// the default image. Delays are exact fractions of the 90 kHz durations when they fit 16 bits, otherwise rounded on
+/// the cumulative timeline. Identical consecutive frames merge. The output must be seekable (acTL is patched at the
+/// end) and is not disposed.
+///
+public sealed class ApngEncoder
+{
+ private const int TimeScale = 90_000;
+ private const byte DisposeNone = 0;
+ private const byte BlendSource = 0, BlendOver = 1;
+
+ private readonly Stream _output;
+ private readonly int _width;
+ private readonly int _height;
+ private readonly int _bpp;
+ private readonly ApngEncoderOptions _options;
+ private readonly long _actlOffset;
+ private byte[]? _canvas;
+ private Pending? _pending;
+ private long _time;
+ private uint _sequence;
+ private bool _completed;
+
+ public ApngEncoder(Stream output, int width, int height, ApngEncoderOptions? options = null)
+ {
+ ArgumentNullException.ThrowIfNull(output);
+ if (!output.CanSeek || !output.CanWrite) throw new ArgumentException("The output stream must be writable and seekable", nameof(output));
+ ArgumentOutOfRangeException.ThrowIfNegativeOrZero(width);
+ ArgumentOutOfRangeException.ThrowIfNegativeOrZero(height);
+ _options = options ?? new ApngEncoderOptions();
+ ArgumentOutOfRangeException.ThrowIfNegative(_options.LoopCount, nameof(options));
+ _output = output;
+ _width = width;
+ _height = height;
+ _bpp = _options.Alpha ? 4 : 3;
+
+ output.Write([0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A]);
+ Span ihdr = stackalloc byte[13];
+ BinaryPrimitives.WriteInt32BigEndian(ihdr, width);
+ BinaryPrimitives.WriteInt32BigEndian(ihdr[4..], height);
+ ihdr[8] = 8;
+ ihdr[9] = (byte)(_options.Alpha ? PngColorType.Rgba : PngColorType.Rgb);
+ PngEncoder.WriteChunk(output, "IHDR", ihdr);
+ _actlOffset = output.Position;
+ WriteAnimationControl(0);
+ }
+
+ /// Frames written so far (merged identical frames count once).
+ public int FrameCount { get; private set; }
+
+ /// Adds a linear-light frame shown for ticks.
+ public void AddFrame(ImageBuffer frame, long duration90k)
+ {
+ if (frame.Width != _width || frame.Height != _height) throw new ArgumentException("Frame size differs from the animation size", nameof(frame));
+ var n = _width * _height;
+ var pixels = new byte[n * _bpp];
+ var r = frame.Plane(0);
+ var g = frame.Channels >= 3 ? frame.Plane(1) : r;
+ var b = frame.Channels >= 3 ? frame.Plane(2) : r;
+ var a = frame.Channels == 4 ? frame.Plane(3) : default;
+ for (var i = 0; i < n; i++)
+ {
+ var o = i * _bpp;
+ pixels[o] = ColorSpace.Encode8(r[i]);
+ pixels[o + 1] = ColorSpace.Encode8(g[i]);
+ pixels[o + 2] = ColorSpace.Encode8(b[i]);
+ if (_bpp == 4) pixels[o + 3] = a.IsEmpty ? (byte)255 : (byte)(Math.Clamp(a[i], 0f, 1f) * 255f + 0.5f);
+ }
+ AddPixels(pixels, duration90k);
+ }
+
+ /// Adds interleaved 8-bit sRGB pixels (RGB, or RGBA when ).
+ public void AddFrame(ReadOnlySpan pixels, long duration90k)
+ {
+ if (pixels.Length != _width * _height * _bpp) throw new ArgumentException($"Expected width × height × {_bpp} bytes", nameof(pixels));
+ AddPixels(pixels.ToArray(), duration90k);
+ }
+
+ /// Writes the last frame and IEND, then patches the frame count.
+ public void Complete()
+ {
+ if (_completed) throw new InvalidOperationException("The encoder is already complete");
+ if (_pending is null) throw new InvalidOperationException("No frames were added");
+ Emit(_time);
+ PngEncoder.WriteChunk(_output, "IEND", []);
+ var end = _output.Position;
+ _output.Position = _actlOffset;
+ WriteAnimationControl(FrameCount);
+ _output.Position = end;
+ _output.Flush();
+ _completed = true;
+ }
+
+ private sealed record Pending(long Start, int X, int Y, int Width, int Height, byte Blend, byte[] Data);
+
+ private void AddPixels(byte[] pixels, long duration)
+ {
+ if (_completed) throw new InvalidOperationException("The encoder is complete");
+ ArgumentOutOfRangeException.ThrowIfNegativeOrZero(duration);
+ int x = 0, y = 0, w = _width, h = _height;
+ var blend = BlendSource;
+ var region = pixels;
+ if (_canvas is not null && _options.FrameDifferencing)
+ {
+ (x, y, w, h) = ChangedArea(pixels, _canvas);
+ if (w == 0)
+ {
+ _time += duration; // identical frame: the previous one stays longer
+ return;
+ }
+ region = Crop(pixels, x, y, w, h, out var opaque);
+ if (_bpp == 4 && opaque)
+ {
+ // Unchanged pixels become fully transparent and OVER keeps what is displayed beneath them.
+ for (var row = 0; row < h; row++)
+ {
+ for (var col = 0; col < w; col++)
+ {
+ var c = ((y + row) * _width + x + col) * 4;
+ if (pixels.AsSpan(c, 4).SequenceEqual(_canvas.AsSpan(c, 4))) region.AsSpan((row * w + col) * 4, 4).Clear();
+ }
+ }
+ blend = BlendOver;
+ }
+ }
+ _canvas = pixels;
+ var data = PngEncoder.Compress(region, h, w * _bpp, _bpp, _options.CompressionLevel);
+ Emit(_time);
+ _pending = new Pending(_time, x, y, w, h, blend, data);
+ _time += duration;
+ }
+
+ private (int X, int Y, int Width, int Height) ChangedArea(byte[] pixels, byte[] canvas)
+ {
+ int left = _width, top = _height, right = -1, bottom = -1;
+ for (var y = 0; y < _height; y++)
+ {
+ var row = y * _width * _bpp;
+ for (var x = 0; x < _width; x++)
+ {
+ var o = row + x * _bpp;
+ if (pixels.AsSpan(o, _bpp).SequenceEqual(canvas.AsSpan(o, _bpp))) continue;
+ left = Math.Min(left, x);
+ right = Math.Max(right, x);
+ top = Math.Min(top, y);
+ bottom = y;
+ }
+ }
+ return right < 0 ? (0, 0, 0, 0) : (left, top, right - left + 1, bottom - top + 1);
+ }
+
+ private byte[] Crop(byte[] pixels, int x, int y, int w, int h, out bool opaque)
+ {
+ var region = new byte[w * h * _bpp];
+ opaque = true;
+ for (var row = 0; row < h; row++) pixels.AsSpan(((y + row) * _width + x) * _bpp, w * _bpp).CopyTo(region.AsSpan(row * w * _bpp));
+ if (_bpp == 4)
+ {
+ for (var i = 3; i < region.Length && opaque; i += 4) opaque = region[i] == 255;
+ }
+ return region;
+ }
+
+ private void Emit(long end)
+ {
+ if (_pending is not { } frame) return;
+ var (num, den) = Delay(frame.Start, end);
+ Span fctl = stackalloc byte[26];
+ BinaryPrimitives.WriteUInt32BigEndian(fctl, _sequence++);
+ BinaryPrimitives.WriteInt32BigEndian(fctl[4..], frame.Width);
+ BinaryPrimitives.WriteInt32BigEndian(fctl[8..], frame.Height);
+ BinaryPrimitives.WriteInt32BigEndian(fctl[12..], frame.X);
+ BinaryPrimitives.WriteInt32BigEndian(fctl[16..], frame.Y);
+ BinaryPrimitives.WriteUInt16BigEndian(fctl[20..], num);
+ BinaryPrimitives.WriteUInt16BigEndian(fctl[22..], den);
+ fctl[24] = DisposeNone;
+ fctl[25] = frame.Blend;
+ PngEncoder.WriteChunk(_output, "fcTL", fctl);
+ if (FrameCount == 0)
+ {
+ PngEncoder.WriteChunk(_output, "IDAT", frame.Data);
+ }
+ else
+ {
+ var fdat = new byte[4 + frame.Data.Length];
+ BinaryPrimitives.WriteUInt32BigEndian(fdat, _sequence++);
+ frame.Data.CopyTo(fdat, 4);
+ PngEncoder.WriteChunk(_output, "fdAT", fdat);
+ }
+ FrameCount++;
+ _pending = null;
+ }
+
+ /// Exact reduced fraction of a second when it fits 16 bits; otherwise the cumulative timeline rounded to 1/1000 … 1 s.
+ private static (ushort Num, ushort Den) Delay(long start, long end)
+ {
+ var duration = end - start;
+ var g = Gcd(duration, TimeScale);
+ if (duration / g <= ushort.MaxValue && TimeScale / g <= ushort.MaxValue) return ((ushort)(duration / g), (ushort)(TimeScale / g));
+ foreach (var den in (ReadOnlySpan)[1000, 100, 10, 1])
+ {
+ var num = Rounded(end, den) - Rounded(start, den);
+ if (num <= ushort.MaxValue) return ((ushort)num, (ushort)den);
+ }
+ return (ushort.MaxValue, 1);
+
+ static long Rounded(long ticks, int den) => (ticks * den + TimeScale / 2) / TimeScale;
+ }
+
+ private static long Gcd(long a, long b)
+ {
+ while (b != 0) (a, b) = (b, a % b);
+ return a;
+ }
+
+ private void WriteAnimationControl(int frames)
+ {
+ Span actl = stackalloc byte[8];
+ BinaryPrimitives.WriteInt32BigEndian(actl, frames);
+ BinaryPrimitives.WriteInt32BigEndian(actl[4..], _options.LoopCount);
+ PngEncoder.WriteChunk(_output, "acTL", actl);
+ }
+}
diff --git a/tests/Titano.Core.Tests/Video/ApngEncoderTests.cs b/tests/Titano.Core.Tests/Video/ApngEncoderTests.cs
new file mode 100644
index 00000000..db4eba39
--- /dev/null
+++ b/tests/Titano.Core.Tests/Video/ApngEncoderTests.cs
@@ -0,0 +1,221 @@
+using System.Buffers.Binary;
+using System.IO.Compression;
+using System.Text;
+using Titano.Core.Codecs.Apng;
+using Titano.Core.Hashing;
+using Titano.Core.Imaging;
+using Titano.Testing;
+
+namespace Titano.Core.Tests.Video;
+
+public sealed class ApngEncoderTests
+{
+ private const int W = 40, H = 30;
+
+ [Test]
+ public void ChunkOrderSequenceNumbersAndCrcsAreValid()
+ {
+ var frames = Enumerable.Range(0, 5).Select(i => Pattern(i, 3)).ToList();
+ var bytes = Encode(frames, new ApngEncoderOptions(), 3000);
+ var chunks = Chunks(bytes);
+ Assert.SequenceEqual(
+ ["IHDR", "acTL", "fcTL", "IDAT", "fcTL", "fdAT", "fcTL", "fdAT", "fcTL", "fdAT", "fcTL", "fdAT", "IEND"],
+ chunks.Select(c => c.Type));
+ var actl = chunks[1].Data;
+ Assert.Equal(5, BinaryPrimitives.ReadInt32BigEndian(actl));
+ Assert.Equal(0, BinaryPrimitives.ReadInt32BigEndian(actl.AsSpan(4)));
+ var sequence = chunks.Where(c => c.Type is "fcTL" or "fdAT").Select(c => BinaryPrimitives.ReadUInt32BigEndian(c.Data)).ToList();
+ Assert.SequenceEqual(Enumerable.Range(0, sequence.Count).Select(i => (uint)i), sequence);
+ var first = chunks[2].Data;
+ Assert.Equal((W, H, 0, 0), (BinaryPrimitives.ReadInt32BigEndian(first.AsSpan(4)), BinaryPrimitives.ReadInt32BigEndian(first.AsSpan(8)),
+ BinaryPrimitives.ReadInt32BigEndian(first.AsSpan(12)), BinaryPrimitives.ReadInt32BigEndian(first.AsSpan(16))));
+ Assert.Equal((1, 30), Delay(first));
+ }
+
+ [Test]
+ public void FirstFrameIsTheDefaultImageAndAllFramesComposeExactly()
+ {
+ var frames = new List { Pattern(0, 3), Pattern(0, 3), Pattern(1, 3) };
+ // Frame 3 changes only a small block of frame 2.
+ var last = (byte[])frames[2].Clone();
+ for (var y = 5; y < 9; y++)
+ {
+ for (var x = 20; x < 26; x++) last[(y * W + x) * 3] ^= 0xFF;
+ }
+ frames.Add(last);
+ var bytes = Encode(frames, new ApngEncoderOptions(), 1500);
+ var decoded = Decode(bytes, 3);
+ Assert.Equal(3, decoded.Count); // the duplicate merged into the first frame
+ Assert.BytesEqual(frames[0], decoded[0].Canvas);
+ Assert.BytesEqual(frames[2], decoded[1].Canvas);
+ Assert.BytesEqual(frames[3], decoded[2].Canvas);
+ Assert.Equal((1, 30), decoded[0].Delay);
+ Assert.Equal((20, 5, 6, 4), decoded[2].Rect);
+ Assert.Equal(0, decoded[2].Blend); // RGB output always uses SOURCE
+ }
+
+ [Test]
+ public void RgbaDifferencingUsesOverWithTransparentUnchangedPixels()
+ {
+ var a = Pattern(2, 4);
+ var b = (byte[])a.Clone();
+ b[(10 * W + 10) * 4] ^= 0x80;
+ b[(12 * W + 14) * 4 + 1] ^= 0x80;
+ var bytes = Encode([a, b], new ApngEncoderOptions { Alpha = true }, 3000);
+ var decoded = Decode(bytes, 4);
+ Assert.Equal(2, decoded.Count);
+ Assert.Equal(1, decoded[1].Blend);
+ Assert.Equal((10, 10, 5, 3), decoded[1].Rect);
+ Assert.BytesEqual(b, decoded[1].Canvas);
+ }
+
+ [Theory]
+ [Case(3003L, 1001, 30000)]
+ [Case(90000L * 30, 30, 1)]
+ [Case(3001L, 33, 1000)]
+ public void DelaysAreExactFractionsOrCumulativelyRounded(long duration, int num, int den)
+ {
+ var bytes = Encode([Pattern(0, 3), Pattern(1, 3)], new ApngEncoderOptions(), duration);
+ var fctl = Chunks(bytes).Where(c => c.Type == "fcTL").ToList();
+ Assert.Equal((num, den), Delay(fctl[0].Data));
+ }
+
+ [Test]
+ public void LinearBuffersAreEncodedAsSrgb()
+ {
+ using var image = new ImageBuffer(W, H, 4);
+ image.Plane(0).Fill(ColorSpace.Linear8(200));
+ image.Plane(1).Fill(ColorSpace.Linear8(100));
+ image.Plane(3).Fill(0.5f);
+ using var ms = new MemoryStream();
+ var encoder = new ApngEncoder(ms, W, H, new ApngEncoderOptions { Alpha = true, LoopCount = 2 });
+ encoder.AddFrame(image, 9000);
+ encoder.Complete();
+ var decoded = Decode(ms.ToArray(), 4);
+ Assert.SequenceEqual(new byte[] { 200, 100, 0, 128 }, decoded[0].Canvas.Take(4));
+ Assert.Equal(2, BinaryPrimitives.ReadInt32BigEndian(Chunks(ms.ToArray())[1].Data.AsSpan(4)));
+ }
+
+ private static byte[] Encode(List frames, ApngEncoderOptions options, long duration)
+ {
+ using var ms = new MemoryStream();
+ var encoder = new ApngEncoder(ms, W, H, options);
+ foreach (var f in frames) encoder.AddFrame(f, duration);
+ encoder.Complete();
+ return ms.ToArray();
+ }
+
+ private static (int, int) Delay(byte[] fctl) =>
+ (BinaryPrimitives.ReadUInt16BigEndian(fctl.AsSpan(20)), BinaryPrimitives.ReadUInt16BigEndian(fctl.AsSpan(22)));
+
+ private sealed record Chunk(string Type, byte[] Data);
+
+ /// Splits the PNG into chunks, checking the signature, lengths and every CRC.
+ private static List Chunks(byte[] png)
+ {
+ Assert.BytesEqual([0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A], png.AsSpan(0, 8));
+ var list = new List();
+ var pos = 8;
+ while (pos < png.Length)
+ {
+ var length = BinaryPrimitives.ReadInt32BigEndian(png.AsSpan(pos));
+ var type = Encoding.ASCII.GetString(png, pos + 4, 4);
+ Assert.Equal(BinaryPrimitives.ReadUInt32BigEndian(png.AsSpan(pos + 8 + length)), Crc32.Compute(png.AsSpan(pos + 4, length + 4)), $"CRC of {type}");
+ list.Add(new Chunk(type, png.AsSpan(pos + 8, length).ToArray()));
+ pos += 12 + length;
+ }
+ Assert.Equal(png.Length, pos);
+ return list;
+ }
+
+ private sealed record Frame(byte[] Canvas, (int, int) Delay, (int X, int Y, int W, int H) Rect, int Blend);
+
+ /// Inflates, unfilters and composites every frame (dispose NONE, blend SOURCE/OVER with binary alpha).
+ private static List Decode(byte[] png, int bpp)
+ {
+ var chunks = Chunks(png);
+ var canvas = new byte[W * H * bpp];
+ var frames = new List();
+ for (var i = 0; i < chunks.Count; i++)
+ {
+ if (chunks[i].Type != "fcTL") continue;
+ var f = chunks[i].Data;
+ int w = BinaryPrimitives.ReadInt32BigEndian(f.AsSpan(4)), h = BinaryPrimitives.ReadInt32BigEndian(f.AsSpan(8));
+ int x = BinaryPrimitives.ReadInt32BigEndian(f.AsSpan(12)), y = BinaryPrimitives.ReadInt32BigEndian(f.AsSpan(16));
+ Assert.Equal((byte)0, f[24]);
+ var data = chunks[i + 1].Type == "IDAT" ? chunks[i + 1].Data : chunks[i + 1].Data[4..];
+ var pixels = Unfilter(Inflate(data), w, h, bpp);
+ for (var row = 0; row < h; row++)
+ {
+ for (var col = 0; col < w; col++)
+ {
+ var s = (row * w + col) * bpp;
+ var d = ((y + row) * W + x + col) * bpp;
+ if (f[25] == 1 && bpp == 4 && pixels[s + 3] == 0) continue;
+ pixels.AsSpan(s, bpp).CopyTo(canvas.AsSpan(d));
+ }
+ }
+ frames.Add(new Frame((byte[])canvas.Clone(), Delay(f), (x, y, w, h), f[25]));
+ }
+ return frames;
+ }
+
+ private static byte[] Inflate(byte[] zlib)
+ {
+ using var z = new ZLibStream(new MemoryStream(zlib), CompressionMode.Decompress);
+ using var ms = new MemoryStream();
+ z.CopyTo(ms);
+ return ms.ToArray();
+ }
+
+ private static byte[] Unfilter(byte[] filtered, int w, int h, int bpp)
+ {
+ var stride = w * bpp;
+ Assert.Equal((stride + 1) * h, filtered.Length);
+ var output = new byte[stride * h];
+ for (var y = 0; y < h; y++)
+ {
+ var filter = filtered[y * (stride + 1)];
+ for (var i = 0; i < stride; i++)
+ {
+ int raw = filtered[y * (stride + 1) + 1 + i];
+ int a = i >= bpp ? output[y * stride + i - bpp] : 0;
+ int b = y > 0 ? output[(y - 1) * stride + i] : 0;
+ int c = i >= bpp && y > 0 ? output[(y - 1) * stride + i - bpp] : 0;
+ output[y * stride + i] = (byte)(filter switch
+ {
+ 0 => raw,
+ 1 => raw + a,
+ 2 => raw + b,
+ 3 => raw + ((a + b) >> 1),
+ _ => raw + Paeth(a, b, c),
+ });
+ }
+ }
+ return output;
+ }
+
+ private static int Paeth(int a, int b, int c)
+ {
+ var p = a + b - c;
+ int pa = Math.Abs(p - a), pb = Math.Abs(p - b), pc = Math.Abs(p - c);
+ return pa <= pb && pa <= pc ? a : pb <= pc ? b : c;
+ }
+
+ private static byte[] Pattern(int variant, int bpp)
+ {
+ var pixels = new byte[W * H * bpp];
+ for (var y = 0; y < H; y++)
+ {
+ for (var x = 0; x < W; x++)
+ {
+ var o = (y * W + x) * bpp;
+ pixels[o] = (byte)(x * 6 + variant * 40);
+ pixels[o + 1] = (byte)(y * 8);
+ pixels[o + 2] = (byte)((x ^ y) * 4 + variant);
+ if (bpp == 4) pixels[o + 3] = 255;
+ }
+ }
+ return pixels;
+ }
+}