feat(video): managed encoder provider for MJPEG-AVI, image sequences, GIF and APNG

Sessions write to a temporary file or folder that Complete renames into
place and Dispose deletes; constant-rate outputs repeat held frames.
Adds AVI/GIF/APNG readers used to verify rendered outputs.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012iLMBNwBE2GnphAsu4cjaC
This commit is contained in:
Claude committed 2026-10-02 10:42:05 +00:00
1 parent 33d7284c25
commit b3801961aa
4 files changed
+934

No files matched your search

@@ -0,0 +1,410 @@
using System.Buffers.Binary;
using System.Text;
using Titano.Core.Codecs.Png;
using Titano.Core.Hashing;
using Titano.Core.Imaging;
using Titano.Core.Video;
namespace Titano.Core.Render.Diagnostics;
/// <summary>A composed animation frame (8-bit sRGB RGBA canvas) and how long it is shown.</summary>
internal sealed record AnimationFrame(byte[] Rgba, long Duration90k);
/// <summary>A decoded GIF or APNG used to verify rendered outputs.</summary>
internal sealed record AnimationInfo(int Width, int Height, IReadOnlyList<AnimationFrame> Frames, int? LoopCount)
{
public long Duration90k => Frames.Sum(f => f.Duration90k);
/// <summary>Frame <paramref name="index"/> as a linear-light RGB buffer (alpha dropped).</summary>
public ImageBuffer ToLinear(int index) => PixelConvert.FromInterleaved8(Frames[index].Rgba, Width, Height, 4, TransferFunction.Srgb, 3);
}
/// <summary>The structure of an MJPEG AVI: headers, the JPEG of every frame and the legacy index size.</summary>
internal sealed record AviInfo(int Width, int Height, Rational FrameRate, int HeaderFrames, int StreamFrames, IReadOnlyList<byte[]> Frames, int IndexEntries);
/// <summary>Bounds-checked big/little-endian reads; every violation is an <see cref="InvalidDataException"/>.</summary>
internal ref struct ByteCursor(ReadOnlySpan<byte> data)
{
private readonly ReadOnlySpan<byte> _data = data;
public int Position { get; set; }
public readonly int Remaining => _data.Length - Position;
public ReadOnlySpan<byte> Take(int count)
{
if (count < 0 || count > Remaining) throw new InvalidDataException($"Truncated data at offset {Position}");
var span = _data.Slice(Position, count);
Position += count;
return span;
}
public byte U8() => Take(1)[0];
public ushort U16Le() => BinaryPrimitives.ReadUInt16LittleEndian(Take(2));
public uint U32Le() => BinaryPrimitives.ReadUInt32LittleEndian(Take(4));
public uint U32Be() => BinaryPrimitives.ReadUInt32BigEndian(Take(4));
public string FourCc() => Encoding.ASCII.GetString(Take(4));
}
/// <summary>Reads AVI files written by <see cref="Video.Avi.AviMjpegWriter"/> (RIFF 'AVI ' plus 'AVIX' continuations).</summary>
internal static class AviReader
{
public static AviInfo Read(ReadOnlySpan<byte> data)
{
var cursor = new ByteCursor(data);
var frames = new List<byte[]>();
int width = 0, height = 0, headerFrames = 0, streamFrames = 0, index = 0;
var rate = default(Rational);
var first = true;
while (cursor.Remaining >= 12)
{
if (cursor.FourCc() != "RIFF") throw new InvalidDataException("RIFF expected");
var size = (int)cursor.U32Le();
var end = cursor.Position + size;
var type = cursor.FourCc();
if (type != (first ? "AVI " : "AVIX")) throw new InvalidDataException($"Unexpected RIFF type '{type}'");
Walk(ref cursor, end, frames, ref width, ref height, ref headerFrames, ref streamFrames, ref rate, ref index);
cursor.Position = end + (size & 1);
first = false;
}
if (first) throw new InvalidDataException("No RIFF list");
if (width == 0 || rate.Numerator == 0) throw new InvalidDataException("Missing avih/strh headers");
return new AviInfo(width, height, rate, headerFrames, streamFrames, frames, index);
}
private static void Walk(ref ByteCursor cursor, int end, List<byte[]> frames, ref int width, ref int height, ref int headerFrames,
ref int streamFrames, ref Rational rate, ref int index)
{
while (cursor.Position + 8 <= end)
{
var id = cursor.FourCc();
var size = (int)cursor.U32Le();
if (size < 0 || cursor.Position + size > end) throw new InvalidDataException($"Chunk '{id}' overruns its list");
if (id == "LIST")
{
var listEnd = cursor.Position + size;
cursor.FourCc();
Walk(ref cursor, listEnd, frames, ref width, ref height, ref headerFrames, ref streamFrames, ref rate, ref index);
cursor.Position = listEnd + (size & 1);
continue;
}
var body = cursor.Take(size);
switch (id)
{
case "avih":
headerFrames = (int)BinaryPrimitives.ReadUInt32LittleEndian(body[16..]);
width = (int)BinaryPrimitives.ReadUInt32LittleEndian(body[32..]);
height = (int)BinaryPrimitives.ReadUInt32LittleEndian(body[36..]);
break;
case "strh":
var scale = (int)BinaryPrimitives.ReadUInt32LittleEndian(body[20..]);
var rateValue = (int)BinaryPrimitives.ReadUInt32LittleEndian(body[24..]);
if (scale <= 0 || rateValue <= 0) throw new InvalidDataException("Invalid stream rate");
rate = new Rational(rateValue, scale);
streamFrames = (int)BinaryPrimitives.ReadUInt32LittleEndian(body[32..]);
break;
case "00dc":
if (size < 4 || body[0] != 0xFF || body[1] != 0xD8) throw new InvalidDataException("Video chunk is not a JPEG");
frames.Add(body.ToArray());
break;
case "idx1":
index = size / 16;
break;
}
cursor.Position += size & 1;
}
}
}
/// <summary>GIF89a decoder with frame composition (disposal 0–3, transparency) for output verification.</summary>
internal static class GifReader
{
public static AnimationInfo Decode(ReadOnlySpan<byte> data)
{
var cursor = new ByteCursor(data);
var signature = Encoding.ASCII.GetString(cursor.Take(6));
if (signature is not ("GIF89a" or "GIF87a")) throw new InvalidDataException("Not a GIF");
int width = cursor.U16Le(), height = cursor.U16Le();
var packed = cursor.U8();
cursor.Take(2);
if (width == 0 || height == 0) throw new InvalidDataException("Empty logical screen");
var global = (packed & 0x80) != 0 ? cursor.Take(3 << ((packed & 7) + 1)).ToArray() : null;
var canvas = new byte[width * height * 4];
var frames = new List<AnimationFrame>();
int? loop = null;
int delay = 0, disposal = 0, transparent = -1;
while (true)
{
var block = cursor.U8();
if (block == 0x3B) break;
if (block == 0x21)
{
var label = cursor.U8();
if (label == 0xF9)
{
if (cursor.U8() != 4) throw new InvalidDataException("Bad graphic control extension");
var flags = cursor.U8();
delay = cursor.U16Le();
var index = cursor.U8();
disposal = (flags >> 2) & 7;
transparent = (flags & 1) != 0 ? index : -1;
if (cursor.U8() != 0) throw new InvalidDataException("Unterminated graphic control extension");
continue;
}
var payload = SubBlocks(ref cursor);
if (label == 0xFF && payload.Length >= 14 && Encoding.ASCII.GetString(payload, 0, 11) == "NETSCAPE2.0") loop = payload[12] | payload[13] << 8;
continue;
}
if (block != 0x2C) throw new InvalidDataException($"Unexpected block 0x{block:X2}");
int left = cursor.U16Le(), top = cursor.U16Le(), w = cursor.U16Le(), h = cursor.U16Le();
var imagePacked = cursor.U8();
if (left + w > width || top + h > height || w == 0 || h == 0) throw new InvalidDataException("Frame outside the logical screen");
if ((imagePacked & 0x40) != 0) throw new InvalidDataException("Interlaced frames are not verified");
var table = (imagePacked & 0x80) != 0 ? cursor.Take(3 << ((imagePacked & 7) + 1)).ToArray() : global
?? throw new InvalidDataException("No colour table");
var minCode = cursor.U8();
if (minCode is < 2 or > 8) throw new InvalidDataException("Bad LZW code size");
var indices = Lzw(SubBlocks(ref cursor), minCode, w * h);
var saved = disposal == 3 ? (byte[])canvas.Clone() : null;
for (var y = 0; y < h; y++)
{
for (var x = 0; x < w; x++)
{
var i = indices[y * w + x];
if (i == transparent) continue;
if (i * 3 + 2 >= table.Length) throw new InvalidDataException("Index outside the colour table");
var o = ((top + y) * width + left + x) * 4;
canvas[o] = table[i * 3];
canvas[o + 1] = table[i * 3 + 1];
canvas[o + 2] = table[i * 3 + 2];
canvas[o + 3] = 255;
}
}
frames.Add(new AnimationFrame((byte[])canvas.Clone(), delay * 900L));
if (disposal == 2)
{
for (var y = 0; y < h; y++) canvas.AsSpan(((top + y) * width + left) * 4, w * 4).Clear();
}
else if (saved is not null)
{
canvas = saved;
}
delay = 0;
disposal = 0;
transparent = -1;
}
return new AnimationInfo(width, height, frames, loop);
}
private static byte[] SubBlocks(ref ByteCursor cursor)
{
using var buffer = new MemoryStream();
while (true)
{
var length = cursor.U8();
if (length == 0) return buffer.ToArray();
buffer.Write(cursor.Take(length));
}
}
/// <summary>Variable-length LZW (GIF flavour: clear/end codes, codes up to 12 bits, deferred clear allowed).</summary>
private static byte[] Lzw(byte[] data, int minCode, int count)
{
var output = new byte[count];
var prefix = new short[4096];
var suffix = new byte[4096];
var stack = new byte[4097];
int clear = 1 << minCode, end = clear + 1;
int size = minCode + 1, next = end + 1, previous = -1, written = 0;
byte first = 0;
long bits = 0;
var bitCount = 0;
var pos = 0;
while (written < count)
{
while (bitCount < size && pos < data.Length)
{
bits |= (long)data[pos++] << bitCount;
bitCount += 8;
}
if (bitCount < size) throw new InvalidDataException("Image data ends early");
var code = (int)(bits & ((1 << size) - 1));
bits >>= size;
bitCount -= size;
if (code == clear)
{
size = minCode + 1;
next = end + 1;
previous = -1;
continue;
}
if (code == end) break;
int top = 0, current = code;
if (previous < 0)
{
if (code >= clear) throw new InvalidDataException("First code is not a literal");
first = (byte)code;
output[written++] = first;
previous = code;
continue;
}
if (code > next || (code == next && next >= 4096)) throw new InvalidDataException("Invalid LZW code");
if (code == next)
{
stack[top++] = first;
current = previous;
}
while (current >= clear)
{
stack[top++] = suffix[current];
current = prefix[current];
}
first = (byte)current;
stack[top++] = first;
while (top > 0 && written < count) output[written++] = stack[--top];
if (next < 4096)
{
prefix[next] = (short)previous;
suffix[next] = first;
next++;
if (next == 1 << size && size < 12) size++;
}
previous = code;
}
if (written < count) throw new InvalidDataException("Image data ends early");
return output;
}
}
/// <summary>APNG decoder for output verification: chunk CRCs, the shared sequence counter, fcTL/fdAT layout, and
/// composition with every dispose and blend operation (each frame is decoded through <see cref="PngDecoder"/>).</summary>
internal static class ApngReader
{
private static readonly byte[] Signature = [0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A];
private sealed record Control(int Width, int Height, int X, int Y, long Duration90k, byte Dispose, byte Blend)
{
public List<byte[]> Data { get; } = [];
}
public static AnimationInfo Decode(ReadOnlySpan<byte> data)
{
var cursor = new ByteCursor(data);
if (!cursor.Take(8).SequenceEqual(Signature)) throw new InvalidDataException("Not a PNG");
byte[]? ihdr = null;
int? declaredFrames = null, plays = null;
var controls = new List<Control>();
var sequence = 0u;
while (true)
{
var length = (int)cursor.U32Be();
if (length < 0) throw new InvalidDataException("Chunk too long");
var typeAndBody = cursor.Take(4 + length);
if (Crc32.Compute(typeAndBody) != cursor.U32Be()) throw new InvalidDataException("Chunk CRC mismatch");
var type = Encoding.ASCII.GetString(typeAndBody[..4]);
var body = typeAndBody[4..];
switch (type)
{
case "IHDR":
ihdr = body.ToArray();
break;
case "acTL":
declaredFrames = (int)BinaryPrimitives.ReadUInt32BigEndian(body);
plays = (int)BinaryPrimitives.ReadUInt32BigEndian(body[4..]);
break;
case "fcTL":
Expect(ref sequence, body);
var num = BinaryPrimitives.ReadUInt16BigEndian(body[20..]);
var den = BinaryPrimitives.ReadUInt16BigEndian(body[22..]);
controls.Add(new Control(
(int)BinaryPrimitives.ReadUInt32BigEndian(body[4..]), (int)BinaryPrimitives.ReadUInt32BigEndian(body[8..]),
(int)BinaryPrimitives.ReadUInt32BigEndian(body[12..]), (int)BinaryPrimitives.ReadUInt32BigEndian(body[16..]),
num * 90000L / (den == 0 ? 100 : den), body[24], body[25]));
break;
case "IDAT":
if (controls.Count != 1) throw new InvalidDataException("The default image must be the first frame");
controls[0].Data.Add(body.ToArray());
break;
case "fdAT":
Expect(ref sequence, body);
if (controls.Count == 0) throw new InvalidDataException("fdAT before fcTL");
controls[^1].Data.Add(body[4..].ToArray());
break;
}
if (type == "IEND") break;
}
if (ihdr is null || declaredFrames is null) throw new InvalidDataException("Missing IHDR or acTL");
if (declaredFrames != controls.Count) throw new InvalidDataException($"acTL declares {declaredFrames} frames, {controls.Count} found");
var width = (int)BinaryPrimitives.ReadUInt32BigEndian(ihdr);
var height = (int)BinaryPrimitives.ReadUInt32BigEndian(ihdr.AsSpan(4));
var canvas = new byte[width * height * 4];
var frames = new List<AnimationFrame>(controls.Count);
foreach (var c in controls)
{
if (c.X + c.Width > width || c.Y + c.Height > height || c.Data.Count == 0) throw new InvalidDataException("Frame outside the canvas or without data");
var saved = c.Dispose == 2 ? (byte[])canvas.Clone() : null;
Compose(canvas, width, Region(ihdr, c), c);
frames.Add(new AnimationFrame((byte[])canvas.Clone(), c.Duration90k));
if (c.Dispose == 1)
{
for (var y = 0; y < c.Height; y++) canvas.AsSpan(((c.Y + y) * width + c.X) * 4, c.Width * 4).Clear();
}
else if (saved is not null)
{
canvas = saved;
}
}
return new AnimationInfo(width, height, frames, plays);
}
private static void Expect(ref uint sequence, ReadOnlySpan<byte> body)
{
if (BinaryPrimitives.ReadUInt32BigEndian(body) != sequence) throw new InvalidDataException($"Sequence number {sequence} expected");
sequence++;
}
/// <summary>Decodes one frame's data as a stand-alone PNG with the frame's size.</summary>
private static PngImage Region(byte[] ihdr, Control c)
{
using var png = new MemoryStream();
png.Write(Signature);
var header = (byte[])ihdr.Clone();
BinaryPrimitives.WriteUInt32BigEndian(header, (uint)c.Width);
BinaryPrimitives.WriteUInt32BigEndian(header.AsSpan(4), (uint)c.Height);
PngEncoder.WriteChunk(png, "IHDR", header);
foreach (var part in c.Data) PngEncoder.WriteChunk(png, "IDAT", part);
PngEncoder.WriteChunk(png, "IEND", []);
var image = PngDecoder.Decode(png.ToArray());
if (image.Warnings.Count > 0) throw new InvalidDataException("Frame data: " + image.Warnings[0]);
if (image.Pixels8 is null || image.Channels is not (3 or 4)) throw new InvalidDataException("Only 8-bit RGB/RGBA frames are verified");
return image;
}
private static void Compose(byte[] canvas, int width, PngImage frame, Control c)
{
var pixels = frame.Pixels8!;
var channels = frame.Channels;
for (var y = 0; y < c.Height; y++)
{
for (var x = 0; x < c.Width; x++)
{
var s = (y * c.Width + x) * channels;
var o = ((c.Y + y) * width + c.X + x) * 4;
var alpha = channels == 4 ? pixels[s + 3] : 255;
if (c.Blend == 1)
{
if (alpha == 0) continue;
if (alpha < 255) throw new InvalidDataException("Partial alpha blending is not verified");
}
canvas[o] = pixels[s];
canvas[o + 1] = pixels[s + 1];
canvas[o + 2] = pixels[s + 2];
canvas[o + 3] = (byte)alpha;
}
}
}
}
@@ -0,0 +1,64 @@
namespace Titano.Core.Video.Managed;
/// <summary>
/// The encoders every platform has (BRIEF §11.3): MJPEG in AVI, JPEG / PNG (8 or 16-bit) / TIFF-16 / linear DNG image
/// sequences, animated GIF and APNG, all written by the in-house codecs. Frames are linear-light buffers at the output
/// size. Single files are written to a temporary sibling and renamed on <see cref="IVideoEncoderSession.Complete"/>;
/// sequences go to a temporary folder renamed the same way, so a cancelled or failed encode leaves nothing behind.
/// AVI and image sequences are constant frame rate: a frame lasting several periods is repeated.
/// </summary>
public sealed class ManagedEncoderProvider : IVideoEncoderProvider
{
public const string ProviderName = "managed";
/// <summary>Largest width or height of any managed output (JPEG, GIF and AVI headers use 16-bit sizes).</summary>
public const int MaxDimension = 65535;
public string Name => ProviderName;
public IReadOnlyList<EncoderCapability> Capabilities { get; } =
[
new(VideoCodec.Mjpeg, "Managed MJPEG", false, MaxDimension, MaxDimension, false),
new(VideoCodec.JpegSequence, "Managed JPEG sequence", false, MaxDimension, MaxDimension, false),
new(VideoCodec.PngSequence, "Managed PNG sequence", false, MaxDimension, MaxDimension, true),
new(VideoCodec.Tiff16Sequence, "Managed TIFF sequence", false, MaxDimension, MaxDimension, true),
new(VideoCodec.LinearDngSequence, "Managed linear DNG sequence", false, MaxDimension, MaxDimension, true),
new(VideoCodec.Gif, "Managed GIF", false, MaxDimension, MaxDimension, false),
new(VideoCodec.Apng, "Managed APNG", false, MaxDimension, MaxDimension, false),
];
/// <summary>Bit depths each managed codec writes.</summary>
public static IReadOnlyList<int> BitDepths(VideoCodec codec) => codec switch
{
VideoCodec.PngSequence => [8, 16],
VideoCodec.Tiff16Sequence => [16, 8],
VideoCodec.LinearDngSequence => [16],
VideoCodec.Mjpeg or VideoCodec.JpegSequence or VideoCodec.Gif or VideoCodec.Apng => [8],
_ => [],
};
public bool CanEncode(EncodeSettings settings) => Problem(settings) is null;
public IVideoEncoderSession Open(EncodeSettings settings)
{
ArgumentNullException.ThrowIfNull(settings);
if (Problem(settings) is { } problem) throw new NotSupportedException(problem);
var name = Capabilities.First(c => c.Codec == settings.Codec).Name;
return settings.Codec switch
{
VideoCodec.Mjpeg => new AviMjpegSession(settings, name),
VideoCodec.Gif => new GifSession(settings, name),
VideoCodec.Apng => new ApngSession(settings, name),
_ => new ImageSequenceSession(settings, name),
};
}
private static string? Problem(EncodeSettings s)
{
if (!VideoCodecInfo.IsManaged(s.Codec)) return $"{s.Codec} needs a platform encoder";
if (s.Width is <= 0 or > MaxDimension || s.Height is <= 0 or > MaxDimension) return $"{s.Width}×{s.Height} is outside 1–{MaxDimension}";
if (s.FrameRate.Numerator <= 0 || s.FrameRate.Denominator <= 0) return "The frame rate must be positive";
if (!BitDepths(s.Codec).Contains(s.BitDepth)) return $"{s.Codec} cannot be written with {s.BitDepth}-bit samples";
return string.IsNullOrWhiteSpace(s.OutputPath) ? "No output path" : null;
}
}
@@ -0,0 +1,270 @@
using System.IO.Compression;
using Titano.Core.Codecs.Apng;
using Titano.Core.Codecs.Dng;
using Titano.Core.Codecs.Gif;
using Titano.Core.Codecs.Jpeg;
using Titano.Core.Codecs.Png;
using Titano.Core.Codecs.Tiff;
using Titano.Core.Diagnostics;
using Titano.Core.Imaging;
using Titano.Core.IO;
using Titano.Core.Video.Avi;
namespace Titano.Core.Video.Managed;
/// <summary>Lifecycle shared by the managed sessions: validation, completion, and deletion of partial output on dispose.</summary>
internal abstract class ManagedSession(EncodeSettings settings, string encoderName) : IVideoEncoderSession
{
protected const string LogCategory = "ManagedEncoder";
private bool _completed;
private bool _disposed;
private int _frames;
public string EncoderName { get; } = encoderName;
public bool IsHardware => false;
protected EncodeSettings Settings { get; } = settings;
public void WriteFrame(ImageBuffer frame, long duration90k)
{
ArgumentNullException.ThrowIfNull(frame);
ObjectDisposedException.ThrowIf(_disposed, this);
if (_completed) throw new InvalidOperationException("The session is complete");
if (frame.Width != Settings.Width || frame.Height != Settings.Height) throw new ArgumentException("Frame size differs from the encode size", nameof(frame));
ArgumentOutOfRangeException.ThrowIfNegativeOrZero(duration90k);
Write(frame, duration90k);
_frames++;
}
public void Complete()
{
ObjectDisposedException.ThrowIf(_disposed, this);
if (_completed) throw new InvalidOperationException("The session is already complete");
if (_frames == 0) throw new InvalidOperationException("No frames were written");
Commit();
_completed = true;
}
public void Dispose()
{
if (_disposed) return;
_disposed = true;
if (!_completed) Discard();
}
protected abstract void Write(ImageBuffer frame, long duration90k);
/// <summary>Finishes the container and moves it to <see cref="EncodeSettings.OutputPath"/>.</summary>
protected abstract void Commit();
/// <summary>Closes and deletes everything written so far.</summary>
protected abstract void Discard();
protected static JpegEncodeOptions JpegOptions(int quality) => new()
{
Quality = int.Clamp(quality, 1, 100),
Subsampling = quality >= 90 ? JpegSubsampling.Yuv444 : JpegSubsampling.Yuv420,
OptimizeHuffman = true,
};
}
/// <summary>Maps variable frame durations onto a constant-rate grid: a frame is repeated for every period it covers
/// (rounded on the cumulative timeline, so the total stays exact).</summary>
internal sealed class ConstantRateClock(Rational frameRate)
{
private long _ticks;
private long _periods;
/// <summary>Periods the next frame of <paramref name="duration90k"/> ticks occupies (0 when it is shorter than the grid allows).</summary>
public int Advance(long duration90k)
{
_ticks += duration90k;
var end = (_ticks * frameRate.Numerator * 2 + 90000L * frameRate.Denominator) / (2 * 90000L * frameRate.Denominator);
var periods = (int)(end - _periods);
_periods = end;
return periods;
}
}
/// <summary>A single output file written to a temporary sibling and renamed into place.</summary>
internal abstract class SingleFileSession : ManagedSession
{
private readonly string _tempPath;
protected SingleFileSession(EncodeSettings settings, string encoderName) : base(settings, encoderName)
{
_tempPath = AtomicFile.TempPathFor(settings.OutputPath);
File = new FileStream(_tempPath, FileMode.CreateNew, FileAccess.ReadWrite, FileShare.None, 1 << 20);
}
protected FileStream File { get; }
protected abstract void Finish();
protected override void Commit()
{
Finish();
File.Flush(flushToDisk: true);
File.Dispose();
AtomicFile.Commit(_tempPath, Settings.OutputPath);
}
protected override void Discard()
{
File.Dispose();
try
{
System.IO.File.Delete(_tempPath);
}
catch (Exception ex) when (ex is IOException or UnauthorizedAccessException)
{
Log.Warning(LogCategory, "Could not delete the partial output " + _tempPath, ex);
}
}
}
internal sealed class AviMjpegSession : SingleFileSession
{
private readonly AviMjpegWriter _writer;
private readonly ConstantRateClock _clock;
private readonly JpegEncodeOptions _jpeg;
public AviMjpegSession(EncodeSettings settings, string encoderName) : base(settings, encoderName)
{
try
{
_writer = new AviMjpegWriter(File, settings.Width, settings.Height, settings.FrameRate);
}
catch
{
Discard();
throw;
}
_clock = new ConstantRateClock(settings.FrameRate);
_jpeg = JpegOptions(settings.Quality);
}
protected override void Write(ImageBuffer frame, long duration90k)
{
var repeats = _clock.Advance(duration90k);
if (repeats == 0) return;
var jpeg = JpegEncoder.Encode(frame, _jpeg);
for (var i = 0; i < repeats; i++) _writer.WriteFrame(jpeg);
}
protected override void Finish() => _writer.Complete();
}
internal sealed class GifSession : SingleFileSession
{
private readonly GifEncoder _encoder;
public GifSession(EncodeSettings settings, string encoderName) : base(settings, encoderName)
{
try
{
_encoder = new GifEncoder(File, settings.Width, settings.Height);
}
catch
{
Discard();
throw;
}
}
protected override void Write(ImageBuffer frame, long duration90k) => _encoder.AddFrame(frame, duration90k);
protected override void Finish() => _encoder.Complete();
}
internal sealed class ApngSession : SingleFileSession
{
private readonly ApngEncoder _encoder;
public ApngSession(EncodeSettings settings, string encoderName) : base(settings, encoderName)
{
try
{
_encoder = new ApngEncoder(File, settings.Width, settings.Height, new ApngEncoderOptions { CompressionLevel = CompressionLevel.Optimal });
}
catch
{
Discard();
throw;
}
}
protected override void Write(ImageBuffer frame, long duration90k) => _encoder.AddFrame(frame, duration90k);
protected override void Finish() => _encoder.Complete();
}
/// <summary>
/// Numbered image files (<c>&lt;folder name&gt;_000001.ext</c>, 1-based, six digits) in the output folder. Files are written
/// (and flushed) into a hidden temporary sibling folder that is renamed to the output folder on completion.
/// </summary>
internal sealed class ImageSequenceSession : ManagedSession
{
private readonly string _folder;
private readonly string _temp;
private readonly string _stem;
private readonly string _extension;
private readonly ConstantRateClock _clock;
private int _index;
public ImageSequenceSession(EncodeSettings settings, string encoderName) : base(settings, encoderName)
{
_folder = Path.GetFullPath(settings.OutputPath).TrimEnd(Path.DirectorySeparatorChar, Path.AltDirectorySeparatorChar);
if (Directory.Exists(_folder) || System.IO.File.Exists(_folder)) throw new IOException($"The output \"{_folder}\" already exists");
var parent = Path.GetDirectoryName(_folder) ?? throw new ArgumentException("The output folder needs a parent", nameof(settings));
_stem = Path.GetFileName(_folder);
_extension = VideoCodecInfo.FileExtension(settings.Codec);
Directory.CreateDirectory(parent);
_temp = Path.Combine(parent, "." + _stem + "." + Guid.NewGuid().ToString("N")[..8] + ".tmp");
Directory.CreateDirectory(_temp);
_clock = new ConstantRateClock(settings.FrameRate);
}
/// <summary>File name of the 1-based frame <paramref name="number"/> inside a sequence folder named <paramref name="stem"/>.</summary>
public static string FrameName(string stem, int number, string extension) =>
string.Create(System.Globalization.CultureInfo.InvariantCulture, $"{stem}_{number:D6}{extension}");
protected override void Write(ImageBuffer frame, long duration90k)
{
var repeats = _clock.Advance(duration90k);
if (repeats == 0) return;
var bytes = Encode(frame);
for (var i = 0; i < repeats; i++)
{
_index++;
using var file = new FileStream(Path.Combine(_temp, FrameName(_stem, _index, _extension)), FileMode.CreateNew, FileAccess.Write, FileShare.None, 1 << 16);
file.Write(bytes);
file.Flush(flushToDisk: true);
}
}
protected override void Commit() => Directory.Move(_temp, _folder);
protected override void Discard()
{
try
{
Directory.Delete(_temp, recursive: true);
}
catch (Exception ex) when (ex is IOException or UnauthorizedAccessException)
{
Log.Warning(LogCategory, "Could not delete the partial sequence " + _temp, ex);
}
}
private byte[] Encode(ImageBuffer frame) => Settings.Codec switch
{
VideoCodec.JpegSequence => JpegEncoder.Encode(frame, JpegOptions(Settings.Quality)),
VideoCodec.PngSequence => PngEncoder.Encode(frame, Settings.BitDepth == 16 ? 16 : 8, CompressionLevel.Optimal),
VideoCodec.Tiff16Sequence => TiffWriter.Write(frame, new TiffWriteOptions { BitsPerSample = Settings.BitDepth == 8 ? 8 : 16 }),
VideoCodec.LinearDngSequence => LinearDngWriter.Write(frame),
_ => throw new NotSupportedException($"{Settings.Codec} is not an image sequence"),
};
}
@@ -0,0 +1,190 @@
using Titano.Core.Codecs.Jpeg;
using Titano.Core.Codecs.Png;
using Titano.Core.Codecs.Tiff;
using Titano.Core.Imaging;
using Titano.Core.Render.Diagnostics;
using Titano.Core.Video;
using Titano.Core.Video.Managed;
using Titano.Testing;
namespace Titano.Core.Tests.Export;
public sealed class ManagedEncoderTests
{
private const int Width = 48;
private const int Height = 32;
private static readonly Rational Fps = new(30, 1);
private readonly TestContext _context;
public ManagedEncoderTests(TestContext context) => _context = context;
private static ImageBuffer Frame(int seed)
{
var image = new ImageBuffer(Width, Height);
for (var y = 0; y < Height; y++)
{
for (var x = 0; x < Width; x++)
{
image[0, x, y] = (x + seed * 7) % Width / (float)Width;
image[1, x, y] = y / (float)Height * 0.8f;
image[2, x, y] = (x * y + seed * 13) % 23 / 22f * 0.5f;
}
}
return image;
}
private static EncodeSettings Settings(string path, VideoCodec codec, int bitDepth = 8) =>
new() { OutputPath = path, Codec = codec, Width = Width, Height = Height, FrameRate = Fps, BitDepth = bitDepth, Quality = 95 };
/// <summary>Three distinct frames lasting one, two and one periods.</summary>
private static void Encode(IVideoEncoderSession session)
{
long[] durations = [3000, 6000, 3000];
for (var i = 0; i < 3; i++)
{
using var frame = Frame(i);
session.WriteFrame(frame, durations[i]);
}
session.Complete();
}
private static double Psnr(ImageBuffer expected, ImageBuffer actual)
{
var a = PixelConvert.ToInterleaved8(expected, 3);
var b = PixelConvert.ToInterleaved8(actual, 3);
double sum = 0;
for (var i = 0; i < a.Length; i++) sum += (a[i] - b[i]) * (a[i] - b[i]);
return sum == 0 ? double.PositiveInfinity : 10 * Math.Log10(255.0 * 255 / (sum / a.Length));
}
[Test]
public void MjpegAviRepeatsHeldFramesOnTheConstantRateGrid()
{
var dir = _context.CreateTempDirectory();
var path = Path.Combine(dir, "out.avi");
using (var session = new ManagedEncoderProvider().Open(Settings(path, VideoCodec.Mjpeg))) Encode(session);
var avi = AviReader.Read(File.ReadAllBytes(path));
Assert.Equal(4, avi.Frames.Count);
Assert.Equal(4, avi.HeaderFrames);
Assert.Equal(4, avi.IndexEntries);
Assert.Equal(Fps, avi.FrameRate);
Assert.BytesEqual(avi.Frames[1], avi.Frames[2]);
using var decoded = JpegDecoder.DecodeToLinear(avi.Frames[3]);
using var expected = Frame(2);
Assert.Greater(Psnr(expected, decoded), 35);
Assert.SequenceEqual(new[] { "out.avi" }, Directory.GetFiles(dir).Select(Path.GetFileName));
}
[Theory]
[Case(VideoCodec.JpegSequence, 8)]
[Case(VideoCodec.PngSequence, 8)]
[Case(VideoCodec.PngSequence, 16)]
[Case(VideoCodec.Tiff16Sequence, 16)]
[Case(VideoCodec.LinearDngSequence, 16)]
public void SequencesWriteNumberedFilesIntoTheOutputFolder(VideoCodec codec, int bitDepth)
{
var dir = _context.CreateTempDirectory();
var folder = Path.Combine(dir, "Harbour - sequence");
using (var session = new ManagedEncoderProvider().Open(Settings(folder, codec, bitDepth))) Encode(session);
Assert.SequenceEqual(new[] { "Harbour - sequence" }, Directory.GetFileSystemEntries(dir).Select(Path.GetFileName));
var ext = VideoCodecInfo.FileExtension(codec);
var files = Directory.GetFiles(folder).Order(StringComparer.Ordinal).ToArray();
Assert.SequenceEqual(Enumerable.Range(1, 4).Select(i => $"Harbour - sequence_{i:D6}{ext}"), files.Select(Path.GetFileName));
Assert.BytesEqual(File.ReadAllBytes(files[1]), File.ReadAllBytes(files[2]));
using var expected = Frame(2);
var bytes = File.ReadAllBytes(files[3]);
switch (codec)
{
case VideoCodec.JpegSequence:
using (var jpeg = JpegDecoder.DecodeToLinear(bytes)) Assert.Greater(Psnr(expected, jpeg), 35);
break;
case VideoCodec.PngSequence when bitDepth == 8:
Assert.BytesEqual(PixelConvert.ToInterleaved8(expected, 3), PngDecoder.Decode(bytes).Pixels8);
break;
case VideoCodec.PngSequence:
Assert.SequenceEqual(PixelConvert.ToInterleaved16(expected, 3), PngDecoder.Decode(bytes).Pixels16!);
break;
case VideoCodec.Tiff16Sequence:
using (var tiff = TiffImageReader.Decode(bytes))
{
for (var i = 0; i < tiff.Data.Length; i += 7) Assert.Approximately(expected.Data[i], tiff.Data[i], 2e-4);
}
break;
default:
using (var dng = TiffImageReader.Decode(bytes))
{
for (var i = 0; i < dng.Data.Length; i += 7) Assert.Approximately(expected.Data[i], dng.Data[i], 1.0 / 65535);
}
break;
}
}
[Theory]
[Case(VideoCodec.Gif)]
[Case(VideoCodec.Apng)]
public void AnimationsKeepVariableDurations(VideoCodec codec)
{
var dir = _context.CreateTempDirectory();
var path = Path.Combine(dir, "out" + VideoCodecInfo.FileExtension(codec));
using (var session = new ManagedEncoderProvider().Open(Settings(path, codec))) Encode(session);
var bytes = File.ReadAllBytes(path);
var animation = codec == VideoCodec.Gif ? GifReader.Decode(bytes) : ApngReader.Decode(bytes);
Assert.Equal(3, animation.Frames.Count);
if (codec == VideoCodec.Apng)
{
Assert.SequenceEqual(new long[] { 3000, 6000, 3000 }, animation.Frames.Select(f => f.Duration90k));
using var decoded = animation.ToLinear(1);
using var expected = Frame(1);
Assert.True(Psnr(expected, decoded) > 60);
}
else
{
Assert.Approximately(12000, animation.Duration90k, 900);
using var decoded = animation.ToLinear(1);
using var expected = Frame(1);
Assert.Greater(Psnr(expected, decoded), 22);
}
}
[Theory]
[Case(VideoCodec.Mjpeg)]
[Case(VideoCodec.PngSequence)]
[Case(VideoCodec.Gif)]
[Case(VideoCodec.Apng)]
public void DisposingWithoutCompleteLeavesNothing(VideoCodec codec)
{
var dir = _context.CreateTempDirectory();
var path = Path.Combine(dir, "partial" + (VideoCodecInfo.DefaultContainer(codec) == ContainerFormat.ImageSequence ? string.Empty : VideoCodecInfo.FileExtension(codec)));
using (var session = new ManagedEncoderProvider().Open(Settings(path, codec)))
{
using var frame = Frame(0);
session.WriteFrame(frame, 3000);
session.WriteFrame(frame, 3000);
}
Assert.Empty(Directory.GetFileSystemEntries(dir));
}
[Test]
public void SessionsValidateTheirInput()
{
var dir = _context.CreateTempDirectory();
var provider = new ManagedEncoderProvider();
using (var session = provider.Open(Settings(Path.Combine(dir, "a.avi"), VideoCodec.Mjpeg)))
{
using var wrong = new ImageBuffer(Width + 2, Height);
Assert.Throws<ArgumentException>(() => session.WriteFrame(wrong, 3000));
Assert.Throws<InvalidOperationException>(session.Complete);
}
Assert.Empty(Directory.GetFileSystemEntries(dir));
var existing = Directory.CreateDirectory(Path.Combine(dir, "taken")).FullName;
Assert.Throws<IOException>(() => provider.Open(Settings(existing, VideoCodec.PngSequence)));
Assert.False(provider.CanEncode(Settings(Path.Combine(dir, "x.mp4"), VideoCodec.H264)));
Assert.False(provider.CanEncode(Settings(Path.Combine(dir, "x"), VideoCodec.PngSequence, bitDepth: 10)));
Assert.True(provider.CanEncode(Settings(Path.Combine(dir, "x"), VideoCodec.PngSequence, bitDepth: 16)));
Assert.Throws<NotSupportedException>(() => provider.Open(Settings(Path.Combine(dir, "x.mp4"), VideoCodec.Hevc)));
Assert.Equal(7, provider.Capabilities.Count);
Assert.True(provider.Capabilities.All(c => !c.Hardware && VideoCodecInfo.IsManaged(c.Codec)));
}
}