diff --git a/src/Titano.Core/Export/EncoderSelector.cs b/src/Titano.Core/Export/EncoderSelector.cs
new file mode 100644
index 00000000..a318a06d
--- /dev/null
+++ b/src/Titano.Core/Export/EncoderSelector.cs
@@ -0,0 +1,227 @@
+using System.Globalization;
+using Titano.Core.Video;
+using Titano.Core.Video.Managed;
+
+namespace Titano.Core.Export;
+
+/// Where a render runs: clients have platform encoders, the server only managed ones (BRIEF §4.2, §14.7).
+public enum EncoderHost
+{
+ Client,
+ Server,
+}
+
+public enum EncoderSelectionStatus
+{
+ /// An encoder accepts the (possibly adjusted) settings.
+ Ready,
+
+ /// The codec needs a platform encoder: delegate the job to a render node (server).
+ NeedsRenderNode,
+
+ /// No encoder on this machine can produce the codec.
+ Unavailable,
+}
+
+/// A localisable explanation of a selection decision; arguments are invariant-culture strings.
+public sealed record EncoderNotice(string Key, IReadOnlyList Args)
+{
+ public EncoderNotice(string key, params string[] args) : this(key, (IReadOnlyList)args)
+ {
+ }
+}
+
+/// Result of .
+public sealed record EncoderSelection
+{
+ public required EncoderSelectionStatus Status { get; init; }
+
+ /// The settings to open the encoder with (codec, size, bit depth or bit rate may differ from the request).
+ public required EncodeSettings Settings { get; init; }
+
+ public IVideoEncoderProvider? Provider { get; init; }
+
+ /// The capability expected to serve the encode (the provider makes the final choice).
+ public EncoderCapability? Capability { get; init; }
+
+ /// Lowest codec level the final settings fit (video codecs only).
+ public CodecLevel? Level { get; init; }
+
+ public IReadOnlyList Notices { get; init; } = [];
+
+ public bool IsReady => Status == EncoderSelectionStatus.Ready;
+
+ /// Opens the session; only valid when .
+ public IVideoEncoderSession Open() =>
+ Provider is not null && IsReady ? Provider.Open(Settings) : throw new InvalidOperationException($"No encoder is ready ({Status})");
+}
+
+/// Notice keys produced by .
+public static class EncoderNotices
+{
+ public const string NeedsRenderNode = "Export.Encoder.NeedsRenderNode";
+ public const string NoEncoder = "Export.Encoder.NoEncoder";
+ public const string FallbackToH264 = "Export.Encoder.FallbackToH264";
+ public const string SoftwareOnly = "Export.Encoder.SoftwareOnly";
+ public const string TenBitUnavailable = "Export.Encoder.TenBitUnavailable";
+ public const string BitDepthAdjusted = "Export.Encoder.BitDepthAdjusted";
+ public const string ResolutionCappedByLevel = "Export.Encoder.ResolutionCappedByLevel";
+ public const string ResolutionCappedByEncoder = "Export.Encoder.ResolutionCappedByEncoder";
+ public const string BitRateCapped = "Export.Encoder.BitRateCapped";
+}
+
+///
+/// Picks the encoder for an export (BRIEF §11.3). Providers are given in priority order (client: Media Foundation, then
+/// managed; server: managed only).
+///
+/// - Managed codecs go to the first provider that accepts them; an unsupported bit depth becomes the shallowest
+/// supported depth that keeps all its precision (or the deepest available).
+/// - H.264/HEVC/AV1 on the server need a render node. On a client the capability is chosen by named encoder, then
+/// 10-bit support when asked, then hardware (or software) as preferred, then provider order. HEVC and AV1 without any
+/// encoder fall back to H.264 8-bit (bit rate scaled by the bits-per-pixel defaults), 10-bit without a 10-bit encoder
+/// drops to 8-bit, and the size is capped to the highest codec level and to the encoder's maximum (aspect kept, even
+/// sizes), the bit rate to the level's ceiling. Every adjustment carries a notice.
+///
+///
+public static class EncoderSelector
+{
+ public static EncoderSelection Select(EncodeSettings requested, IReadOnlyList providers, EncoderHost host)
+ {
+ ArgumentNullException.ThrowIfNull(requested);
+ ArgumentNullException.ThrowIfNull(providers);
+ var notices = new List();
+ return VideoCodecInfo.IsManaged(requested.Codec)
+ ? SelectManaged(requested, providers, notices)
+ : SelectVideo(requested, providers, host, notices);
+ }
+
+ private static EncoderSelection SelectManaged(EncodeSettings settings, IReadOnlyList providers, List notices)
+ {
+ var depths = ManagedEncoderProvider.BitDepths(settings.Codec);
+ if (depths.Count > 0 && !depths.Contains(settings.BitDepth))
+ {
+ var deeper = depths.Where(d => d >= settings.BitDepth).ToList();
+ var depth = deeper.Count > 0 ? deeper.Min() : depths.Max();
+ notices.Add(new EncoderNotice(EncoderNotices.BitDepthAdjusted, Invariant(settings.BitDepth), Invariant(depth)));
+ settings = settings with { BitDepth = depth };
+ }
+ foreach (var provider in providers)
+ {
+ if (!provider.CanEncode(settings)) continue;
+ return new EncoderSelection
+ {
+ Status = EncoderSelectionStatus.Ready,
+ Settings = settings,
+ Provider = provider,
+ Capability = provider.Capabilities.FirstOrDefault(c => c.Codec == settings.Codec),
+ Notices = notices,
+ };
+ }
+ notices.Add(new EncoderNotice(EncoderNotices.NoEncoder, settings.Codec.ToString()));
+ return new EncoderSelection { Status = EncoderSelectionStatus.Unavailable, Settings = settings, Notices = notices };
+ }
+
+ private static EncoderSelection SelectVideo(EncodeSettings settings, IReadOnlyList providers, EncoderHost host, List notices)
+ {
+ if (host == EncoderHost.Server)
+ {
+ notices.Add(new EncoderNotice(EncoderNotices.NeedsRenderNode, settings.Codec.ToString()));
+ return new EncoderSelection { Status = EncoderSelectionStatus.NeedsRenderNode, Settings = settings, Notices = notices };
+ }
+ if (settings.Codec != VideoCodec.H264 && Candidates(providers, settings.Codec).Count == 0)
+ {
+ notices.Add(new EncoderNotice(EncoderNotices.FallbackToH264, settings.Codec.ToString()));
+ var factor = ExportPreset.DefaultBitsPerPixel(VideoCodec.H264) / ExportPreset.DefaultBitsPerPixel(settings.Codec);
+ settings = settings with
+ {
+ Codec = VideoCodec.H264,
+ Profile = CodecProfile.H264High,
+ BitDepth = 8,
+ BitRate = (long)double.Round(settings.BitRate * factor),
+ };
+ }
+ if (settings.Codec == VideoCodec.H264 && settings.BitDepth != 8)
+ {
+ notices.Add(new EncoderNotice(EncoderNotices.BitDepthAdjusted, Invariant(settings.BitDepth), "8"));
+ settings = settings with { BitDepth = 8 };
+ }
+
+ var candidates = Candidates(providers, settings.Codec);
+ if (candidates.Count == 0)
+ {
+ notices.Add(new EncoderNotice(EncoderNotices.NoEncoder, settings.Codec.ToString()));
+ return new EncoderSelection { Status = EncoderSelectionStatus.Unavailable, Settings = settings, Notices = notices };
+ }
+ var wantsTenBit = settings.BitDepth > 8;
+ var ordered = candidates
+ .Select((c, order) => (c.Provider, c.Capability, Order: order))
+ .OrderByDescending(c => settings.EncoderName is not null && c.Capability.Name == settings.EncoderName)
+ .ThenByDescending(c => wantsTenBit && c.Capability.SupportsTenBit)
+ .ThenByDescending(c => c.Capability.Hardware == settings.PreferHardware)
+ .ThenBy(c => c.Order)
+ .ToList();
+
+ foreach (var (provider, capability, _) in ordered)
+ {
+ var local = new List(notices);
+ var adjusted = Fit(settings, capability, local);
+ if (!provider.CanEncode(adjusted)) continue;
+ if (settings.PreferHardware && !capability.Hardware) local.Add(new EncoderNotice(EncoderNotices.SoftwareOnly, capability.Name));
+ var check = CodecLimits.Check(adjusted.Codec, adjusted.Width, adjusted.Height, adjusted.FrameRate.Value, adjusted.BitRate, adjusted.Profile);
+ return new EncoderSelection
+ {
+ Status = EncoderSelectionStatus.Ready,
+ Settings = adjusted,
+ Provider = provider,
+ Capability = capability,
+ Level = check.Level,
+ Notices = local,
+ };
+ }
+ notices.Add(new EncoderNotice(EncoderNotices.NoEncoder, settings.Codec.ToString()));
+ return new EncoderSelection { Status = EncoderSelectionStatus.Unavailable, Settings = settings, Notices = notices };
+ }
+
+ private static List<(IVideoEncoderProvider Provider, EncoderCapability Capability)> Candidates(IReadOnlyList providers, VideoCodec codec) =>
+ [.. providers.SelectMany(p => p.Capabilities.Where(c => c.Codec == codec).Select(c => (p, c)))];
+
+ /// Applies bit-depth, level and encoder-size limits for one capability.
+ private static EncodeSettings Fit(EncodeSettings s, EncoderCapability capability, List notices)
+ {
+ if (s.BitDepth > 8 && !capability.SupportsTenBit)
+ {
+ notices.Add(new EncoderNotice(EncoderNotices.TenBitUnavailable, capability.Name));
+ s = s with { BitDepth = 8, Profile = s.Profile == CodecProfile.HevcMain10 ? CodecProfile.HevcMain : s.Profile };
+ }
+ var even = (Width: s.Width & ~1, Height: s.Height & ~1);
+ s = s with { Width = int.Max(2, even.Width), Height = int.Max(2, even.Height) };
+
+ var fps = s.FrameRate.Value;
+ var check = CodecLimits.Check(s.Codec, s.Width, s.Height, fps, 0, s.Profile);
+ if (!check.Fits && check.SuggestedWidth > 0)
+ {
+ s = s with { Width = check.SuggestedWidth, Height = check.SuggestedHeight };
+ notices.Add(new EncoderNotice(EncoderNotices.ResolutionCappedByLevel, check.HighestLevel.Name, Size(s)));
+ }
+ if (s.Width > capability.MaxWidth || s.Height > capability.MaxHeight)
+ {
+ var scale = double.Min((double)capability.MaxWidth / s.Width, (double)capability.MaxHeight / s.Height);
+ var width = int.Max(2, (int)(s.Width * scale) & ~1);
+ var height = int.Max(2, (int)double.Round(width * (double)s.Height / s.Width / 2) * 2);
+ if (height > capability.MaxHeight) height = capability.MaxHeight & ~1;
+ s = s with { Width = width, Height = height };
+ notices.Add(new EncoderNotice(EncoderNotices.ResolutionCappedByEncoder, capability.Name, Size(s)));
+ }
+ var limits = CodecLimits.Check(s.Codec, s.Width, s.Height, fps, 0, s.Profile);
+ if (s.BitRate > limits.MaxBitRate)
+ {
+ s = s with { BitRate = limits.MaxBitRate };
+ notices.Add(new EncoderNotice(EncoderNotices.BitRateCapped, limits.HighestLevel.Name, Invariant(limits.MaxBitRate)));
+ }
+ return s;
+ }
+
+ private static string Size(EncodeSettings s) => string.Create(CultureInfo.InvariantCulture, $"{s.Width}×{s.Height}");
+
+ private static string Invariant(long value) => value.ToString(CultureInfo.InvariantCulture);
+}
diff --git a/src/Titano.Core/Export/ExportEstimate.cs b/src/Titano.Core/Export/ExportEstimate.cs
new file mode 100644
index 00000000..bcd09ba0
--- /dev/null
+++ b/src/Titano.Core/Export/ExportEstimate.cs
@@ -0,0 +1,145 @@
+using Titano.Core.Video;
+
+namespace Titano.Core.Export;
+
+/// What a render will do, in the units the estimates need.
+/// Distinct output pictures (planned frames).
+/// Output frame periods (pictures repeated on constant-rate outputs).
+/// Video duration.
+/// Output width.
+/// Output height.
+/// Pixels of each decoded source frame.
+/// Output frames that need optical flow (synthesised or motion-blurred).
+/// Frames read by the preparation pass (0 when cached analysis covers everything).
+/// True when a hardware encoder is expected.
+public sealed record ExportWorkload(
+ int OutputFrames,
+ int OutputPeriods,
+ double DurationSeconds,
+ int Width,
+ int Height,
+ long WorkingPixels,
+ int FlowFrames,
+ int AnalysisFrames,
+ bool HardwareEncoder);
+
+/// Estimated output size and render time.
+public sealed record ExportEstimate(long Bytes, TimeSpan Time);
+
+///
+/// Throughput of the stages on this machine, in megapixels (or frames) per second. Defaults are conservative figures
+/// for a 4-core desktop; folds the measured time of a finished render into .
+///
+public sealed record ThroughputModel
+{
+ public static ThroughputModel Default { get; } = new();
+
+ public double DecodeMegapixelsPerSecond { get; init; } = 80;
+
+ /// Exposure, geometry and stacking per working-size pixel.
+ public double ProcessMegapixelsPerSecond { get; init; } = 60;
+
+ /// Optical flow plus synthesis or blur per output pixel.
+ public double FlowMegapixelsPerSecond { get; init; } = 5;
+
+ public double AnalysisFramesPerSecond { get; init; } = 40;
+
+ public double HardwareEncodeMegapixelsPerSecond { get; init; } = 400;
+
+ public double SoftwareVideoEncodeMegapixelsPerSecond { get; init; } = 50;
+
+ public double JpegEncodeMegapixelsPerSecond { get; init; } = 60;
+
+ public double PngEncodeMegapixelsPerSecond { get; init; } = 12;
+
+ public double TiffEncodeMegapixelsPerSecond { get; init; } = 25;
+
+ public double GifEncodeMegapixelsPerSecond { get; init; } = 20;
+
+ /// Machine factor learnt from finished renders (2 = twice as fast as the defaults).
+ public double Scale { get; init; } = 1;
+
+ /// Moves towards the ratio of a predicted to an actual render time.
+ /// 0 keeps the old scale, 1 adopts the new measurement entirely.
+ public ThroughputModel Calibrate(TimeSpan predicted, TimeSpan actual, double weight = 0.5)
+ {
+ if (predicted <= TimeSpan.Zero || actual <= TimeSpan.Zero) return this;
+ var ratio = predicted.TotalSeconds / actual.TotalSeconds;
+ return this with { Scale = double.Clamp(Scale * double.Pow(ratio, double.Clamp(weight, 0, 1)), 0.02, 50) };
+ }
+
+ internal double EncodeMegapixelsPerSecond(VideoCodec codec, bool hardware) => codec switch
+ {
+ VideoCodec.H264 or VideoCodec.Hevc or VideoCodec.Av1 => hardware ? HardwareEncodeMegapixelsPerSecond : SoftwareVideoEncodeMegapixelsPerSecond,
+ VideoCodec.Mjpeg or VideoCodec.JpegSequence => JpegEncodeMegapixelsPerSecond,
+ VideoCodec.PngSequence or VideoCodec.Apng => PngEncodeMegapixelsPerSecond,
+ VideoCodec.Gif => GifEncodeMegapixelsPerSecond,
+ _ => TiffEncodeMegapixelsPerSecond,
+ };
+}
+
+///
+/// Output size and render time estimates for the Export tab. Video codecs: bit rate × duration plus 1 % container
+/// overhead. Frame-based outputs: bits per pixel typical of photographic time-lapse content — JPEG by quality
+/// (≈1 bpp at 50 to ≈9 bpp at 100), PNG 12/30 bpp (8/16-bit), TIFF-16 30 bpp, DNG 26 bpp, GIF 2.5 bpp for the first
+/// frame and 1.2 bpp per difference frame, APNG 10 and 6 bpp — times the pictures written (constant-rate outputs repeat
+/// held pictures).
+///
+public static class ExportEstimator
+{
+ private static readonly (int Quality, double Bpp)[] JpegBits = [(1, 0.3), (50, 1.0), (75, 1.6), (85, 2.2), (90, 2.8), (95, 4.0), (100, 9.0)];
+
+ public static ExportEstimate Estimate(ResolvedExport export, ExportWorkload workload, ThroughputModel? model = null)
+ {
+ ArgumentNullException.ThrowIfNull(export);
+ ArgumentNullException.ThrowIfNull(workload);
+ return new ExportEstimate(EstimateBytes(export, workload), EstimateTime(export.Codec, workload, model ?? ThroughputModel.Default));
+ }
+
+ public static long EstimateBytes(ResolvedExport export, ExportWorkload w)
+ {
+ ArgumentNullException.ThrowIfNull(export);
+ ArgumentNullException.ThrowIfNull(w);
+ double pixels = (double)w.Width * w.Height;
+ var bits = export.Codec switch
+ {
+ VideoCodec.H264 or VideoCodec.Hevc or VideoCodec.Av1 => export.EffectiveBitRate(w.Width, w.Height) * w.DurationSeconds * 1.01,
+ VideoCodec.Mjpeg => (JpegBitsPerPixel(export.Quality) * pixels + 24 * 8) * w.OutputPeriods,
+ VideoCodec.JpegSequence => JpegBitsPerPixel(export.Quality) * pixels * w.OutputPeriods,
+ VideoCodec.PngSequence => (export.BitDepth > 8 ? 30 : 12) * pixels * w.OutputPeriods,
+ VideoCodec.Tiff16Sequence => (export.BitDepth > 8 ? 30 : 12) * pixels * w.OutputPeriods,
+ VideoCodec.LinearDngSequence => 26 * pixels * w.OutputPeriods,
+ VideoCodec.Gif => w.OutputFrames > 0 ? (2.5 + 1.2 * (w.OutputFrames - 1)) * pixels : 0,
+ VideoCodec.Apng => w.OutputFrames > 0 ? (10 + 6.0 * (w.OutputFrames - 1)) * pixels : 0,
+ _ => 0,
+ };
+ return (long)double.Ceiling(bits / 8);
+ }
+
+ public static TimeSpan EstimateTime(VideoCodec codec, ExportWorkload w, ThroughputModel model)
+ {
+ ArgumentNullException.ThrowIfNull(w);
+ ArgumentNullException.ThrowIfNull(model);
+ var outputMp = (double)w.Width * w.Height / 1e6;
+ var workingMp = w.WorkingPixels / 1e6;
+ var seconds = w.AnalysisFrames / model.AnalysisFramesPerSecond
+ + w.OutputFrames * (workingMp / model.DecodeMegapixelsPerSecond + workingMp / model.ProcessMegapixelsPerSecond
+ + outputMp / model.EncodeMegapixelsPerSecond(codec, w.HardwareEncoder))
+ + w.FlowFrames * outputMp / model.FlowMegapixelsPerSecond;
+ return TimeSpan.FromSeconds(seconds / model.Scale);
+ }
+
+ /// Typical JPEG bits per pixel at an IJG quality, piecewise linear between measured points.
+ public static double JpegBitsPerPixel(int quality)
+ {
+ quality = int.Clamp(quality, 1, 100);
+ for (var i = 1; i < JpegBits.Length; i++)
+ {
+ var (q1, b1) = JpegBits[i];
+ if (quality > q1) continue;
+ var (q0, b0) = JpegBits[i - 1];
+ return b0 + (b1 - b0) * (quality - q0) / (q1 - q0);
+ }
+ return JpegBits[^1].Bpp;
+ }
+}
diff --git a/src/Titano.Core/Export/ExportNaming.cs b/src/Titano.Core/Export/ExportNaming.cs
new file mode 100644
index 00000000..f594b0b1
--- /dev/null
+++ b/src/Titano.Core/Export/ExportNaming.cs
@@ -0,0 +1,153 @@
+using System.Globalization;
+using System.Text;
+using Titano.Core.Naming;
+using Titano.Core.Project;
+using Titano.Core.Video;
+
+namespace Titano.Core.Export;
+
+/// Values of the export name tokens.
+public sealed record ExportNameContext
+{
+ /// Shoot date of the sequence (first capture), or the render date when unknown.
+ public required DateTime Date { get; init; }
+
+ public string? Title { get; init; }
+
+ /// Display name of the preset in the user's language ("Custom" for custom values).
+ public required string PresetName { get; init; }
+
+ public int Width { get; init; }
+ public int Height { get; init; }
+ public Rational FrameRate { get; init; } = new(30, 1);
+ public required VideoCodec Codec { get; init; }
+}
+
+/// An expanded export name and any template problems.
+public sealed record ExportName(string Name, IReadOnlyList Errors)
+{
+ public bool IsValid => Errors.Count == 0;
+}
+
+///
+/// Output names from (BRIEF §11.5). Tokens: {date} (optionally
+/// {date:yyyyMMdd}), {title}, {preset}, {width}, {height}, {fps}, {codec};
+/// {{/}} are literal braces. The result is sanitised like ; an existing file or
+/// folder gets a " (2)", " (3)"… suffix.
+///
+public static class ExportNaming
+{
+ public static IReadOnlyList Tokens { get; } = ["date", "title", "preset", "width", "height", "fps", "codec"];
+
+ /// Name used when a template expands to nothing.
+ public const string FallbackName = "Render";
+
+ /// Short, file-name safe codec label ("H.264", "HEVC", "PNG"…).
+ public static string CodecLabel(VideoCodec codec) => codec switch
+ {
+ VideoCodec.H264 => "H.264",
+ VideoCodec.Hevc => "HEVC",
+ VideoCodec.Av1 => "AV1",
+ VideoCodec.Mjpeg => "MJPEG",
+ VideoCodec.JpegSequence => "JPEG",
+ VideoCodec.PngSequence => "PNG",
+ VideoCodec.Tiff16Sequence => "TIFF",
+ VideoCodec.LinearDngSequence => "DNG",
+ VideoCodec.Gif => "GIF",
+ VideoCodec.Apng => "APNG",
+ _ => codec.ToString(),
+ };
+
+ /// Expands into a sanitised name without extension.
+ public static ExportName Expand(string template, ExportNameContext context)
+ {
+ ArgumentNullException.ThrowIfNull(template);
+ ArgumentNullException.ThrowIfNull(context);
+ var errors = new List();
+ var sb = new StringBuilder();
+ for (var i = 0; i < template.Length; i++)
+ {
+ var c = template[i];
+ if ((c == '{' || c == '}') && i + 1 < template.Length && template[i + 1] == c)
+ {
+ sb.Append(c);
+ i++;
+ continue;
+ }
+ if (c == '}')
+ {
+ errors.Add(new TemplateError(i, "UnopenedBrace", null));
+ continue;
+ }
+ if (c != '{')
+ {
+ sb.Append(c);
+ continue;
+ }
+ var close = template.IndexOf('}', i + 1);
+ if (close < 0)
+ {
+ errors.Add(new TemplateError(i, "UnclosedBrace", null));
+ sb.Append(template, i, template.Length - i);
+ break;
+ }
+ var body = template[(i + 1)..close];
+ var colon = body.IndexOf(':', StringComparison.Ordinal);
+ var name = (colon < 0 ? body : body[..colon]).Trim().ToLowerInvariant();
+ var format = colon < 0 ? null : body[(colon + 1)..];
+ if (Value(name, format, context) is { } value) sb.Append(value.Replace('/', '-').Replace('\\', '-'));
+ else errors.Add(new TemplateError(i, name.Length == 0 ? "EmptyToken" : "UnknownToken", name));
+ i = close;
+ }
+ var result = PathTemplate.SanitizeSegment(sb.ToString());
+ return new ExportName(result.Length == 0 ? FallbackName : result, errors);
+ }
+
+ ///
+ /// Full output path inside : the expanded name plus the codec's extension, or the bare name
+ /// for image sequences (a folder), made unique against existing files and folders.
+ ///
+ public static string OutputPath(string folder, string template, ExportNameContext context)
+ {
+ ArgumentException.ThrowIfNullOrWhiteSpace(folder);
+ var name = Expand(template, context).Name;
+ var extension = VideoCodecInfo.DefaultContainer(context.Codec) == ContainerFormat.ImageSequence ? string.Empty : VideoCodecInfo.FileExtension(context.Codec);
+ return Unique(folder, name, extension);
+ }
+
+ ///
+ /// Output path of a project's export: or, when unset, the sequence's exports folder,
+ /// named by .
+ ///
+ public static string OutputPath(ExportSettings settings, string sequenceExportsFolder, ExportNameContext context)
+ {
+ ArgumentNullException.ThrowIfNull(settings);
+ return OutputPath(string.IsNullOrWhiteSpace(settings.Folder) ? sequenceExportsFolder : settings.Folder, settings.NameTemplate, context);
+ }
+
+ /// "name.ext", or "name (2).ext", "name (3).ext"… when a file or folder of that name exists.
+ public static string Unique(string folder, string name, string extension)
+ {
+ for (var n = 1; ; n++)
+ {
+ var candidate = Path.Combine(folder, (n == 1 ? name : string.Create(CultureInfo.InvariantCulture, $"{name} ({n})")) + extension);
+ if (!File.Exists(candidate) && !Directory.Exists(candidate)) return candidate;
+ }
+ }
+
+ private static string? Value(string token, string? format, ExportNameContext c)
+ {
+ var inv = CultureInfo.InvariantCulture;
+ return token switch
+ {
+ "date" => c.Date.ToString(format ?? "yyyy-MM-dd", inv),
+ "title" => c.Title ?? string.Empty,
+ "preset" => c.PresetName,
+ "width" => c.Width.ToString(format, inv),
+ "height" => c.Height.ToString(format, inv),
+ "fps" => c.FrameRate.ToString(),
+ "codec" => CodecLabel(c.Codec),
+ _ => null,
+ };
+ }
+}
diff --git a/src/Titano.Core/Export/ExportResolver.cs b/src/Titano.Core/Export/ExportResolver.cs
new file mode 100644
index 00000000..36be3b54
--- /dev/null
+++ b/src/Titano.Core/Export/ExportResolver.cs
@@ -0,0 +1,229 @@
+using Titano.Core.Project;
+using Titano.Core.Video;
+
+namespace Titano.Core.Export;
+
+/// Export values after applying a project's overrides to its preset (BRIEF §11.4).
+public sealed record ResolvedExport
+{
+ /// Id of the preset whose values these are, or .
+ public required string PresetId { get; init; }
+
+ /// Id of the preset the overrides were applied to.
+ public required string BasePresetId { get; init; }
+
+ /// Localisation key of the effective preset's name; null when custom.
+ public string? NameKey { get; init; }
+
+ public bool IsCustom => PresetId == ExportResolver.CustomId;
+
+ public required VideoCodec Codec { get; init; }
+
+ public ContainerFormat Container => VideoCodecInfo.DefaultContainer(Codec);
+
+ public CodecProfile Profile { get; init; }
+
+ public int BitDepth { get; init; } = 8;
+
+ /// Output width; 0 derives it from the height and the aspect, or from the source.
+ public int Width { get; init; }
+
+ /// Output height; 0 derives it from the width and the aspect, or from the source.
+ public int Height { get; init; }
+
+ public Rational FrameRate { get; init; } = new(30, 1);
+
+ /// Fixed bit rate in bit/s; 0 = at the render size.
+ public long BitRate { get; init; }
+
+ public double BitsPerPixel { get; init; }
+
+ /// Key-frame distance in frames.
+ public int GopFrames { get; init; }
+
+ public int BFrames { get; init; }
+
+ public int Quality { get; init; } = 92;
+
+ public RateControl RateControl { get; init; } = RateControl.Vbr;
+
+ /// Specific encoder name requested by the user, or null.
+ public string? Encoder { get; init; }
+
+ /// Localisation keys of ignored or invalid override values.
+ public IReadOnlyList Warnings { get; init; } = [];
+
+ /// Average bit rate for a render of ×.
+ public long EffectiveBitRate(int width, int height)
+ {
+ if (BitRate > 0) return BitRate;
+ var bpp = BitsPerPixel > 0 ? BitsPerPixel : ExportPreset.DefaultBitsPerPixel(Codec);
+ return (long)double.Round(bpp * width * height * FrameRate.Value);
+ }
+
+ public EncodeSettings ToEncodeSettings(string outputPath, int width, int height) => new()
+ {
+ OutputPath = outputPath,
+ Codec = Codec,
+ Width = width,
+ Height = height,
+ FrameRate = FrameRate,
+ Profile = Profile,
+ BitDepth = BitDepth,
+ RateControl = RateControl,
+ BitRate = EffectiveBitRate(width, height),
+ Quality = Quality,
+ GopLength = GopFrames,
+ BFrames = BFrames,
+ EncoderName = Encoder,
+ };
+}
+
+///
+/// Applies to the selected preset and names the result: the preset's id when the values
+/// equal it (or equal another preset), otherwise. Editing any value therefore flips the name to
+/// "Custom" and editing it back restores the preset name. Unknown or contradictory override values are ignored with a
+/// warning key.
+///
+public static class ExportResolver
+{
+ public const string CustomId = "custom";
+
+ /// Preset used when none is selected, the stored id is unknown or the selection is "custom".
+ public const string DefaultPresetId = "1080p-h264";
+
+ public static ResolvedExport Resolve(ExportSettings settings, IReadOnlyList? presets = null)
+ {
+ ArgumentNullException.ThrowIfNull(settings);
+ presets ??= ExportPresets.BuiltIn;
+ var warnings = new List();
+ var id = settings.Preset.Resolve(DefaultPresetId);
+ var basePreset = Find(presets, id) ?? Find(presets, DefaultPresetId) ?? presets.FirstOrDefault()
+ ?? throw new ArgumentException("No presets", nameof(presets));
+ if (!basePreset.Id.Equals(id, StringComparison.OrdinalIgnoreCase) && !id.Equals(CustomId, StringComparison.OrdinalIgnoreCase))
+ warnings.Add("Export.Warning.UnknownPreset");
+
+ var values = Apply(FromPreset(basePreset), settings.Overrides, warnings);
+ var match = Matches(values, FromPreset(basePreset)) ? basePreset : presets.FirstOrDefault(p => Matches(values, FromPreset(p)));
+ return values with
+ {
+ PresetId = match?.Id ?? CustomId,
+ BasePresetId = basePreset.Id,
+ NameKey = match?.NameKey,
+ Warnings = warnings,
+ };
+ }
+
+ /// The preset's own values (no overrides).
+ public static ResolvedExport FromPreset(ExportPreset preset)
+ {
+ ArgumentNullException.ThrowIfNull(preset);
+ return new ResolvedExport
+ {
+ PresetId = preset.Id,
+ BasePresetId = preset.Id,
+ NameKey = preset.NameKey,
+ Codec = preset.Codec,
+ Profile = preset.Profile,
+ BitDepth = preset.BitDepth,
+ Width = preset.Width,
+ Height = preset.Height,
+ FrameRate = preset.FrameRate,
+ BitRate = preset.BitRate,
+ BitsPerPixel = preset.BitsPerPixel,
+ GopFrames = int.Max(1, (int)double.Round(preset.GopSeconds * preset.FrameRate.Value)),
+ BFrames = preset.BFrames,
+ Quality = preset.Quality,
+ };
+ }
+
+ /// Parses a codec name or alias ("h264", "H.265", "hevc", "png", "tiff16", "dng"…).
+ public static bool TryParseCodec(string? text, out VideoCodec codec)
+ {
+ codec = default;
+ if (string.IsNullOrWhiteSpace(text)) return false;
+ var key = text.Trim().ToLowerInvariant().Replace(".", string.Empty, StringComparison.Ordinal).Replace("-", string.Empty, StringComparison.Ordinal).Replace(" ", string.Empty, StringComparison.Ordinal);
+ VideoCodec? parsed = key switch
+ {
+ "h264" or "avc" => VideoCodec.H264,
+ "h265" or "hevc" => VideoCodec.Hevc,
+ "av1" => VideoCodec.Av1,
+ "mjpeg" or "mjpg" => VideoCodec.Mjpeg,
+ "jpeg" or "jpg" or "jpegsequence" => VideoCodec.JpegSequence,
+ "png" or "pngsequence" => VideoCodec.PngSequence,
+ "tiff" or "tif" or "tiff16" or "tiff16sequence" => VideoCodec.Tiff16Sequence,
+ "dng" or "lineardng" or "lineardngsequence" => VideoCodec.LinearDngSequence,
+ "gif" => VideoCodec.Gif,
+ "apng" => VideoCodec.Apng,
+ _ => null,
+ };
+ if (parsed is null) return false;
+ codec = parsed.Value;
+ return true;
+ }
+
+ private static ExportPreset? Find(IReadOnlyList presets, string id) =>
+ presets.FirstOrDefault(p => p.Id.Equals(id, StringComparison.OrdinalIgnoreCase));
+
+ private static ResolvedExport Apply(ResolvedExport v, ExportOverrides o, List warnings)
+ {
+ if (o.Codec is not null)
+ {
+ if (TryParseCodec(o.Codec, out var codec))
+ {
+ if (codec != v.Codec) v = v with { Codec = codec, Profile = CodecProfile.Auto, BitRate = 0, BitsPerPixel = 0 };
+ }
+ else
+ {
+ warnings.Add("Export.Warning.UnknownCodec");
+ }
+ }
+ if (o.Container is not null && !ContainerMatches(o.Container, v.Container)) warnings.Add("Export.Warning.ContainerIgnored");
+ if (o.Profile is not null)
+ {
+ if (Enum.TryParse(o.Profile, ignoreCase: true, out var profile) && Enum.IsDefined(profile)) v = v with { Profile = profile };
+ else warnings.Add("Export.Warning.UnknownProfile");
+ }
+ if (o.BitDepth is { } depth) v = v with { BitDepth = depth };
+ if (o.Width is { } width) v = v with { Width = int.Max(0, width) };
+ if (o.Height is { } height) v = v with { Height = int.Max(0, height) };
+ if (o.FrameRate is not null)
+ {
+ if (FrameRateText.TryParse(o.FrameRate, out var rate))
+ {
+ // A preset's GOP is defined in seconds: keep its duration at the new rate unless the GOP is overridden too.
+ var seconds = v.GopFrames / v.FrameRate.Value;
+ v = v with { FrameRate = rate, GopFrames = int.Max(1, (int)double.Round(seconds * rate.Value)) };
+ }
+ else
+ {
+ warnings.Add("Export.Warning.UnknownFrameRate");
+ }
+ }
+ if (o.BitRate is { } bitRate) v = v with { BitRate = long.Max(0, bitRate) };
+ if (o.GopFrames is { } gop) v = v with { GopFrames = int.Max(1, gop) };
+ if (o.BFrames is { } bFrames) v = v with { BFrames = int.Max(0, bFrames) };
+ if (o.Quality is { } quality) v = v with { Quality = int.Clamp(quality, 1, 100) };
+ if (o.RateControl is not null)
+ {
+ if (Enum.TryParse(o.RateControl, ignoreCase: true, out var rc) && Enum.IsDefined(rc)) v = v with { RateControl = rc };
+ else warnings.Add("Export.Warning.UnknownRateControl");
+ }
+ if (o.Encoder is not null) v = v with { Encoder = string.IsNullOrWhiteSpace(o.Encoder) ? null : o.Encoder };
+ return v;
+ }
+
+ private static bool ContainerMatches(string text, ContainerFormat container) =>
+ Enum.TryParse(text, ignoreCase: true, out var parsed) && parsed == container;
+
+ /// Equal export values; bit rates compare as effective rates when the size is fixed.
+ private static bool Matches(ResolvedExport a, ResolvedExport b)
+ {
+ if (a.Codec != b.Codec || a.Profile != b.Profile || a.BitDepth != b.BitDepth || a.Width != b.Width || a.Height != b.Height
+ || !FrameRateText.AreEqual(a.FrameRate, b.FrameRate) || a.GopFrames != b.GopFrames || a.BFrames != b.BFrames
+ || a.Quality != b.Quality || a.RateControl != b.RateControl || a.Encoder != b.Encoder) return false;
+ return a.Width > 0 && a.Height > 0
+ ? a.EffectiveBitRate(a.Width, a.Height) == b.EffectiveBitRate(b.Width, b.Height)
+ : a.BitRate == b.BitRate && a.BitsPerPixel == b.BitsPerPixel;
+ }
+}
diff --git a/src/Titano.Core/Export/FrameRateText.cs b/src/Titano.Core/Export/FrameRateText.cs
new file mode 100644
index 00000000..c4a6013c
--- /dev/null
+++ b/src/Titano.Core/Export/FrameRateText.cs
@@ -0,0 +1,36 @@
+using System.Globalization;
+using Titano.Core.Video;
+
+namespace Titano.Core.Export;
+
+/// Frame rates as stored in project files: "num/den" ("24000/1001"), a decimal ("29.97") or an integer ("30").
+public static class FrameRateText
+{
+ /// Parses a frame rate; decimals near the NTSC rates map to their exact fractions.
+ public static bool TryParse(string? text, out Rational rate)
+ {
+ rate = default;
+ if (string.IsNullOrWhiteSpace(text)) return false;
+ var s = text.Trim();
+ var slash = s.IndexOf('/', StringComparison.Ordinal);
+ if (slash >= 0)
+ {
+ if (!int.TryParse(s.AsSpan(0, slash), NumberStyles.None, CultureInfo.InvariantCulture, out var num)
+ || !int.TryParse(s.AsSpan(slash + 1), NumberStyles.None, CultureInfo.InvariantCulture, out var den)
+ || num <= 0 || den <= 0) return false;
+ rate = new Rational(num, den);
+ return true;
+ }
+ if (!double.TryParse(s, NumberStyles.Float, CultureInfo.InvariantCulture, out var fps) || !(fps > 0 && fps <= 1000)) return false;
+ rate = Rational.FromFps(fps);
+ return true;
+ }
+
+ /// Canonical text: "num/den" for fractional rates, the integer otherwise.
+ public static string Format(Rational rate) => rate.Denominator == 1
+ ? rate.Numerator.ToString(CultureInfo.InvariantCulture)
+ : string.Create(CultureInfo.InvariantCulture, $"{rate.Numerator}/{rate.Denominator}");
+
+ /// Exact rational equality (24000/1001 equals 48000/2002).
+ public static bool AreEqual(Rational a, Rational b) => (long)a.Numerator * b.Denominator == (long)b.Numerator * a.Denominator;
+}
diff --git a/src/Titano.Core/Render/Diagnostics/OutputReaders.cs b/src/Titano.Core/Render/Diagnostics/OutputReaders.cs
new file mode 100644
index 00000000..ddc7f5d3
--- /dev/null
+++ b/src/Titano.Core/Render/Diagnostics/OutputReaders.cs
@@ -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;
+
+/// A composed animation frame (8-bit sRGB RGBA canvas) and how long it is shown.
+internal sealed record AnimationFrame(byte[] Rgba, long Duration90k);
+
+/// A decoded GIF or APNG used to verify rendered outputs.
+internal sealed record AnimationInfo(int Width, int Height, IReadOnlyList Frames, int? LoopCount)
+{
+ public long Duration90k => Frames.Sum(f => f.Duration90k);
+
+ /// Frame as a linear-light RGB buffer (alpha dropped).
+ public ImageBuffer ToLinear(int index) => PixelConvert.FromInterleaved8(Frames[index].Rgba, Width, Height, 4, TransferFunction.Srgb, 3);
+}
+
+/// The structure of an MJPEG AVI: headers, the JPEG of every frame and the legacy index size.
+internal sealed record AviInfo(int Width, int Height, Rational FrameRate, int HeaderFrames, int StreamFrames, IReadOnlyList Frames, int IndexEntries);
+
+/// Bounds-checked big/little-endian reads; every violation is an .
+internal ref struct ByteCursor(ReadOnlySpan data)
+{
+ private readonly ReadOnlySpan _data = data;
+
+ public int Position { get; set; }
+
+ public readonly int Remaining => _data.Length - Position;
+
+ public ReadOnlySpan 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));
+}
+
+/// Reads AVI files written by (RIFF 'AVI ' plus 'AVIX' continuations).
+internal static class AviReader
+{
+ public static AviInfo Read(ReadOnlySpan data)
+ {
+ var cursor = new ByteCursor(data);
+ var frames = new List();
+ 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 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;
+ }
+ }
+}
+
+/// GIF89a decoder with frame composition (disposal 0–3, transparency) for output verification.
+internal static class GifReader
+{
+ public static AnimationInfo Decode(ReadOnlySpan 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();
+ 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));
+ }
+ }
+
+ /// Variable-length LZW (GIF flavour: clear/end codes, codes up to 12 bits, deferred clear allowed).
+ 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;
+ }
+}
+
+/// 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 ).
+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 Data { get; } = [];
+ }
+
+ public static AnimationInfo Decode(ReadOnlySpan 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();
+ 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(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 body)
+ {
+ if (BinaryPrimitives.ReadUInt32BigEndian(body) != sequence) throw new InvalidDataException($"Sequence number {sequence} expected");
+ sequence++;
+ }
+
+ /// Decodes one frame's data as a stand-alone PNG with the frame's size.
+ 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;
+ }
+ }
+ }
+}
diff --git a/src/Titano.Core/Render/Diagnostics/PatternFrameSource.cs b/src/Titano.Core/Render/Diagnostics/PatternFrameSource.cs
new file mode 100644
index 00000000..e2a7bc90
--- /dev/null
+++ b/src/Titano.Core/Render/Diagnostics/PatternFrameSource.cs
@@ -0,0 +1,105 @@
+using Titano.Core.Imaging;
+
+namespace Titano.Core.Render.Diagnostics;
+
+///
+/// A continuous fractal value-noise texture (four octaves, periods 4–32 px, amplitude proportional to the period like
+/// natural scenes) moved by a per-frame camera offset: exact sub-pixel motion and broadband texture for stabilisation,
+/// flow and interpolation checks. Unlike per-pixel noise it passes the stabiliser's texture gate, and unlike sinusoids
+/// it has no periodic ambiguity.
+///
+public sealed class PatternFrameSource(int width, int height, int frameCount, Func? cameraMotion = null, double intervalSeconds = 10)
+ : IRenderFrameSource
+{
+ private static readonly DateTime Start = new(2024, 6, 21, 21, 0, 0);
+
+ public int FrameCount { get; } = frameCount > 0 ? frameCount : throw new ArgumentOutOfRangeException(nameof(frameCount));
+
+ public int Width { get; } = width > 0 ? width : throw new ArgumentOutOfRangeException(nameof(width));
+
+ public int Height { get; } = height > 0 ? height : throw new ArgumentOutOfRangeException(nameof(height));
+
+ /// Content displacement of frame in full-resolution pixels.
+ public (double X, double Y) Offset(int index) => cameraMotion?.Invoke(index) ?? (0, 0);
+
+ /// Regular capture times, 1/250 s exposures.
+ public SourceFrameInfo[] Metadata()
+ {
+ var result = new SourceFrameInfo[FrameCount];
+ for (var i = 0; i < FrameCount; i++) result[i] = new SourceFrameInfo(Start.AddSeconds(i * intervalSeconds), 1.0 / 250, 10);
+ return result;
+ }
+
+ /// The texture at full resolution displaced by (, ).
+ public ImageBuffer Render(double dx, double dy)
+ {
+ var image = new ImageBuffer(Width, Height, 3, clear: false);
+ var r = image.Plane(0);
+ var g = image.Plane(1);
+ var b = image.Plane(2);
+ for (var y = 0; y < Height; y++)
+ {
+ for (var x = 0; x < Width; x++)
+ {
+ double u = x - dx, v = y - dy;
+ var value = 0.06 + 0.4 * Texture(u, v);
+ var i = y * Width + x;
+ r[i] = (float)(value * (0.9 + 0.2 * ValueNoise(u / 48, v / 48, 101)));
+ g[i] = (float)value;
+ b[i] = (float)(value * (0.8 + 0.2 * ValueNoise(u / 48, v / 48, 102)));
+ }
+ }
+ return image;
+ }
+
+ /// Fractal value noise in [0, 1): octaves of period 4, 8, 16, 32 px weighted by their period.
+ private static double Texture(double x, double y)
+ {
+ double sum = 0, weights = 0;
+ for (var octave = 0; octave < 4; octave++)
+ {
+ double period = 4 << octave;
+ sum += period * ValueNoise(x / period, y / period, octave);
+ weights += period;
+ }
+ return sum / weights;
+ }
+
+ /// Hashed lattice values blended with a C1 smoothstep: continuous in x and y.
+ private static double ValueNoise(double x, double y, int seed)
+ {
+ var xi = (long)double.Floor(x);
+ var yi = (long)double.Floor(y);
+ var fx = x - xi;
+ var fy = y - yi;
+ fx = fx * fx * (3 - 2 * fx);
+ fy = fy * fy * (3 - 2 * fy);
+ var a = Hash(xi, yi, seed);
+ var b = Hash(xi + 1, yi, seed);
+ var c = Hash(xi, yi + 1, seed);
+ var d = Hash(xi + 1, yi + 1, seed);
+ var top = a + (b - a) * fx;
+ return top + (c + (d - c) * fx - top) * fy;
+ }
+
+ /// Uniform [0, 1) from a SplitMix64 mix of the lattice point (stable across processes).
+ private static double Hash(long x, long y, int seed)
+ {
+ var z = unchecked((ulong)x * 0x9E3779B97F4A7C15UL ^ (ulong)y * 0xC2B2AE3D27D4EB4FUL ^ (ulong)(uint)seed * 0x165667B19E3779F9UL);
+ z = unchecked((z ^ (z >> 30)) * 0xBF58476D1CE4E5B9UL);
+ z = unchecked((z ^ (z >> 27)) * 0x94D049BB133111EBUL);
+ z ^= z >> 31;
+ return (z >> 11) * (1.0 / (1UL << 53));
+ }
+
+ public ValueTask GetFrameAsync(int index, int maxLongEdge, DecodePurpose purpose, CancellationToken cancellationToken)
+ {
+ ArgumentOutOfRangeException.ThrowIfNegative(index);
+ ArgumentOutOfRangeException.ThrowIfGreaterThanOrEqual(index, FrameCount);
+ cancellationToken.ThrowIfCancellationRequested();
+ var (dx, dy) = Offset(index);
+ var frame = Render(dx, dy);
+ if (maxLongEdge <= 0 || int.Max(Width, Height) <= maxLongEdge) return ValueTask.FromResult(frame);
+ using (frame) return ValueTask.FromResult(Resampler.Thumbnail(frame, maxLongEdge));
+ }
+}
diff --git a/src/Titano.Core/Render/Diagnostics/SelfTest.cs b/src/Titano.Core/Render/Diagnostics/SelfTest.cs
new file mode 100644
index 00000000..735ce36b
--- /dev/null
+++ b/src/Titano.Core/Render/Diagnostics/SelfTest.cs
@@ -0,0 +1,219 @@
+using System.Diagnostics;
+using System.Globalization;
+using Titano.Core.Codecs.Png;
+using Titano.Core.Diagnostics.Synthetic;
+using Titano.Core.Export;
+using Titano.Core.Imaging;
+using Titano.Core.Project;
+using Titano.Core.Video;
+using Titano.Core.Video.Managed;
+
+namespace Titano.Core.Render.Diagnostics;
+
+public enum SelfTestOutcome
+{
+ Passed,
+ Failed,
+
+ /// The check needs something this machine does not have (e.g. an MP4 encoder).
+ Skipped,
+}
+
+/// Outcome of one self-test check; carries the measured figures or the failure.
+public sealed record SelfTestResult(string Id, string Group, string Description, SelfTestOutcome Outcome, string Detail, TimeSpan Elapsed);
+
+/// What a check may use: its own empty folder, the encoders, and the run's cancellation.
+public sealed record SelfTestContext(string WorkDirectory, IReadOnlyList Encoders, IReadOnlyList PlatformEncoders,
+ CancellationToken Cancellation);
+
+/// One end-to-end check; it returns a short detail on success and throws on failure.
+public sealed record SelfTestCheck(string Id, string Group, string Description, Func> Run);
+
+public sealed record SelfTestOptions
+{
+ /// Platform encoders tested in addition to the managed ones (the desktop passes Media Foundation).
+ public IReadOnlyList PlatformEncoders { get; init; } = [];
+
+ /// Parent folder of the run's scratch folder (deleted afterwards); default the system temp folder.
+ public string? WorkDirectory { get; init; }
+
+ /// Run only checks whose id starts with one of these prefixes (all when empty).
+ public IReadOnlyList Filters { get; init; } = [];
+}
+
+///
+/// The engine's end-to-end self-test (BRIEF §20.2, §20.4), shared by Titano.Tools selftest and the desktop
+/// Settings page: render plans, export resolution and naming, encoder selection, managed codec round trips, renders of
+/// small synthetic sequences into every managed format (and MP4 when a platform encoder is supplied) with their outputs
+/// decoded back and compared, the processing modules measured on rendered frames, and cancellation, failure,
+/// determinism and memory behaviour.
+///
+public static partial class SelfTest
+{
+ public static IReadOnlyList Checks { get; } = [.. PlanChecks(), .. ExportChecks(), .. CodecChecks(), .. RenderChecks(), .. ProcessingChecks(), .. RobustnessChecks()];
+
+ public static async Task> RunAsync(SelfTestOptions? options = null, IProgress? progress = null,
+ CancellationToken cancellationToken = default)
+ {
+ options ??= new SelfTestOptions();
+ var root = Path.Combine(options.WorkDirectory ?? Path.GetTempPath(), "titano-selftest-" + Guid.NewGuid().ToString("N")[..8]);
+ Directory.CreateDirectory(root);
+ IVideoEncoderProvider[] encoders = [.. options.PlatformEncoders, new ManagedEncoderProvider()];
+ var results = new List();
+ try
+ {
+ foreach (var check in Checks)
+ {
+ if (options.Filters.Count > 0 && !options.Filters.Any(f => check.Id.StartsWith(f, StringComparison.OrdinalIgnoreCase))) continue;
+ cancellationToken.ThrowIfCancellationRequested();
+ var directory = Path.Combine(root, check.Id);
+ Directory.CreateDirectory(directory);
+ var context = new SelfTestContext(directory, encoders, options.PlatformEncoders, cancellationToken);
+ var clock = Stopwatch.StartNew();
+ SelfTestOutcome outcome;
+ string detail;
+ try
+ {
+ detail = await check.Run(context).ConfigureAwait(false);
+ outcome = SelfTestOutcome.Passed;
+ }
+ catch (SkipException skip)
+ {
+ (outcome, detail) = (SelfTestOutcome.Skipped, skip.Message);
+ }
+ catch (OperationCanceledException) when (cancellationToken.IsCancellationRequested)
+ {
+ throw;
+ }
+ catch (Exception ex)
+ {
+ (outcome, detail) = (SelfTestOutcome.Failed, ex is FailureException ? ex.Message : $"{ex.GetType().Name}: {ex.Message}");
+ }
+ var result = new SelfTestResult(check.Id, check.Group, check.Description, outcome, detail, clock.Elapsed);
+ results.Add(result);
+ progress?.Report(result);
+ }
+ }
+ finally
+ {
+ try
+ {
+ Directory.Delete(root, recursive: true);
+ }
+ catch (Exception ex) when (ex is IOException or UnauthorizedAccessException)
+ {
+ Titano.Core.Diagnostics.Log.Warning("SelfTest", "Could not delete " + root, ex);
+ }
+ }
+ return results;
+ }
+
+ private sealed class FailureException(string message) : Exception(message);
+
+ private sealed class SkipException(string message) : Exception(message);
+
+ private static void Require(bool condition, string failure)
+ {
+ if (!condition) throw new FailureException(failure);
+ }
+
+ private static SelfTestCheck Check(string id, string description, Func> run) =>
+ new(id, id[..id.IndexOf('.', StringComparison.Ordinal)], description, run);
+
+ private static SelfTestCheck Check(string id, string description, Func run) => Check(id, description, _ => Task.FromResult(run()));
+
+ private static string Invariant(FormattableString text) => text.ToString(CultureInfo.InvariantCulture);
+
+ /// No module and no knee: renders reproduce the source.
+ private static ProjectSettings Plain { get; } = new() { Exposure = new ExposureSettings { HighlightKnee = null } };
+
+ private static Auto Manual(T value) => new Auto().WithManual(value);
+
+ private static SyntheticFrameSource Synthetic(int frames, Func? configure = null,
+ Func? motion = null)
+ {
+ var options = new SyntheticSequenceOptions { FrameCount = frames, StartEv = 0, EndEv = 1, Seed = 5 };
+ return new SyntheticFrameSource(SyntheticSequence.Create(configure is null ? options : configure(options)), motion);
+ }
+
+ private static RenderInput Input(SyntheticFrameSource source, ProjectSettings? project = null) =>
+ new() { Source = source, Frames = source.Metadata(), Project = project ?? Plain };
+
+ /// A built-in preset's values at the synthetic frame size (or another size; 0×0 = source).
+ private static ResolvedExport Preset(string id, int width = 96, int height = 64) =>
+ ExportResolver.FromPreset(ExportPresets.Find(id)!) with { Width = width, Height = height };
+
+ private static RenderTarget Target(SelfTestContext context, ResolvedExport export, string name = "out") =>
+ new(export, Path.Combine(context.WorkDirectory, name + (export.Container == ContainerFormat.ImageSequence ? string.Empty : VideoCodecInfo.FileExtension(export.Codec))));
+
+ private static RenderPipeline Pipeline(SelfTestContext context) => new(context.Encoders);
+
+ /// Renders to a 16-bit PNG sequence and decodes every picture back (linear light).
+ private static async Task> RenderDecodedAsync(SelfTestContext context, RenderInput input, ResolvedExport? export = null, string name = "decoded")
+ {
+ var target = Target(context, (export ?? Preset("png-sequence")) with { Codec = VideoCodec.PngSequence, BitDepth = 16 }, name);
+ await Pipeline(context).RenderAsync(input, target, cancellationToken: context.Cancellation).ConfigureAwait(false);
+ var frames = new List();
+ foreach (var file in Directory.GetFiles(target.OutputPath).Order(StringComparer.Ordinal))
+ frames.Add(PngDecoder.DecodeToLinear(await File.ReadAllBytesAsync(file, context.Cancellation).ConfigureAwait(false)));
+ return frames;
+ }
+
+ private static void DisposeAll(IEnumerable frames)
+ {
+ foreach (var f in frames) f.Dispose();
+ }
+
+ /// Peak signal-to-noise ratio of the 8-bit sRGB encodings, optionally inside a margin.
+ private static double Psnr(ImageBuffer expected, ImageBuffer actual, int margin = 0)
+ {
+ var a = PixelConvert.ToInterleaved8(expected, 3);
+ var b = PixelConvert.ToInterleaved8(actual, 3);
+ double sum = 0;
+ long count = 0;
+ for (var y = margin; y < expected.Height - margin; y++)
+ {
+ for (var i = (y * expected.Width + margin) * 3; i < (y * expected.Width + expected.Width - margin) * 3; i++)
+ {
+ sum += (a[i] - b[i]) * (a[i] - b[i]);
+ count++;
+ }
+ }
+ return sum == 0 ? double.PositiveInfinity : 10 * double.Log10(255.0 * 255 / (sum / count));
+ }
+
+ private static double Rms(IReadOnlyList values)
+ {
+ var mean = values.Average();
+ return double.Sqrt(values.Sum(v => (v - mean) * (v - mean)) / values.Count);
+ }
+
+ /// RMS of the frame-to-frame change of (series − truth): flicker relative to the true curve.
+ private static double FrameToFrameResidual(IReadOnlyList series, IReadOnlyList truth)
+ {
+ double sum = 0;
+ for (var i = 1; i < series.Count; i++)
+ {
+ var d = series[i] - series[i - 1] - (truth[i] - truth[i - 1]);
+ sum += d * d;
+ }
+ return double.Sqrt(sum / (series.Count - 1));
+ }
+
+ /// Largest |series − truth − c| with c the mean offset (the measurement constant).
+ private static double MaxDeviation(IReadOnlyList series, IReadOnlyList truth)
+ {
+ var offset = 0.0;
+ for (var i = 0; i < series.Count; i++) offset += series[i] - truth[i];
+ offset /= series.Count;
+ var max = 0.0;
+ for (var i = 0; i < series.Count; i++) max = double.Max(max, double.Abs(series[i] - truth[i] - offset));
+ return max;
+ }
+
+ /// Synchronous progress sink (Progress<T> would post to the thread pool).
+ private sealed class Sink(Action report) : IProgress
+ {
+ public void Report(T value) => report(value);
+ }
+}
diff --git a/src/Titano.Core/Render/Diagnostics/SelfTestChecks.cs b/src/Titano.Core/Render/Diagnostics/SelfTestChecks.cs
new file mode 100644
index 00000000..bdb76ed3
--- /dev/null
+++ b/src/Titano.Core/Render/Diagnostics/SelfTestChecks.cs
@@ -0,0 +1,317 @@
+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.Export;
+using Titano.Core.Imaging;
+using Titano.Core.Metadata.Tiff;
+using Titano.Core.Project;
+using Titano.Core.Video;
+using Titano.Core.Video.Avi;
+
+namespace Titano.Core.Render.Diagnostics;
+
+/// Plan, export, encoder-selection and codec checks.
+public static partial class SelfTest
+{
+ private static readonly DateTime Origin = new(2024, 6, 21, 19, 0, 0);
+
+ private static DateTime?[] Regular(int count) => [.. Enumerable.Range(0, count).Select(i => (DateTime?)Origin.AddSeconds(10 * i))];
+
+ private static ProjectSettings Timing(TimingMode mode, double? fit = null, IReadOnlyList? curve = null, IReadOnlyList? excluded = null) => new()
+ {
+ Timing = new TimingSettings { Mode = Manual(mode), FitToSeconds = fit, RemapCurve = curve ?? [new(0, 0), new(1, 1)] },
+ ExcludedFrames = excluded ?? [],
+ };
+
+ private static void RequireExact(RenderPlan plan)
+ {
+ Require(plan.Frames.Sum(f => f.Duration90k) == plan.Duration90k, "durations do not add up to the total");
+ Require(plan.Duration90k == RenderPlan.TicksAt(plan.FrameRate, plan.SlotCount), "total differs from the period grid");
+ for (var k = 1; k < plan.Frames.Count; k++)
+ {
+ Require(plan.Frames[k].Start90k == plan.Frames[k - 1].Start90k + plan.Frames[k - 1].Duration90k, "frames are not contiguous");
+ Require(plan.Frames[k].SourcePosition >= plan.Frames[k - 1].SourcePosition, "source positions go backwards");
+ }
+ }
+
+ private static IEnumerable PlanChecks()
+ {
+ yield return Check("plan.constant", "Constant timing: one frame per period, exact durations", () =>
+ {
+ var plan = RenderPlan.Build(Regular(120), Timing(TimingMode.Constant), new Rational(24, 1));
+ RequireExact(plan);
+ Require(plan.Frames.Count == 120 && plan.Frames.All(f => f.Duration90k == 3750 && f.Slots == 1), "not one 1/24 s frame per source frame");
+ return Invariant($"120 frames, {plan.DurationSeconds} s");
+ });
+ yield return Check("plan.ntsc", "29.97 fps durations accumulate without drift", () =>
+ {
+ var plan = RenderPlan.Build(Regular(1001), Timing(TimingMode.Constant), Rational.Fps2997);
+ RequireExact(plan);
+ Require(plan.Duration90k == 1001 * 3003L, Invariant($"total {plan.Duration90k} ticks, expected {1001 * 3003L}"));
+ return Invariant($"1001 frames = {plan.Duration90k} ticks");
+ });
+ yield return Check("plan.excluded", "Excluded frames are skipped", () =>
+ {
+ var plan = RenderPlan.Build(Regular(30), Timing(TimingMode.Constant, excluded: [3, 4, 17]), new Rational(30, 1));
+ RequireExact(plan);
+ Require(plan.Frames.Count == 27 && !plan.Frames.Any(f => f.From is 3 or 4 or 17 || f.To is 3 or 4 or 17), "an excluded frame is used");
+ return "27 of 30 frames";
+ });
+ yield return Check("plan.adaptive.gap", "Adaptive: a doubled interval holds the frame for two periods", () =>
+ {
+ var times = Regular(20);
+ for (var i = 10; i < 20; i++) times[i] = times[i]!.Value.AddSeconds(10);
+ var plan = RenderPlan.Build(times, Timing(TimingMode.Adaptive), new Rational(24, 1));
+ RequireExact(plan);
+ Require(plan.Frames[9].Slots == 2 && plan.Frames[9].IsHeld, Invariant($"frame 9 lasts {plan.Frames[9].Slots} periods"));
+ return "held 2 periods";
+ });
+ yield return Check("plan.adaptive.pause", "Adaptive: a deliberate pause becomes a short cut", () =>
+ {
+ var times = Regular(20);
+ for (var i = 10; i < 20; i++) times[i] = times[i]!.Value.AddHours(2);
+ var plan = RenderPlan.Build(times, Timing(TimingMode.Adaptive), new Rational(24, 1));
+ RequireExact(plan);
+ var seconds = plan.Frames[9].Duration90k / 90000.0;
+ Require(seconds <= 0.25 && plan.IsCutBefore(10), Invariant($"pause shown for {seconds:0.###} s"));
+ return Invariant($"2 h pause shown for {seconds:0.###} s");
+ });
+ yield return Check("plan.interpolated", "Interpolated: a missing capture is synthesised half-way", () =>
+ {
+ var times = Regular(20);
+ for (var i = 10; i < 20; i++) times[i] = times[i]!.Value.AddSeconds(10);
+ var plan = RenderPlan.Build(times, Timing(TimingMode.Interpolated), new Rational(24, 1));
+ RequireExact(plan);
+ Require(plan.Frames.Count == 21 && plan.Frames.Count(f => f.IsInterpolated) == 1 && plan.Frames[10].SourcePosition == 9.5, "no synthesised frame at 9.5");
+ return "21 frames, 9.5 synthesised";
+ });
+ yield return Check("plan.remap.monotonic", "Remapped: positions are monotone even for a non-monotone curve", () =>
+ {
+ var plan = RenderPlan.Build(Regular(90), Timing(TimingMode.Remapped, curve: [new(0, 0), new(0.3, 0.6), new(0.5, 0.4), new(1, 1)]), new Rational(24, 1));
+ RequireExact(plan);
+ Require(plan.Warnings.Contains("Export.Plan.RemapNotMonotonic"), "the curve repair is not reported");
+ return Invariant($"{plan.Frames.Count} frames, {plan.Statistics.InterpolatedFrames} synthesised");
+ });
+ yield return Check("plan.fit", "Fit to duration rescales the plan exactly", () =>
+ {
+ var plan = RenderPlan.Build(Regular(300), Timing(TimingMode.Constant, fit: 5), new Rational(25, 1));
+ RequireExact(plan);
+ Require(plan.SlotCount == 125 && plan.Duration90k == 450_000, Invariant($"{plan.SlotCount} periods, {plan.DurationSeconds} s"));
+ return Invariant($"300 frames in {plan.DurationSeconds} s, speed {plan.Statistics.MaximumSpeed:0.##}×");
+ });
+ }
+
+ private static IEnumerable ExportChecks()
+ {
+ yield return Check("export.presets", "Every built-in preset resolves to itself and to valid encode settings", () =>
+ {
+ foreach (var preset in ExportPresets.BuiltIn)
+ {
+ var resolved = ExportResolver.Resolve(new ExportSettings { Preset = Manual(preset.Id) });
+ Require(resolved.PresetId == preset.Id && resolved.Warnings.Count == 0, preset.Id + " does not resolve to itself");
+ var settings = resolved.ToEncodeSettings("out", int.Max(2, preset.Width), int.Max(2, preset.Height));
+ Require(settings.GopLength >= 1 && (VideoCodecInfo.IsManaged(preset.Codec) || settings.BitRate > 0), preset.Id + " has invalid encode settings");
+ }
+ return Invariant($"{ExportPresets.BuiltIn.Count} presets");
+ });
+ yield return Check("export.custom", "Editing a value gives Custom; equal values restore the preset", () =>
+ {
+ var edited = ExportResolver.Resolve(new ExportSettings { Preset = Manual("1080p-h264"), Overrides = new ExportOverrides { Height = 1000 } });
+ var restored = ExportResolver.Resolve(new ExportSettings { Preset = Manual("1080p-h264"), Overrides = new ExportOverrides { Height = 1080, Codec = "H.264" } });
+ var other = ExportResolver.Resolve(new ExportSettings { Preset = Manual("1080p-h264"), Overrides = new ExportOverrides { FrameRate = "60" } });
+ Require(edited.IsCustom && restored.PresetId == "1080p-h264" && other.PresetId == "1080p60", "the Custom rule is broken");
+ return "custom ↔ preset";
+ });
+ yield return Check("export.naming", "Name tokens expand and are sanitised", () =>
+ {
+ var name = ExportNaming.Expand("{date} {title} - {preset} {width}x{height} {fps} {codec}", new ExportNameContext
+ {
+ Date = Origin,
+ Title = "Harbour: sunset",
+ PresetName = "4K",
+ Width = 3840,
+ Height = 2160,
+ FrameRate = Rational.Fps2997,
+ Codec = VideoCodec.Hevc,
+ });
+ Require(name.IsValid && name.Name == "2024-06-21 Harbour_ sunset - 4K 3840x2160 29.97 HEVC", "expanded to \"" + name.Name + "\"");
+ return name.Name;
+ });
+ yield return Check("export.collision", "Existing outputs get a numbered suffix", context =>
+ {
+ var nameContext = new ExportNameContext { Date = Origin, PresetName = "GIF", Codec = VideoCodec.Gif, Title = "Clip" };
+ var first = ExportNaming.OutputPath(context.WorkDirectory, "{title}", nameContext);
+ File.WriteAllBytes(first, [0]);
+ var second = ExportNaming.OutputPath(context.WorkDirectory, "{title}", nameContext);
+ Require(Path.GetFileName(first) == "Clip.gif" && Path.GetFileName(second) == "Clip (2).gif", "got " + Path.GetFileName(second));
+ return Task.FromResult(Path.GetFileName(second));
+ });
+ yield return Check("export.estimate", "Size and time estimates are consistent", () =>
+ {
+ var export = ExportResolver.FromPreset(ExportPresets.Find("4k-hevc")!);
+ var workload = new ExportWorkload(720, 720, 24, 3840, 2160, 3840L * 2160, 0, 0, true);
+ var bytes = ExportEstimator.EstimateBytes(export, workload);
+ var expected = export.EffectiveBitRate(3840, 2160) * 24 / 8.0 * 1.01;
+ Require(double.Abs(bytes - expected) <= 1, "video size is not bit rate × duration");
+ var time = ExportEstimator.EstimateTime(export.Codec, workload, ThroughputModel.Default);
+ var calibrated = ThroughputModel.Default.Calibrate(time, time / 2, 1);
+ Require(double.Abs(ExportEstimator.EstimateTime(export.Codec, workload, calibrated).TotalSeconds * 2 - time.TotalSeconds) < 1e-6, "calibration does not rescale");
+ return Invariant($"{bytes / 1e6:0.#} MB, {time.TotalSeconds:0} s");
+ });
+ yield return Check("select.managed", "Managed codecs select the managed encoder on clients and servers", context =>
+ {
+ foreach (var host in new[] { EncoderHost.Client, EncoderHost.Server })
+ {
+ var selection = EncoderSelector.Select(ExportResolver.FromPreset(ExportPresets.Find("png-sequence")!).ToEncodeSettings("x", 640, 360), context.Encoders, host);
+ Require(selection.IsReady && selection.Provider is Video.Managed.ManagedEncoderProvider, "PNG is not served by the managed encoder");
+ }
+ return Task.FromResult("managed");
+ });
+ yield return Check("select.server", "MP4 on the server needs a render node", context =>
+ {
+ var selection = EncoderSelector.Select(ExportResolver.FromPreset(ExportPresets.Find("1080p-h264")!).ToEncodeSettings("x.mp4", 1920, 1080), context.Encoders, EncoderHost.Server);
+ Require(selection.Status == EncoderSelectionStatus.NeedsRenderNode && selection.Notices.Any(n => n.Key == EncoderNotices.NeedsRenderNode), "no render-node notice");
+ return Task.FromResult(selection.Notices[0].Key);
+ });
+ yield return Check("select.client", "MP4 on this client: hardware preferred, HEVC falls back to H.264 with a reason", context =>
+ {
+ var hevc = EncoderSelector.Select(ExportResolver.FromPreset(ExportPresets.Find("4k-hevc")!).ToEncodeSettings("x.mp4", 3840, 2160), context.Encoders, EncoderHost.Client);
+ var hasHevc = context.Encoders.Any(p => p.Capabilities.Any(c => c.Codec == VideoCodec.Hevc));
+ var hasH264 = context.Encoders.Any(p => p.Capabilities.Any(c => c.Codec == VideoCodec.H264));
+ if (!hasHevc) Require(hevc.Notices.Count > 0 && hevc.Notices[0].Key == EncoderNotices.FallbackToH264, "no H.264 fallback notice");
+ if (!hasHevc && !hasH264) Require(hevc.Status == EncoderSelectionStatus.Unavailable, "an MP4 encoder was selected without any");
+ if (hasH264)
+ {
+ var h264 = EncoderSelector.Select(ExportResolver.FromPreset(ExportPresets.Find("1080p-h264")!).ToEncodeSettings("x.mp4", 1920, 1080), context.Encoders, EncoderHost.Client);
+ var hardware = context.Encoders.SelectMany(p => p.Capabilities).Any(c => c.Codec == VideoCodec.H264 && c.Hardware);
+ Require(h264.IsReady && h264.Capability!.Hardware == hardware, "hardware H.264 is not preferred");
+ return Task.FromResult($"{hevc.Status} via {hevc.Capability?.Name ?? "none"}; H.264 via {h264.Capability!.Name}");
+ }
+ return Task.FromResult(string.Join(", ", hevc.Notices.Select(n => n.Key)));
+ });
+ yield return Check("export.setup", "A render setup reports size, encoder, plan and estimates before rendering", context =>
+ {
+ var source = Synthetic(48, o => o with { Width = 480, Height = 320 });
+ var input = Input(source, Plain with { Exposure = new ExposureSettings { Deflicker = Manual(true) } });
+ var setup = Pipeline(context).Setup(input, Target(context, Preset("gif-preview", 480, 270)));
+ var estimate = setup.Estimate();
+ Require(setup.Encoder.IsReady && (setup.Geometry.OutputWidth, setup.Geometry.OutputHeight) == (480, 270) && setup.Plan.Frames.Count == 48
+ && setup.NeedsPreparation && setup.Geometry.WorkingLongEdge == 480 && estimate.Bytes > 0 && estimate.Time > TimeSpan.Zero, "the setup is inconsistent");
+ return Task.FromResult(Invariant($"{estimate.Bytes / 1024} KiB, {estimate.Time.TotalSeconds:0.#} s estimated"));
+ });
+ yield return Check("select.limits", "Sizes beyond the codec levels are capped with a reason", () =>
+ {
+ var check = CodecLimits.Check(VideoCodec.Hevc, 7680, 4320, 240, 0);
+ Require(!check.Fits && check.SuggestedWidth > 0, "8K at 240 fps should exceed HEVC level 6.2");
+ Require(CodecLimits.Check(VideoCodec.Hevc, check.SuggestedWidth, check.SuggestedHeight, 240, 0).Fits, "the suggested size does not fit");
+ return Invariant($"8K240 → {check.SuggestedWidth}×{check.SuggestedHeight}");
+ });
+ }
+
+ private static ImageBuffer CodecFrame(int seed)
+ {
+ var image = new ImageBuffer(64, 48);
+ for (var y = 0; y < 48; y++)
+ {
+ for (var x = 0; x < 64; x++)
+ {
+ image[0, x, y] = (x + seed * 5) % 64 / 64f;
+ image[1, x, y] = y / 48f * 0.8f;
+ image[2, x, y] = (x * y + seed) % 29 / 28f * 0.6f;
+ }
+ }
+ return image;
+ }
+
+ private static IEnumerable CodecChecks()
+ {
+ yield return Check("codec.jpeg", "JPEG round trip", () =>
+ {
+ using var frame = CodecFrame(1);
+ using var back = JpegDecoder.DecodeToLinear(JpegEncoder.Encode(frame, new JpegEncodeOptions { Quality = 95, Subsampling = JpegSubsampling.Yuv444 }));
+ var psnr = Psnr(frame, back);
+ Require(psnr > 33, Invariant($"PSNR {psnr:0.#} dB"));
+ return Invariant($"PSNR {psnr:0.#} dB");
+ });
+ yield return Check("codec.png8", "PNG 8-bit round trip is exact", () =>
+ {
+ using var frame = CodecFrame(2);
+ Require(PngDecoder.Decode(PngEncoder.Encode(frame)).Pixels8!.AsSpan().SequenceEqual(PixelConvert.ToInterleaved8(frame, 3)), "pixels differ");
+ return "exact";
+ });
+ yield return Check("codec.png16", "PNG 16-bit round trip is exact", () =>
+ {
+ using var frame = CodecFrame(3);
+ Require(PngDecoder.Decode(PngEncoder.Encode(frame, 16)).Pixels16!.AsSpan().SequenceEqual(PixelConvert.ToInterleaved16(frame, 3)), "pixels differ");
+ return "exact";
+ });
+ yield return Check("codec.tiff16", "TIFF 16-bit round trip is exact", () =>
+ {
+ using var frame = CodecFrame(4);
+ var reader = TiffReader.Open(new MemoryStream(TiffWriter.Write(frame))) ?? throw new InvalidDataException("Not a TIFF");
+ var raster = TiffImageReader.ReadRaster(reader, reader.ReadChain()[0]);
+ Require(raster.Samples is not null && raster.Samples.AsSpan().SequenceEqual(PixelConvert.ToInterleaved16(frame, 3)), "samples differ");
+ return "exact";
+ });
+ yield return Check("codec.dng", "Linear DNG round trip within one 16-bit step", () =>
+ {
+ using var frame = CodecFrame(5);
+ using var back = TiffImageReader.Decode(LinearDngWriter.Write(frame, new LinearDngOptions { TileSize = 64 }));
+ var error = 0.0;
+ for (var i = 0; i < frame.Data.Length; i++) error = double.Max(error, double.Abs(frame.Data[i] - back.Data[i]));
+ Require(error <= 1.0 / 65535 + 1e-7, Invariant($"error {error:E2}"));
+ return Invariant($"max error {error * 65535:0.##} LSB");
+ });
+ yield return Check("codec.gif", "GIF frames and delays round trip", () =>
+ {
+ using var stream = new MemoryStream();
+ var gif = new GifEncoder(stream, 64, 48);
+ for (var i = 0; i < 3; i++)
+ {
+ using var f = CodecFrame(i);
+ gif.AddFrame(f, 9000 * (i + 1));
+ }
+ gif.Complete();
+ var animation = GifReader.Decode(stream.ToArray());
+ Require(animation.Frames.Count == 3 && animation.Duration90k == 54000 && animation.LoopCount == 0, "frames or delays differ");
+ using var expected = CodecFrame(2);
+ using var decoded = animation.ToLinear(2);
+ var psnr = Psnr(expected, decoded);
+ Require(psnr > 25, Invariant($"PSNR {psnr:0.#} dB"));
+ return Invariant($"3 frames, 0.6 s, PSNR {psnr:0.#} dB");
+ });
+ yield return Check("codec.apng", "APNG frames and delays round trip exactly", () =>
+ {
+ using var stream = new MemoryStream();
+ var apng = new ApngEncoder(stream, 64, 48);
+ for (var i = 0; i < 3; i++)
+ {
+ using var f = CodecFrame(i);
+ apng.AddFrame(f, 6000);
+ }
+ apng.Complete();
+ var animation = ApngReader.Decode(stream.ToArray());
+ using var expected = CodecFrame(1);
+ using var decoded = animation.ToLinear(1);
+ var psnr = Psnr(expected, decoded);
+ Require(animation.Frames.Count == 3 && animation.Duration90k == 18000 && psnr > 60, Invariant($"{animation.Frames.Count} frames, {animation.Duration90k} ticks, PSNR {psnr:0.#} dB"));
+ return "3 frames, exact delays";
+ });
+ yield return Check("codec.avi", "MJPEG AVI headers and indexes", () =>
+ {
+ using var stream = new MemoryStream();
+ var writer = new AviMjpegWriter(stream, 64, 48, Rational.Fps2997);
+ using var frame = CodecFrame(0);
+ var jpeg = JpegEncoder.Encode(frame);
+ for (var i = 0; i < 5; i++) writer.WriteFrame(jpeg);
+ writer.Complete();
+ var avi = AviReader.Read(stream.ToArray());
+ Require(avi.Frames.Count == 5 && avi.HeaderFrames == 5 && avi.StreamFrames == 5 && avi.IndexEntries == 5 && avi.FrameRate == Rational.Fps2997
+ && (avi.Width, avi.Height) == (64, 48), "AVI structure differs");
+ return "5 frames, 30000/1001";
+ });
+ }
+}
diff --git a/src/Titano.Core/Render/Diagnostics/SelfTestRenderChecks.cs b/src/Titano.Core/Render/Diagnostics/SelfTestRenderChecks.cs
new file mode 100644
index 00000000..e2735a62
--- /dev/null
+++ b/src/Titano.Core/Render/Diagnostics/SelfTestRenderChecks.cs
@@ -0,0 +1,558 @@
+using Titano.Core.Analysis;
+using Titano.Core.Codecs.Jpeg;
+using Titano.Core.Codecs.Png;
+using Titano.Core.Codecs.Tiff;
+using Titano.Core.Diagnostics.Synthetic;
+using Titano.Core.Export;
+using Titano.Core.Imaging;
+using Titano.Core.Imaging.Geometry;
+using Titano.Core.Motion;
+using Titano.Core.Project;
+using Titano.Core.Video;
+using Titano.Core.Video.Managed;
+
+namespace Titano.Core.Render.Diagnostics;
+
+/// Renders through the whole pipeline: output formats, processing modules and robustness.
+public static partial class SelfTest
+{
+ private static IEnumerable RenderChecks()
+ {
+ (string Id, string Preset, int Depth, double MinPsnr)[] formats =
+ [
+ ("render.mjpeg", "mjpeg-avi", 8, 35), ("render.jpeg", "jpeg-sequence", 8, 35), ("render.png8", "png-sequence", 8, 60),
+ ("render.png16", "png-sequence", 16, 60), ("render.tiff16", "tiff16-sequence", 16, 60), ("render.dng", "dng-sequence", 16, 60),
+ ("render.gif", "gif-preview", 8, 25), ("render.apng", "apng", 8, 60),
+ ];
+ foreach (var (id, preset, depth, minPsnr) in formats)
+ yield return Check(id, $"Render a synthetic sequence to {preset} ({depth}-bit) and decode it back", context => RenderFormatAsync(context, preset, depth, minPsnr));
+ yield return Check("render.mp4", "Render MP4 with this machine's platform encoders and inspect the file", RenderMp4Async);
+ yield return Check("render.held", "Held frames repeat on constant-rate outputs", async context =>
+ {
+ var source = Synthetic(10, o => o with { TimeShifts = [new SyntheticTimeShift(5, 20)] });
+ var project = Plain with { Timing = new TimingSettings { Mode = Manual(TimingMode.Adaptive) } };
+ var result = await Pipeline(context).RenderAsync(Input(source, project), Target(context, Preset("mjpeg-avi")), cancellationToken: context.Cancellation).ConfigureAwait(false);
+ var avi = AviReader.Read(await File.ReadAllBytesAsync(result.OutputPath, context.Cancellation).ConfigureAwait(false));
+ Require(result.FrameCount == 10 && avi.Frames.Count == 12, Invariant($"{result.FrameCount} pictures in {avi.Frames.Count} AVI frames"));
+ return "10 pictures, 12 frames";
+ });
+ }
+
+ private static async Task RenderFormatAsync(SelfTestContext context, string presetId, int bitDepth, double minPsnr)
+ {
+ var source = Synthetic(12);
+ var export = Preset(presetId) with { BitDepth = bitDepth };
+ var target = Target(context, export);
+ var result = await Pipeline(context).RenderAsync(Input(source), target, cancellationToken: context.Cancellation).ConfigureAwait(false);
+ var entries = Directory.GetFileSystemEntries(context.WorkDirectory);
+ Require(entries.Length == 1 && entries[0] == target.OutputPath, "the folder holds more than the output");
+ Require(result.Bytes > 0 && result.FrameCount == 12, Invariant($"{result.FrameCount} frames, {result.Bytes} bytes"));
+
+ int count;
+ ImageBuffer decoded;
+ switch (export.Codec)
+ {
+ case VideoCodec.Mjpeg:
+ var avi = AviReader.Read(await File.ReadAllBytesAsync(target.OutputPath, context.Cancellation).ConfigureAwait(false));
+ Require(avi.FrameRate == export.FrameRate && (avi.Width, avi.Height) == (96, 64), "AVI headers differ");
+ count = avi.Frames.Count;
+ decoded = JpegDecoder.DecodeToLinear(avi.Frames[5]);
+ break;
+ case VideoCodec.Gif or VideoCodec.Apng:
+ var bytes = await File.ReadAllBytesAsync(target.OutputPath, context.Cancellation).ConfigureAwait(false);
+ var animation = export.Codec == VideoCodec.Gif ? GifReader.Decode(bytes) : ApngReader.Decode(bytes);
+ var expectedTicks = RenderPlan.TicksAt(export.FrameRate, 12);
+ Require(double.Abs(animation.Duration90k - expectedTicks) <= 900, Invariant($"duration {animation.Duration90k} ticks, expected {expectedTicks}"));
+ count = animation.Frames.Count;
+ decoded = animation.ToLinear(5);
+ break;
+ default:
+ var files = Directory.GetFiles(target.OutputPath).Order(StringComparer.Ordinal).ToArray();
+ var stem = Path.GetFileName(target.OutputPath);
+ Require(files.Select(Path.GetFileName).SequenceEqual(Enumerable.Range(1, files.Length).Select(i => ImageSequenceSession.FrameName(stem, i, VideoCodecInfo.FileExtension(export.Codec)))),
+ "frame files are not numbered 1…n");
+ count = files.Length;
+ var data = await File.ReadAllBytesAsync(files[5], context.Cancellation).ConfigureAwait(false);
+ decoded = export.Codec switch
+ {
+ VideoCodec.JpegSequence => JpegDecoder.DecodeToLinear(data),
+ VideoCodec.PngSequence => PngDecoder.DecodeToLinear(data),
+ _ => TiffImageReader.Decode(data),
+ };
+ break;
+ }
+ using (decoded)
+ using (var expected = source.Sequence.Render(5))
+ {
+ Require(count == 12, Invariant($"{count} pictures in the output"));
+ var psnr = Psnr(expected, decoded);
+ Require(psnr >= minPsnr, Invariant($"PSNR {psnr:0.#} dB < {minPsnr} dB"));
+ return Invariant($"{result.Bytes} bytes, PSNR {(double.IsPositiveInfinity(psnr) ? "∞" : psnr.ToString("0.#", System.Globalization.CultureInfo.InvariantCulture))} dB, {result.EncoderName}");
+ }
+ }
+
+ private static async Task RenderMp4Async(SelfTestContext context)
+ {
+ var codecs = context.PlatformEncoders.SelectMany(p => p.Capabilities).Select(c => c.Codec).Where(c => !VideoCodecInfo.IsManaged(c)).Distinct().ToList();
+ if (codecs.Count == 0) throw new SkipException("no MP4 encoder on this machine");
+ var pipeline = new RenderPipeline(context.Encoders);
+ var details = new List();
+ foreach (var codec in codecs)
+ {
+ var export = Preset("1080p-h264", 320, 180) with { Codec = codec, Profile = CodecProfile.Auto, BitRate = 0, BitsPerPixel = 0 };
+ var result = await pipeline.RenderAsync(Input(Synthetic(24)), Target(context, export, codec.ToString()), cancellationToken: context.Cancellation).ConfigureAwait(false);
+ var report = Mp4Inspector.Inspect(result.OutputPath);
+ Require(report.IsValid, codec + ": " + string.Join("; ", report.Errors));
+ Require(report.Codec == codec && report.FrameCount == 24 && (report.Width, report.Height) == (320, 180), Invariant($"{codec}: {report.Codec} {report.Width}×{report.Height}, {report.FrameCount} frames"));
+ Require(double.Abs(report.Duration.TotalSeconds - result.DurationSeconds) < 0.05, Invariant($"{codec}: duration {report.Duration.TotalSeconds:0.###} s"));
+ details.Add($"{codec} via {result.EncoderName}{(result.Hardware ? " (hardware)" : string.Empty)}");
+ }
+ return string.Join(", ", details);
+ }
+
+ private static IEnumerable ProcessingChecks()
+ {
+ yield return Check("proc.deflicker", "Deflicker on rendered frames: flicker −60 % or better, ramp kept within 0.05 EV (§20.4)", async context =>
+ {
+ var source = Synthetic(200, o => o with { Seed = 3, StartEv = -2, EndEv = 1, FlickerEv = 0.1 });
+ var project = Plain with { Exposure = new ExposureSettings { Deflicker = Manual(true), DeflickerWindow = Manual(21), HighlightKnee = null } };
+ var frames = await RenderDecodedAsync(context, Input(source, project)).ConfigureAwait(false);
+ var output = frames.Select(f => FrameStatistics.MeasureLogLuminance(f)).ToArray();
+ DisposeAll(frames);
+ var input = Enumerable.Range(0, 200).Select(i =>
+ {
+ using var f = source.Sequence.Render(i);
+ return FrameStatistics.MeasureLogLuminance(f);
+ }).ToArray();
+ var before = FrameToFrameResidual(input, source.Sequence.SceneEv);
+ var after = FrameToFrameResidual(output, source.Sequence.SceneEv);
+ var ramp = MaxDeviation(output, source.Sequence.SceneEv);
+ Require(1 - after / before >= 0.6, Invariant($"flicker reduced by {1 - after / before:P0} only"));
+ Require(ramp <= 0.05, Invariant($"ramp deviates by {ramp:0.###} EV"));
+ return Invariant($"flicker −{1 - after / before:P0}, ramp within {ramp:0.###} EV");
+ });
+ yield return Check("proc.holygrail", "Holy grail: no output step above 0.3 EV (§20.4)", async context =>
+ {
+ var source = Synthetic(80, o => o with { ExposureSteps = [new SyntheticExposureStep(40, 1.0)], StartEv = 0, EndEv = 0 });
+ var project = Plain with { Exposure = new ExposureSettings { HolyGrail = Manual(true), Deflicker = Manual(true), HighlightKnee = null } };
+ var frames = await RenderDecodedAsync(context, Input(source, project)).ConfigureAwait(false);
+ var output = frames.Select(f => FrameStatistics.MeasureLogLuminance(f)).ToArray();
+ DisposeAll(frames);
+ var step = output.Zip(output.Skip(1), (a, b) => double.Abs(b - a)).Max();
+ Require(step <= 0.32, Invariant($"largest step {step:0.###} EV"));
+ Require(double.Abs(output[^1] - output[0] + 1) <= 0.1, "the exposure step was not kept");
+ return Invariant($"largest step {step:0.###} EV");
+ });
+ yield return Check("proc.regions", "Region deflicker: land residual at most half of the global correction's", async context =>
+ {
+ var source = Synthetic(48, o => o with { SkyFlickerEv = 0.3, LandFlickerEv = 0.3, StartEv = 0, EndEv = 0 });
+ var land = new float[96 * 64];
+ for (var y = 0; y < 64; y++)
+ {
+ for (var x = 0; x < 96; x++) land[y * 96 + x] = source.Sequence.IsSky(x, y) || y + 0.5 < source.Sequence.HorizonRow(x + 0.5) + 2 ? 0 : 1;
+ }
+ async Task LandResidualAsync(RegionMode mode, string name)
+ {
+ var project = Plain with { Exposure = new ExposureSettings { Deflicker = Manual(true), Regions = Manual(mode), HighlightKnee = null } };
+ var frames = await RenderDecodedAsync(context, Input(source, project), name: name).ConfigureAwait(false);
+ var series = frames.Select(f => FrameStatistics.MeasureLogLuminance(f, land)).ToArray();
+ DisposeAll(frames);
+ return Rms(series);
+ }
+ var global = await LandResidualAsync(RegionMode.Off, "global").ConfigureAwait(false);
+ var regions = await LandResidualAsync(RegionMode.Horizon, "regions").ConfigureAwait(false);
+ Require(regions <= 0.5 * global, Invariant($"land residual {regions:0.###} EV vs global {global:0.###} EV"));
+ return Invariant($"land residual {regions:0.###} vs {global:0.###} EV");
+ });
+ yield return Check("proc.whitebalance", "White-balance smoothing removes colour jitter", async context =>
+ {
+ var source = Synthetic(48, o => o with { WhiteBalanceJitter = 0.1 });
+ var project = Plain with { Exposure = new ExposureSettings { WhiteBalanceSmoothing = Manual(true), HighlightKnee = null } };
+ var frames = await RenderDecodedAsync(context, Input(source, project)).ConfigureAwait(false);
+ static double Ratio(ImageBuffer f)
+ {
+ var stats = FrameStatistics.Measure(f);
+ return double.Log2(stats.MeanRed / stats.MeanGreen);
+ }
+ var after = frames.Select(Ratio).ToArray();
+ DisposeAll(frames);
+ var before = Enumerable.Range(0, 48).Select(i =>
+ {
+ using var f = source.Sequence.Render(i);
+ return Ratio(f);
+ }).ToArray();
+ static double Jitter(double[] r) => double.Sqrt(r.Zip(r.Skip(1), (a, b) => (b - a) * (b - a)).Average());
+ Require(Jitter(after) < 0.3 * Jitter(before), Invariant($"R/G jitter {Jitter(before):0.####} → {Jitter(after):0.####}"));
+ return Invariant($"R/G jitter {Jitter(before):0.###} → {Jitter(after):0.####}");
+ });
+ yield return Check("proc.offset", "Exposure offset +1 EV doubles linear values", async context =>
+ {
+ var source = Synthetic(2);
+ var plain = await RenderDecodedAsync(context, Input(source), name: "plain").ConfigureAwait(false);
+ var brighter = await RenderDecodedAsync(context, Input(source, Plain with { Exposure = new ExposureSettings { ExposureOffsetEv = 1, HighlightKnee = null } }), name: "bright")
+ .ConfigureAwait(false);
+ var error = 0.0;
+ for (var i = 0; i < plain[0].Data.Length; i++) error = double.Max(error, double.Abs(2 * plain[0].Data[i] - brighter[0].Data[i]) / (1e-3 + brighter[0].Data[i]));
+ DisposeAll(plain);
+ DisposeAll(brighter);
+ Require(error < 0.01, Invariant($"relative error {error:P2}"));
+ return Invariant($"relative error {error:P3}");
+ });
+ yield return Check("proc.knee", "The highlight knee keeps values below 1 and leaves shadows alone", async context =>
+ {
+ var source = Synthetic(2, o => o with { StartEv = 2, EndEv = 2 });
+ var hard = await RenderDecodedAsync(context, Input(source), name: "hard").ConfigureAwait(false);
+ var knee = await RenderDecodedAsync(context, Input(source, Plain with { Exposure = new ExposureSettings { HighlightKnee = 0.8 } }), name: "knee").ConfigureAwait(false);
+ var clipped = hard[0].Data.ToArray().Count(v => v >= 0.9999f);
+ var top = knee[0].Data.ToArray().Max();
+ var shadows = true;
+ for (var i = 0; i < hard[0].Data.Length; i++)
+ {
+ if (hard[0].Data[i] < 0.5f) shadows &= double.Abs(hard[0].Data[i] - knee[0].Data[i]) < 1e-4;
+ }
+ DisposeAll(hard);
+ DisposeAll(knee);
+ Require(clipped > 0 && top < 0.9999f && shadows, Invariant($"{clipped} clipped samples without knee, max {top:0.####} with it"));
+ return Invariant($"{clipped} clipped samples → max {top:0.###}");
+ });
+ yield return Check("proc.aspect", "A square export crops the centre of a 3:2 frame", async context =>
+ {
+ var source = Synthetic(3);
+ var frames = await RenderDecodedAsync(context, Input(source), Preset("png-sequence", 64, 64)).ConfigureAwait(false);
+ using var reference = source.Sequence.Render(1);
+ using var expected = GeometryStage.Apply(reference, new GeometrySettings { Crop = new RectD(16, 0, 64, 64), OutputWidth = 64, OutputHeight = 64 });
+ var psnr = Psnr(expected, frames[1]);
+ DisposeAll(frames);
+ Require(psnr > 60, Invariant($"PSNR {psnr:0.#} dB"));
+ return "centre 64×64";
+ });
+ yield return Check("proc.crop", "The camera crop selects its region at source size", async context =>
+ {
+ var source = Synthetic(3);
+ var project = Plain with { Camera = new CameraSettings { Crop = [0.5, 0.5, 0.5, 0.5] } };
+ var frames = await RenderDecodedAsync(context, Input(source, project), Preset("png-sequence", 0, 0)).ConfigureAwait(false);
+ using var reference = source.Sequence.Render(1);
+ using var expected = GeometryStage.Apply(reference, new GeometrySettings { Crop = new RectD(48, 32, 48, 32) });
+ var size = (frames[1].Width, frames[1].Height);
+ var psnr = Psnr(expected, frames[1]);
+ DisposeAll(frames);
+ Require(size == (48, 32) && psnr > 60, Invariant($"{size}, PSNR {psnr:0.#} dB"));
+ return "quarter 48×32";
+ });
+ yield return Check("proc.zoom", "Virtual-camera zoom matches a direct crop and doubles the decode size", async context =>
+ {
+ var source = Synthetic(3, o => o with { Width = 480, Height = 320 });
+ var project = Plain with { Camera = new CameraSettings { Keyframes = [new CameraKey(0, 0.5, 0.5, 2, 0), new CameraKey(2, 0.5, 0.5, 2, 0)] } };
+ var frames = await RenderDecodedAsync(context, Input(source, project), Preset("png-sequence", 96, 64)).ConfigureAwait(false);
+ using var full = source.Sequence.Render(1);
+ using var expected = GeometryStage.Apply(full, new GeometrySettings { Crop = new RectD(120, 80, 240, 160), OutputWidth = 96, OutputHeight = 64 });
+ var psnr = Psnr(expected, frames[1]);
+ DisposeAll(frames);
+ Require(psnr > 28 && source.LargestRenderRequest == 192, Invariant($"PSNR {psnr:0.#} dB, decoded at {source.LargestRenderRequest} px"));
+ return Invariant($"PSNR {psnr:0.#} dB, decode {source.LargestRenderRequest} px");
+ });
+ yield return Check("proc.stabilize", "Stabilisation removes 90 % of the camera shake", async context =>
+ {
+ var random = new Random(11);
+ var shake = Enumerable.Range(0, 24).Select(_ => (X: random.NextDouble() * 6 - 3, Y: random.NextDouble() * 6 - 3)).ToArray();
+ var source = new PatternFrameSource(320, 192, 24, i => shake[i]);
+ var project = Plain with { Motion = new MotionSettings { Stabilize = Manual(true), StabilizeSmoothing = Manual(12.0) } };
+ var input = new RenderInput { Source = source, Frames = source.Metadata(), Project = project };
+ var frames = await RenderDecodedAsync(context, input, Preset("png-sequence", 0, 0)).ConfigureAwait(false);
+ using var stabilizer = new Stabilizer(320, 192);
+ var motions = frames.Select(f => stabilizer.AddFrame(f).Transform).Skip(1).ToArray();
+ DisposeAll(frames);
+ var after = double.Sqrt(motions.Average(m => m.Tx * m.Tx + m.Ty * m.Ty));
+ var before = double.Sqrt(Enumerable.Range(1, 23).Average(k => double.Pow(shake[k].X - shake[k - 1].X, 2) + double.Pow(shake[k].Y - shake[k - 1].Y, 2)));
+ Require(after <= 0.1 * before * 1.2, Invariant($"frame-to-frame shake {before:0.##} → {after:0.###} px"));
+ return Invariant($"shake {before:0.##} → {after:0.###} px");
+ });
+ yield return Check("proc.interpolate", "Synthesised in-betweens follow the motion", async context =>
+ {
+ var source = Synthetic(6, o => o with { StartEv = 0, EndEv = 0 }, i => (2.0 * i, 0));
+ var project = Plain with { Timing = new TimingSettings { Mode = Manual(TimingMode.Interpolated), FrameRate = Manual("15") } };
+ var frames = await RenderDecodedAsync(context, Input(source, project)).ConfigureAwait(false);
+ var truth = Synthetic(6, o => o with { StartEv = 0, EndEv = 0 }, i => (2.0 * i + 1, 0));
+ using var halfway = await truth.GetFrameAsync(2, 0, DecodePurpose.Render, context.Cancellation).ConfigureAwait(false);
+ var synthesised = Psnr(halfway, frames[5], 8);
+ var nearest = Psnr(halfway, frames[4], 8);
+ var count = frames.Count;
+ DisposeAll(frames);
+ Require(count == 12 && synthesised > 30 && synthesised > nearest + 5, Invariant($"{count} frames, {synthesised:0.#} dB vs nearest {nearest:0.#} dB"));
+ return Invariant($"{synthesised:0.#} dB (nearest whole frame {nearest:0.#} dB)");
+ });
+ yield return Check("proc.motionblur", "Motion blur smears along the motion and leaves still scenes alone", async context =>
+ {
+ var blur = new MotionSettings { MotionBlur = Manual(true), TargetShutterAngle = Manual(360.0) };
+ var moving = Synthetic(6, o => o with { StartEv = 0, EndEv = 0 }, i => (3.0 * i, 0));
+ var sharp = await RenderDecodedAsync(context, Input(moving), name: "sharp").ConfigureAwait(false);
+ var blurred = await RenderDecodedAsync(context, Input(moving, Plain with { Motion = blur }), name: "blurred").ConfigureAwait(false);
+ static double Gradient(ImageBuffer f, int dx, int dy)
+ {
+ double sum = 0;
+ var g = f.Plane(1);
+ for (var y = 8; y < f.Height - 8; y++)
+ {
+ for (var x = 8; x < f.Width - 8; x++) sum += double.Abs(g[y * f.Width + x] - g[(y + dy) * f.Width + x + dx]);
+ }
+ return sum;
+ }
+ var horizontal = Gradient(blurred[3], 1, 0) / Gradient(sharp[3], 1, 0);
+ var vertical = Gradient(blurred[3], 0, 1) / Gradient(sharp[3], 0, 1);
+ DisposeAll(sharp);
+ DisposeAll(blurred);
+ var still = Synthetic(4, o => o with { StartEv = 0, EndEv = 0 });
+ var a = await RenderDecodedAsync(context, Input(still), name: "still").ConfigureAwait(false);
+ var b = await RenderDecodedAsync(context, Input(still, Plain with { Motion = blur }), name: "still-blur").ConfigureAwait(false);
+ var stillPsnr = Psnr(a[2], b[2]);
+ DisposeAll(a);
+ DisposeAll(b);
+ Require(horizontal < 0.75 && vertical > horizontal + 0.1 && stillPsnr > 40, Invariant($"gradients ×{horizontal:0.##} along, ×{vertical:0.##} across; still {stillPsnr:0.#} dB"));
+ return Invariant($"gradient ×{horizontal:0.##} along, ×{vertical:0.##} across");
+ });
+ yield return Check("proc.median", "A median stack removes a one-frame transient", async context =>
+ {
+ var source = Synthetic(9, o => o with { StartEv = 0, EndEv = 0 });
+ var project = Plain with { Stack = new StackSettings { Mode = StackSetting.Median, Length = 5 } };
+ var input = Input(source, project) with { Source = new TransientSource(source, 4) };
+ var frames = await RenderDecodedAsync(context, input).ConfigureAwait(false);
+ using var clean = source.Sequence.Render(4);
+ var psnr = Psnr(clean, frames[4]);
+ DisposeAll(frames);
+ Require(psnr > 45, Invariant($"PSNR {psnr:0.#} dB"));
+ return "transient removed";
+ });
+ yield return Check("proc.startrails", "Star-trail luminance never decreases on 99 % of steps (§20.4)", async context =>
+ {
+ var source = Synthetic(16, o => o with { StarField = true, StarCount = 60, StartEv = 0, EndEv = 0 }, i => (1.0 * i, 0.5 * i));
+ var project = Plain with { Stack = new StackSettings { Mode = StackSetting.StarTrails, Length = 0 } };
+ var frames = await RenderDecodedAsync(context, Input(source, project)).ConfigureAwait(false);
+ var luminance = frames.Select(f => FrameStatistics.MeasureLogLuminance(f, default, 0, 0)).ToArray();
+ DisposeAll(frames);
+ var rising = luminance.Zip(luminance.Skip(1), (a, b) => b >= a - 1e-9).Count(r => r);
+ Require(rising >= 0.99 * (luminance.Length - 1), Invariant($"{rising} of {luminance.Length - 1} steps non-decreasing"));
+ return Invariant($"{rising}/{luminance.Length - 1} steps non-decreasing");
+ });
+ yield return Check("proc.cached", "Cached analysis skips the measuring pass and gives the same corrections", async context =>
+ {
+ var source = Synthetic(30, o => o with { FlickerEv = 0.2 });
+ var project = Plain with { Exposure = new ExposureSettings { Deflicker = Manual(true) } };
+ var measured = await RenderPreparation.PrepareAsync(Input(source, project), cancellationToken: context.Cancellation).ConfigureAwait(false);
+ var decodes = source.Decodes;
+ var cached = await RenderPreparation.PrepareAsync(Input(source, project) with { Analysis = new PrecomputedAnalysis { LogLuminance = measured.MeasuredLogLuminance } },
+ cancellationToken: context.Cancellation).ConfigureAwait(false);
+ Require(cached.Report.MeasuredFrames == 0 && source.Decodes == decodes && cached.ExposureEv.AsSpan().SequenceEqual(measured.ExposureEv), "the cache was not used as is");
+ return Invariant($"{measured.Report.MeasuredFrames} frames measured once");
+ });
+ }
+
+ private static IEnumerable RobustnessChecks()
+ {
+ yield return Check("robust.deterministic", "Identical inputs give byte-identical lossless outputs", async context =>
+ {
+ var project = Plain with
+ {
+ Exposure = new ExposureSettings { Deflicker = Manual(true) },
+ Timing = new TimingSettings { Mode = Manual(TimingMode.Interpolated), FrameRate = Manual("15") },
+ };
+ var a = await Pipeline(context).RenderAsync(Input(Synthetic(12, o => o with { FlickerEv = 0.2 }), project), Target(context, Preset("png-sequence"), "a"), cancellationToken: context.Cancellation)
+ .ConfigureAwait(false);
+ var b = await Pipeline(context).RenderAsync(Input(Synthetic(12, o => o with { FlickerEv = 0.2 }), project), Target(context, Preset("png-sequence"), "b"), cancellationToken: context.Cancellation)
+ .ConfigureAwait(false);
+ var filesA = Directory.GetFiles(a.OutputPath).Order(StringComparer.Ordinal).ToArray();
+ var filesB = Directory.GetFiles(b.OutputPath).Order(StringComparer.Ordinal).ToArray();
+ Require(filesA.Length == filesB.Length && filesA.Length > 12, "different frame counts");
+ for (var i = 0; i < filesA.Length; i++) Require(File.ReadAllBytes(filesA[i]).AsSpan().SequenceEqual(File.ReadAllBytes(filesB[i])), $"frame {i + 1} differs");
+ return Invariant($"{filesA.Length} frames identical");
+ });
+ foreach (var preset in new[] { "mjpeg-avi", "png-sequence", "gif-preview", "apng" })
+ {
+ yield return Check("robust.cancel." + preset.Split('-')[0], $"Cancelling a {preset} render leaves no file behind (§20.4)", async context =>
+ {
+ using var cts = CancellationTokenSource.CreateLinkedTokenSource(context.Cancellation);
+ var progress = new Sink(p =>
+ {
+ if (p.Stage == RenderStage.Rendering && p.Done == 5) cts.Cancel();
+ });
+ try
+ {
+ await Pipeline(context).RenderAsync(Input(Synthetic(24)), Target(context, Preset(preset)), progress: progress, cancellationToken: cts.Token).ConfigureAwait(false);
+ Require(false, "the render was not cancelled");
+ }
+ catch (OperationCanceledException) when (!context.Cancellation.IsCancellationRequested)
+ {
+ }
+ Require(Directory.GetFileSystemEntries(context.WorkDirectory).Length == 0, "partial output or temporary files remain");
+ return "nothing left";
+ });
+ }
+ yield return Check("robust.source-failure", "A failing frame stops the render once, without output", async context =>
+ {
+ var input = Input(Synthetic(12)) with { Source = new FailingSource(Synthetic(12), 7) };
+ var error = await CaptureAsync(() => Pipeline(context).RenderAsync(input, Target(context, Preset("mjpeg-avi")), cancellationToken: context.Cancellation)).ConfigureAwait(false);
+ Require(error is IOException { Message: "frame 7 is unreadable" }, "unexpected error " + error?.GetType().Name);
+ Require(Directory.GetFileSystemEntries(context.WorkDirectory).Length == 0, "partial output remains");
+ return "IOException, no output";
+ });
+ yield return Check("robust.encoder-failure", "An encoder failure stops the render once, without output", async context =>
+ {
+ var pipeline = new RenderPipeline([new FaultInjectingProvider(new ManagedEncoderProvider(), 4)]);
+ var error = await CaptureAsync(() => pipeline.RenderAsync(Input(Synthetic(12)), Target(context, Preset("png-sequence")), cancellationToken: context.Cancellation)).ConfigureAwait(false);
+ Require(error is InvalidDataException { Message: FaultInjectingProvider.Message }, "unexpected error " + error?.GetType().Name);
+ Require(Directory.GetFileSystemEntries(context.WorkDirectory).Length == 0, "partial output remains");
+ return "InvalidDataException, no output";
+ });
+ yield return Check("robust.unobserved", "Failed renders leave no unobserved task exceptions (§20.4)", async context =>
+ {
+ var unobserved = 0;
+ void Handler(object? sender, UnobservedTaskExceptionEventArgs e) => Interlocked.Increment(ref unobserved);
+ TaskScheduler.UnobservedTaskException += Handler;
+ try
+ {
+ for (var i = 0; i < 3; i++)
+ {
+ var pipeline = new RenderPipeline([new FaultInjectingProvider(new ManagedEncoderProvider(), 2 + i)]);
+ await CaptureAsync(() => pipeline.RenderAsync(Input(Synthetic(12)), Target(context, Preset("gif-preview")), cancellationToken: context.Cancellation)).ConfigureAwait(false);
+ var input = Input(Synthetic(12)) with { Source = new FailingSource(Synthetic(12), 3 + i) };
+ await CaptureAsync(() => Pipeline(context).RenderAsync(input, Target(context, Preset("png-sequence")), cancellationToken: context.Cancellation)).ConfigureAwait(false);
+ }
+ GC.Collect();
+ GC.WaitForPendingFinalizers();
+ GC.Collect();
+ }
+ finally
+ {
+ TaskScheduler.UnobservedTaskException -= Handler;
+ }
+ Require(unobserved == 0, Invariant($"{unobserved} unobserved exceptions"));
+ return "none";
+ });
+ yield return Check("robust.memory", "Peak memory does not depend on the sequence length (§20.4)", async context =>
+ {
+ async Task PeakAsync(int frames, string name)
+ {
+ long peak = 0;
+ var progress = new Sink(p =>
+ {
+ if (p.Stage == RenderStage.Rendering && p.Done % 8 == 0) peak = long.Max(peak, GC.GetTotalMemory(forceFullCollection: true));
+ });
+ var project = Plain with { Exposure = new ExposureSettings { Deflicker = Manual(true) } };
+ await Pipeline(context).RenderAsync(Input(Synthetic(frames), project), Target(context, Preset("mjpeg-avi"), name), progress: progress,
+ cancellationToken: context.Cancellation).ConfigureAwait(false);
+ return peak;
+ }
+ await PeakAsync(16, "warm-up").ConfigureAwait(false);
+ var small = await PeakAsync(48, "short").ConfigureAwait(false);
+ var large = await PeakAsync(192, "long").ConfigureAwait(false);
+ Require(large - small < 2 << 20, Invariant($"live heap grew by {(large - small) / 1024} KiB from 48 to 192 frames"));
+ return Invariant($"48 frames {small / 1024} KiB, 192 frames {large / 1024} KiB");
+ });
+ yield return Check("robust.batch", "A batch renders every target and reports the ones that cannot run", async context =>
+ {
+ var server = new RenderPipeline([new ManagedEncoderProvider()], EncoderHost.Server);
+ var results = await server.RenderBatchAsync(Input(Synthetic(12)),
+ [Target(context, Preset("png-sequence"), "png"), Target(context, Preset("1080p-h264"), "h264"), Target(context, Preset("apng"), "apng")],
+ cancellationToken: context.Cancellation).ConfigureAwait(false);
+ Require(results.Count == 3 && results[0].Succeeded && results[2].Succeeded, "a renderable target failed");
+ Require(results[1].Error is RenderException { ReasonKey: EncoderNotices.NeedsRenderNode }, "the MP4 target was not reported as needing a render node");
+ return "2 rendered, 1 needs a render node";
+ });
+ yield return Check("robust.progress", "Progress counts frames, estimates the end and delivers previews", async context =>
+ {
+ var reports = new List();
+ var options = new RenderOptions { PreviewInterval = 4, PreviewLongEdge = 48 };
+ await Pipeline(context).RenderAsync(Input(Synthetic(12)), Target(context, Preset("jpeg-sequence")), options, new Sink(reports.Add), context.Cancellation)
+ .ConfigureAwait(false);
+ var rendering = reports.Where(r => r.Stage == RenderStage.Rendering).ToList();
+ var previews = rendering.Where(r => r.Preview is not null).ToList();
+ var ok = rendering.Select(r => r.Done).SequenceEqual(Enumerable.Range(1, 12)) && rendering.All(r => r.Remaining >= TimeSpan.Zero)
+ && previews.Count == 3 && previews.All(r => r.Preview!.Width == 48) && reports[^1].Stage == RenderStage.Finishing;
+ foreach (var r in previews) r.Preview!.Dispose();
+ Require(ok, Invariant($"{rendering.Count} reports, {previews.Count} previews"));
+ return Invariant($"{rendering.Count} reports, {previews.Count} previews");
+ });
+ yield return Check("robust.excluded", "Excluding every frame is reported, not rendered", async context =>
+ {
+ var project = Plain with { ExcludedFrames = [.. Enumerable.Range(0, 6)] };
+ var error = await CaptureAsync(() => Pipeline(context).RenderAsync(Input(Synthetic(6), project), Target(context, Preset("png-sequence")), cancellationToken: context.Cancellation))
+ .ConfigureAwait(false);
+ Require(error is RenderException { ReasonKey: "Export.Render.NoFrames" } && Directory.GetFileSystemEntries(context.WorkDirectory).Length == 0, "no NoFrames error");
+ return "Export.Render.NoFrames";
+ });
+ }
+
+ /// The exception throws, or null.
+ private static async Task CaptureAsync(Func render)
+ {
+ try
+ {
+ await render().ConfigureAwait(false);
+ return null;
+ }
+ catch (Exception ex) when (ex is not OperationCanceledException)
+ {
+ return ex;
+ }
+ }
+
+ /// Throws an for one frame, as an unreadable file would.
+ private sealed class FailingSource(IRenderFrameSource inner, int failAt) : IRenderFrameSource
+ {
+ public int FrameCount => inner.FrameCount;
+ public int Width => inner.Width;
+ public int Height => inner.Height;
+
+ public ValueTask GetFrameAsync(int index, int maxLongEdge, DecodePurpose purpose, CancellationToken cancellationToken) =>
+ index == failAt ? throw new IOException($"frame {index} is unreadable") : inner.GetFrameAsync(index, maxLongEdge, purpose, cancellationToken);
+ }
+
+ /// Adds a bright square to one frame (a passing aircraft light).
+ private sealed class TransientSource(IRenderFrameSource inner, int frame) : IRenderFrameSource
+ {
+ public int FrameCount => inner.FrameCount;
+ public int Width => inner.Width;
+ public int Height => inner.Height;
+
+ public async ValueTask GetFrameAsync(int index, int maxLongEdge, DecodePurpose purpose, CancellationToken cancellationToken)
+ {
+ var image = await inner.GetFrameAsync(index, maxLongEdge, purpose, cancellationToken).ConfigureAwait(false);
+ if (index != frame) return image;
+ for (var c = 0; c < image.Channels; c++)
+ {
+ for (var y = image.Height / 3; y < image.Height / 3 + 10; y++)
+ {
+ for (var x = image.Width / 2; x < image.Width / 2 + 10; x++) image[c, x, y] = 1;
+ }
+ }
+ return image;
+ }
+ }
+
+ /// Wraps a real provider and fails its sessions at a given frame (fault injection).
+ private sealed class FaultInjectingProvider(IVideoEncoderProvider inner, int failAt) : IVideoEncoderProvider
+ {
+ public const string Message = "injected encoder fault";
+
+ public string Name => inner.Name;
+ public IReadOnlyList Capabilities => inner.Capabilities;
+ public bool CanEncode(EncodeSettings settings) => inner.CanEncode(settings);
+ public IVideoEncoderSession Open(EncodeSettings settings) => new Session(inner.Open(settings), failAt);
+
+ private sealed class Session(IVideoEncoderSession inner, int failAt) : IVideoEncoderSession
+ {
+ private int _frames;
+
+ public string EncoderName => inner.EncoderName;
+ public bool IsHardware => inner.IsHardware;
+
+ public void WriteFrame(ImageBuffer frame, long duration90k)
+ {
+ if (_frames++ == failAt) throw new InvalidDataException(Message);
+ inner.WriteFrame(frame, duration90k);
+ }
+
+ public void Complete() => inner.Complete();
+ public void Dispose() => inner.Dispose();
+ }
+ }
+}
diff --git a/src/Titano.Core/Render/Diagnostics/SyntheticFrameSource.cs b/src/Titano.Core/Render/Diagnostics/SyntheticFrameSource.cs
new file mode 100644
index 00000000..35b53542
--- /dev/null
+++ b/src/Titano.Core/Render/Diagnostics/SyntheticFrameSource.cs
@@ -0,0 +1,83 @@
+using Titano.Core.Diagnostics.Synthetic;
+using Titano.Core.Imaging;
+using Titano.Core.Imaging.Geometry;
+
+namespace Titano.Core.Render.Diagnostics;
+
+///
+/// over a (self-test and tests). An optional camera
+/// motion translates each frame's content by a per-frame offset in pixels (pans, shake). Frames are rendered on demand,
+/// so memory does not depend on the sequence length.
+///
+public sealed class SyntheticFrameSource(SyntheticSequence sequence, Func? cameraMotion = null) : IRenderFrameSource
+{
+ private int _decodes;
+ private int _largestRequest;
+
+ public SyntheticSequence Sequence { get; } = sequence ?? throw new ArgumentNullException(nameof(sequence));
+
+ public int FrameCount => Sequence.Count;
+
+ public int Width => Sequence.Options.Width;
+
+ public int Height => Sequence.Options.Height;
+
+ /// Frames produced so far.
+ public int Decodes => Volatile.Read(ref _decodes);
+
+ /// Largest long edge requested for rendering (0 = full size).
+ public int LargestRenderRequest => Volatile.Read(ref _largestRequest);
+
+ /// Capture metadata of the sequence's frames.
+ public SourceFrameInfo[] Metadata() => SourceFrameInfo.From(Sequence.Frames);
+
+ public ValueTask GetFrameAsync(int index, int maxLongEdge, DecodePurpose purpose, CancellationToken cancellationToken)
+ {
+ cancellationToken.ThrowIfCancellationRequested();
+ Interlocked.Increment(ref _decodes);
+ if (purpose == DecodePurpose.Render) InterlockedMax(ref _largestRequest, maxLongEdge);
+ var frame = Sequence.Render(index);
+ try
+ {
+ if (cameraMotion is not null)
+ {
+ var (dx, dy) = cameraMotion(index);
+ var moved = new ImageBuffer(frame.Width, frame.Height, frame.Channels, clear: false);
+ try
+ {
+ GeometryStage.Warp(frame, moved, Affine2D.Translation(-dx, -dy), BorderMode.Clamp, cancellationToken);
+ }
+ catch
+ {
+ moved.Dispose();
+ throw;
+ }
+ frame.Dispose();
+ frame = moved;
+ }
+ if (maxLongEdge > 0 && int.Max(frame.Width, frame.Height) > maxLongEdge)
+ {
+ var small = Resampler.Thumbnail(frame, maxLongEdge);
+ frame.Dispose();
+ frame = small;
+ }
+ return ValueTask.FromResult(frame);
+ }
+ catch
+ {
+ frame.Dispose();
+ throw;
+ }
+ }
+
+ private static void InterlockedMax(ref int target, int value)
+ {
+ var current = Volatile.Read(ref target);
+ while (value > current)
+ {
+ var seen = Interlocked.CompareExchange(ref target, value, current);
+ if (seen == current) return;
+ current = seen;
+ }
+ }
+}
diff --git a/src/Titano.Core/Render/FrameCaches.cs b/src/Titano.Core/Render/FrameCaches.cs
new file mode 100644
index 00000000..356f27a1
--- /dev/null
+++ b/src/Titano.Core/Render/FrameCaches.cs
@@ -0,0 +1,95 @@
+using Titano.Core.Imaging;
+using Titano.Core.Motion;
+
+namespace Titano.Core.Render;
+
+/// Least-recently-used cache of prepared (corrected and warped) frames by source index; owns its buffers.
+internal sealed class PreparedFrameCache(int capacity) : IDisposable
+{
+ private readonly List<(int Index, ImageBuffer Frame)> _entries = new(capacity + 1);
+
+ public bool TryGet(int index, out ImageBuffer frame)
+ {
+ for (var i = 0; i < _entries.Count; i++)
+ {
+ if (_entries[i].Index != index) continue;
+ var entry = _entries[i];
+ _entries.RemoveAt(i);
+ _entries.Add(entry);
+ frame = entry.Frame;
+ return true;
+ }
+ frame = null!;
+ return false;
+ }
+
+ public void Add(int index, ImageBuffer frame)
+ {
+ _entries.Add((index, frame));
+ while (_entries.Count > capacity)
+ {
+ _entries[0].Frame.Dispose();
+ _entries.RemoveAt(0);
+ }
+ }
+
+ public void Dispose()
+ {
+ foreach (var (_, frame) in _entries) frame.Dispose();
+ _entries.Clear();
+ }
+}
+
+/// Flow fields between two source frames (forward, and backward when synthesis needed it).
+internal sealed record FlowPair(MotionField Forward, MotionField? Backward);
+
+/// Least-recently-used cache of flow fields by source pair; owns its fields.
+internal sealed class FlowCache(int capacity) : IDisposable
+{
+ private readonly List<(int From, int To, FlowPair Flows)> _entries = new(capacity + 1);
+
+ public bool TryGet(int from, int to, bool needBackward, out FlowPair flows)
+ {
+ for (var i = 0; i < _entries.Count; i++)
+ {
+ var entry = _entries[i];
+ if (entry.From != from || entry.To != to) continue;
+ if (needBackward && entry.Flows.Backward is null) break;
+ _entries.RemoveAt(i);
+ _entries.Add(entry);
+ flows = entry.Flows;
+ return true;
+ }
+ flows = null!;
+ return false;
+ }
+
+ /// Adds (or replaces) the flows of a pair.
+ public void Add(int from, int to, FlowPair flows)
+ {
+ var existing = _entries.FindIndex(e => e.From == from && e.To == to);
+ if (existing >= 0)
+ {
+ Release(_entries[existing].Flows);
+ _entries.RemoveAt(existing);
+ }
+ _entries.Add((from, to, flows));
+ while (_entries.Count > capacity)
+ {
+ Release(_entries[0].Flows);
+ _entries.RemoveAt(0);
+ }
+ }
+
+ public void Dispose()
+ {
+ foreach (var entry in _entries) Release(entry.Flows);
+ _entries.Clear();
+ }
+
+ private static void Release(FlowPair flows)
+ {
+ flows.Forward.Dispose();
+ flows.Backward?.Dispose();
+ }
+}
diff --git a/src/Titano.Core/Render/IRenderFrameSource.cs b/src/Titano.Core/Render/IRenderFrameSource.cs
new file mode 100644
index 00000000..7aa5e8bf
--- /dev/null
+++ b/src/Titano.Core/Render/IRenderFrameSource.cs
@@ -0,0 +1,47 @@
+using Titano.Core.Imaging;
+using Titano.Core.Model;
+
+namespace Titano.Core.Render;
+
+///
+/// Decoded source frames of a render by index. The application backs it with the image decoders and the sliding
+/// FrameWindow (read-ahead, disk spill); tests and the self-test use synthetic sources. Sequential index order is
+/// the common access pattern; neighbours may be requested again for flow and interpolation.
+///
+public interface IRenderFrameSource
+{
+ int FrameCount { get; }
+
+ /// Full-resolution width after orientation.
+ int Width { get; }
+
+ /// Full-resolution height after orientation.
+ int Height { get; }
+
+ ///
+ /// Frame in linear light, its long edge at most (0 = full size).
+ /// A source may return a smaller frame of the same aspect (e.g. an embedded preview). The caller owns the buffer.
+ ///
+ ValueTask GetFrameAsync(int index, int maxLongEdge, DecodePurpose purpose, CancellationToken cancellationToken);
+}
+
+/// Capture metadata of one source frame used by the plan and the preparation.
+/// Camera clock (clock-corrected when available); null when unknown.
+/// Shutter time in seconds (real shutter angle for motion blur).
+/// EV at ISO 100 (holy-grail steps).
+public readonly record struct SourceFrameInfo(DateTime? CapturedAt, double? ExposureTime, double? ExposureValue)
+{
+ /// Metadata of archived frames, optionally with clock-corrected times (LightAnalysisReport.AdjustedTimes).
+ public static SourceFrameInfo[] From(IReadOnlyList frames, IReadOnlyList? adjustedTimes = null)
+ {
+ ArgumentNullException.ThrowIfNull(frames);
+ if (adjustedTimes is not null && adjustedTimes.Count != frames.Count) throw new ArgumentException("One time per frame is required.", nameof(adjustedTimes));
+ var result = new SourceFrameInfo[frames.Count];
+ for (var i = 0; i < frames.Count; i++)
+ {
+ var f = frames[i];
+ result[i] = new SourceFrameInfo(adjustedTimes is null ? f.CapturedAt : adjustedTimes[i], f.ExposureTime, f.ExposureValue);
+ }
+ return result;
+ }
+}
diff --git a/src/Titano.Core/Render/ProjectValues.cs b/src/Titano.Core/Render/ProjectValues.cs
new file mode 100644
index 00000000..67b3f40c
--- /dev/null
+++ b/src/Titano.Core/Render/ProjectValues.cs
@@ -0,0 +1,17 @@
+using Titano.Core.Project;
+
+namespace Titano.Core.Render;
+
+///
+/// Reads value-type settings. For value types is never null (an
+/// unconstrained T? is T), so returns default instead of the fallback
+/// when there is no advice; here a default automatic value means "no advice" and yields the fallback.
+///
+internal static class ProjectValues
+{
+ public static T Get(Auto setting, T fallback) where T : struct
+ {
+ if (!setting.IsAuto) return setting.Manual;
+ return EqualityComparer.Default.Equals(setting.AutoValue, default) ? fallback : setting.AutoValue;
+ }
+}
diff --git a/src/Titano.Core/Render/RenderGeometry.cs b/src/Titano.Core/Render/RenderGeometry.cs
new file mode 100644
index 00000000..45b6f172
--- /dev/null
+++ b/src/Titano.Core/Render/RenderGeometry.cs
@@ -0,0 +1,206 @@
+using System.Globalization;
+using Titano.Core.Export;
+using Titano.Core.Imaging.Geometry;
+using Titano.Core.Motion;
+using Titano.Core.Project;
+using Titano.Core.Video;
+
+namespace Titano.Core.Render;
+
+///
+/// Output size, decode size and per-frame warp of a render. is a normalised
+/// [x, y, width, height] rectangle of the camera view; the output aspect is the export's when it fixes both dimensions,
+/// otherwise the camera aspect (source = frame aspect). Virtual-camera keyframes are keyed to source frame positions, so
+/// they stay attached to the content when timing, frame rate or fitting change. The stabiliser correction, the camera
+/// pose (zoomed by the stabilisation zoom) and the crop become one output→source map, resampled once.
+///
+public sealed class RenderGeometry
+{
+ private static readonly CameraState Neutral = new(0.5, 0.5, 1, 0);
+ private readonly VirtualCamera? _camera;
+ private readonly RectD _crop;
+ private readonly double _offsetX;
+ private readonly double _offsetY;
+ private readonly double _stabilizationZoom;
+ private readonly double _fittedWidth;
+ private readonly double _fittedHeight;
+ private readonly double _maxZoom;
+ private readonly int _maxWorkingLongEdge;
+
+ private RenderGeometry(VirtualCamera? camera, RectD crop, double offsetX, double offsetY, double stabilizationZoom, int sourceWidth, int sourceHeight,
+ int outputWidth, int outputHeight, double fittedWidth, double fittedHeight, double maxZoom, int maxWorkingLongEdge, IReadOnlyList warnings)
+ {
+ _camera = camera;
+ _crop = crop;
+ _offsetX = offsetX;
+ _offsetY = offsetY;
+ _stabilizationZoom = stabilizationZoom;
+ SourceWidth = sourceWidth;
+ SourceHeight = sourceHeight;
+ OutputWidth = outputWidth;
+ OutputHeight = outputHeight;
+ _fittedWidth = fittedWidth;
+ _fittedHeight = fittedHeight;
+ _maxZoom = maxZoom;
+ _maxWorkingLongEdge = maxWorkingLongEdge;
+ Warnings = warnings;
+ }
+
+ public int SourceWidth { get; }
+ public int SourceHeight { get; }
+ public int OutputWidth { get; }
+ public int OutputHeight { get; }
+
+ /// Remarks about ignored camera values.
+ public IReadOnlyList Warnings { get; }
+
+ ///
+ /// Long edge to decode source frames at: enough that the most zoomed-in view still has one source pixel per output
+ /// pixel, never more than the source, capped by .
+ ///
+ public int WorkingLongEdge
+ {
+ get
+ {
+ var needed = double.Max(OutputWidth / _fittedWidth, OutputHeight / _fittedHeight) * _maxZoom;
+ var edge = (int)double.Ceiling(int.Max(SourceWidth, SourceHeight) * double.Min(1, needed));
+ edge = int.Clamp(edge, int.Min(16, int.Max(SourceWidth, SourceHeight)), int.Max(SourceWidth, SourceHeight));
+ return _maxWorkingLongEdge > 0 ? int.Min(edge, _maxWorkingLongEdge) : edge;
+ }
+ }
+
+ /// Plans the geometry of for a source of the given full-resolution size.
+ /// Zoom that hides stabilisation borders ().
+ /// Decode-size cap (0 = none); it also caps source-sized outputs.
+ public static RenderGeometry Create(CameraSettings camera, ResolvedExport export, int sourceWidth, int sourceHeight, double stabilizationZoom = 1, int maxWorkingLongEdge = 0)
+ {
+ ArgumentNullException.ThrowIfNull(camera);
+ ArgumentNullException.ThrowIfNull(export);
+ ArgumentOutOfRangeException.ThrowIfNegativeOrZero(sourceWidth);
+ ArgumentOutOfRangeException.ThrowIfNegativeOrZero(sourceHeight);
+ var warnings = new List();
+ var crop = NormalisedCrop(camera.Crop, warnings);
+ if (!AspectRatio.TryParse(camera.Aspect.Resolve("source"), out var aspect))
+ {
+ warnings.Add(new RenderWarning("Export.Render.AspectIgnored", camera.Aspect.Resolve(string.Empty)));
+ aspect = AspectRatio.Source;
+ }
+ var fixedSize = export.Width > 0 && export.Height > 0;
+ var ratio = fixedSize ? export.Width / (double)export.Height : aspect.Resolve(sourceWidth, sourceHeight);
+ if (fixedSize && !aspect.IsSource && double.Abs(aspect.Resolve(sourceWidth, sourceHeight) / ratio - 1) > 0.01)
+ warnings.Add(new RenderWarning("Export.Render.AspectFromPreset", aspect.ToString(), string.Create(CultureInfo.InvariantCulture, $"{export.Width}:{export.Height}")));
+ var cropPixels = new RectD(crop.X * sourceWidth, crop.Y * sourceHeight, crop.Width * sourceWidth, crop.Height * sourceHeight);
+ var fitted = AspectRatio.FitCrop(cropPixels, ratio, camera.OffsetX, camera.OffsetY);
+
+ int width, height;
+ if (fixedSize) (width, height) = (export.Width, export.Height);
+ else if (export.Width > 0) (width, height) = (export.Width, (int)double.Round(export.Width / ratio));
+ else if (export.Height > 0) (width, height) = ((int)double.Round(export.Height * ratio), export.Height);
+ else
+ {
+ var scale = maxWorkingLongEdge > 0 ? double.Min(1, maxWorkingLongEdge / double.Max(fitted.Width, fitted.Height)) : 1;
+ (width, height) = ((int)double.Round(fitted.Width * scale), (int)double.Round(fitted.Height * scale));
+ }
+ if (!VideoCodecInfo.IsManaged(export.Codec))
+ {
+ width &= ~1;
+ height &= ~1;
+ }
+ width = int.Max(VideoCodecInfo.IsManaged(export.Codec) ? 1 : 2, width);
+ height = int.Max(VideoCodecInfo.IsManaged(export.Codec) ? 1 : 2, height);
+
+ var cameraPath = Camera(camera.Keyframes, warnings);
+ var maxZoom = (cameraPath?.Keyframes.Max(k => k.Zoom) ?? 1) * stabilizationZoom;
+ return new RenderGeometry(cameraPath, crop, camera.OffsetX, camera.OffsetY, stabilizationZoom, sourceWidth, sourceHeight, width, height,
+ fitted.Width, fitted.Height, maxZoom, maxWorkingLongEdge, warnings);
+ }
+
+ /// The same geometry rendering into a different output size (e.g. capped by the encoder).
+ public RenderGeometry WithOutputSize(int width, int height) => width == OutputWidth && height == OutputHeight
+ ? this
+ : new RenderGeometry(_camera, _crop, _offsetX, _offsetY, _stabilizationZoom, SourceWidth, SourceHeight, width, height, _fittedWidth, _fittedHeight,
+ _maxZoom, _maxWorkingLongEdge, Warnings);
+
+ /// Camera pose at a (fractional) source position, including the stabilisation zoom.
+ public CameraState PoseAt(double sourcePosition)
+ {
+ var pose = _camera?.Evaluate(sourcePosition) ?? Neutral;
+ return pose with { Zoom = pose.Zoom * _stabilizationZoom };
+ }
+
+ /// Geometry of one decoded frame of × pixels.
+ /// The frame's stabiliser correction at this frame size (source → stabilised).
+ public GeometrySettings For(int frameWidth, int frameHeight, double sourcePosition, Affine2D stabilization)
+ {
+ var view = VirtualCamera.ViewToSource(PoseAt(sourcePosition), frameWidth, frameHeight);
+ return new GeometrySettings
+ {
+ Crop = new RectD(_crop.X * frameWidth, _crop.Y * frameHeight, _crop.Width * frameWidth, _crop.Height * frameHeight),
+ Aspect = AspectRatio.Source,
+ OffsetX = _offsetX,
+ OffsetY = _offsetY,
+ OutputWidth = OutputWidth,
+ OutputHeight = OutputHeight,
+ Warp = stabilization.IsIdentity() ? view : stabilization.Invert() * view,
+ Border = BorderMode.Clamp,
+ };
+ }
+
+ private static RectD NormalisedCrop(double[]? crop, List warnings)
+ {
+ var full = new RectD(0, 0, 1, 1);
+ if (crop is null) return full;
+ if (crop.Length != 4 || !crop.All(double.IsFinite))
+ {
+ warnings.Add(new RenderWarning("Export.Render.CropIgnored"));
+ return full;
+ }
+ var x = double.Clamp(crop[0], 0, 1);
+ var y = double.Clamp(crop[1], 0, 1);
+ var w = double.Min(crop[2], 1 - x);
+ var h = double.Min(crop[3], 1 - y);
+ if (w <= 1e-3 || h <= 1e-3)
+ {
+ warnings.Add(new RenderWarning("Export.Render.CropIgnored"));
+ return full;
+ }
+ return new RectD(x, y, w, h);
+ }
+
+ private static VirtualCamera? Camera(IReadOnlyList keys, List warnings)
+ {
+ if (keys.Count == 0) return null;
+ var frames = new Dictionary();
+ foreach (var k in keys)
+ {
+ if (!double.IsFinite(k.CenterX + k.CenterY + k.Zoom + k.Rotation))
+ {
+ warnings.Add(new RenderWarning("Export.Render.KeyframeIgnored", k.Frame.ToString(CultureInfo.InvariantCulture)));
+ continue;
+ }
+ frames[k.Frame] = new CameraKeyframe(k.Frame, k.CenterX, k.CenterY, double.Max(1, k.Zoom), k.Rotation) { Easing = Easing(k.Easing, warnings) };
+ }
+ return frames.Count == 0 ? null : new VirtualCamera(frames.Values);
+ }
+
+ /// "Linear", "EaseIn", "EaseOut", "EaseInOut" or "x1,y1,x2,y2" control points (CSS cubic-bezier).
+ private static BezierEasing Easing(string? text, List warnings)
+ {
+ switch (text?.Trim().ToLowerInvariant())
+ {
+ case null or "" or "easeinout": return BezierEasing.EaseInOut;
+ case "linear": return BezierEasing.Linear;
+ case "easein": return BezierEasing.EaseIn;
+ case "easeout": return BezierEasing.EaseOut;
+ }
+ var parts = text.Split(',');
+ if (parts.Length == 4
+ && double.TryParse(parts[0], NumberStyles.Float, CultureInfo.InvariantCulture, out var x1) && x1 is >= 0 and <= 1
+ && double.TryParse(parts[1], NumberStyles.Float, CultureInfo.InvariantCulture, out var y1) && double.IsFinite(y1)
+ && double.TryParse(parts[2], NumberStyles.Float, CultureInfo.InvariantCulture, out var x2) && x2 is >= 0 and <= 1
+ && double.TryParse(parts[3], NumberStyles.Float, CultureInfo.InvariantCulture, out var y2) && double.IsFinite(y2))
+ return new BezierEasing(x1, y1, x2, y2);
+ warnings.Add(new RenderWarning("Export.Render.EasingIgnored", text));
+ return BezierEasing.EaseInOut;
+ }
+}
diff --git a/src/Titano.Core/Render/RenderModels.cs b/src/Titano.Core/Render/RenderModels.cs
new file mode 100644
index 00000000..27f90c1c
--- /dev/null
+++ b/src/Titano.Core/Render/RenderModels.cs
@@ -0,0 +1,127 @@
+using Titano.Core.Analysis;
+using Titano.Core.Export;
+using Titano.Core.Imaging;
+using Titano.Core.Motion;
+using Titano.Core.Project;
+
+namespace Titano.Core.Render;
+
+/// Everything a render of one sequence reads, shared by every preset of a batch.
+public sealed record RenderInput
+{
+ public required IRenderFrameSource Source { get; init; }
+
+ /// Capture metadata, one entry per source frame.
+ public required IReadOnlyList Frames { get; init; }
+
+ public required ProjectSettings Project { get; init; }
+
+ /// Cached deep-analysis results; missing parts are measured by the preparation pass.
+ public PrecomputedAnalysis? Analysis { get; init; }
+}
+
+/// One output of a render: the resolved export values and where the file (or sequence folder) goes.
+/// Full path of the file, or of the folder for image sequences (see ).
+public sealed record RenderTarget(ResolvedExport Export, string OutputPath);
+
+/// Tuning of a render that is not part of the project.
+public sealed record RenderOptions
+{
+ public static RenderOptions Default { get; } = new();
+
+ /// Long edge of the frames measured by the preparation pass.
+ public int AnalysisLongEdge { get; init; } = 512;
+
+ /// Upper bound of the decode size (0 = as large as the output geometry needs); previews set a small value.
+ public int MaxWorkingLongEdge { get; init; }
+
+ /// A downscaled copy of every n-th rendered frame is reported for the live preview (0 = never).
+ public int PreviewInterval { get; init; }
+
+ public int PreviewLongEdge { get; init; } = 640;
+
+ /// Prepared (exposure-corrected, warped) frames kept for flow and interpolation neighbours (at least 3).
+ public int CacheFrames { get; init; } = 4;
+
+ public RenderPlanOptions Plan { get; init; } = RenderPlanOptions.Default;
+}
+
+public enum RenderStage
+{
+ /// Measuring the sequence (luminance, colour, camera path).
+ Preparing,
+
+ /// Rendering and encoding output frames.
+ Rendering,
+
+ /// Flushing and committing the output.
+ Finishing,
+}
+
+/// Progress of a render. (when present) belongs to the receiver, which disposes it.
+/// Frames measured (Preparing) or output frames rendered (Rendering).
+/// Frames of the current stage.
+/// Recent throughput of the current stage.
+/// Estimated time to the end of the stage; null until measurable.
+public sealed record RenderProgress(RenderStage Stage, int Done, int Total, double FramesPerSecond, TimeSpan Elapsed, TimeSpan? Remaining, ImageBuffer? Preview = null)
+{
+ public double Fraction => Total > 0 ? (double)Done / Total : 0;
+}
+
+///
+/// Results of the advisor's deep analysis reused by the preparation (all arrays have one entry per source frame).
+/// Invalid or mismatched parts are ignored and measured again.
+///
+public sealed record PrecomputedAnalysis
+{
+ /// Trimmed-mean log2 luminance (NaN = unusable frame).
+ public double[]? LogLuminance { get; init; }
+
+ /// Mean linear red, green and blue (white-balance smoothing).
+ public double[]? MeanRed { get; init; }
+
+ public double[]? MeanGreen { get; init; }
+ public double[]? MeanBlue { get; init; }
+
+ /// Sky/land mask with the region series measured through it.
+ public RegionMask? Regions { get; init; }
+
+ public double[]? SkyLogLuminance { get; init; }
+ public double[]? LandLogLuminance { get; init; }
+
+ /// Stabilisation solved over the sequence, one correction per source frame, in pixels of a frame of
+ /// ×.
+ public StabilizationResult? Stabilization { get; init; }
+
+ public int StabilizationWidth { get; init; }
+ public int StabilizationHeight { get; init; }
+
+ /// Path smoothing σ the stabilisation was solved with; a different project value triggers a new solve.
+ public double StabilizationSmoothing { get; init; }
+}
+
+/// A localisable remark about a render (key plus invariant-culture arguments).
+public sealed record RenderWarning(string Key, IReadOnlyList Args)
+{
+ public RenderWarning(string key, params string[] args) : this(key, (IReadOnlyList)args)
+ {
+ }
+
+ public override string ToString() => Args.Count == 0 ? Key : $"{Key}({string.Join(", ", Args)})";
+}
+
+/// A render that cannot start or continue for a reason the user can act on.
+public sealed class RenderException : Exception
+{
+ public RenderException(string reasonKey, string message, IReadOnlyList? args = null, Exception? innerException = null)
+ : base(message, innerException)
+ {
+ ReasonKey = reasonKey;
+ Args = args ?? [];
+ }
+
+ /// Localisation key of the reason (e.g. ).
+ public string ReasonKey { get; }
+
+ public IReadOnlyList Args { get; }
+}
diff --git a/src/Titano.Core/Render/RenderPipeline.cs b/src/Titano.Core/Render/RenderPipeline.cs
new file mode 100644
index 00000000..dd2575e6
--- /dev/null
+++ b/src/Titano.Core/Render/RenderPipeline.cs
@@ -0,0 +1,461 @@
+using System.Diagnostics;
+using System.Globalization;
+using Titano.Core.Analysis;
+using Titano.Core.Diagnostics;
+using Titano.Core.Export;
+using Titano.Core.Imaging;
+using Titano.Core.Imaging.Geometry;
+using Titano.Core.Motion;
+using Titano.Core.Project;
+using Titano.Core.Video;
+
+namespace Titano.Core.Render;
+
+///
+/// Renders sequences (BRIEF §11). For every planned output frame: source frames come from the
+/// at the working size; per-frame exposure corrections (deflicker, holy grail, white
+/// balance, regions) are applied; stabilisation, virtual camera and crop are resampled once to the output size;
+/// fractional positions are synthesised from the bidirectional flow; motion blur follows the flow with shutter-angle
+/// composition; stacking (median, mean, star trails) and the highlight knee come last, then the encoder. Encoding of a
+/// frame overlaps the processing of the next. Cancellation and failures leave no output behind (sessions delete their
+/// partial files on dispose) and every background task is awaited, so exceptions surface exactly once.
+///
+public sealed class RenderPipeline(IReadOnlyList encoders, EncoderHost host = EncoderHost.Client)
+{
+ internal const string LogCategory = "Render";
+
+ /// Encoder providers in priority order (client: Media Foundation, then managed; server: managed).
+ public IReadOnlyList Encoders { get; } = encoders ?? throw new ArgumentNullException(nameof(encoders));
+
+ public EncoderHost Host { get; } = host;
+
+ /// Geometry, encoder and plan of a target without rendering (Export tab, estimates).
+ public RenderSetup Setup(RenderInput input, RenderTarget target, RenderOptions? options = null, RenderCorrections? corrections = null) =>
+ RenderSetup.Create(input, target, Encoders, Host, options, corrections);
+
+ /// Prepares the sequence and renders one target.
+ public async Task RenderAsync(RenderInput input, RenderTarget target, RenderOptions? options = null, IProgress? progress = null,
+ CancellationToken cancellationToken = default)
+ {
+ var corrections = await RenderPreparation.PrepareAsync(input, options, progress, cancellationToken).ConfigureAwait(false);
+ return await RenderAsync(input, corrections, target, options, progress, cancellationToken).ConfigureAwait(false);
+ }
+
+ /// Renders one target with corrections prepared earlier (shared by a batch).
+ /// No encoder can produce the target, or every frame is excluded.
+ public async Task RenderAsync(RenderInput input, RenderCorrections corrections, RenderTarget target, RenderOptions? options = null,
+ IProgress? progress = null, CancellationToken cancellationToken = default)
+ {
+ ArgumentNullException.ThrowIfNull(input);
+ ArgumentNullException.ThrowIfNull(corrections);
+ ArgumentNullException.ThrowIfNull(target);
+ options ??= RenderOptions.Default;
+ if (corrections.FrameCount != input.Source.FrameCount) throw new ArgumentException("The corrections belong to another sequence.", nameof(corrections));
+ await Task.CompletedTask.ConfigureAwait(ConfigureAwaitOptions.ForceYielding);
+ cancellationToken.ThrowIfCancellationRequested();
+
+ var setup = Setup(input, target, options, corrections);
+ if (!setup.Encoder.IsReady)
+ {
+ var notice = setup.Encoder.Notices.LastOrDefault() ?? new EncoderNotice(EncoderNotices.NoEncoder, setup.Encoder.Settings.Codec.ToString());
+ throw new RenderException(notice.Key, $"No encoder can produce {target.Export.Codec} here ({setup.Encoder.Status})", notice.Args);
+ }
+ if (setup.Plan.Frames.Count == 0) throw new RenderException("Export.Render.NoFrames", "Every frame is excluded.");
+ using var run = new RenderRun(input, corrections, setup, options, progress);
+ return await run.ExecuteAsync(cancellationToken).ConfigureAwait(false);
+ }
+
+ ///
+ /// Renders several targets of one sequence one after the other, preparing the sequence once. A failing target is
+ /// reported and the batch continues; cancellation stops the batch.
+ ///
+ public async Task> RenderBatchAsync(RenderInput input, IReadOnlyList targets, RenderOptions? options = null,
+ IProgress? progress = null, CancellationToken cancellationToken = default)
+ {
+ ArgumentNullException.ThrowIfNull(targets);
+ var corrections = await RenderPreparation.PrepareAsync(input, options, progress, cancellationToken).ConfigureAwait(false);
+ var results = new List(targets.Count);
+ foreach (var target in targets)
+ {
+ cancellationToken.ThrowIfCancellationRequested();
+ try
+ {
+ results.Add(new BatchItemResult(target, await RenderAsync(input, corrections, target, options, progress, cancellationToken).ConfigureAwait(false), null));
+ }
+ catch (Exception ex) when (!(ex is OperationCanceledException && cancellationToken.IsCancellationRequested))
+ {
+ Log.Warning(LogCategory, $"Batch target {target.OutputPath} failed", ex);
+ results.Add(new BatchItemResult(target, null, ex));
+ }
+ }
+ return results;
+ }
+}
+
+/// State of one render: caches, flow, stacking, the encoder session and the encode in flight.
+internal sealed class RenderRun : IDisposable
+{
+ /// Largest speed (source frames per output period) that scales motion blur; faster plans blur no further.
+ private const double MaxBlurSpeed = 4;
+
+ private readonly RenderInput _input;
+ private readonly RenderCorrections _corrections;
+ private readonly RenderSetup _setup;
+ private readonly RenderOptions _options;
+ private readonly IProgress? _progress;
+ private readonly RenderPlan _plan;
+ private readonly RenderGeometry _geometry;
+ private readonly PreparedFrameCache _prepared;
+ private readonly FlowCache _flows = new(2);
+ private readonly MotionBlurRenderer _blur = new();
+ private readonly List _warnings = [];
+ private readonly Stopwatch _clock = new();
+ private readonly int _workingEdge;
+ private readonly float? _knee;
+ private readonly double _targetShutter;
+ private readonly FlowQuality _flowQuality;
+ private OpticalFlowEngine? _flowEngine;
+ private RegionMask? _mask;
+ private IVideoEncoderSession? _session;
+ private Task? _encoding;
+ private int _done;
+
+ public RenderRun(RenderInput input, RenderCorrections corrections, RenderSetup setup, RenderOptions options, IProgress? progress)
+ {
+ _input = input;
+ _corrections = corrections;
+ _setup = setup;
+ _options = options;
+ _progress = progress;
+ _plan = setup.Plan;
+ _geometry = setup.Geometry;
+ _prepared = new PreparedFrameCache(int.Max(3, options.CacheFrames));
+ _workingEdge = _geometry.WorkingLongEdge;
+ var exposure = input.Project.Exposure;
+ if (exposure.HighlightKnee is { } knee)
+ {
+ if (knee is > 0 and < 1) _knee = (float)knee;
+ else _warnings.Add(new RenderWarning("Export.Render.KneeIgnored", knee.ToString(CultureInfo.InvariantCulture)));
+ }
+ var motion = input.Project.Motion;
+ _targetShutter = double.Clamp(ProjectValues.Get(motion.TargetShutterAngle, 180.0), 0, 360);
+ _flowQuality = ProjectValues.Get(motion.FlowQuality, FlowQualitySetting.Balanced) switch
+ {
+ FlowQualitySetting.Draft => FlowQuality.Draft,
+ FlowQualitySetting.Best => FlowQuality.Best,
+ _ => FlowQuality.Balanced,
+ };
+ }
+
+ public async Task ExecuteAsync(CancellationToken cancellationToken)
+ {
+ var settings = _setup.Encoder.Settings;
+ _clock.Start();
+ Log.Info(RenderPipeline.LogCategory, $"Rendering {_plan.Frames.Count} frames ({_plan.SlotCount} periods) to {settings.Codec} {settings.Width}×{settings.Height} @ {settings.FrameRate}: {settings.OutputPath}");
+ var session = _session = _setup.Encoder.Open();
+ try
+ {
+ await RenderFramesAsync(cancellationToken).ConfigureAwait(false);
+ await FlushEncodingAsync().ConfigureAwait(false);
+ _progress?.Report(new RenderProgress(RenderStage.Finishing, _done, _plan.Frames.Count, Fps(), _clock.Elapsed, TimeSpan.Zero));
+ session.Complete();
+ }
+ catch
+ {
+ await ObserveEncodingAsync().ConfigureAwait(false);
+ throw;
+ }
+ finally
+ {
+ session.Dispose();
+ }
+ _clock.Stop();
+ var warnings = new List(_setup.Warnings);
+ warnings.AddRange(_corrections.Report.Warnings);
+ warnings.AddRange(_warnings);
+ var result = new RenderResult
+ {
+ OutputPath = settings.OutputPath,
+ PresetId = _setup.Target.Export.PresetId,
+ Codec = settings.Codec,
+ Width = settings.Width,
+ Height = settings.Height,
+ FrameRate = settings.FrameRate,
+ DurationSeconds = _plan.DurationSeconds,
+ FrameCount = _plan.Frames.Count,
+ Bytes = RenderResult.SizeOf(settings.OutputPath),
+ EncoderName = session.EncoderName,
+ Hardware = session.IsHardware,
+ Elapsed = _clock.Elapsed,
+ Warnings = warnings,
+ };
+ Log.Info(RenderPipeline.LogCategory, $"Rendered {result.FrameCount} frames in {result.Elapsed.TotalSeconds:F1} s with {result.EncoderName}: {result.Bytes} bytes");
+ return result;
+ }
+
+ public void Dispose()
+ {
+ _prepared.Dispose();
+ _flows.Dispose();
+ _flowEngine?.Dispose();
+ }
+
+ private async Task RenderFramesAsync(CancellationToken cancellationToken)
+ {
+ var stack = _input.Project.Stack;
+ switch (stack.Mode)
+ {
+ case StackSetting.Median or StackSetting.Mean:
+ await RenderWindowStackAsync(stack, cancellationToken).ConfigureAwait(false);
+ break;
+ case StackSetting.StarTrails:
+ using (var trails = new StarTrailStacker(StarTrailStacker.DecayForTrailLength(stack.Length > 0 ? stack.Length : double.PositiveInfinity)))
+ {
+ foreach (var planned in _plan.Frames)
+ {
+ cancellationToken.ThrowIfCancellationRequested();
+ using (var frame = await RenderFrameAsync(planned, blur: false, cancellationToken).ConfigureAwait(false)) trails.Add(frame);
+ await EmitAsync(trails.Result!.Clone(), planned.Duration90k).ConfigureAwait(false);
+ }
+ }
+ break;
+ default:
+ foreach (var planned in _plan.Frames)
+ {
+ cancellationToken.ThrowIfCancellationRequested();
+ var frame = await RenderFrameAsync(planned, _setup.MotionBlur, cancellationToken).ConfigureAwait(false);
+ await EmitAsync(frame, planned.Duration90k).ConfigureAwait(false);
+ }
+ break;
+ }
+ }
+
+ /// Centred median/mean window: output k is emitted once frame k + half has been pushed (the tail reuses the
+ /// last full window).
+ private async Task RenderWindowStackAsync(StackSettings stack, CancellationToken cancellationToken)
+ {
+ var window = int.Max(1, stack.Length);
+ var half = (window - 1) / 2;
+ using var stacker = new TemporalStacker(window, stack.Mode == StackSetting.Median ? StackMode.Median : StackMode.Mean);
+ var pending = new Queue();
+ foreach (var planned in _plan.Frames)
+ {
+ cancellationToken.ThrowIfCancellationRequested();
+ using (var frame = await RenderFrameAsync(planned, blur: false, cancellationToken).ConfigureAwait(false)) stacker.Push(frame);
+ pending.Enqueue(planned);
+ if (pending.Count > half) await EmitStackAsync(stacker, pending.Dequeue(), cancellationToken).ConfigureAwait(false);
+ }
+ while (pending.Count > 0) await EmitStackAsync(stacker, pending.Dequeue(), cancellationToken).ConfigureAwait(false);
+ }
+
+ private async Task EmitStackAsync(TemporalStacker stacker, PlannedFrame planned, CancellationToken cancellationToken)
+ {
+ var output = new ImageBuffer(_geometry.OutputWidth, _geometry.OutputHeight, 3, clear: false);
+ try
+ {
+ stacker.Render(output, cancellationToken);
+ }
+ catch
+ {
+ output.Dispose();
+ throw;
+ }
+ await EmitAsync(output, planned.Duration90k).ConfigureAwait(false);
+ }
+
+ /// The picture of one planned frame at the output size (a new buffer owned by the caller).
+ private async Task RenderFrameAsync(PlannedFrame planned, bool blur, CancellationToken cancellationToken)
+ {
+ if (planned.Fraction == 0)
+ {
+ var frame = await PreparedAsync(planned.From, cancellationToken).ConfigureAwait(false);
+ if (blur && BlurPair(planned.From) is { } pair && BlurFraction(pair.From, pair.To, planned.Speed) is var fraction and > 0)
+ {
+ var flows = await FlowAsync(pair.From, pair.To, needBackward: false, cancellationToken).ConfigureAwait(false);
+ frame = await PreparedAsync(planned.From, cancellationToken).ConfigureAwait(false);
+ return Blurred(frame, flows.Forward, fraction, cancellationToken);
+ }
+ return frame.Clone();
+ }
+
+ var pairFlows = await FlowAsync(planned.From, planned.To, needBackward: true, cancellationToken).ConfigureAwait(false);
+ var a = await PreparedAsync(planned.From, cancellationToken).ConfigureAwait(false);
+ var b = await PreparedAsync(planned.To, cancellationToken).ConfigureAwait(false);
+ var synthesised = new ImageBuffer(a.Width, a.Height, a.Channels, clear: false);
+ try
+ {
+ FrameInterpolator.Synthesize(a, b, pairFlows.Forward, pairFlows.Backward!, planned.Fraction, synthesised, cancellationToken: cancellationToken);
+ var fraction = blur ? BlurFraction(planned.From, planned.To, planned.Speed) : 0;
+ if (fraction <= 0) return synthesised;
+ using (synthesised) return Blurred(synthesised, pairFlows.Forward, fraction, cancellationToken);
+ }
+ catch
+ {
+ synthesised.Dispose();
+ throw;
+ }
+ }
+
+ private ImageBuffer Blurred(ImageBuffer source, MotionField flow, double fraction, CancellationToken cancellationToken)
+ {
+ var output = new ImageBuffer(source.Width, source.Height, source.Channels, clear: false);
+ try
+ {
+ _blur.Render(source, flow, fraction, output, cancellationToken);
+ return output;
+ }
+ catch
+ {
+ output.Dispose();
+ throw;
+ }
+ }
+
+ /// Continuous neighbours whose flow describes the motion at .
+ private (int From, int To)? BlurPair(int index)
+ {
+ var next = _plan.NextContinuous(index);
+ if (next >= 0) return (index, next);
+ var previous = _plan.PreviousContinuous(index);
+ return previous >= 0 ? (previous, index) : null;
+ }
+
+ ///
+ /// Fraction of the → flow to smear: the target shutter is relative to the
+ /// output period, which spans source intervals, and the camera's own exposure already
+ /// blurred of one interval (√(target² − real²) composition, §11.1).
+ ///
+ private double BlurFraction(int from, int to, double speed)
+ {
+ var steps = to - from;
+ if (steps <= 0) return 0;
+ var real = 0.0;
+ var info = _input.Frames[from];
+ if (info.ExposureTime is > 0 and var exposure && info.CapturedAt is { } t0 && _input.Frames[to].CapturedAt is { } t1 && t1 > t0)
+ real = double.Min(360, ShutterAngle.FromExposure(exposure, (t1 - t0).TotalSeconds / steps));
+ return ShutterAngle.BlurFraction(_targetShutter * double.Clamp(double.Abs(speed), 0, MaxBlurSpeed), real) / steps;
+ }
+
+ private async Task FlowAsync(int from, int to, bool needBackward, CancellationToken cancellationToken)
+ {
+ if (_flows.TryGet(from, to, needBackward, out var cached)) return cached;
+ var a = await PreparedAsync(from, cancellationToken).ConfigureAwait(false);
+ var b = await PreparedAsync(to, cancellationToken).ConfigureAwait(false);
+ _flowEngine ??= new OpticalFlowEngine(_flowQuality);
+ FlowPair flows;
+ if (needBackward)
+ {
+ var (forward, backward) = _flowEngine.ComputeBidirectional(a, b, cancellationToken);
+ flows = new FlowPair(forward, backward);
+ }
+ else
+ {
+ flows = new FlowPair(_flowEngine.Compute(a, b, cancellationToken), null);
+ }
+ _flows.Add(from, to, flows);
+ return flows;
+ }
+
+ /// Source frame decoded, exposure-corrected and warped to the output size (cached).
+ private async Task PreparedAsync(int index, CancellationToken cancellationToken)
+ {
+ if (_prepared.TryGet(index, out var cached)) return cached;
+ var raw = await _input.Source.GetFrameAsync(index, _workingEdge, DecodePurpose.Render, cancellationToken).ConfigureAwait(false);
+ ImageBuffer prepared;
+ try
+ {
+ raw = Rgb(raw);
+ ApplyExposure(raw, index);
+ var settings = _geometry.For(raw.Width, raw.Height, index, _corrections.StabilizationAt(index, raw.Width, raw.Height));
+ prepared = GeometryStage.Apply(raw, settings, cancellationToken);
+ }
+ finally
+ {
+ raw.Dispose();
+ }
+ _prepared.Add(index, prepared);
+ return prepared;
+ }
+
+ /// Gray sources become RGB and alpha is dropped, so every stage and encoder sees three channels.
+ private static ImageBuffer Rgb(ImageBuffer frame)
+ {
+ if (frame.Channels == 3) return frame;
+ using (frame)
+ {
+ if (frame.Channels == 1) return PixelConvert.GrayToRgb(frame);
+ var rgb = new ImageBuffer(frame.Width, frame.Height, 3, clear: false);
+ frame.Data[..(3 * frame.PlaneLength)].CopyTo(rgb.Data);
+ return rgb;
+ }
+ }
+
+ private void ApplyExposure(ImageBuffer frame, int index)
+ {
+ var gains = _corrections.WhiteBalance?[index];
+ if (_corrections is { Regions: { } mask, SkyEv: { } sky, LandEv: { } land })
+ {
+ if (_mask is null || _mask.Width != frame.Width || _mask.Height != frame.Height) _mask = mask.Resample(frame.Width, frame.Height);
+ ExposureProcessor.ApplyRegion(frame, _mask.Sky, sky[index], land[index], gains);
+ return;
+ }
+ var ev = _corrections.ExposureEv[index];
+ if (ev != 0 || (gains is { } g && g != ChannelGains.Identity)) ExposureProcessor.Apply(frame, ev, gains);
+ }
+
+ /// Applies the knee and hands the frame to the encoder once the previous frame is encoded; owns .
+ private async Task EmitAsync(ImageBuffer frame, long duration90k)
+ {
+ ImageBuffer? preview = null;
+ try
+ {
+ await FlushEncodingAsync().ConfigureAwait(false);
+ if (_knee is { } knee) ExposureProcessor.Apply(frame, 0, null, knee);
+ _done++;
+ if (_options.PreviewInterval > 0 && (_done - 1) % _options.PreviewInterval == 0) preview = Resampler.Thumbnail(frame, _options.PreviewLongEdge);
+ }
+ catch
+ {
+ frame.Dispose();
+ throw;
+ }
+ var session = _session!;
+ _encoding = Task.Run(() =>
+ {
+ using (frame) session.WriteFrame(frame, duration90k);
+ }, CancellationToken.None);
+ if (_progress is not null)
+ {
+ var fps = Fps();
+ _progress.Report(new RenderProgress(RenderStage.Rendering, _done, _plan.Frames.Count, fps, _clock.Elapsed,
+ fps > 0 ? TimeSpan.FromSeconds((_plan.Frames.Count - _done) / fps) : null, preview));
+ }
+ else
+ {
+ preview?.Dispose();
+ }
+ }
+
+ private double Fps() => _done / double.Max(_clock.Elapsed.TotalSeconds, 1e-6);
+
+ /// Waits for the encode in flight; its failure propagates here (once).
+ private async Task FlushEncodingAsync()
+ {
+ var encoding = _encoding;
+ _encoding = null;
+ if (encoding is not null) await encoding.ConfigureAwait(false);
+ }
+
+ /// After a failure: waits for the encode in flight and logs (never throws) a second error.
+ private async Task ObserveEncodingAsync()
+ {
+ try
+ {
+ await FlushEncodingAsync().ConfigureAwait(false);
+ }
+ catch (Exception ex)
+ {
+ Log.Warning(RenderPipeline.LogCategory, "The encoder also failed while the render was stopping", ex);
+ }
+ }
+}
diff --git a/src/Titano.Core/Render/RenderPlan.cs b/src/Titano.Core/Render/RenderPlan.cs
new file mode 100644
index 00000000..6ddc6c1b
--- /dev/null
+++ b/src/Titano.Core/Render/RenderPlan.cs
@@ -0,0 +1,444 @@
+using Titano.Core.Export;
+using Titano.Core.Mathematics;
+using Titano.Core.Project;
+using Titano.Core.Video;
+
+namespace Titano.Core.Render;
+
+[Flags]
+public enum PlannedFrameFlags
+{
+ None = 0,
+
+ /// Synthesised between two included source frames from the motion field.
+ Interpolated = 1,
+
+ /// Shown for more than one output frame period.
+ Held = 2,
+}
+
+/// One output frame of a .
+/// Source frame index; fractional for synthesised frames (it may fall on an excluded frame).
+/// Included source frame at or before the position.
+/// Included source frame after the position; equals for whole frames.
+/// Blend position between (0) and (1); 0 for whole frames.
+/// Presentation time on the 90 kHz clock.
+/// Display duration on the 90 kHz clock.
+/// First output frame period at .
+/// Output frame periods covered (more than one = held).
+/// Source frames advanced per output frame period towards the next planned frame (scales motion blur).
+public readonly record struct PlannedFrame(
+ double SourcePosition,
+ int From,
+ int To,
+ double Fraction,
+ long Start90k,
+ long Duration90k,
+ int StartSlot,
+ int Slots,
+ double Speed,
+ PlannedFrameFlags Flags)
+{
+ public bool IsInterpolated => (Flags & PlannedFrameFlags.Interpolated) != 0;
+
+ public bool IsHeld => (Flags & PlannedFrameFlags.Held) != 0;
+}
+
+/// Rules of the timing modes (documented defaults; BRIEF §11.1).
+public sealed record RenderPlanOptions
+{
+ public static RenderPlanOptions Default { get; } = new();
+
+ /// An interval longer than this multiple of the median capture interval is a gap: Adaptive compresses
+ /// it and motion (blur, synthesis) is treated as discontinuous across it.
+ public double GapFactor { get; init; } = 3;
+
+ /// Adaptive: longest display of a compressed gap, in playback frames (gaps are shown as
+ /// GapFactor + log2(ratio / GapFactor) frames up to this cap).
+ public double MaxGapFrames { get; init; } = 5;
+
+ /// Adaptive: an interval of at least this multiple of the median and is a
+ /// deliberate pause and becomes a fixed visual cut.
+ public double PauseFactor { get; init; } = 20;
+
+ public double MinimumPauseSeconds { get; init; } = 120;
+
+ /// Adaptive: video seconds the frame before a deliberate pause stays on screen.
+ public double PauseCutSeconds { get; init; } = 0.2;
+
+ /// Interpolated: most consecutive missing (or excluded) frames synthesised in one gap; longer gaps are cuts.
+ public int MaxSynthesizedFrames { get; init; } = 3;
+}
+
+/// Figures for the Time tab's plan chart.
+/// Frames in the sequence.
+/// Frames excluded by the user.
+/// Included frames shown whole at least once.
+/// Included frames never shown nor used for synthesis (dropped by speed-ups).
+/// Planned frames (held frames count once).
+/// Output frame periods at the plan frame rate.
+/// Planned frames covering several periods.
+/// Planned frames synthesised between two source frames.
+/// Motion discontinuities (gaps, pauses, long exclusion runs).
+/// Median capture interval, when capture times are known.
+public sealed record RenderPlanStatistics(
+ int SourceFrames,
+ int ExcludedFrames,
+ int ShownFrames,
+ int SkippedFrames,
+ int OutputFrames,
+ int OutputSlots,
+ int HeldFrames,
+ int InterpolatedFrames,
+ int Cuts,
+ double DurationSeconds,
+ double MinimumSpeed,
+ double MaximumSpeed,
+ double? MedianIntervalSeconds);
+
+///
+/// The list of output frames of a render (BRIEF §11.1): every timing mode produces planned frames with a (possibly
+/// fractional) source position and a duration on the output frame grid.
+///
+/// - The playback rate (, default the output rate) is how many source frames
+/// one second of video shows; the output grid is the export frame rate.
+/// - Constant: every included frame lasts one playback frame (whole frames only).
+/// - Adaptive: a frame lasts its capture interval in median intervals; intervals up to
+/// are kept proportional (bursts play faster, small gaps are held), longer gaps are compressed logarithmically and
+/// capped, deliberate pauses become a fixed cut of ; unknown or
+/// non-positive intervals count as one.
+/// - Interpolated: like Constant, but gaps of up to missing or
+/// excluded frames get their periods back with synthesised in-betweens, and slower-than-real-time playback is
+/// synthesised rather than held.
+/// - Remapped: a Fritsch–Carlson monotone spline through maps output time to
+/// source time (both 0–1); fractional positions are synthesised.
+///
+/// rescales the output time axis. Each output period shows one picture
+/// (synthesised stretches sampled at the period start, whole frames at its centre); consecutive periods showing the
+/// same picture merge into one held frame. Durations are differences of the rounded 90 kHz times of period boundaries,
+/// so they add up exactly to the total.
+///
+public sealed class RenderPlan
+{
+ private const double SnapEpsilon = 1e-6;
+ private readonly bool[] _cutBefore;
+ private readonly int[] _includedOrder;
+
+ private RenderPlan(TimingMode mode, Rational frameRate, double playbackRate, PlannedFrame[] frames, int slots, int[] included,
+ bool[] cutBefore, RenderPlanStatistics statistics, IReadOnlyList warnings)
+ {
+ Mode = mode;
+ FrameRate = frameRate;
+ PlaybackRate = playbackRate;
+ Frames = frames;
+ SlotCount = slots;
+ Duration90k = TicksAt(frameRate, slots);
+ IncludedFrames = included;
+ _cutBefore = cutBefore;
+ _includedOrder = new int[cutBefore.Length];
+ Array.Fill(_includedOrder, -1);
+ for (var k = 0; k < included.Length; k++) _includedOrder[included[k]] = k;
+ Statistics = statistics;
+ Warnings = warnings;
+ }
+
+ public TimingMode Mode { get; }
+
+ /// Output frame rate (the grid of every duration).
+ public Rational FrameRate { get; }
+
+ /// Source frames per second of video before fitting.
+ public double PlaybackRate { get; }
+
+ public IReadOnlyList Frames { get; }
+
+ /// Output frame periods covered by the plan.
+ public int SlotCount { get; }
+
+ /// Exact total duration on the 90 kHz clock.
+ public long Duration90k { get; }
+
+ public double DurationSeconds => Duration90k / 90000.0;
+
+ /// Source indices that are not excluded, ascending.
+ public IReadOnlyList IncludedFrames { get; }
+
+ public RenderPlanStatistics Statistics { get; }
+
+ /// Localisation keys of planning remarks (e.g. Adaptive without capture times).
+ public IReadOnlyList Warnings { get; }
+
+ /// True when motion is discontinuous between and the included frame before it.
+ public bool IsCutBefore(int sourceIndex) => _cutBefore[sourceIndex];
+
+ /// The included frame after with continuous motion, or −1.
+ public int NextContinuous(int sourceIndex)
+ {
+ var k = _includedOrder[sourceIndex];
+ if (k < 0 || k + 1 >= IncludedFrames.Count) return -1;
+ var next = IncludedFrames[k + 1];
+ return _cutBefore[next] ? -1 : next;
+ }
+
+ /// The included frame before with continuous motion, or −1.
+ public int PreviousContinuous(int sourceIndex)
+ {
+ var k = _includedOrder[sourceIndex];
+ return k <= 0 || _cutBefore[sourceIndex] ? -1 : IncludedFrames[k - 1];
+ }
+
+ /// Start of output period on the 90 kHz clock, rounded half up.
+ public static long TicksAt(Rational frameRate, long slot) =>
+ (slot * 90000L * frameRate.Denominator * 2 + frameRate.Numerator) / (2L * frameRate.Numerator);
+
+ /// Builds the plan for a sequence.
+ /// Capture time per source frame (clock-corrected when available, e.g.
+ /// LightAnalysisReport.AdjustedTimes); null for unknown.
+ /// Timing settings and excluded frames.
+ /// Output (encoded) frame rate.
+ public static RenderPlan Build(IReadOnlyList captureTimes, ProjectSettings project, Rational frameRate, RenderPlanOptions? options = null)
+ {
+ ArgumentNullException.ThrowIfNull(captureTimes);
+ ArgumentNullException.ThrowIfNull(project);
+ if (frameRate.Numerator <= 0 || frameRate.Denominator <= 0) throw new ArgumentOutOfRangeException(nameof(frameRate));
+ options ??= RenderPlanOptions.Default;
+ var n = captureTimes.Count;
+ var timing = project.Timing;
+ var mode = ProjectValues.Get(timing.Mode, TimingMode.Constant);
+ var warnings = new List();
+ var playbackText = timing.FrameRate.Resolve(string.Empty);
+ var playback = FrameRateText.TryParse(playbackText, out var rate) ? rate.Value : frameRate.Value;
+ if (playbackText.Length > 0 && rate.Numerator == 0) warnings.Add("Export.Plan.FrameRateIgnored");
+
+ var excluded = new bool[n];
+ foreach (var i in project.ExcludedFrames)
+ {
+ if ((uint)i < (uint)n) excluded[i] = true;
+ }
+ var included = new List(n);
+ for (var i = 0; i < n; i++)
+ {
+ if (!excluded[i]) included.Add(i);
+ }
+
+ var median = MedianInterval(captureTimes);
+ if (mode is TimingMode.Adaptive or TimingMode.Interpolated && median is null) warnings.Add("Export.Plan.NoCaptureTimes");
+ var cutBefore = new bool[n];
+ var entries = Timeline(captureTimes, included, mode, playback, median, options, cutBefore);
+ if (entries.Length == 0)
+ {
+ warnings.Add("Export.Plan.NoFrames");
+ var empty = new RenderPlanStatistics(n, n - included.Count, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, median);
+ return new RenderPlan(mode, frameRate, playback, [], 0, [.. included], cutBefore, empty, warnings);
+ }
+
+ var total = entries[^1].Start + entries[^1].Length;
+ var seconds = timing.FitToSeconds is { } fit && fit > 0 ? fit : total / playback;
+ var slots = (int)long.Clamp((long)double.Round(seconds * frameRate.Value), 1, int.MaxValue / 2);
+ var remap = mode == TimingMode.Remapped ? RemapSpline(timing.RemapCurve, warnings) : null;
+
+ var frames = new List();
+ Sample? open = null;
+ var openStart = 0;
+ for (var k = 0; k <= slots; k++)
+ {
+ Sample? sample = null;
+ if (k < slots)
+ {
+ sample = Locate(entries, TimelinePosition(k, slots, total, remap), TimelinePosition(k + 0.5, slots, total, remap), total);
+ if (open is { } current && current.SameAs(sample.Value)) continue;
+ }
+ if (open is { } done) frames.Add(Planned(done, openStart, k - openStart, frameRate));
+ open = sample;
+ openStart = k;
+ }
+
+ var planned = frames.ToArray();
+ AssignSpeeds(planned);
+ var statistics = Summarise(n, n - included.Count, included, planned, slots, cutBefore, frameRate, median);
+ return new RenderPlan(mode, frameRate, playback, planned, slots, [.. included], cutBefore, statistics, warnings);
+ }
+
+ /// A stretch of the playback timeline shown by one included frame.
+ /// Start in playback frames.
+ /// Length in playback frames (> 0).
+ /// Source index shown at the start.
+ /// Next included source index, −1 for the last.
+ /// The position moves linearly towards across the stretch (synthesis).
+ private readonly record struct Entry(double Start, double Length, int Index, int Next, bool Continuous);
+
+ private readonly record struct Sample(int From, int To, double Fraction, double Position)
+ {
+ public bool SameAs(Sample other) => From == other.From && To == other.To && Fraction == other.Fraction;
+ }
+
+ private static Entry[] Timeline(IReadOnlyList times, List included, TimingMode mode, double playback, double? median,
+ RenderPlanOptions options, bool[] cutBefore)
+ {
+ var entries = new Entry[included.Count];
+ double start = 0;
+ for (var k = 0; k < included.Count; k++)
+ {
+ var index = included[k];
+ var next = k + 1 < included.Count ? included[k + 1] : -1;
+ double length = 1;
+ var continuous = false;
+ if (next >= 0)
+ {
+ var seconds = times[index] is { } a && times[next] is { } b ? (b - a).TotalSeconds : double.NaN;
+ var ratio = median is { } m && seconds > 0 ? seconds / m : double.NaN;
+ var steps = next - index;
+ var gap = double.Max(double.IsNaN(ratio) ? steps : ratio, steps) > options.GapFactor;
+ switch (mode)
+ {
+ case TimingMode.Adaptive:
+ length = AdaptiveLength(ratio, seconds, playback, options, ref gap);
+ break;
+ case TimingMode.Interpolated:
+ var periods = int.Max(steps, double.IsNaN(ratio) ? 1 : (int)double.Min(double.Round(ratio), int.MaxValue / 2));
+ gap = periods - 1 > options.MaxSynthesizedFrames;
+ if (!gap)
+ {
+ length = periods;
+ continuous = true;
+ }
+ break;
+ case TimingMode.Remapped:
+ continuous = !gap;
+ break;
+ }
+ cutBefore[next] = gap;
+ }
+ entries[k] = new Entry(start, length, index, next, continuous);
+ start += length;
+ }
+ return entries;
+ }
+
+ private static double AdaptiveLength(double ratio, double seconds, double playback, RenderPlanOptions options, ref bool gap)
+ {
+ if (double.IsNaN(ratio)) return 1;
+ if (ratio <= options.GapFactor) return ratio;
+ gap = true;
+ if (ratio >= options.PauseFactor && seconds >= options.MinimumPauseSeconds) return double.Max(options.PauseCutSeconds * playback, 1e-3);
+ return double.Min(options.MaxGapFrames, options.GapFactor + double.Log2(ratio / options.GapFactor));
+ }
+
+ /// Playback-timeline position of output period (fractional slots address its interior).
+ private static double TimelinePosition(double slot, int slots, double total, MonotoneSpline? remap)
+ {
+ var x = slot / slots;
+ return remap is null ? x * total : double.Clamp(remap.Evaluate(x), 0, 1) * total;
+ }
+
+ ///
+ /// The picture of an output period. Synthesised stretches are sampled at the period start (so equal rates give whole
+ /// frames); whole-frame stretches at the period centre, which rounds every frame boundary to the nearest period
+ /// (ties keep the earlier frame, so a 2× speed-up shows frames 0, 2, 4…).
+ ///
+ private static Sample Locate(Entry[] entries, double start, double centre, double total)
+ {
+ var e = entries[Find(entries, double.Clamp(start, 0, total), atBoundary: true)];
+ if (e.Continuous && e.Next >= 0)
+ {
+ var fraction = double.Clamp((start - e.Start) / e.Length, 0, 1);
+ if (fraction < SnapEpsilon) return new Sample(e.Index, e.Index, 0, e.Index);
+ if (fraction > 1 - SnapEpsilon) return new Sample(e.Next, e.Next, 0, e.Next);
+ return new Sample(e.Index, e.Next, fraction, e.Index + fraction * (e.Next - e.Index));
+ }
+ var index = entries[Find(entries, double.Clamp(centre, 0, total), atBoundary: false)].Index;
+ return new Sample(index, index, 0, index);
+ }
+
+ /// Entry containing ; a position within 1e-9 of a boundary belongs to the entry starting
+ /// there when , else to the one ending there.
+ private static int Find(Entry[] entries, double u, bool atBoundary)
+ {
+ var limit = atBoundary ? u + 1e-9 : u - 1e-9;
+ int lo = 0, hi = entries.Length - 1;
+ while (lo < hi)
+ {
+ var mid = (lo + hi + 1) >> 1;
+ if (atBoundary ? entries[mid].Start <= limit : entries[mid].Start < limit) lo = mid;
+ else hi = mid - 1;
+ }
+ return lo;
+ }
+ private static PlannedFrame Planned(Sample s, int startSlot, int slots, Rational rate)
+ {
+ var start = TicksAt(rate, startSlot);
+ var flags = (s.Fraction > 0 ? PlannedFrameFlags.Interpolated : PlannedFrameFlags.None) | (slots > 1 ? PlannedFrameFlags.Held : PlannedFrameFlags.None);
+ return new PlannedFrame(s.Position, s.From, s.To, s.Fraction, start, TicksAt(rate, startSlot + slots) - start, startSlot, slots, 0, flags);
+ }
+
+ private static void AssignSpeeds(PlannedFrame[] frames)
+ {
+ for (var k = 0; k + 1 < frames.Length; k++)
+ frames[k] = frames[k] with { Speed = (frames[k + 1].SourcePosition - frames[k].SourcePosition) / frames[k].Slots };
+ if (frames.Length > 1) frames[^1] = frames[^1] with { Speed = frames[^2].Speed };
+ else if (frames.Length == 1) frames[0] = frames[0] with { Speed = 1 };
+ }
+
+ /// Sorted, clamped and made non-decreasing so the spline (and the remap) is monotone.
+ private static MonotoneSpline? RemapSpline(IReadOnlyList curve, List warnings)
+ {
+ var points = curve.Where(p => double.IsFinite(p.X) && double.IsFinite(p.Y))
+ .Select(p => (X: double.Clamp(p.X, 0, 1), Y: double.Clamp(p.Y, 0, 1)))
+ .OrderBy(p => p.X)
+ .ToList();
+ if (points.Count == 0) return null;
+ var xs = new List(points.Count);
+ var ys = new List(points.Count);
+ var adjusted = false;
+ foreach (var (x, y) in points)
+ {
+ var value = y;
+ if (ys.Count > 0 && value < ys[^1])
+ {
+ value = ys[^1];
+ adjusted = true;
+ }
+ if (xs.Count > 0 && x == xs[^1])
+ {
+ ys[^1] = double.Max(ys[^1], value);
+ continue;
+ }
+ xs.Add(x);
+ ys.Add(value);
+ }
+ if (adjusted) warnings.Add("Export.Plan.RemapNotMonotonic");
+ return new MonotoneSpline(xs.ToArray(), ys.ToArray());
+ }
+
+ private static double? MedianInterval(IReadOnlyList times)
+ {
+ var intervals = new List(times.Count);
+ for (var i = 1; i < times.Count; i++)
+ {
+ if (times[i - 1] is { } a && times[i] is { } b && b > a) intervals.Add((b - a).TotalSeconds);
+ }
+ return intervals.Count == 0 ? null : Mathematics.Statistics.Median(intervals.ToArray());
+ }
+
+ private static RenderPlanStatistics Summarise(int sourceFrames, int excludedFrames, List included, PlannedFrame[] frames, int slots,
+ bool[] cutBefore, Rational rate, double? median)
+ {
+ var shown = new HashSet();
+ var used = new HashSet();
+ int held = 0, interpolated = 0;
+ double minSpeed = double.PositiveInfinity, maxSpeed = double.NegativeInfinity;
+ foreach (var f in frames)
+ {
+ used.Add(f.From);
+ used.Add(f.To);
+ if (f.Fraction == 0) shown.Add(f.From);
+ if (f.IsHeld) held++;
+ if (f.IsInterpolated) interpolated++;
+ minSpeed = double.Min(minSpeed, f.Speed);
+ maxSpeed = double.Max(maxSpeed, f.Speed);
+ }
+ var cuts = cutBefore.Count(c => c);
+ return new RenderPlanStatistics(sourceFrames, excludedFrames, shown.Count, included.Count - used.Count, frames.Length, slots, held, interpolated,
+ cuts, TicksAt(rate, slots) / 90000.0, frames.Length > 0 ? minSpeed : 0, frames.Length > 0 ? maxSpeed : 0, median);
+ }
+}
diff --git a/src/Titano.Core/Render/RenderPreparation.cs b/src/Titano.Core/Render/RenderPreparation.cs
new file mode 100644
index 00000000..b35316d5
--- /dev/null
+++ b/src/Titano.Core/Render/RenderPreparation.cs
@@ -0,0 +1,459 @@
+using System.Diagnostics;
+using System.Globalization;
+using Titano.Core.Analysis;
+using Titano.Core.Imaging;
+using Titano.Core.Imaging.Geometry;
+using Titano.Core.Motion;
+using Titano.Core.Project;
+
+namespace Titano.Core.Render;
+
+/// Diagnostics of for the editor's measuring tools and the render log.
+public sealed record RenderPreparationReport
+{
+ /// Frames decoded by the preparation pass (0 when cached analysis covered everything needed).
+ public int MeasuredFrames { get; init; }
+
+ public DeflickerDiagnostics? Deflicker { get; init; }
+
+ /// Holy-grail transitions (received and ignored steps).
+ public IReadOnlyList Transitions { get; init; } = [];
+
+ /// Largest frame-to-frame change of the holy-grail target, in EV.
+ public double? MaxTargetStepEv { get; init; }
+
+ public double? ShakeRms { get; init; }
+
+ public RegionMethod? RegionMethod { get; init; }
+
+ public IReadOnlyList Warnings { get; init; } = [];
+}
+
+/// Per-source-frame corrections computed once per render (every array has one entry per source frame).
+public sealed record RenderCorrections
+{
+ public required int FrameCount { get; init; }
+
+ /// Measured log2 luminance (NaN where not measured): the amber curve of the Exposure chart.
+ public required double[] MeasuredLogLuminance { get; init; }
+
+ /// Global exposure correction in EV, including the project's exposure offset.
+ public required double[] ExposureEv { get; init; }
+
+ /// White-balance gains; null when smoothing is off.
+ public ChannelGains[]? WhiteBalance { get; init; }
+
+ /// Sky/land mask; when set, and replace .
+ public RegionMask? Regions { get; init; }
+
+ public double[]? SkyEv { get; init; }
+ public double[]? LandEv { get; init; }
+
+ /// Stabiliser corrections (source → stabilised) in pixels of a -wide frame.
+ public Affine2D[]? Stabilization { get; init; }
+
+ public int StabilizationWidth { get; init; }
+ public int StabilizationHeight { get; init; }
+
+ /// Zoom applied about the centre so stabilisation borders stay outside the picture (1 = none).
+ public double StabilizationZoom { get; init; } = 1;
+
+ public RenderPreparationReport Report { get; init; } = new();
+
+ /// Target log2 luminance (measured + correction): the accent curve of the Exposure chart.
+ public double[] TargetLogLuminance()
+ {
+ var target = new double[FrameCount];
+ for (var i = 0; i < FrameCount; i++) target[i] = MeasuredLogLuminance[i] + ExposureEv[i];
+ return target;
+ }
+
+ /// The stabiliser correction of frame for a frame of ×.
+ public Affine2D StabilizationAt(int index, int width, int height)
+ {
+ if (Stabilization is null) return Affine2D.Identity;
+ var c = Stabilization[index];
+ if (c.IsIdentity() || (width == StabilizationWidth && height == StabilizationHeight)) return c;
+ // Pixel-centre scaling between the two frame sizes: x' = (x + ½)·s − ½.
+ double sx = (double)width / StabilizationWidth, sy = (double)height / StabilizationHeight;
+ var toFrame = new Affine2D(sx, 0, 0, sy, (sx - 1) / 2, (sy - 1) / 2);
+ return toFrame * c * toFrame.Invert();
+ }
+}
+
+///
+/// The pass over the sequence that a render needs before its first frame (BRIEF §11.1–§11.2): luminance, colour and
+/// region series for deflicker / holy grail / white balance / region deflicker, and the stabilisation path. Values the
+/// cached provides are reused; the rest is measured on frames decoded at
+/// one at a time (memory does not grow with the sequence).
+///
+/// - Modules switch on only when their setting resolves to true; Auto without advice changes nothing.
+/// - Deflicker keeps metadata exposure steps (as intentional offsets); holy grail turns the received steps into
+/// ramps (alone, or on top of deflicker); region deflicker gives sky and land their own curves.
+/// - Stabilisation analyses the included frames only and zooms in by 1 / crop scale (at most 1 / 0.75) to hide borders.
+///
+///
+public static class RenderPreparation
+{
+ /// Smallest stabilisation crop scale compensated by zooming; below it borders may show.
+ public const double MinimumCropScale = 0.75;
+
+ /// Region masks below this confidence are not used when the region mode is Auto.
+ public const double MinimumRegionConfidence = 0.3;
+
+ public static async Task PrepareAsync(RenderInput input, RenderOptions? options = null, IProgress? progress = null,
+ CancellationToken cancellationToken = default)
+ {
+ ArgumentNullException.ThrowIfNull(input);
+ options ??= RenderOptions.Default;
+ await Task.CompletedTask.ConfigureAwait(ConfigureAwaitOptions.ForceYielding);
+ var n = input.Source.FrameCount;
+ if (input.Frames.Count != n) throw new ArgumentException("One metadata entry per source frame is required.", nameof(input));
+ var exposure = input.Project.Exposure;
+ var motion = input.Project.Motion;
+ var cached = input.Analysis;
+ var warnings = new List();
+ var included = Included(input.Project.ExcludedFrames, n);
+ var excluded = new bool[n];
+ Array.Fill(excluded, true);
+ foreach (var i in included) excluded[i] = false;
+
+ var deflicker = ProjectValues.Get(exposure.Deflicker, false);
+ var holyGrail = ProjectValues.Get(exposure.HolyGrail, false);
+ var regionMode = deflicker ? ProjectValues.Get(exposure.Regions, RegionMode.Off) : RegionMode.Off;
+ var whiteBalance = ProjectValues.Get(exposure.WhiteBalanceSmoothing, false);
+ var stabilize = ProjectValues.Get(motion.Stabilize, false);
+ var smoothing = ProjectValues.Get(motion.StabilizeSmoothing, new StabilizerOptions().SmoothingSigma);
+
+ var luminance = deflicker || holyGrail ? Valid(cached?.LogLuminance, excluded) : null;
+ var measureLuminance = (deflicker || holyGrail) && luminance is null;
+ double[]? red = null, green = null, blue = null;
+ if (whiteBalance && Valid(cached?.MeanRed, excluded) is { } r && Valid(cached?.MeanGreen, excluded) is { } g && Valid(cached?.MeanBlue, excluded) is { } b)
+ (red, green, blue) = (r, g, b);
+ var measureColour = whiteBalance && red is null;
+ RegionMask? mask = null;
+ double[]? sky = null, land = null;
+ if (regionMode != RegionMode.Off && cached?.Regions is { } m && Valid(cached.SkyLogLuminance, excluded) is { } s && Valid(cached.LandLogLuminance, excluded) is { } l)
+ (mask, sky, land) = (m, s, l);
+ var stabilization = stabilize ? CachedStabilization(cached, n, smoothing) : null;
+ var measureStabilization = stabilize && stabilization is null;
+
+ if (regionMode != RegionMode.Off && mask is null && included.Count > 0)
+ {
+ mask = await SegmentAsync(input.Source, included, regionMode, options.AnalysisLongEdge, cancellationToken).ConfigureAwait(false);
+ if (mask is null) warnings.Add(new RenderWarning("Export.Render.RegionsUnavailable"));
+ else if (regionMode == RegionMode.Auto && mask.Confidence < MinimumRegionConfidence)
+ {
+ warnings.Add(new RenderWarning("Export.Render.RegionsUnreliable", mask.Confidence.ToString("0.00", CultureInfo.InvariantCulture)));
+ mask = null;
+ }
+ }
+ var measureRegions = mask is not null && sky is null;
+
+ var pass = new MeasurementPass(n, measureLuminance, measureColour, measureRegions ? mask : null, measureStabilization, smoothing);
+ if (pass.Needed)
+ {
+ await pass.RunAsync(input.Source, included, options.AnalysisLongEdge, progress, cancellationToken).ConfigureAwait(false);
+ luminance ??= pass.Luminance;
+ red ??= pass.Red;
+ green ??= pass.Green;
+ blue ??= pass.Blue;
+ sky ??= pass.Sky;
+ land ??= pass.Land;
+ if (measureStabilization)
+ {
+ stabilization = pass.SolveStabilization(included, n);
+ if (stabilization is null) warnings.Add(new RenderWarning("Export.Render.StabilizationUnavailable"));
+ }
+ }
+
+ return Combine(input, excluded, luminance, red, green, blue, mask, sky, land, stabilization, deflicker, holyGrail, pass.MeasuredFrames, warnings);
+ }
+
+ private static RenderCorrections Combine(RenderInput input, bool[] excluded, double[]? luminance, double[]? red, double[]? green, double[]? blue, RegionMask? mask,
+ double[]? sky, double[]? land, StabilizationData? stabilization, bool deflicker, bool holyGrail, int measured, List warnings)
+ {
+ var n = input.Source.FrameCount;
+ var exposure = input.Project.Exposure;
+ var ev = new double[n];
+ double[]? skyEv = null, landEv = null;
+ DeflickerDiagnostics? diagnostics = null;
+ HolyGrailResult? hg = null;
+ if (luminance is not null)
+ {
+ var options = new DeflickerOptions
+ {
+ Window = int.Max(3, ProjectValues.Get(exposure.DeflickerWindow, 0) is var w and > 0 ? w : RecommendedWindow(luminance)),
+ Strength = double.Clamp(ProjectValues.Get(exposure.DeflickerStrength, 1.0), 0, 1),
+ };
+ var evs = new double?[n];
+ // Excluded frames (test shots, bumps) must not create exposure steps.
+ for (var i = 0; i < n; i++) evs[i] = excluded[i] ? null : input.Frames[i].ExposureValue;
+ if (holyGrail)
+ {
+ var transition = ProjectValues.Get(exposure.TransitionLength, 0);
+ hg = HolyGrailEngine.Compute(luminance, evs, new HolyGrailOptions { TransitionFrames = transition > 0 ? transition : null, Deflicker = options });
+ }
+ var offsets = hg?.StepOffsets ?? DeflickerEngine.OffsetsFromExposure(evs);
+ if (deflicker && hg is not null)
+ {
+ Array.Copy(hg.CorrectionEv, ev, n);
+ diagnostics = hg.Deflicker.Diagnostics;
+ }
+ else if (deflicker)
+ {
+ var result = DeflickerEngine.Compute(luminance, options, offsets);
+ Array.Copy(result.CorrectionEv, ev, n);
+ diagnostics = result.Diagnostics;
+ }
+ else if (hg is not null)
+ {
+ for (var i = 0; i < n; i++) ev[i] = hg.SmoothedOffsets[i] - hg.StepOffsets[i];
+ }
+ if (mask is not null && sky is not null && land is not null)
+ {
+ var regions = RegionDeflicker.Compute(sky, land, options, offsets);
+ skyEv = new double[n];
+ landEv = new double[n];
+ for (var i = 0; i < n; i++)
+ {
+ var ramp = hg is null ? 0 : hg.SmoothedOffsets[i] - hg.StepOffsets[i];
+ skyEv[i] = regions.Sky.CorrectionEv[i] + ramp + exposure.ExposureOffsetEv;
+ landEv[i] = regions.Land.CorrectionEv[i] + ramp + exposure.ExposureOffsetEv;
+ }
+ }
+ }
+ for (var i = 0; i < n; i++) ev[i] += exposure.ExposureOffsetEv;
+
+ ChannelGains[]? gains = red is not null && green is not null && blue is not null ? WhiteBalanceSmoother.Smooth(red, green, blue).Gains : null;
+ var zoom = 1.0;
+ if (stabilization is not null)
+ {
+ zoom = 1 / double.Max(stabilization.CropScale, MinimumCropScale);
+ if (stabilization.CropScale < MinimumCropScale)
+ warnings.Add(new RenderWarning("Export.Render.StabilizationBorders", stabilization.CropScale.ToString("0.00", CultureInfo.InvariantCulture)));
+ }
+ var measuredLuminance = luminance ?? NaNs(n);
+ return new RenderCorrections
+ {
+ FrameCount = n,
+ MeasuredLogLuminance = measuredLuminance,
+ ExposureEv = ev,
+ WhiteBalance = gains,
+ Regions = skyEv is null ? null : mask,
+ SkyEv = skyEv,
+ LandEv = landEv,
+ Stabilization = stabilization?.Corrections,
+ StabilizationWidth = stabilization?.Width ?? 0,
+ StabilizationHeight = stabilization?.Height ?? 0,
+ StabilizationZoom = zoom,
+ Report = new RenderPreparationReport
+ {
+ MeasuredFrames = measured,
+ Deflicker = diagnostics,
+ Transitions = hg?.Transitions ?? [],
+ MaxTargetStepEv = hg?.MaxFrameStepEv,
+ ShakeRms = stabilization?.ShakeRms,
+ RegionMethod = skyEv is null ? null : mask!.Method,
+ Warnings = warnings,
+ },
+ };
+ }
+
+ /// Corrections for every source frame (identity for excluded ones) with the frame size they are measured in.
+ private sealed record StabilizationData(Affine2D[] Corrections, int Width, int Height, double CropScale, double ShakeRms);
+
+ private static StabilizationData? CachedStabilization(PrecomputedAnalysis? cached, int n, double smoothing)
+ {
+ if (cached?.Stabilization is not { } result || result.Corrections.Count != n || cached.StabilizationWidth <= 0 || cached.StabilizationHeight <= 0
+ || double.Abs(cached.StabilizationSmoothing - smoothing) > 1e-9) return null;
+ return new StabilizationData([.. result.Corrections], cached.StabilizationWidth, cached.StabilizationHeight, result.CropScale, result.ShakeRms);
+ }
+
+ private static int RecommendedWindow(double[] luminance)
+ {
+ var finite = luminance.Where(double.IsFinite).ToArray();
+ return finite.Length >= 16 ? FlickerSpectrum.Analyze(finite).RecommendedWindow : DeflickerOptions.Default.Window;
+ }
+
+ private static List Included(IReadOnlyList excluded, int n)
+ {
+ var skip = new bool[n];
+ foreach (var i in excluded)
+ {
+ if ((uint)i < (uint)n) skip[i] = true;
+ }
+ var result = new List(n);
+ for (var i = 0; i < n; i++)
+ {
+ if (!skip[i]) result.Add(i);
+ }
+ return result;
+ }
+
+ /// A copy of a cached series with excluded frames marked unusable, or null when it does not fit the sequence.
+ private static double[]? Valid(double[]? values, bool[] excluded)
+ {
+ if (values is null || values.Length != excluded.Length) return null;
+ var copy = (double[])values.Clone();
+ for (var i = 0; i < copy.Length; i++)
+ {
+ if (excluded[i]) copy[i] = double.NaN;
+ }
+ return copy;
+ }
+
+ private static double[] NaNs(int n)
+ {
+ var values = new double[n];
+ Array.Fill(values, double.NaN);
+ return values;
+ }
+
+ private static async Task SegmentAsync(IRenderFrameSource source, List included, RegionMode mode, int longEdge, CancellationToken cancellationToken)
+ {
+ var options = new RegionSegmenterOptions
+ {
+ // Horizon mode accepts any detected horizon; Luminance mode lets the horizon win only when it is more confident.
+ MinimumHorizonConfidence = mode switch { RegionMode.Horizon => 0, RegionMode.Luminance => 2, _ => RegionSegmenterOptions.Default.MinimumHorizonConfidence },
+ };
+ var count = int.Min(options.MaxFrames, included.Count);
+ var frames = new List(count);
+ try
+ {
+ for (var k = 0; k < count; k++)
+ {
+ var index = included[(int)((long)k * (included.Count - 1) / int.Max(1, count - 1))];
+ var frame = await source.GetFrameAsync(index, longEdge, DecodePurpose.Analysis, cancellationToken).ConfigureAwait(false);
+ frames.Add(frames.Count == 0 ? frame : Conform(frame, frames[0].Width, frames[0].Height));
+ }
+ return frames[0].Height < 8 ? null : RegionSegmenter.Segment(frames, options);
+ }
+ finally
+ {
+ foreach (var f in frames) f.Dispose();
+ }
+ }
+
+ /// Resizes to the given size (disposing it) when a source returns frames of varying size.
+ internal static ImageBuffer Conform(ImageBuffer frame, int width, int height)
+ {
+ if (frame.Width == width && frame.Height == height) return frame;
+ try
+ {
+ return Resampler.Resize(frame, width, height);
+ }
+ finally
+ {
+ frame.Dispose();
+ }
+ }
+
+ /// One sequential pass that measures whatever the cache did not provide.
+ private sealed class MeasurementPass(int n, bool luminance, bool colour, RegionMask? regions, bool stabilization, double smoothing)
+ {
+ public bool Needed => luminance || colour || regions is not null || stabilization;
+ public int MeasuredFrames { get; private set; }
+ public double[]? Luminance { get; } = luminance ? NaNs(n) : null;
+ public double[]? Red { get; } = colour ? NaNs(n) : null;
+ public double[]? Green { get; } = colour ? NaNs(n) : null;
+ public double[]? Blue { get; } = colour ? NaNs(n) : null;
+ public double[]? Sky { get; } = regions is not null ? NaNs(n) : null;
+ public double[]? Land { get; } = regions is not null ? NaNs(n) : null;
+ private Stabilizer? _stabilizer;
+
+ public async Task RunAsync(IRenderFrameSource source, List included, int longEdge, IProgress? progress, CancellationToken cancellationToken)
+ {
+ var clock = Stopwatch.StartNew();
+ RegionMask? fitted = null;
+ var stabilize = stabilization;
+ try
+ {
+ foreach (var index in included)
+ {
+ cancellationToken.ThrowIfCancellationRequested();
+ var frame = await source.GetFrameAsync(index, longEdge, DecodePurpose.Analysis, cancellationToken).ConfigureAwait(false);
+ using (frame)
+ {
+ if (Luminance is not null) Luminance[index] = FrameStatistics.MeasureLogLuminance(frame);
+ if (Red is not null) (Red[index], Green![index], Blue![index]) = Means(frame);
+ if (regions is not null && Sky is not null)
+ {
+ if (fitted is null || fitted.Width != frame.Width || fitted.Height != frame.Height) fitted = regions.Resample(frame.Width, frame.Height);
+ (Sky[index], Land![index]) = RegionDeflicker.Measure(frame, fitted);
+ }
+ if (stabilize) stabilize = AddToStabilizer(frame);
+ }
+ MeasuredFrames++;
+ if (progress is not null)
+ {
+ var elapsed = clock.Elapsed;
+ var fps = MeasuredFrames / double.Max(elapsed.TotalSeconds, 1e-6);
+ progress.Report(new RenderProgress(RenderStage.Preparing, MeasuredFrames, included.Count, fps, elapsed,
+ TimeSpan.FromSeconds((included.Count - MeasuredFrames) / fps)));
+ }
+ }
+ }
+ catch
+ {
+ _stabilizer?.Dispose();
+ _stabilizer = null;
+ throw;
+ }
+ if (!stabilize)
+ {
+ _stabilizer?.Dispose();
+ _stabilizer = null;
+ }
+ }
+
+ /// False when the frames are too small to stabilise.
+ private bool AddToStabilizer(ImageBuffer frame)
+ {
+ if (_stabilizer is null)
+ {
+ if (frame.Width < 16 || frame.Height < 16) return false;
+ _stabilizer = new Stabilizer(frame.Width, frame.Height, new StabilizerOptions { SmoothingSigma = smoothing });
+ }
+ if (frame.Width == _stabilizer.Width && frame.Height == _stabilizer.Height)
+ {
+ _stabilizer.AddFrame(frame);
+ return true;
+ }
+ using var resized = Resampler.Resize(frame, _stabilizer.Width, _stabilizer.Height);
+ _stabilizer.AddFrame(resized);
+ return true;
+ }
+
+ public StabilizationData? SolveStabilization(List included, int frameCount)
+ {
+ var stabilizer = _stabilizer;
+ _stabilizer = null;
+ if (stabilizer is null) return null;
+ using (stabilizer)
+ {
+ if (stabilizer.FrameCount == 0) return null;
+ var result = stabilizer.Solve();
+ var corrections = new Affine2D[frameCount];
+ Array.Fill(corrections, Affine2D.Identity);
+ for (var k = 0; k < included.Count; k++) corrections[included[k]] = result.Corrections[k];
+ return new StabilizationData(corrections, stabilizer.Width, stabilizer.Height, result.CropScale, result.ShakeRms);
+ }
+ }
+
+ private static (double R, double G, double B) Means(ImageBuffer image)
+ {
+ var count = image.PlaneLength;
+ var r = Sum(image.Plane(0)) / count;
+ if (image.Channels < 3) return (r, r, r);
+ return (r, Sum(image.Plane(1)) / count, Sum(image.Plane(2)) / count);
+ }
+
+ private static double Sum(ReadOnlySpan values)
+ {
+ double sum = 0;
+ foreach (var v in values) sum += v;
+ return sum;
+ }
+ }
+}
diff --git a/src/Titano.Core/Render/RenderResult.cs b/src/Titano.Core/Render/RenderResult.cs
new file mode 100644
index 00000000..cd244ff3
--- /dev/null
+++ b/src/Titano.Core/Render/RenderResult.cs
@@ -0,0 +1,71 @@
+using Titano.Core.Export;
+using Titano.Core.Video;
+
+namespace Titano.Core.Render;
+
+/// A finished render, for the render history and the database ().
+public sealed record RenderResult
+{
+ /// The output file, or folder for image sequences.
+ public required string OutputPath { get; init; }
+
+ /// Effective preset id (or ).
+ public required string PresetId { get; init; }
+
+ public required VideoCodec Codec { get; init; }
+ public ContainerFormat Container => VideoCodecInfo.DefaultContainer(Codec);
+ public required int Width { get; init; }
+ public required int Height { get; init; }
+ public required Rational FrameRate { get; init; }
+ public required double DurationSeconds { get; init; }
+
+ /// Output pictures rendered (held frames count once).
+ public required int FrameCount { get; init; }
+
+ /// Size of the file, or of every file of a sequence.
+ public required long Bytes { get; init; }
+
+ public required string EncoderName { get; init; }
+ public required bool Hardware { get; init; }
+ public required TimeSpan Elapsed { get; init; }
+
+ /// Plan, geometry, encoder and preparation remarks.
+ public IReadOnlyList Warnings { get; init; } = [];
+
+ /// The render-history entity.
+ /// Display name of the preset at render time.
+ /// The project settings used ().
+ /// Client or render-node name.
+ public Model.Render ToEntity(Guid sequenceId, string presetName, string? settingsJson, string? producedBy) => new()
+ {
+ Id = Guid.CreateVersion7(),
+ SequenceId = sequenceId,
+ PresetName = presetName,
+ SettingsJson = settingsJson,
+ OutputPath = OutputPath,
+ Codec = Codec.ToString(),
+ Width = Width,
+ Height = Height,
+ Fps = FrameRate.Value,
+ DurationSeconds = DurationSeconds,
+ Bytes = Bytes,
+ Created = DateTimeOffset.UtcNow,
+ ProducedBy = producedBy,
+ };
+
+ /// Bytes of a file, or the total of the files in a folder.
+ internal static long SizeOf(string path)
+ {
+ if (File.Exists(path)) return new FileInfo(path).Length;
+ if (!Directory.Exists(path)) return 0;
+ long total = 0;
+ foreach (var file in new DirectoryInfo(path).EnumerateFiles("*", SearchOption.AllDirectories)) total += file.Length;
+ return total;
+ }
+}
+
+/// Outcome of one target of : a result or the failure that stopped it.
+public sealed record BatchItemResult(RenderTarget Target, RenderResult? Result, Exception? Error)
+{
+ public bool Succeeded => Result is not null;
+}
diff --git a/src/Titano.Core/Render/RenderSetup.cs b/src/Titano.Core/Render/RenderSetup.cs
new file mode 100644
index 00000000..ae6e1d2b
--- /dev/null
+++ b/src/Titano.Core/Render/RenderSetup.cs
@@ -0,0 +1,83 @@
+using Titano.Core.Export;
+using Titano.Core.Project;
+using Titano.Core.Video;
+
+namespace Titano.Core.Render;
+
+///
+/// What a render will do, decided before its first frame: output geometry, encoder (with its adjustments) and plan.
+/// The Export tab uses it for the output size, encoder notices, plan chart and estimates.
+///
+public sealed record RenderSetup
+{
+ public required RenderTarget Target { get; init; }
+ public required RenderGeometry Geometry { get; init; }
+ public required EncoderSelection Encoder { get; init; }
+ public required RenderPlan Plan { get; init; }
+
+ /// Synthetic motion blur applies (it is off while stacking).
+ public bool MotionBlur { get; init; }
+
+ /// The preparation pass decodes frames (no corrections were supplied and a module needs measurements).
+ public bool NeedsPreparation { get; init; }
+
+ /// Geometry, plan and encoder remarks.
+ public IReadOnlyList Warnings { get; init; } = [];
+
+ /// Decides geometry, encoder and plan for one target.
+ /// Prepared corrections when available (their stabilisation zoom affects the decode size).
+ public static RenderSetup Create(RenderInput input, RenderTarget target, IReadOnlyList encoders, EncoderHost host,
+ RenderOptions? options = null, RenderCorrections? corrections = null)
+ {
+ ArgumentNullException.ThrowIfNull(input);
+ ArgumentNullException.ThrowIfNull(target);
+ ArgumentNullException.ThrowIfNull(encoders);
+ options ??= RenderOptions.Default;
+ if (input.Frames.Count != input.Source.FrameCount) throw new ArgumentException("One metadata entry per source frame is required.", nameof(input));
+ var project = input.Project;
+ var geometry = RenderGeometry.Create(project.Camera, target.Export, input.Source.Width, input.Source.Height,
+ corrections?.StabilizationZoom ?? 1, options.MaxWorkingLongEdge);
+ var selection = EncoderSelector.Select(target.Export.ToEncodeSettings(target.OutputPath, geometry.OutputWidth, geometry.OutputHeight), encoders, host);
+ geometry = geometry.WithOutputSize(selection.Settings.Width, selection.Settings.Height);
+ var times = new DateTime?[input.Frames.Count];
+ for (var i = 0; i < times.Length; i++) times[i] = input.Frames[i].CapturedAt;
+ var plan = RenderPlan.Build(times, project, selection.Settings.FrameRate, options.Plan);
+
+ var warnings = new List(geometry.Warnings);
+ warnings.AddRange(plan.Warnings.Select(k => new RenderWarning(k)));
+ warnings.AddRange(selection.Notices.Select(n => new RenderWarning(n.Key, n.Args)));
+ var stacking = project.Stack.Mode != StackSetting.None;
+ var blur = ProjectValues.Get(project.Motion.MotionBlur, false);
+ if (blur && stacking) warnings.Add(new RenderWarning("Export.Render.BlurOffWhileStacking"));
+ var exposure = project.Exposure;
+ var measuring = ProjectValues.Get(exposure.Deflicker, false) || ProjectValues.Get(exposure.HolyGrail, false)
+ || ProjectValues.Get(exposure.WhiteBalanceSmoothing, false) || ProjectValues.Get(project.Motion.Stabilize, false);
+ return new RenderSetup
+ {
+ Target = target,
+ Geometry = geometry,
+ Encoder = selection,
+ Plan = plan,
+ MotionBlur = blur && !stacking,
+ NeedsPreparation = corrections is null && measuring,
+ Warnings = warnings,
+ };
+ }
+
+ /// The render's workload in the units of .
+ public ExportWorkload Workload()
+ {
+ var edge = Geometry.WorkingLongEdge;
+ var shortEdge = (long)double.Round(edge * (double)int.Min(Geometry.SourceWidth, Geometry.SourceHeight) / int.Max(Geometry.SourceWidth, Geometry.SourceHeight));
+ var flowFrames = MotionBlur ? Plan.Frames.Count : Plan.Statistics.InterpolatedFrames;
+ return new ExportWorkload(Plan.Frames.Count, Plan.SlotCount, Plan.DurationSeconds, Geometry.OutputWidth, Geometry.OutputHeight, edge * shortEdge,
+ flowFrames, NeedsPreparation ? Plan.IncludedFrames.Count : 0, Encoder.Capability?.Hardware ?? false);
+ }
+
+ /// Size and time estimates for the values the encoder will actually use.
+ public ExportEstimate Estimate(ThroughputModel? model = null)
+ {
+ var s = Encoder.Settings;
+ return ExportEstimator.Estimate(Target.Export with { Codec = s.Codec, BitRate = s.BitRate, BitDepth = s.BitDepth, Quality = s.Quality }, Workload(), model);
+ }
+}
diff --git a/src/Titano.Core/Video/Managed/ManagedEncoderProvider.cs b/src/Titano.Core/Video/Managed/ManagedEncoderProvider.cs
new file mode 100644
index 00000000..f2b604bb
--- /dev/null
+++ b/src/Titano.Core/Video/Managed/ManagedEncoderProvider.cs
@@ -0,0 +1,64 @@
+namespace Titano.Core.Video.Managed;
+
+///
+/// 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 ;
+/// 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.
+///
+public sealed class ManagedEncoderProvider : IVideoEncoderProvider
+{
+ public const string ProviderName = "managed";
+
+ /// Largest width or height of any managed output (JPEG, GIF and AVI headers use 16-bit sizes).
+ public const int MaxDimension = 65535;
+
+ public string Name => ProviderName;
+
+ public IReadOnlyList 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),
+ ];
+
+ /// Bit depths each managed codec writes.
+ public static IReadOnlyList 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;
+ }
+}
diff --git a/src/Titano.Core/Video/Managed/ManagedSessions.cs b/src/Titano.Core/Video/Managed/ManagedSessions.cs
new file mode 100644
index 00000000..36efb605
--- /dev/null
+++ b/src/Titano.Core/Video/Managed/ManagedSessions.cs
@@ -0,0 +1,301 @@
+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;
+
+/// Lifecycle shared by the managed sessions: validation, completion, and deletion of partial output on dispose.
+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);
+
+ /// Finishes the container and moves it to .
+ protected abstract void Commit();
+
+ /// Closes and deletes everything written so far.
+ 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,
+ };
+}
+
+/// 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).
+internal sealed class ConstantRateClock(Rational frameRate)
+{
+ private long _ticks;
+ private long _periods;
+
+ /// Periods the next frame of ticks occupies (0 when it is shorter than the grid allows).
+ 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;
+ }
+}
+
+/// A single output file written to a temporary sibling and renamed into place.
+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();
+}
+
+///
+/// Numbered image files (<folder name>_000001.ext, 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. Frames are
+/// independent, so several are encoded at once (each single-threaded, at most one per core): PNG's Deflate would
+/// otherwise run on one core. A failed encode surfaces on a later or on
+/// .
+///
+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 readonly Queue _inFlight = new();
+ private readonly int _maxInFlight = int.Clamp(Environment.ProcessorCount, 1, 8);
+ 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);
+ }
+
+ /// File name of the 1-based frame inside a sequence folder named .
+ 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;
+ while (_inFlight.Count >= _maxInFlight) _inFlight.Dequeue().GetAwaiter().GetResult();
+ var first = _index + 1;
+ _index += repeats;
+ var copy = frame.Clone();
+ _inFlight.Enqueue(Task.Run(() =>
+ {
+ byte[] bytes;
+ using (copy) bytes = Encode(copy);
+ for (var number = first; number < first + repeats; number++)
+ {
+ using var file = new FileStream(Path.Combine(_temp, FrameName(_stem, number, _extension)), FileMode.CreateNew, FileAccess.Write, FileShare.None, 1 << 16);
+ file.Write(bytes);
+ file.Flush(flushToDisk: true);
+ }
+ }));
+ }
+
+ protected override void Commit()
+ {
+ while (_inFlight.Count > 0) _inFlight.Dequeue().GetAwaiter().GetResult();
+ Directory.Move(_temp, _folder);
+ }
+
+ protected override void Discard()
+ {
+ // Every encode must have stopped writing before the folder goes; their failures are already superseded.
+ while (_inFlight.Count > 0)
+ {
+ try
+ {
+ _inFlight.Dequeue().GetAwaiter().GetResult();
+ }
+ catch (Exception ex)
+ {
+ Log.Warning(LogCategory, "A sequence frame failed while the encode was being discarded", ex);
+ }
+ }
+ 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);
+ }
+ }
+
+ /// One frame, single-threaded (frames are encoded concurrently).
+ private byte[] Encode(ImageBuffer frame) => Settings.Codec switch
+ {
+ VideoCodec.JpegSequence => JpegEncoder.Encode(frame, JpegOptions(Settings.Quality) with { MaxDegreeOfParallelism = 1 }),
+ 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, MaxDegreeOfParallelism = 1 }),
+ // Tiles no larger than the frame: edge padding of a 256-pixel tile would dominate small outputs.
+ VideoCodec.LinearDngSequence => LinearDngWriter.Write(frame,
+ new LinearDngOptions { TileSize = int.Clamp((int.Max(frame.Width, frame.Height) + 15) / 16 * 16, 16, 256), MaxDegreeOfParallelism = 1 }),
+ _ => throw new NotSupportedException($"{Settings.Codec} is not an image sequence"),
+ };
+}
diff --git a/src/Titano.Tools/Commands/SelfTestCommand.cs b/src/Titano.Tools/Commands/SelfTestCommand.cs
new file mode 100644
index 00000000..3189f769
--- /dev/null
+++ b/src/Titano.Tools/Commands/SelfTestCommand.cs
@@ -0,0 +1,79 @@
+using System.Diagnostics;
+using System.Globalization;
+using Titano.Core.Diagnostics;
+using Titano.Core.Render.Diagnostics;
+
+namespace Titano.Tools.Commands;
+
+///
+/// selftest [prefix…] [--filter prefix] [--list]: the engine's end-to-end self-test (BRIEF §20.2, §20.4) with
+/// the managed encoders. Prints a PASS/FAIL table; exits 1 when a check fails, 2 when no check matched.
+///
+internal sealed class SelfTestCommand : ICommand
+{
+ public string Name => "selftest";
+ public string Summary => "Render synthetic sequences end to end and verify the outputs";
+
+ public async Task RunAsync(string[] args)
+ {
+ var a = new Args(args, "list");
+ var filters = a.Positional.ToList();
+ if (a.Get("filter") is { } filter) filters.Add(filter);
+ if (a.Has("list"))
+ {
+ foreach (var check in SelfTest.Checks) Console.WriteLine($"{check.Id,-26} {check.Description}");
+ return 0;
+ }
+
+ using var cts = new CancellationTokenSource();
+ ConsoleCancelEventHandler cancel = (_, e) =>
+ {
+ e.Cancel = true;
+ cts.Cancel();
+ };
+ Console.CancelKeyPress += cancel;
+ // Expected failures (fault injection, render-node notices) are logged by the engine; the table says enough.
+ var level = Log.MinimumLevel;
+ Log.MinimumLevel = LogLevel.Error;
+ try
+ {
+ var clock = Stopwatch.StartNew();
+ Console.WriteLine($"{"RESULT",-6} {"CHECK",-26} {"TIME",8} DETAIL");
+ var results = await SelfTest.RunAsync(new SelfTestOptions { Filters = filters }, new ConsoleRows(), cts.Token);
+ var passed = results.Count(r => r.Outcome == SelfTestOutcome.Passed);
+ var failed = results.Count(r => r.Outcome == SelfTestOutcome.Failed);
+ var skipped = results.Count(r => r.Outcome == SelfTestOutcome.Skipped);
+ Console.WriteLine(string.Create(CultureInfo.InvariantCulture,
+ $"{(failed == 0 ? "PASSED" : "FAILED")} {results.Count} checks: {passed} passed, {failed} failed, {skipped} skipped in {clock.Elapsed.TotalSeconds:F1} s"));
+ if (results.Count == 0) return 2;
+ return failed == 0 ? 0 : 1;
+ }
+ catch (OperationCanceledException) when (cts.IsCancellationRequested)
+ {
+ Console.Error.WriteLine("Self-test cancelled.");
+ return 2;
+ }
+ finally
+ {
+ Log.MinimumLevel = level;
+ Console.CancelKeyPress -= cancel;
+ }
+ }
+
+ /// Prints each result as soon as its check finishes.
+ private sealed class ConsoleRows : IProgress
+ {
+ public void Report(SelfTestResult r)
+ {
+ var label = r.Outcome switch
+ {
+ SelfTestOutcome.Passed => "PASS",
+ SelfTestOutcome.Failed => "FAIL",
+ _ => "SKIP",
+ };
+ var line = string.Create(CultureInfo.InvariantCulture, $"{label,-6} {r.Id,-26} {r.Elapsed.TotalMilliseconds,6:F0} ms {r.Detail}");
+ if (r.Outcome == SelfTestOutcome.Failed) Console.Error.WriteLine(line);
+ else Console.WriteLine(line);
+ }
+ }
+}
diff --git a/src/Titano.Tools/Program.cs b/src/Titano.Tools/Program.cs
index 78f6e44d..6bf7af38 100644
--- a/src/Titano.Tools/Program.cs
+++ b/src/Titano.Tools/Program.cs
@@ -9,6 +9,7 @@ var commands = new ICommand[]
new PackageGuardCommand(),
new ChangelogCommand(),
new PackInstallerCommand(),
+ new SelfTestCommand(),
};
if (args.Length == 0 || args[0] is "-h" or "--help" or "help")
diff --git a/tests/Titano.Core.Tests/Export/EncoderSelectorTests.cs b/tests/Titano.Core.Tests/Export/EncoderSelectorTests.cs
new file mode 100644
index 00000000..31af272f
--- /dev/null
+++ b/tests/Titano.Core.Tests/Export/EncoderSelectorTests.cs
@@ -0,0 +1,146 @@
+using Titano.Core.Export;
+using Titano.Core.Tests.Render;
+using Titano.Core.Video;
+using Titano.Core.Video.Managed;
+using Titano.Testing;
+
+namespace Titano.Core.Tests.Export;
+
+public sealed class EncoderSelectorTests
+{
+ private static readonly EncoderCapability SoftwareH264 = new(VideoCodec.H264, "Microsoft H.264", false, 4096, 2304, false);
+ private static readonly EncoderCapability HardwareH264 = new(VideoCodec.H264, "NVENC H.264", true, 4096, 4096, false, "NVIDIA");
+ private static readonly EncoderCapability HardwareHevc = new(VideoCodec.Hevc, "NVENC HEVC", true, 8192, 8192, true, "NVIDIA");
+ private static readonly EncoderCapability HardwareHevc8 = new(VideoCodec.Hevc, "QSV HEVC", true, 8192, 8192, false, "Intel");
+
+ private static EncodeSettings Request(VideoCodec codec, int width = 3840, int height = 2160, int bitDepth = 8, long bitRate = 20_000_000, Rational? fps = null) => new()
+ {
+ OutputPath = "/exports/out" + VideoCodecInfo.FileExtension(codec),
+ Codec = codec,
+ Width = width,
+ Height = height,
+ FrameRate = fps ?? new Rational(30, 1),
+ BitDepth = bitDepth,
+ BitRate = bitRate,
+ Profile = bitDepth == 10 ? CodecProfile.HevcMain10 : CodecProfile.Auto,
+ };
+
+ private static IVideoEncoderProvider[] Client(params EncoderCapability[] capabilities) =>
+ [new CapturingEncoderProvider("Media Foundation", capabilities), new ManagedEncoderProvider()];
+
+ [Test]
+ public void ManagedCodecsUseTheManagedProviderEverywhere()
+ {
+ foreach (var host in new[] { EncoderHost.Client, EncoderHost.Server })
+ {
+ var selection = EncoderSelector.Select(Request(VideoCodec.Mjpeg, bitDepth: 8), Client(HardwareH264), host);
+ Assert.True(selection.IsReady);
+ Assert.Equal(ManagedEncoderProvider.ProviderName, selection.Provider!.Name);
+ Assert.Equal("Managed MJPEG", selection.Capability!.Name);
+ Assert.Empty(selection.Notices);
+ }
+ }
+
+ [Test]
+ public void ManagedBitDepthsAreAdjustedWithANotice()
+ {
+ var png = EncoderSelector.Select(Request(VideoCodec.PngSequence, bitDepth: 10), [new ManagedEncoderProvider()], EncoderHost.Server);
+ Assert.Equal(16, png.Settings.BitDepth);
+ Assert.Equal(EncoderNotices.BitDepthAdjusted, png.Notices.Single().Key);
+ Assert.SequenceEqual(new[] { "10", "16" }, png.Notices.Single().Args);
+ var jpeg = EncoderSelector.Select(Request(VideoCodec.JpegSequence, bitDepth: 16), [new ManagedEncoderProvider()], EncoderHost.Server);
+ Assert.Equal(8, jpeg.Settings.BitDepth);
+ }
+
+ [Test]
+ public void ServerNeedsARenderNodeForMp4()
+ {
+ var selection = EncoderSelector.Select(Request(VideoCodec.H264), [new ManagedEncoderProvider()], EncoderHost.Server);
+ Assert.Equal(EncoderSelectionStatus.NeedsRenderNode, selection.Status);
+ Assert.Null(selection.Provider);
+ Assert.Equal(EncoderNotices.NeedsRenderNode, selection.Notices.Single().Key);
+ Assert.Throws(() => selection.Open());
+ }
+
+ [Test]
+ public void HardwareIsPreferredUnlessSoftwareIsAsked()
+ {
+ var providers = Client(SoftwareH264, HardwareH264);
+ var hardware = EncoderSelector.Select(Request(VideoCodec.H264), providers, EncoderHost.Client);
+ Assert.True(hardware.IsReady);
+ Assert.Equal("NVENC H.264", hardware.Capability!.Name);
+ Assert.Empty(hardware.Notices);
+ Assert.Equal(new CodecLevel(VideoCodec.H264, 5, 1), hardware.Level);
+
+ var software = EncoderSelector.Select(Request(VideoCodec.H264) with { PreferHardware = false }, providers, EncoderHost.Client);
+ Assert.Equal("Microsoft H.264", software.Capability!.Name);
+
+ var named = EncoderSelector.Select(Request(VideoCodec.H264) with { EncoderName = "Microsoft H.264" }, providers, EncoderHost.Client);
+ Assert.Equal("Microsoft H.264", named.Capability!.Name);
+ Assert.Equal(EncoderNotices.SoftwareOnly, named.Notices.Single().Key);
+ }
+
+ [Test]
+ public void HevcFallsBackToH264WhenNoEncoderExists()
+ {
+ var selection = EncoderSelector.Select(Request(VideoCodec.Hevc, bitDepth: 10, bitRate: 14_000_000), Client(SoftwareH264), EncoderHost.Client);
+ Assert.True(selection.IsReady);
+ Assert.Equal(VideoCodec.H264, selection.Settings.Codec);
+ Assert.Equal(8, selection.Settings.BitDepth);
+ Assert.Equal(CodecProfile.H264High, selection.Settings.Profile);
+ Assert.Equal(20_000_000L, selection.Settings.BitRate);
+ Assert.Equal(EncoderNotices.FallbackToH264, selection.Notices[0].Key);
+ Assert.SequenceEqual(new[] { "Hevc" }, selection.Notices[0].Args);
+ Assert.Contains(selection.Notices, n => n.Key == EncoderNotices.SoftwareOnly);
+ Assert.Equal(".mp4", Path.GetExtension(selection.Settings.OutputPath));
+ }
+
+ [Test]
+ public void TenBitNeedsATenBitEncoder()
+ {
+ var eightOnly = EncoderSelector.Select(Request(VideoCodec.Hevc, bitDepth: 10), Client(HardwareHevc8), EncoderHost.Client);
+ Assert.Equal(8, eightOnly.Settings.BitDepth);
+ Assert.Equal(CodecProfile.HevcMain, eightOnly.Settings.Profile);
+ Assert.Equal(EncoderNotices.TenBitUnavailable, eightOnly.Notices.Single().Key);
+
+ var tenBit = EncoderSelector.Select(Request(VideoCodec.Hevc, bitDepth: 10), Client(HardwareHevc8, HardwareHevc), EncoderHost.Client);
+ Assert.Equal("NVENC HEVC", tenBit.Capability!.Name);
+ Assert.Equal(10, tenBit.Settings.BitDepth);
+ Assert.Empty(tenBit.Notices);
+ }
+
+ [Test]
+ public void SizeIsCappedByEncoderAndLevel()
+ {
+ var encoder = EncoderSelector.Select(Request(VideoCodec.H264, 7680, 4320), Client(HardwareH264), EncoderHost.Client);
+ Assert.Equal((4096, 2304), (encoder.Settings.Width, encoder.Settings.Height));
+ Assert.Equal(EncoderNotices.ResolutionCappedByEncoder, encoder.Notices.Single().Key);
+ Assert.SequenceEqual(new[] { "NVENC H.264", "4096×2304" }, encoder.Notices.Single().Args);
+
+ var level = EncoderSelector.Select(Request(VideoCodec.Hevc, 7680, 4320, fps: new Rational(240, 1)), Client(HardwareHevc), EncoderHost.Client);
+ Assert.Equal(EncoderNotices.ResolutionCappedByLevel, level.Notices[0].Key);
+ Assert.Less(level.Settings.Width, 7680);
+ Assert.Equal(0, level.Settings.Width % 2);
+ Assert.Approximately(16.0 / 9, level.Settings.Width / (double)level.Settings.Height, 0.01);
+ Assert.True(CodecLimits.Check(VideoCodec.Hevc, level.Settings.Width, level.Settings.Height, 240, level.Settings.BitRate).Fits);
+
+ var odd = EncoderSelector.Select(Request(VideoCodec.H264, 1081, 607), Client(HardwareH264), EncoderHost.Client);
+ Assert.Equal((1080, 606), (odd.Settings.Width, odd.Settings.Height));
+ }
+
+ [Test]
+ public void BitRateIsCappedByTheHighestLevel()
+ {
+ var selection = EncoderSelector.Select(Request(VideoCodec.H264, 1920, 1080, bitRate: 2_000_000_000), Client(HardwareH264), EncoderHost.Client);
+ Assert.Equal(1_000_000_000L, selection.Settings.BitRate);
+ Assert.Equal(EncoderNotices.BitRateCapped, selection.Notices.Single().Key);
+ }
+
+ [Test]
+ public void NoVideoEncoderMeansUnavailable()
+ {
+ var selection = EncoderSelector.Select(Request(VideoCodec.Av1), [new ManagedEncoderProvider()], EncoderHost.Client);
+ Assert.Equal(EncoderSelectionStatus.Unavailable, selection.Status);
+ Assert.SequenceEqual(new[] { EncoderNotices.FallbackToH264, EncoderNotices.NoEncoder }, selection.Notices.Select(n => n.Key));
+ }
+}
diff --git a/tests/Titano.Core.Tests/Export/ExportEstimateTests.cs b/tests/Titano.Core.Tests/Export/ExportEstimateTests.cs
new file mode 100644
index 00000000..7da50b5e
--- /dev/null
+++ b/tests/Titano.Core.Tests/Export/ExportEstimateTests.cs
@@ -0,0 +1,61 @@
+using Titano.Core.Export;
+using Titano.Core.Video;
+using Titano.Testing;
+
+namespace Titano.Core.Tests.Export;
+
+public sealed class ExportEstimateTests
+{
+ private static ExportWorkload Workload(int frames = 600, int width = 3840, int height = 2160, int flow = 0, int analysis = 0, bool hardware = true) =>
+ new(frames, frames, frames / 24.0, width, height, (long)width * height, flow, analysis, hardware);
+
+ private static ResolvedExport Preset(string id) => ExportResolver.FromPreset(ExportPresets.Find(id)!);
+
+ [Test]
+ public void VideoSizeIsBitRateTimesDuration()
+ {
+ var export = Preset("4k-h264");
+ var bytes = ExportEstimator.EstimateBytes(export, Workload());
+ var expected = 0.10 * 3840 * 2160 * 24 * 25 / 8 * 1.01;
+ Assert.Approximately(expected, bytes, 1);
+ Assert.InRange(bytes / 1e6, 60, 70); // ≈ 63 MB for 25 s of 4K at 19.9 Mb/s
+ }
+
+ [Test]
+ public void FrameBasedSizesScaleWithPicturesAndDepth()
+ {
+ var png8 = ExportResolver.FromPreset(ExportPresets.Find("png-sequence")!) with { Width = 1920, Height = 1080 };
+ var png16 = png8 with { BitDepth = 16 };
+ var w = Workload(240, 1920, 1080) with { OutputPeriods = 480 };
+ Assert.Equal(2 * ExportEstimator.EstimateBytes(png8, Workload(240, 1920, 1080)), ExportEstimator.EstimateBytes(png8, w));
+ Assert.Greater(ExportEstimator.EstimateBytes(png16, w), 2 * ExportEstimator.EstimateBytes(png8, w));
+ var gif = Preset("gif-preview");
+ Assert.Less(ExportEstimator.EstimateBytes(gif, Workload(240, 480, 270)), ExportEstimator.EstimateBytes(Preset("apng"), Workload(240, 480, 270)));
+ Assert.Monotonic(Enumerable.Range(1, 100).Select(q => ExportEstimator.JpegBitsPerPixel(q)), strict: true);
+ Assert.Approximately(2.8, ExportEstimator.JpegBitsPerPixel(90), 1e-12);
+ var mjpeg = Preset("mjpeg-avi");
+ Assert.Greater(ExportEstimator.EstimateBytes(mjpeg, Workload()), ExportEstimator.EstimateBytes(Preset("4k-hevc10-archive"), Workload()));
+ }
+
+ [Test]
+ public void TimeGrowsWithWorkAndCalibrationRescalesIt()
+ {
+ var export = Preset("4k-hevc");
+ var model = ThroughputModel.Default;
+ var plain = ExportEstimator.EstimateTime(export.Codec, Workload(), model);
+ Assert.Greater(ExportEstimator.EstimateTime(export.Codec, Workload(flow: 600), model).TotalSeconds, 2 * plain.TotalSeconds);
+ Assert.Greater(ExportEstimator.EstimateTime(export.Codec, Workload(analysis: 600), model).TotalSeconds, plain.TotalSeconds);
+ Assert.Greater(ExportEstimator.EstimateTime(export.Codec, Workload(hardware: false), model).TotalSeconds, plain.TotalSeconds);
+ Assert.InRange(plain.TotalSeconds, 30, 600); // ≈ 4 frames per second of 4K on the default model
+
+ var faster = model.Calibrate(plain, plain / 2, weight: 1);
+ Assert.Approximately(2.0, faster.Scale, 1e-9);
+ Assert.Approximately(plain.TotalSeconds / 2, ExportEstimator.EstimateTime(export.Codec, Workload(), faster).TotalSeconds, 1e-6);
+ Assert.Approximately(Math.Sqrt(2), model.Calibrate(plain, plain / 2).Scale, 1e-9);
+ Assert.Same(model, model.Calibrate(TimeSpan.Zero, plain));
+
+ var estimate = ExportEstimator.Estimate(export, Workload());
+ Assert.Equal(ExportEstimator.EstimateBytes(export, Workload()), estimate.Bytes);
+ Assert.Equal(plain, estimate.Time);
+ }
+}
diff --git a/tests/Titano.Core.Tests/Export/ExportNamingTests.cs b/tests/Titano.Core.Tests/Export/ExportNamingTests.cs
new file mode 100644
index 00000000..46b5e126
--- /dev/null
+++ b/tests/Titano.Core.Tests/Export/ExportNamingTests.cs
@@ -0,0 +1,83 @@
+using Titano.Core.Export;
+using Titano.Core.Project;
+using Titano.Core.Video;
+using Titano.Testing;
+
+namespace Titano.Core.Tests.Export;
+
+public sealed class ExportNamingTests
+{
+ private readonly TestContext _context;
+
+ public ExportNamingTests(TestContext context) => _context = context;
+
+ private static ExportNameContext Context(VideoCodec codec = VideoCodec.Hevc, string? title = "Harbour sunset") => new()
+ {
+ Date = new DateTime(2024, 6, 21, 19, 30, 0),
+ Title = title,
+ PresetName = "4K UHD HEVC",
+ Width = 3840,
+ Height = 2160,
+ FrameRate = Rational.Fps2997,
+ Codec = codec,
+ };
+
+ [Test]
+ public void DefaultTemplateNamesTheRender()
+ {
+ var name = ExportNaming.Expand("{date} {title} - {preset}", Context());
+ Assert.Equal("2024-06-21 Harbour sunset - 4K UHD HEVC", name.Name);
+ Assert.True(name.IsValid);
+ }
+
+ [Test]
+ public void EveryTokenExpands()
+ {
+ var name = ExportNaming.Expand("{date:yyyyMMdd}_{width}x{height}_{fps}fps_{codec}_{{raw}}", Context());
+ Assert.Equal("20240621_3840x2160_29.97fps_HEVC_{raw}", name.Name);
+ Assert.Equal("PNG", ExportNaming.CodecLabel(VideoCodec.PngSequence));
+ Assert.Equal("H.264", ExportNaming.CodecLabel(VideoCodec.H264));
+ }
+
+ [Test]
+ public void IllegalCharactersAndProblemsAreReported()
+ {
+ var name = ExportNaming.Expand("{title} {bogus} {", Context(title: "a/b:c*d?"));
+ Assert.Equal("a-b_c_d_ {", name.Name);
+ Assert.Count(2, name.Errors);
+ Assert.Equal("UnknownToken", name.Errors[0].Code);
+ Assert.Equal("UnclosedBrace", name.Errors[1].Code);
+ Assert.Equal(ExportNaming.FallbackName, ExportNaming.Expand("{title}", Context(title: null)).Name);
+ Assert.Equal("2024-06-21 - 4K UHD HEVC", ExportNaming.Expand("{date} {title} - {preset}", Context(title: null)).Name);
+ }
+
+ [Test]
+ public void CollisionsGetANumberedSuffix()
+ {
+ var dir = _context.CreateTempDirectory();
+ var first = ExportNaming.OutputPath(dir, "{title}", Context());
+ Assert.Equal(Path.Combine(dir, "Harbour sunset.mp4"), first);
+ File.WriteAllBytes(first, [1]);
+ var second = ExportNaming.OutputPath(dir, "{title}", Context());
+ Assert.Equal(Path.Combine(dir, "Harbour sunset (2).mp4"), second);
+ File.WriteAllBytes(second, [1]);
+ Assert.Equal(Path.Combine(dir, "Harbour sunset (3).mp4"), ExportNaming.OutputPath(dir, "{title}", Context()));
+
+ var sequence = ExportNaming.OutputPath(dir, "{title}", Context(VideoCodec.PngSequence));
+ Assert.Equal(Path.Combine(dir, "Harbour sunset"), sequence);
+ Directory.CreateDirectory(sequence);
+ Assert.Equal(Path.Combine(dir, "Harbour sunset (2)"), ExportNaming.OutputPath(dir, "{title}", Context(VideoCodec.PngSequence)));
+ Assert.Equal(Path.Combine(dir, "Harbour sunset.gif"), ExportNaming.OutputPath(dir, "{title}", Context(VideoCodec.Gif)));
+ }
+
+ [Test]
+ public void ProjectSettingsChooseFolderAndTemplate()
+ {
+ var exports = _context.CreateTempDirectory("exports");
+ var custom = _context.CreateTempDirectory("custom");
+ var byDefault = ExportNaming.OutputPath(new ExportSettings(), exports, Context());
+ Assert.Equal(Path.Combine(exports, "2024-06-21 Harbour sunset - 4K UHD HEVC.mp4"), byDefault);
+ var chosen = ExportNaming.OutputPath(new ExportSettings { Folder = custom, NameTemplate = "{title} {width}" }, exports, Context());
+ Assert.Equal(Path.Combine(custom, "Harbour sunset 3840.mp4"), chosen);
+ }
+}
diff --git a/tests/Titano.Core.Tests/Export/ExportResolverTests.cs b/tests/Titano.Core.Tests/Export/ExportResolverTests.cs
new file mode 100644
index 00000000..c934f4be
--- /dev/null
+++ b/tests/Titano.Core.Tests/Export/ExportResolverTests.cs
@@ -0,0 +1,131 @@
+using Titano.Core.Export;
+using Titano.Core.Project;
+using Titano.Core.Video;
+using Titano.Testing;
+
+namespace Titano.Core.Tests.Export;
+
+public sealed class ExportResolverTests
+{
+ private static ExportSettings Export(string preset, ExportOverrides? overrides = null) =>
+ new() { Preset = new Auto().WithManual(preset), Overrides = overrides ?? new ExportOverrides() };
+
+ [Test]
+ public void EveryBuiltInPresetResolvesToItself()
+ {
+ foreach (var preset in ExportPresets.BuiltIn)
+ {
+ var resolved = ExportResolver.Resolve(Export(preset.Id));
+ Assert.Equal(preset.Id, resolved.PresetId);
+ Assert.False(resolved.IsCustom);
+ Assert.Equal(preset.NameKey, resolved.NameKey);
+ Assert.Equal(preset.Codec, resolved.Codec);
+ Assert.Empty(resolved.Warnings);
+ }
+ }
+
+ [Test]
+ public void EditingAValueMakesTheExportCustom()
+ {
+ var resolved = ExportResolver.Resolve(Export("4k-hevc", new ExportOverrides { BitRate = 50_000_000 }));
+ Assert.True(resolved.IsCustom);
+ Assert.Equal(ExportResolver.CustomId, resolved.PresetId);
+ Assert.Equal("4k-hevc", resolved.BasePresetId);
+ Assert.Null(resolved.NameKey);
+ Assert.Equal(50_000_000L, resolved.EffectiveBitRate(3840, 2160));
+ Assert.Equal(3840, resolved.Width);
+ }
+
+ [Test]
+ public void ValuesEqualToThePresetRestoreItsName()
+ {
+ var resolved = ExportResolver.Resolve(Export("1080p-h264", new ExportOverrides
+ {
+ Codec = "h.264",
+ Container = "mp4",
+ Width = 1920,
+ Height = 1080,
+ FrameRate = "30",
+ BitRate = 6_220_800, // the preset's 0.10 bpp at 1920×1080×30
+ GopFrames = 30,
+ Profile = "H264High",
+ RateControl = "vbr",
+ }));
+ Assert.Equal("1080p-h264", resolved.PresetId);
+ Assert.Empty(resolved.Warnings);
+ }
+
+ [Test]
+ public void ValuesEqualToAnotherPresetTakeItsName()
+ {
+ var resolved = ExportResolver.Resolve(Export("1080p-h264", new ExportOverrides { FrameRate = "60" }));
+ Assert.Equal("1080p60", resolved.PresetId);
+ Assert.Equal(60, resolved.GopFrames);
+ Assert.Equal("1080p-h264", resolved.BasePresetId);
+ }
+
+ [Test]
+ public void FractionalRatesAndGopFollowTheOverride()
+ {
+ var resolved = ExportResolver.Resolve(Export("4k-h264", new ExportOverrides { FrameRate = "24000/1001" }));
+ Assert.True(resolved.IsCustom);
+ Assert.Equal(Rational.Fps23976, resolved.FrameRate);
+ Assert.Equal(24, resolved.GopFrames);
+ var settings = resolved.ToEncodeSettings("x.mp4", 3840, 2160);
+ Assert.Equal(24, settings.GopLength);
+ Assert.Equal((long)Math.Round(0.10 * 3840 * 2160 * 24000 / 1001.0), settings.BitRate);
+ Assert.Equal(CodecProfile.H264High, settings.Profile);
+ }
+
+ [Test]
+ public void BadOverridesAreIgnoredWithWarnings()
+ {
+ var resolved = ExportResolver.Resolve(Export("1080p-h264", new ExportOverrides { Codec = "divx", FrameRate = "fast", Container = "avi", Profile = "ultra", RateControl = "magic" }));
+ Assert.Equal("1080p-h264", resolved.PresetId);
+ Assert.SequenceEqual(new[] { "Export.Warning.UnknownCodec", "Export.Warning.ContainerIgnored", "Export.Warning.UnknownProfile", "Export.Warning.UnknownFrameRate", "Export.Warning.UnknownRateControl" }, resolved.Warnings);
+ }
+
+ [Test]
+ public void UnknownOrCustomSelectionsStartFromTheDefaultPreset()
+ {
+ var unknown = ExportResolver.Resolve(Export("deleted-user-preset"));
+ Assert.Equal(ExportResolver.DefaultPresetId, unknown.PresetId);
+ Assert.Contains("Export.Warning.UnknownPreset", unknown.Warnings);
+
+ var custom = ExportResolver.Resolve(Export("custom", new ExportOverrides { Codec = "png", Width = 0, Height = 0, BitDepth = 16, FrameRate = "30", GopFrames = 30, BFrames = 0, Quality = 92 }));
+ Assert.Empty(custom.Warnings);
+ Assert.Equal(VideoCodec.PngSequence, custom.Codec);
+ Assert.True(custom.IsCustom);
+
+ var auto = ExportResolver.Resolve(new ExportSettings());
+ Assert.Equal(ExportResolver.DefaultPresetId, auto.PresetId);
+ }
+
+ [Test]
+ public void ChangingTheCodecResetsCodecSpecificValues()
+ {
+ var resolved = ExportResolver.Resolve(Export("1080p-h264", new ExportOverrides { Codec = "HEVC" }));
+ Assert.Equal(VideoCodec.Hevc, resolved.Codec);
+ Assert.Equal(CodecProfile.Auto, resolved.Profile);
+ Assert.Equal((long)Math.Round(0.07 * 1920 * 1080 * 30), resolved.EffectiveBitRate(1920, 1080));
+ Assert.True(resolved.IsCustom);
+ Assert.True(ExportResolver.TryParseCodec("TIFF-16", out var tiff) && tiff == VideoCodec.Tiff16Sequence);
+ Assert.False(ExportResolver.TryParseCodec("", out _));
+ }
+
+ [Test]
+ public void FrameRateTextRoundTrips()
+ {
+ Assert.True(FrameRateText.TryParse("30000/1001", out var ntsc));
+ Assert.Equal(Rational.Fps2997, ntsc);
+ Assert.True(FrameRateText.TryParse("29.97", out var decimalNtsc));
+ Assert.Equal(Rational.Fps2997, decimalNtsc);
+ Assert.True(FrameRateText.TryParse(" 25 ", out var pal));
+ Assert.Equal("25", FrameRateText.Format(pal));
+ Assert.Equal("24000/1001", FrameRateText.Format(Rational.Fps23976));
+ Assert.True(FrameRateText.AreEqual(new Rational(48000, 2002), Rational.Fps23976));
+ Assert.False(FrameRateText.TryParse("0", out _));
+ Assert.False(FrameRateText.TryParse("1/0", out _));
+ Assert.False(FrameRateText.TryParse(null, out _));
+ }
+}
diff --git a/tests/Titano.Core.Tests/Export/ManagedEncoderTests.cs b/tests/Titano.Core.Tests/Export/ManagedEncoderTests.cs
new file mode 100644
index 00000000..7e293f58
--- /dev/null
+++ b/tests/Titano.Core.Tests/Export/ManagedEncoderTests.cs
@@ -0,0 +1,213 @@
+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 };
+
+ /// Three distinct frames lasting one, two and one periods.
+ 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 SequenceWriteFailuresSurfaceAndLeaveNothing()
+ {
+ var dir = _context.CreateTempDirectory();
+ var session = new ManagedEncoderProvider().Open(Settings(Path.Combine(dir, "seq"), VideoCodec.PngSequence));
+ using var frame = Frame(0);
+ session.WriteFrame(frame, 3000);
+ Directory.Delete(Directory.GetDirectories(dir, ".seq.*.tmp").Single(), recursive: true);
+ Exception? error = null;
+ try
+ {
+ for (var i = 0; i < 20; i++) session.WriteFrame(frame, 3000);
+ session.Complete();
+ }
+ catch (Exception ex)
+ {
+ error = ex;
+ }
+ session.Dispose();
+ Assert.True(error is IOException, $"unexpected {error?.GetType().Name}");
+ 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(() => session.WriteFrame(wrong, 3000));
+ Assert.Throws(session.Complete);
+ }
+ Assert.Empty(Directory.GetFileSystemEntries(dir));
+
+ var existing = Directory.CreateDirectory(Path.Combine(dir, "taken")).FullName;
+ Assert.Throws(() => 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(() => 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)));
+ }
+}
diff --git a/tests/Titano.Core.Tests/Render/CapturingEncoderProvider.cs b/tests/Titano.Core.Tests/Render/CapturingEncoderProvider.cs
new file mode 100644
index 00000000..cd5e3404
--- /dev/null
+++ b/tests/Titano.Core.Tests/Render/CapturingEncoderProvider.cs
@@ -0,0 +1,57 @@
+using Titano.Core.Imaging;
+using Titano.Core.Video;
+
+namespace Titano.Core.Tests.Render;
+
+/// One encode recorded by .
+internal sealed class CapturedEncode(EncodeSettings settings)
+{
+ public EncodeSettings Settings { get; } = settings;
+ public List Frames { get; } = [];
+ public List Durations { get; } = [];
+ public bool Completed { get; set; }
+ public bool Disposed { get; set; }
+}
+
+/// Test encoder: keeps a copy of every frame, can pretend to be hardware or to fail at a given frame.
+internal sealed class CapturingEncoderProvider(string name, params EncoderCapability[] capabilities) : IVideoEncoderProvider
+{
+ public string Name => name;
+
+ public IReadOnlyList Capabilities => capabilities;
+
+ public List Encodes { get; } = [];
+
+ /// When set, WriteFrame throws this for the frame with that zero-based index.
+ public (int Frame, Exception Error)? FailAt { get; set; }
+
+ public bool CanEncode(EncodeSettings settings) => capabilities.Any(c =>
+ c.Codec == settings.Codec && settings.Width <= c.MaxWidth && settings.Height <= c.MaxHeight && (settings.BitDepth == 8 || c.SupportsTenBit));
+
+ public IVideoEncoderSession Open(EncodeSettings settings)
+ {
+ var encode = new CapturedEncode(settings);
+ Encodes.Add(encode);
+ var capability = capabilities.First(c => c.Codec == settings.Codec);
+ return new Session(this, encode, capability);
+ }
+
+ private sealed class Session(CapturingEncoderProvider owner, CapturedEncode encode, EncoderCapability capability) : IVideoEncoderSession
+ {
+ public string EncoderName => capability.Name;
+
+ public bool IsHardware => capability.Hardware;
+
+ public void WriteFrame(ImageBuffer frame, long duration90k)
+ {
+ if (owner.FailAt is { } fail && fail.Frame == encode.Frames.Count) throw fail.Error;
+ if (frame.Width != encode.Settings.Width || frame.Height != encode.Settings.Height) throw new ArgumentException("size");
+ encode.Frames.Add(frame.Clone());
+ encode.Durations.Add(duration90k);
+ }
+
+ public void Complete() => encode.Completed = true;
+
+ public void Dispose() => encode.Disposed = true;
+ }
+}
diff --git a/tests/Titano.Core.Tests/Render/ProjectValuesTests.cs b/tests/Titano.Core.Tests/Render/ProjectValuesTests.cs
new file mode 100644
index 00000000..dd550837
--- /dev/null
+++ b/tests/Titano.Core.Tests/Render/ProjectValuesTests.cs
@@ -0,0 +1,20 @@
+using Titano.Core.Project;
+using Titano.Core.Render;
+using Titano.Testing;
+
+namespace Titano.Core.Tests.Render;
+
+public sealed class ProjectValuesTests
+{
+ [Test]
+ public void ValueTypeSettingsFallBackWithoutAdvice()
+ {
+ Assert.Equal(21, ProjectValues.Get(new Auto(), 21));
+ Assert.Equal(180.0, ProjectValues.Get(new Auto(), 180.0));
+ Assert.Equal(FlowQualitySetting.Balanced, ProjectValues.Get(new Auto(), FlowQualitySetting.Balanced));
+ Assert.Equal(41, ProjectValues.Get(new Auto().WithAdvice(41, null), 21));
+ Assert.Equal(0.5, ProjectValues.Get(new Auto().WithAdvice(0.8, null).WithManual(0.5), 1.0));
+ Assert.Equal(FlowQualitySetting.Draft, ProjectValues.Get(new Auto().WithManual(FlowQualitySetting.Draft), FlowQualitySetting.Balanced));
+ Assert.False(ProjectValues.Get(new Auto().WithManual(false), true));
+ }
+}
diff --git a/tests/Titano.Core.Tests/Render/RenderFixture.cs b/tests/Titano.Core.Tests/Render/RenderFixture.cs
new file mode 100644
index 00000000..17c77d8c
--- /dev/null
+++ b/tests/Titano.Core.Tests/Render/RenderFixture.cs
@@ -0,0 +1,83 @@
+using Titano.Core.Diagnostics.Synthetic;
+using Titano.Core.Export;
+using Titano.Core.Imaging;
+using Titano.Core.Project;
+using Titano.Core.Render;
+using Titano.Core.Render.Diagnostics;
+using Titano.Core.Video;
+using Titano.Core.Video.Managed;
+
+namespace Titano.Core.Tests.Render;
+
+/// Small synthetic renders shared by the render tests.
+internal static class RenderFixture
+{
+ /// No module and no knee: the output equals the source.
+ public static ProjectSettings Plain { get; } = new() { Exposure = new ExposureSettings { HighlightKnee = null } };
+
+ public static SyntheticFrameSource Source(int frames = 12, double flickerEv = 0, Func? motion = null, int width = 96, int height = 64,
+ Func? configure = null)
+ {
+ var options = new SyntheticSequenceOptions
+ {
+ Width = width,
+ Height = height,
+ FrameCount = frames,
+ StartEv = 0,
+ EndEv = 1,
+ FlickerEv = flickerEv,
+ Seed = 5,
+ };
+ return new SyntheticFrameSource(SyntheticSequence.Create(configure is null ? options : configure(options)), motion);
+ }
+
+ /// Renders into a capturing encoder (PNG-sequence capability) and returns the captured frames.
+ public static async Task<(CapturedEncode Encode, RenderResult Result)> CaptureAsync(RenderInput input, ResolvedExport? export = null, RenderOptions? options = null,
+ CancellationToken cancellationToken = default)
+ {
+ var capture = new CapturingEncoderProvider("capture", new EncoderCapability(VideoCodec.PngSequence, "Capture", false, 8192, 8192, true));
+ var target = new RenderTarget(export ?? Preset("png-sequence"), Path.Combine(Path.GetTempPath(), "titano-capture-" + Guid.NewGuid().ToString("N")));
+ var result = await Pipeline(capture).RenderAsync(input, target, options, cancellationToken: cancellationToken);
+ return (capture.Encodes.Single(), result);
+ }
+
+ public static RenderInput Input(SyntheticFrameSource source, ProjectSettings? project = null) =>
+ new() { Source = source, Frames = source.Metadata(), Project = project ?? Plain };
+
+ /// A built-in preset's values at an explicit size (0×0 = source size).
+ public static ResolvedExport Preset(string presetId, int width = 96, int height = 64) =>
+ ExportResolver.FromPreset(ExportPresets.Find(presetId)!) with { Width = width, Height = height };
+
+ public static RenderTarget Target(string folder, ResolvedExport export, string name = "out") =>
+ new(export, Path.Combine(folder, name + (export.Container == ContainerFormat.ImageSequence ? string.Empty : VideoCodecInfo.FileExtension(export.Codec))));
+
+ public static RenderPipeline Pipeline(params IVideoEncoderProvider[] extra) =>
+ new([.. extra, new ManagedEncoderProvider()]);
+
+ /// Peak signal-to-noise ratio of the 8-bit sRGB encodings.
+ public 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));
+ }
+
+ /// Synchronous progress sink (Progress<T> would post to the thread pool).
+ public sealed class Sink(Action report) : IProgress
+ {
+ public void Report(T value) => report(value);
+ }
+
+ /// Throws an for one frame, as an unreadable file would.
+ public sealed class FailingSource(IRenderFrameSource inner, int failAt) : IRenderFrameSource
+ {
+ public int FrameCount => inner.FrameCount;
+ public int Width => inner.Width;
+ public int Height => inner.Height;
+
+ public ValueTask GetFrameAsync(int index, int maxLongEdge, DecodePurpose purpose, CancellationToken cancellationToken) =>
+ index == failAt ? throw new IOException($"frame {index} is unreadable") : inner.GetFrameAsync(index, maxLongEdge, purpose, cancellationToken);
+ }
+}
diff --git a/tests/Titano.Core.Tests/Render/RenderIsolationTests.cs b/tests/Titano.Core.Tests/Render/RenderIsolationTests.cs
new file mode 100644
index 00000000..50456937
--- /dev/null
+++ b/tests/Titano.Core.Tests/Render/RenderIsolationTests.cs
@@ -0,0 +1,69 @@
+using Titano.Core.Render;
+using Titano.Core.Video;
+using Titano.Testing;
+using static Titano.Core.Tests.Render.RenderFixture;
+
+namespace Titano.Core.Tests.Render;
+
+/// Process-wide observations (unobserved task exceptions, managed heap) that must not overlap other tests.
+[Serial]
+public sealed class RenderIsolationTests
+{
+ private readonly TestContext _context;
+
+ public RenderIsolationTests(TestContext context) => _context = context;
+
+ [Test]
+ public async Task FailuresLeaveNoUnobservedTaskExceptions()
+ {
+ var unobserved = 0;
+ void Handler(object? sender, UnobservedTaskExceptionEventArgs e) => Interlocked.Increment(ref unobserved);
+ TaskScheduler.UnobservedTaskException += Handler;
+ try
+ {
+ var dir = _context.CreateTempDirectory();
+ var capture = new CapturingEncoderProvider("capture", new EncoderCapability(VideoCodec.PngSequence, "Capture", false, 4096, 4096, true))
+ {
+ FailAt = (2, new InvalidDataException("encoder broke")),
+ };
+ for (var i = 0; i < 3; i++)
+ {
+ await Assert.ThrowsAsync(() => Pipeline(capture).RenderAsync(Input(Source()), Target(dir, Preset("png-sequence"))));
+ var input = Input(Source()) with { Source = new FailingSource(Source(), failAt: 3 + i) };
+ await Assert.ThrowsAsync(() => Pipeline().RenderAsync(input, Target(dir, Preset("gif-preview"))));
+ }
+ GC.Collect();
+ GC.WaitForPendingFinalizers();
+ GC.Collect();
+ Assert.Equal(0, unobserved);
+ Assert.Empty(Directory.GetFileSystemEntries(dir));
+ }
+ finally
+ {
+ TaskScheduler.UnobservedTaskException -= Handler;
+ }
+ }
+
+ /// BRIEF §20.4: peak memory does not depend on the sequence length (live managed heap sampled while rendering).
+ [Test]
+ public async Task MemoryDoesNotGrowWithSequenceLength()
+ {
+ async Task PeakAsync(int frames)
+ {
+ var dir = _context.CreateTempDirectory();
+ long peak = 0;
+ var progress = new Sink(p =>
+ {
+ if (p.Stage == RenderStage.Rendering && p.Done % 8 == 0) peak = Math.Max(peak, GC.GetTotalMemory(forceFullCollection: true));
+ });
+ var project = Plain with { Exposure = new Titano.Core.Project.ExposureSettings { Deflicker = new Titano.Core.Project.Auto().WithManual(true) } };
+ await Pipeline().RenderAsync(Input(Source(frames), project), Target(dir, Preset("mjpeg-avi")), progress: progress, cancellationToken: _context.Cancellation);
+ return peak;
+ }
+ await PeakAsync(16);
+ var shortPeak = await PeakAsync(48);
+ var longPeak = await PeakAsync(192);
+ _context.Log($"peak live heap: 48 frames {shortPeak / 1024} KiB, 192 frames {longPeak / 1024} KiB");
+ Assert.Less(longPeak - shortPeak, 2 << 20);
+ }
+}
diff --git a/tests/Titano.Core.Tests/Render/RenderPipelineTests.cs b/tests/Titano.Core.Tests/Render/RenderPipelineTests.cs
new file mode 100644
index 00000000..7e726ba0
--- /dev/null
+++ b/tests/Titano.Core.Tests/Render/RenderPipelineTests.cs
@@ -0,0 +1,208 @@
+using Titano.Core.Codecs.Jpeg;
+using Titano.Core.Codecs.Png;
+using Titano.Core.Codecs.Tiff;
+using Titano.Core.Export;
+using Titano.Core.Imaging;
+using Titano.Core.Project;
+using Titano.Core.Render;
+using Titano.Core.Render.Diagnostics;
+using Titano.Core.Video;
+using Titano.Core.Video.Managed;
+using Titano.Testing;
+using static Titano.Core.Tests.Render.RenderFixture;
+
+namespace Titano.Core.Tests.Render;
+
+public sealed class RenderPipelineTests
+{
+ private readonly TestContext _context;
+
+ public RenderPipelineTests(TestContext context) => _context = context;
+
+ [Theory]
+ [Case("mjpeg-avi", 8)]
+ [Case("jpeg-sequence", 8)]
+ [Case("png-sequence", 8)]
+ [Case("png-sequence", 16)]
+ [Case("tiff16-sequence", 16)]
+ [Case("dng-sequence", 16)]
+ [Case("gif-preview", 8)]
+ [Case("apng", 8)]
+ public async Task RendersEveryManagedFormat(string presetId, int bitDepth)
+ {
+ var dir = _context.CreateTempDirectory();
+ var source = Source();
+ var export = Preset(presetId) with { BitDepth = bitDepth };
+ var target = Target(dir, export);
+ var result = await Pipeline().RenderAsync(Input(source), target, cancellationToken: _context.Cancellation);
+
+ Assert.Equal(target.OutputPath, result.OutputPath);
+ Assert.SequenceEqual(new[] { Path.GetFileName(target.OutputPath) }, Directory.GetFileSystemEntries(dir).Select(Path.GetFileName));
+ Assert.Equal((96, 64), (result.Width, result.Height));
+ Assert.Equal(12, result.FrameCount);
+ Assert.Equal(RenderResultBytes(target.OutputPath), result.Bytes);
+ Assert.False(result.Hardware);
+ Assert.Approximately(12 / export.FrameRate.Value, result.DurationSeconds, 1e-4);
+
+ using var expected = source.Sequence.Render(5);
+ using var decoded = DecodeFrame(export.Codec, target.OutputPath, 5, out var count);
+ Assert.Equal(12, count);
+ var psnr = Psnr(expected, decoded);
+ _context.Log($"{presetId} {bitDepth}-bit: {result.Bytes} bytes, PSNR {psnr:F1} dB");
+ Assert.Greater(psnr, export.Codec switch { VideoCodec.Gif => 25, VideoCodec.Mjpeg or VideoCodec.JpegSequence => 35, _ => 60 });
+ }
+
+ [Test]
+ public async Task LosslessOutputsAreByteIdenticalAcrossRuns()
+ {
+ var dir = _context.CreateTempDirectory();
+ var project = Plain with
+ {
+ Exposure = new ExposureSettings { Deflicker = new Auto().WithManual(true), HighlightKnee = 0.9 },
+ Timing = new TimingSettings { Mode = new Auto().WithManual(TimingMode.Interpolated), FrameRate = new Auto().WithManual("15") },
+ };
+ var first = await Pipeline().RenderAsync(Input(Source(flickerEv: 0.2), project), Target(dir, Preset("png-sequence"), "a"), cancellationToken: _context.Cancellation);
+ var second = await Pipeline().RenderAsync(Input(Source(flickerEv: 0.2), project), Target(dir, Preset("png-sequence"), "b"), cancellationToken: _context.Cancellation);
+ var a = Directory.GetFiles(first.OutputPath).Order(StringComparer.Ordinal).ToArray();
+ var b = Directory.GetFiles(second.OutputPath).Order(StringComparer.Ordinal).ToArray();
+ Assert.Equal(a.Length, b.Length);
+ Assert.Greater(first.FrameCount, 12);
+ for (var i = 0; i < a.Length; i++) Assert.BytesEqual(File.ReadAllBytes(a[i]), File.ReadAllBytes(b[i]));
+
+ var apngA = await Pipeline().RenderAsync(Input(Source(), project), Target(dir, Preset("apng"), "c"), cancellationToken: _context.Cancellation);
+ var apngB = await Pipeline().RenderAsync(Input(Source(), project), Target(dir, Preset("apng"), "d"), cancellationToken: _context.Cancellation);
+ Assert.BytesEqual(File.ReadAllBytes(apngA.OutputPath), File.ReadAllBytes(apngB.OutputPath));
+ }
+
+ [Theory]
+ [Case("mjpeg-avi")]
+ [Case("png-sequence")]
+ [Case("gif-preview")]
+ public async Task CancellationLeavesNoOutput(string presetId)
+ {
+ var dir = _context.CreateTempDirectory();
+ using var cts = CancellationTokenSource.CreateLinkedTokenSource(_context.Cancellation);
+ var progress = new Sink(p =>
+ {
+ if (p.Stage == RenderStage.Rendering && p.Done == 5) cts.Cancel();
+ });
+ await Assert.ThrowsAsync(() => Pipeline().RenderAsync(Input(Source(24)), Target(dir, Preset(presetId)), progress: progress, cancellationToken: cts.Token));
+ Assert.Empty(Directory.GetFileSystemEntries(dir));
+ }
+
+ [Test]
+ public async Task SourceFailurePropagatesOnceAndLeavesNoOutput()
+ {
+ var dir = _context.CreateTempDirectory();
+ var input = Input(Source()) with { Source = new FailingSource(Source(), failAt: 7) };
+ var error = await Assert.ThrowsAsync(() => Pipeline().RenderAsync(input, Target(dir, Preset("mjpeg-avi"))));
+ Assert.Equal("frame 7 is unreadable", error.Message);
+ Assert.Empty(Directory.GetFileSystemEntries(dir));
+ }
+
+ [Test]
+ public async Task EncoderFailurePropagatesAndDisposesTheSession()
+ {
+ var capture = new CapturingEncoderProvider("capture", new EncoderCapability(VideoCodec.PngSequence, "Capture", false, 4096, 4096, true))
+ {
+ FailAt = (4, new InvalidDataException("encoder broke")),
+ };
+ var error = await Assert.ThrowsAsync(() => Pipeline(capture).RenderAsync(Input(Source()), Target(_context.CreateTempDirectory(), Preset("png-sequence"))));
+ Assert.Equal("encoder broke", error.Message);
+ var encode = capture.Encodes.Single();
+ Assert.True(encode.Disposed);
+ Assert.False(encode.Completed);
+ Assert.Equal(4, encode.Frames.Count);
+ }
+
+ [Test]
+ public async Task ProgressReportsEveryFrameAndPreviews()
+ {
+ var reports = new List();
+ var options = new RenderOptions { PreviewInterval = 5, PreviewLongEdge = 32 };
+ var project = Plain with { Exposure = new ExposureSettings { Deflicker = new Auto().WithManual(true), HighlightKnee = null } };
+ await Pipeline().RenderAsync(Input(Source(), project), Target(_context.CreateTempDirectory(), Preset("jpeg-sequence")), options,
+ new Sink(reports.Add), _context.Cancellation);
+ var preparing = reports.Where(r => r.Stage == RenderStage.Preparing).ToList();
+ var rendering = reports.Where(r => r.Stage == RenderStage.Rendering).ToList();
+ Assert.Equal(12, preparing.Count);
+ Assert.SequenceEqual(Enumerable.Range(1, 12), rendering.Select(r => r.Done));
+ Assert.True(rendering.All(r => r.Total == 12 && r.FramesPerSecond > 0 && r.Remaining >= TimeSpan.Zero));
+ Assert.SequenceEqual(new[] { 1, 6, 11 }, rendering.Where(r => r.Preview is not null).Select(r => r.Done));
+ Assert.Equal(32, rendering[0].Preview!.Width);
+ Assert.Equal(RenderStage.Finishing, reports[^1].Stage);
+ foreach (var r in rendering) r.Preview?.Dispose();
+ }
+
+ [Test]
+ public async Task BatchRendersEachTargetAndReportsFailures()
+ {
+ var dir = _context.CreateTempDirectory();
+ var server = new RenderPipeline([new ManagedEncoderProvider()], EncoderHost.Server);
+ var targets = new[]
+ {
+ Target(dir, Preset("png-sequence"), "png"),
+ Target(dir, Preset("1080p-h264"), "h264"),
+ Target(dir, Preset("gif-preview"), "gif"),
+ };
+ var results = await server.RenderBatchAsync(Input(Source()), targets, cancellationToken: _context.Cancellation);
+ Assert.Equal(3, results.Count);
+ Assert.True(results[0].Succeeded && results[2].Succeeded);
+ var error = Assert.NotNull(results[1].Error as RenderException);
+ Assert.Equal(EncoderNotices.NeedsRenderNode, error.ReasonKey);
+ Assert.SequenceEqual(new[] { "gif.gif", "png" }, Directory.GetFileSystemEntries(dir).Select(Path.GetFileName).Order(StringComparer.Ordinal));
+ }
+
+ [Test]
+ public async Task EverythingExcludedIsARenderError()
+ {
+ var project = Plain with { ExcludedFrames = [.. Enumerable.Range(0, 12)] };
+ var error = await Assert.ThrowsAsync(() => Pipeline().RenderAsync(Input(Source(), project), Target(_context.CreateTempDirectory(), Preset("png-sequence"))));
+ Assert.Equal("Export.Render.NoFrames", error.ReasonKey);
+ }
+
+ [Test]
+ public async Task ResultBecomesARenderHistoryEntity()
+ {
+ var result = await Pipeline().RenderAsync(Input(Source()), Target(_context.CreateTempDirectory(), Preset("apng")), cancellationToken: _context.Cancellation);
+ var sequence = Guid.CreateVersion7();
+ var entity = result.ToEntity(sequence, "APNG", "{}", "test");
+ Assert.Equal(sequence, entity.SequenceId);
+ Assert.Equal(result.OutputPath, entity.OutputPath);
+ Assert.Equal("Apng", entity.Codec);
+ Assert.Equal(result.Bytes, entity.Bytes);
+ Assert.Approximately(15, entity.Fps, 1e-12);
+ Assert.Equal("Managed APNG", result.EncoderName);
+ }
+
+ private static long RenderResultBytes(string path) => File.Exists(path)
+ ? new FileInfo(path).Length
+ : new DirectoryInfo(path).EnumerateFiles().Sum(f => f.Length);
+
+ /// Decodes output picture and counts the pictures of the output.
+ private static ImageBuffer DecodeFrame(VideoCodec codec, string path, int index, out int count)
+ {
+ switch (codec)
+ {
+ case VideoCodec.Mjpeg:
+ var avi = AviReader.Read(File.ReadAllBytes(path));
+ count = avi.Frames.Count;
+ return JpegDecoder.DecodeToLinear(avi.Frames[index]);
+ case VideoCodec.Gif or VideoCodec.Apng:
+ var bytes = File.ReadAllBytes(path);
+ var animation = codec == VideoCodec.Gif ? GifReader.Decode(bytes) : ApngReader.Decode(bytes);
+ count = animation.Frames.Count;
+ return animation.ToLinear(index);
+ default:
+ var files = Directory.GetFiles(path).Order(StringComparer.Ordinal).ToArray();
+ count = files.Length;
+ var data = File.ReadAllBytes(files[index]);
+ return codec switch
+ {
+ VideoCodec.JpegSequence => JpegDecoder.DecodeToLinear(data),
+ VideoCodec.PngSequence => PngDecoder.DecodeToLinear(data),
+ _ => TiffImageReader.Decode(data),
+ };
+ }
+ }
+}
diff --git a/tests/Titano.Core.Tests/Render/RenderPlanTests.cs b/tests/Titano.Core.Tests/Render/RenderPlanTests.cs
new file mode 100644
index 00000000..26758d9a
--- /dev/null
+++ b/tests/Titano.Core.Tests/Render/RenderPlanTests.cs
@@ -0,0 +1,202 @@
+using Titano.Core.Project;
+using Titano.Core.Render;
+using Titano.Core.Video;
+using Titano.Testing;
+
+namespace Titano.Core.Tests.Render;
+
+public sealed class RenderPlanTests
+{
+ private static readonly DateTime Start = new(2024, 6, 21, 19, 0, 0);
+
+ private static DateTime?[] Regular(int count, double interval = 10) =>
+ Enumerable.Range(0, count).Select(i => (DateTime?)Start.AddSeconds(i * interval)).ToArray();
+
+ private static ProjectSettings Timing(TimingMode mode, string? playback = null, double? fit = null, IReadOnlyList? curve = null, int[]? excluded = null) => new()
+ {
+ Timing = new TimingSettings
+ {
+ Mode = new Auto().WithManual(mode),
+ FrameRate = playback is null ? new Auto() : new Auto().WithManual(playback),
+ FitToSeconds = fit,
+ RemapCurve = curve ?? [new(0, 0), new(1, 1)],
+ },
+ ExcludedFrames = excluded ?? [],
+ };
+
+ private static void AssertExactDurations(RenderPlan plan)
+ {
+ Assert.Equal(plan.Duration90k, plan.Frames.Sum(f => f.Duration90k));
+ Assert.Equal(RenderPlan.TicksAt(plan.FrameRate, plan.SlotCount), plan.Duration90k);
+ long t = 0;
+ var slot = 0;
+ foreach (var f in plan.Frames)
+ {
+ Assert.Equal(t, f.Start90k);
+ Assert.Equal(slot, f.StartSlot);
+ Assert.Greater(f.Duration90k, 0);
+ t += f.Duration90k;
+ slot += f.Slots;
+ }
+ Assert.Equal(plan.SlotCount, slot);
+ Assert.Monotonic(plan.Frames.Select(f => f.SourcePosition));
+ }
+
+ [Test]
+ public void ConstantShowsEveryFrameOnceAtTheOutputRate()
+ {
+ var plan = RenderPlan.Build(Regular(100), Timing(TimingMode.Constant), new Rational(24, 1));
+ Assert.Equal(100, plan.Frames.Count);
+ Assert.SequenceEqual(Enumerable.Range(0, 100).Select(i => (double)i), plan.Frames.Select(f => f.SourcePosition));
+ Assert.True(plan.Frames.All(f => f.Duration90k == 3750 && f.Flags == PlannedFrameFlags.None && f.Speed == 1));
+ Assert.Equal(375_000L, plan.Duration90k);
+ AssertExactDurations(plan);
+ }
+
+ [Test]
+ public void ExcludedFramesAreSkipped()
+ {
+ var plan = RenderPlan.Build(Regular(20), Timing(TimingMode.Constant, excluded: [3, 7, 99]), new Rational(25, 1));
+ Assert.Equal(18, plan.Frames.Count);
+ Assert.DoesNotContain(3, plan.Frames.Select(f => f.From));
+ Assert.DoesNotContain(7, plan.Frames.Select(f => f.To));
+ Assert.Equal(2, plan.Statistics.ExcludedFrames);
+ Assert.Equal(2.0, plan.Frames.Single(f => f.From == 2).Speed);
+ AssertExactDurations(plan);
+ }
+
+ [Test]
+ public void NtscDurationsAccumulateWithoutDrift()
+ {
+ var plan = RenderPlan.Build(Regular(1001), Timing(TimingMode.Constant), Rational.Fps2997);
+ Assert.Equal(1001 * 3003L, plan.Duration90k);
+ Assert.True(plan.Frames.All(f => f.Duration90k == 3003));
+ var fps23 = RenderPlan.Build(Regular(7), Timing(TimingMode.Constant), Rational.Fps23976);
+ Assert.SequenceEqual(new long[] { 3754, 3754, 3753, 3754, 3754, 3754, 3753 }, fps23.Frames.Select(f => f.Duration90k));
+ Assert.Equal(26_276L, fps23.Duration90k);
+ AssertExactDurations(fps23);
+ }
+
+ [Test]
+ public void SlowerPlaybackHoldsFramesInConstantAndSynthesisesInInterpolated()
+ {
+ var held = RenderPlan.Build(Regular(10), Timing(TimingMode.Constant, playback: "12"), new Rational(24, 1));
+ Assert.Equal(10, held.Frames.Count);
+ Assert.True(held.Frames.All(f => f.Slots == 2 && f.IsHeld && f.Duration90k == 7500));
+ AssertExactDurations(held);
+
+ var smooth = RenderPlan.Build(Regular(10), Timing(TimingMode.Interpolated, playback: "12"), new Rational(24, 1));
+ Assert.Equal(19, smooth.Frames.Count);
+ Assert.Equal(9, smooth.Statistics.InterpolatedFrames);
+ Assert.Equal(0.5, smooth.Frames[1].SourcePosition);
+ Assert.Equal(0.5, smooth.Frames[1].Fraction);
+ Assert.Equal(9.0, smooth.Frames[^1].SourcePosition);
+ Assert.True(smooth.Frames[^1].IsHeld, "the last frame has no successor to blend towards");
+ AssertExactDurations(smooth);
+ }
+
+ [Test]
+ public void FitToSecondsScalesThePlan()
+ {
+ var shorter = RenderPlan.Build(Regular(100), Timing(TimingMode.Constant, fit: 2), new Rational(25, 1));
+ Assert.Equal(50, shorter.SlotCount);
+ Assert.Equal(180_000L, shorter.Duration90k);
+ Assert.True(shorter.Frames.All(f => f.Fraction == 0 && f.SourcePosition % 2 == 0));
+ Assert.Equal(50, shorter.Statistics.SkippedFrames);
+ Assert.Approximately(2.0, shorter.Statistics.MaximumSpeed, 1e-9);
+
+ var longer = RenderPlan.Build(Regular(100), Timing(TimingMode.Interpolated, fit: 7.96), new Rational(25, 1));
+ Assert.Equal(199, longer.SlotCount);
+ Assert.Equal(716_400L, longer.Duration90k);
+ Assert.Greater(longer.Statistics.InterpolatedFrames, 90);
+ AssertExactDurations(longer);
+ }
+
+ [Test]
+ public void AdaptiveFollowsCaptureTimeAndShortensPauses()
+ {
+ var times = Regular(40);
+ for (var i = 11; i < 40; i++) times[i] = times[i]!.Value.AddSeconds(10); // 2× interval into frame 11
+ for (var i = 21; i < 40; i++) times[i] = times[i]!.Value.AddSeconds(60); // 7× gap into frame 21
+ for (var i = 31; i < 40; i++) times[i] = times[i]!.Value.AddHours(1); // deliberate pause into frame 31
+ var plan = RenderPlan.Build(times, Timing(TimingMode.Adaptive), new Rational(24, 1));
+ Assert.Equal(40, plan.Frames.Count);
+ Assert.Equal(2, plan.Frames[10].Slots);
+ Assert.Equal(4, plan.Frames[20].Slots); // 3 + log2(7/3) = 4.22 periods, rounded on the grid
+ Assert.Equal(5, plan.Frames[30].Slots); // 0.2 s × 24 fps = 4.8 periods
+ Assert.True(plan.Frames.Where((_, i) => i is not (10 or 20 or 30)).All(f => f.Slots == 1));
+ Assert.False(plan.IsCutBefore(11));
+ Assert.True(plan.IsCutBefore(21));
+ Assert.True(plan.IsCutBefore(31));
+ Assert.Equal(-1, plan.NextContinuous(30));
+ Assert.Equal(29, plan.PreviousContinuous(30));
+ Assert.Equal(2, plan.Statistics.Cuts);
+ Assert.Approximately(10.0, plan.Statistics.MedianIntervalSeconds!.Value, 1e-9);
+ AssertExactDurations(plan);
+ }
+
+ [Test]
+ public void InterpolatedFillsMissingAndExcludedFrames()
+ {
+ var times = Regular(40);
+ for (var i = 20; i < 40; i++) times[i] = times[i]!.Value.AddSeconds(10); // one capture missing before frame 20
+ for (var i = 35; i < 40; i++) times[i] = times[i]!.Value.AddSeconds(600); // too long to synthesise
+ var plan = RenderPlan.Build(times, Timing(TimingMode.Interpolated, excluded: [30]), new Rational(30, 1));
+ var gap = plan.Frames.Single(f => f.From == 19 && f.IsInterpolated);
+ Assert.Equal(19.5, gap.SourcePosition);
+ Assert.Equal(20, gap.To);
+ var excluded = plan.Frames.Single(f => f.From == 29 && f.IsInterpolated);
+ Assert.Equal(30.0, excluded.SourcePosition);
+ Assert.Equal(31, excluded.To);
+ Assert.Equal(0.5, excluded.Fraction);
+ Assert.True(plan.IsCutBefore(35));
+ Assert.False(plan.Frames.Any(f => f.From == 34 && f.IsInterpolated));
+ Assert.Equal(41, plan.Frames.Count);
+ AssertExactDurations(plan);
+ }
+
+ [Test]
+ public void RemapIsMonotoneEvenForBadCurves()
+ {
+ var ease = RenderPlan.Build(Regular(120), Timing(TimingMode.Remapped, curve: [new(0, 0), new(0.5, 0.2), new(1, 1)]), new Rational(24, 1));
+ AssertExactDurations(ease);
+ Assert.Equal(120, ease.SlotCount);
+ Assert.Equal(0.0, ease.Frames[0].SourcePosition);
+ Assert.Greater(ease.Frames[^1].SourcePosition, 115);
+ Assert.Less(ease.Frames[^1].Speed * ease.Frames[^1].Slots, 3.5);
+ Assert.Less(ease.Frames[10].Speed, 0.5);
+ Assert.Empty(ease.Warnings);
+
+ var bad = RenderPlan.Build(Regular(60), Timing(TimingMode.Remapped, curve: [new(1, 1), new(0, 0.1), new(0.4, 0.8), new(0.6, 0.3)]), new Rational(24, 1));
+ Assert.Contains("Export.Plan.RemapNotMonotonic", bad.Warnings);
+ AssertExactDurations(bad);
+ Assert.Approximately(0.1 * 60, bad.Frames[0].SourcePosition, 1e-9);
+ }
+
+ [Test]
+ public void AnUnreadablePlaybackRateFallsBackToTheOutputRate()
+ {
+ var plan = RenderPlan.Build(Regular(10), Timing(TimingMode.Constant, playback: "fast"), new Rational(25, 1));
+ Assert.Contains("Export.Plan.FrameRateIgnored", plan.Warnings);
+ Assert.Equal(10, plan.SlotCount);
+ Assert.Equal(25.0, plan.PlaybackRate);
+ }
+
+ [Test]
+ public void EverythingExcludedGivesAnEmptyPlan()
+ {
+ var plan = RenderPlan.Build(Regular(3), Timing(TimingMode.Constant, excluded: [0, 1, 2]), new Rational(30, 1));
+ Assert.Empty(plan.Frames);
+ Assert.Equal(0L, plan.Duration90k);
+ Assert.Contains("Export.Plan.NoFrames", plan.Warnings);
+ }
+
+ [Test]
+ public void AdaptiveWithoutCaptureTimesFallsBackToConstantPacing()
+ {
+ var plan = RenderPlan.Build(new DateTime?[12], Timing(TimingMode.Adaptive), new Rational(30, 1));
+ Assert.Equal(12, plan.Frames.Count);
+ Assert.Contains("Export.Plan.NoCaptureTimes", plan.Warnings);
+ AssertExactDurations(plan);
+ }
+}
diff --git a/tests/Titano.Core.Tests/Render/RenderProcessingTests.cs b/tests/Titano.Core.Tests/Render/RenderProcessingTests.cs
new file mode 100644
index 00000000..442ed4be
--- /dev/null
+++ b/tests/Titano.Core.Tests/Render/RenderProcessingTests.cs
@@ -0,0 +1,371 @@
+using Titano.Core.Analysis;
+using Titano.Core.Diagnostics.Synthetic;
+using Titano.Core.Imaging;
+using Titano.Core.Imaging.Geometry;
+using Titano.Core.Motion;
+using Titano.Core.Project;
+using Titano.Core.Render;
+using Titano.Core.Render.Diagnostics;
+using Titano.Testing;
+using static Titano.Core.Tests.Render.RenderFixture;
+
+namespace Titano.Core.Tests.Render;
+
+public sealed class RenderProcessingTests
+{
+ private readonly TestContext _context;
+
+ public RenderProcessingTests(TestContext context) => _context = context;
+
+ private static ProjectSettings With(ExposureSettings? exposure = null, MotionSettings? motion = null, CameraSettings? camera = null, StackSettings? stack = null,
+ TimingSettings? timing = null) => Plain with
+ {
+ Exposure = exposure ?? Plain.Exposure,
+ Motion = motion ?? new MotionSettings(),
+ Camera = camera ?? new CameraSettings(),
+ Stack = stack ?? new StackSettings(),
+ Timing = timing ?? new TimingSettings(),
+ };
+
+ private static Auto On(T value) => new Auto().WithManual(value);
+
+ private static double[] LogLuminance(IEnumerable frames) => [.. frames.Select(f => FrameStatistics.MeasureLogLuminance(f))];
+
+ private static double Rms(IEnumerable values)
+ {
+ var v = values.ToArray();
+ var mean = v.Average();
+ return Math.Sqrt(v.Sum(x => (x - mean) * (x - mean)) / v.Length);
+ }
+
+ /// The §20.4 deflicker gate measured on rendered frames (same recipe as the analysis gate).
+ [Test]
+ public async Task DeflickerRemovesFlickerAndKeepsTheRamp()
+ {
+ var source = Source(200, configure: o => o with { Seed = 3, StartEv = -2, EndEv = 1, FlickerEv = 0.1 });
+ var project = With(new ExposureSettings { Deflicker = On(true), DeflickerWindow = On(21), HighlightKnee = null });
+ var (encode, _) = await CaptureAsync(Input(source, project), cancellationToken: _context.Cancellation);
+ var truth = source.Sequence.SceneEv;
+ var measured = Analysis.AnalysisFixtures.MeasureSeries(source.Sequence);
+ var output = LogLuminance(encode.Frames);
+ var before = Analysis.AnalysisFixtures.FrameToFrameResidualRms(measured, truth);
+ var after = Analysis.AnalysisFixtures.FrameToFrameResidualRms(output, truth);
+ var rampError = Analysis.AnalysisFixtures.MaxDeviation(output, truth);
+ _context.Log($"flicker {before:F4} → {after:F4} EV ({1 - after / before:P0}); max ramp deviation {rampError:F4} EV");
+ Assert.GreaterOrEqual(1 - after / before, 0.6);
+ Assert.LessOrEqual(rampError, 0.05);
+ }
+
+ [Test]
+ public async Task HolyGrailTurnsExposureStepsIntoRamps()
+ {
+ var source = Source(80, configure: o => o with { ExposureSteps = [new SyntheticExposureStep(40, 1.0)], StartEv = 0, EndEv = 0 });
+ var project = With(new ExposureSettings { HolyGrail = On(true), Deflicker = On(true), HighlightKnee = null });
+ var (encode, _) = await CaptureAsync(Input(source, project), cancellationToken: _context.Cancellation);
+ var output = LogLuminance(encode.Frames);
+ var steps = output.Zip(output.Skip(1), (a, b) => Math.Abs(b - a)).ToArray();
+ _context.Log($"largest output step {steps.Max():F3} EV");
+ Assert.LessOrEqual(steps.Max(), 0.3 + 0.02);
+ Assert.Approximately(-1.0, output[^1] - output[0], 0.1, "the step is kept, only spread out");
+ }
+
+ [Test]
+ public async Task ExcludedFramesDoNotCreateExposureSteps()
+ {
+ // Frame 10 is a test shot one stop darker; excluding it must leave no holy-grail step behind.
+ var source = Source(30, configure: o => o with { ExposureSteps = [new SyntheticExposureStep(10, 1.0), new SyntheticExposureStep(11, -1.0)], StartEv = 0, EndEv = 0 });
+ var project = With(new ExposureSettings { HolyGrail = On(true), HighlightKnee = null });
+ var all = await RenderPreparation.PrepareAsync(Input(source, project), cancellationToken: _context.Cancellation);
+ var excluded = await RenderPreparation.PrepareAsync(Input(source, project with { ExcludedFrames = [10] }), cancellationToken: _context.Cancellation);
+ Assert.Count(2, all.Report.Transitions);
+ Assert.Empty(excluded.Report.Transitions);
+ Assert.True(double.IsNaN(excluded.MeasuredLogLuminance[10]));
+ }
+
+ [Test]
+ public async Task WhiteBalanceSmoothingRemovesColourJitter()
+ {
+ var source = Source(48, configure: o => o with { WhiteBalanceJitter = 0.1 });
+ var (encode, _) = await CaptureAsync(Input(source, With(new ExposureSettings { WhiteBalanceSmoothing = On(true), HighlightKnee = null })), cancellationToken: _context.Cancellation);
+ double Ratio(ImageBuffer f)
+ {
+ var stats = FrameStatistics.Measure(f);
+ return Math.Log2(stats.MeanRed / stats.MeanGreen);
+ }
+ var before = Enumerable.Range(0, 48).Select(i =>
+ {
+ using var f = source.Sequence.Render(i);
+ return Ratio(f);
+ }).ToArray();
+ var after = encode.Frames.Select(Ratio).ToArray();
+ double Jitter(double[] r) => Rms(r.Zip(r.Skip(1), (a, b) => b - a));
+ _context.Log($"R/G jitter {Jitter(before):F4} → {Jitter(after):F4}");
+ Assert.Less(Jitter(after), 0.3 * Jitter(before));
+ }
+
+ [Test]
+ public async Task RegionDeflickerCorrectsSkyAndLandSeparately()
+ {
+ var source = Source(48, configure: o => o with { SkyFlickerEv = 0.3, LandFlickerEv = 0.3, StartEv = 0, EndEv = 0 });
+ var landMask = new float[96 * 64];
+ for (var y = 0; y < 64; y++)
+ {
+ for (var x = 0; x < 96; x++) landMask[y * 96 + x] = source.Sequence.IsSky(x, y) ? 0 : 1;
+ }
+ double LandResidual(List frames) => Rms(frames.Select(f => FrameStatistics.MeasureLogLuminance(f, landMask)));
+ var global = await CaptureAsync(Input(source, With(new ExposureSettings { Deflicker = On(true), HighlightKnee = null })), cancellationToken: _context.Cancellation);
+ var regions = await CaptureAsync(Input(source, With(new ExposureSettings { Deflicker = On(true), Regions = On(RegionMode.Horizon), HighlightKnee = null })),
+ cancellationToken: _context.Cancellation);
+ var g = LandResidual(global.Encode.Frames);
+ var r = LandResidual(regions.Encode.Frames);
+ _context.Log($"land residual global {g:F3} EV, regions {r:F3} EV");
+ Assert.Less(r, 0.5 * g);
+ var prepared = await RenderPreparation.PrepareAsync(Input(source, With(new ExposureSettings { Deflicker = On(true), Regions = On(RegionMode.Horizon) })),
+ cancellationToken: _context.Cancellation);
+ Assert.Equal(RegionMethod.Horizon, prepared.Report.RegionMethod);
+ Assert.NotNull(prepared.SkyEv);
+ }
+
+ [Test]
+ public async Task ExportAspectCropsTheCentreAndCameraCropMovesIt()
+ {
+ var source = Source(4);
+ using var reference = source.Sequence.Render(2);
+ var (square, _) = await CaptureAsync(Input(source), Preset("png-sequence", 64, 64), cancellationToken: _context.Cancellation);
+ using (var expected = GeometryStage.Apply(reference, new GeometrySettings { Crop = new RectD(16, 0, 64, 64), OutputWidth = 64, OutputHeight = 64 }))
+ Assert.Greater(Psnr(expected, square.Frames[2]), 60);
+
+ var quarter = With(camera: new CameraSettings { Crop = [0.5, 0.5, 0.5, 0.5] });
+ var (corner, result) = await CaptureAsync(Input(source, quarter), Preset("png-sequence", 0, 0), cancellationToken: _context.Cancellation);
+ Assert.Equal((48, 32), (result.Width, result.Height));
+ using (var expected = GeometryStage.Apply(reference, new GeometrySettings { Crop = new RectD(48, 32, 48, 32) }))
+ Assert.Greater(Psnr(expected, corner.Frames[2]), 60);
+ }
+
+ [Test]
+ public async Task VirtualCameraZoomsAndTheDecodeSizeFollowsTheNeed()
+ {
+ var plain = Source(4, width: 480, height: 320);
+ await CaptureAsync(Input(plain), Preset("png-sequence", 96, 64), cancellationToken: _context.Cancellation);
+ Assert.Equal(96, plain.LargestRenderRequest);
+
+ var zoomed = Source(4, width: 480, height: 320);
+ var camera = With(camera: new CameraSettings { Keyframes = [new CameraKey(0, 0.5, 0.5, 2, 0), new CameraKey(3, 0.5, 0.5, 2, 0)] });
+ var (encode, _) = await CaptureAsync(Input(zoomed, camera), Preset("png-sequence", 96, 64), cancellationToken: _context.Cancellation);
+ Assert.Equal(192, zoomed.LargestRenderRequest);
+ var capped = Source(4, width: 480, height: 320);
+ await CaptureAsync(Input(capped, camera), Preset("png-sequence", 96, 64), new RenderOptions { MaxWorkingLongEdge = 120 }, _context.Cancellation);
+ Assert.Equal(120, capped.LargestRenderRequest);
+ using var full = zoomed.Sequence.Render(1);
+ using var expected = GeometryStage.Apply(full, new GeometrySettings { Crop = new RectD(120, 80, 240, 160), OutputWidth = 96, OutputHeight = 64 });
+ var psnr = Psnr(expected, encode.Frames[1]);
+ _context.Log($"zoom ×2 vs direct crop: {psnr:F1} dB");
+ Assert.Greater(psnr, 28);
+ }
+
+ [Test]
+ public async Task ExposureOffsetAndKneeAreApplied()
+ {
+ var source = Source(3, configure: o => o with { StartEv = 2, EndEv = 2 });
+ var (raw, _) = await CaptureAsync(Input(source), cancellationToken: _context.Cancellation);
+ var (brighter, _) = await CaptureAsync(Input(source, With(new ExposureSettings { ExposureOffsetEv = 1, HighlightKnee = null })), cancellationToken: _context.Cancellation);
+ for (var i = 0; i < raw.Frames[0].Data.Length; i += 13) Assert.Approximately(2 * raw.Frames[0].Data[i], brighter.Frames[0].Data[i], 1e-5);
+ Assert.Greater(raw.Frames[0].Data.ToArray().Max(), 1f);
+
+ var (kneed, _) = await CaptureAsync(Input(source, With(new ExposureSettings { HighlightKnee = 0.8 })), cancellationToken: _context.Cancellation);
+ Assert.Less(kneed.Frames[0].Data.ToArray().Max(), 1f);
+ for (var i = 0; i < raw.Frames[0].Data.Length; i += 13)
+ {
+ if (raw.Frames[0].Data[i] < 0.5f) Assert.Approximately(raw.Frames[0].Data[i], kneed.Frames[0].Data[i], 1e-6);
+ }
+ }
+
+ [Test]
+ public async Task InterpolatedFramesFollowTheMotion()
+ {
+ Func pan = i => (2.0 * i, 0);
+ var source = Source(6, motion: pan, configure: o => o with { StartEv = 0, EndEv = 0 });
+ var timing = new TimingSettings { Mode = On(TimingMode.Interpolated), FrameRate = new Auto().WithManual("15") };
+ var export = Preset("png-sequence") with { FrameRate = new Titano.Core.Video.Rational(30, 1) };
+ var (encode, result) = await CaptureAsync(Input(source, With(timing: timing)), export, cancellationToken: _context.Cancellation);
+ Assert.Equal(11, result.FrameCount);
+ Assert.Equal(12, encode.Durations.Sum() / 3000);
+ var truth = Source(6, motion: i => (2.0 * i + 1, 0), configure: o => o with { StartEv = 0, EndEv = 0 });
+ using var shifted = await truth.GetFrameAsync(2, 0, DecodePurpose.Render, _context.Cancellation);
+ double Interior(ImageBuffer a, ImageBuffer b)
+ {
+ using var ca = GeometryStage.Apply(a, new GeometrySettings { Crop = new RectD(12, 4, 72, 56) });
+ using var cb = GeometryStage.Apply(b, new GeometrySettings { Crop = new RectD(12, 4, 72, 56) });
+ return Psnr(ca, cb);
+ }
+ var synthesised = Interior(shifted, encode.Frames[5]);
+ var nearest = Interior(shifted, encode.Frames[4]);
+ _context.Log($"synthesised frame {synthesised:F1} dB vs nearest whole frame {nearest:F1} dB");
+ Assert.Greater(synthesised, 30);
+ Assert.Greater(synthesised, nearest + 5);
+ }
+
+ [Test]
+ public async Task MotionBlurSmearsAlongTheMotionOnly()
+ {
+ var blur = new MotionSettings { MotionBlur = On(true), TargetShutterAngle = On(360.0) };
+ var moving = Source(6, motion: i => (3.0 * i, 0), configure: o => o with { StartEv = 0, EndEv = 0 });
+ var sharp = await CaptureAsync(Input(moving), cancellationToken: _context.Cancellation);
+ var blurred = await CaptureAsync(Input(moving, With(motion: blur)), cancellationToken: _context.Cancellation);
+ double Gradient(ImageBuffer f, int dx, int dy)
+ {
+ double sum = 0;
+ var g = f.Plane(1);
+ for (var y = 8; y < f.Height - 8; y++)
+ {
+ for (var x = 8; x < f.Width - 8; x++) sum += Math.Abs(g[y * f.Width + x] - g[(y + dy) * f.Width + x + dx]);
+ }
+ return sum;
+ }
+ var horizontal = Gradient(blurred.Encode.Frames[3], 1, 0) / Gradient(sharp.Encode.Frames[3], 1, 0);
+ var vertical = Gradient(blurred.Encode.Frames[3], 0, 1) / Gradient(sharp.Encode.Frames[3], 0, 1);
+ _context.Log($"gradient ratios: horizontal {horizontal:F3}, vertical {vertical:F3}");
+ Assert.Less(horizontal, 0.75);
+ Assert.Greater(vertical, horizontal + 0.1);
+
+ var still = Source(6, configure: o => o with { StartEv = 0, EndEv = 0 });
+ var a = await CaptureAsync(Input(still), cancellationToken: _context.Cancellation);
+ var b = await CaptureAsync(Input(still, With(motion: blur)), cancellationToken: _context.Cancellation);
+ Assert.Greater(Psnr(a.Encode.Frames[3], b.Encode.Frames[3]), 40);
+ }
+
+ [Test]
+ public async Task StabilisationRemovesShake()
+ {
+ var random = new Random(11);
+ var shake = Enumerable.Range(0, 24).Select(_ => (X: random.NextDouble() * 6 - 3, Y: random.NextDouble() * 6 - 3)).ToArray();
+ var source = new PatternFrameSource(320, 192, 24, i => shake[i]);
+ var project = With(motion: new MotionSettings { Stabilize = On(true), StabilizeSmoothing = On(12.0) });
+ var input = new RenderInput { Source = source, Frames = source.Metadata(), Project = project };
+
+ static double Steps(IReadOnlyList<(double X, double Y)> p) =>
+ Math.Sqrt(Enumerable.Range(1, p.Count - 1).Average(k => Math.Pow(p[k].X - p[k - 1].X, 2) + Math.Pow(p[k].Y - p[k - 1].Y, 2)));
+ var prepared = await RenderPreparation.PrepareAsync(input, cancellationToken: _context.Cancellation);
+ var residual = Enumerable.Range(0, 24).Select(k =>
+ {
+ var (x, y) = prepared.Stabilization![k].Apply(159.5, 95.5);
+ return (shake[k].X + x - 159.5, shake[k].Y + y - 95.5);
+ }).ToArray();
+ _context.Log($"camera path steps {Steps(shake):F2} px → {Steps(residual):F3} px after correction; zoom {prepared.StabilizationZoom:F3}");
+ Assert.Less(Steps(residual), 0.1 * Steps(shake));
+ Assert.InRange(prepared.StabilizationZoom, 1.01, 1.2);
+
+ var (encode, result) = await CaptureAsync(input, Preset("png-sequence", 0, 0), cancellationToken: _context.Cancellation);
+ Assert.Equal((320, 192), (result.Width, result.Height));
+ using var stabilizer = new Stabilizer(320, 192);
+ var output = encode.Frames.Select(f => stabilizer.AddFrame(f).Transform).Skip(1).ToArray();
+ var after = Math.Sqrt(output.Average(m => m.Tx * m.Tx + m.Ty * m.Ty));
+ _context.Log($"rendered frame-to-frame shift {after:F3} px");
+ Assert.Less(after, 0.1 * Steps(shake) * prepared.StabilizationZoom);
+ }
+
+ [Test]
+ public async Task MedianStackRemovesTransientsAndStarTrailsNeverDarken()
+ {
+ var source = Source(9, configure: o => o with { StartEv = 0, EndEv = 0 });
+ var input = Input(source, With(stack: new StackSettings { Mode = StackSetting.Median, Length = 5 })) with { Source = new TransientSource(source, 4) };
+ var (median, _) = await CaptureAsync(input, cancellationToken: _context.Cancellation);
+ Assert.Equal(9, median.Frames.Count);
+ using var clean = source.Sequence.Render(4);
+ Assert.Greater(Psnr(clean, median.Frames[4]), 45);
+
+ var stars = Source(12, motion: i => (1.0 * i, 0), configure: o => o with { StarField = true, StartEv = 0, EndEv = 0, StarCount = 60 });
+ var (trails, _) = await CaptureAsync(Input(stars, With(stack: new StackSettings { Mode = StackSetting.StarTrails, Length = 0 })), cancellationToken: _context.Cancellation);
+ var luminance = LogLuminance(trails.Frames);
+ Assert.Monotonic(luminance);
+ for (var k = 1; k < trails.Frames.Count; k++)
+ {
+ var previous = trails.Frames[k - 1].Data;
+ var current = trails.Frames[k].Data;
+ for (var i = 0; i < current.Length; i++) Assert.True(current[i] >= previous[i] - 1e-6f, $"pixel {i} darkened at frame {k}");
+ }
+ }
+
+ [Test]
+ public async Task PrecomputedAnalysisSkipsTheMeasuringPass()
+ {
+ var source = Source(30, flickerEv: 0.2);
+ var project = With(new ExposureSettings { Deflicker = On(true), HighlightKnee = null });
+ var measured = await RenderPreparation.PrepareAsync(Input(source, project), cancellationToken: _context.Cancellation);
+ Assert.Equal(30, measured.Report.MeasuredFrames);
+ var cached = new PrecomputedAnalysis { LogLuminance = measured.MeasuredLogLuminance };
+ var decodes = source.Decodes;
+ var reused = await RenderPreparation.PrepareAsync(Input(source, project) with { Analysis = cached }, cancellationToken: _context.Cancellation);
+ Assert.Equal(0, reused.Report.MeasuredFrames);
+ Assert.Equal(decodes, source.Decodes);
+ Assert.SequenceEqual(measured.ExposureEv, reused.ExposureEv);
+ var target = measured.TargetLogLuminance();
+ Assert.Approximately(measured.MeasuredLogLuminance[7] + measured.ExposureEv[7], target[7], 1e-12);
+ static double[] Steps(double[] v) => [.. v.Zip(v.Skip(1), (a, b) => b - a)];
+ Assert.Less(Rms(Steps(target)), 0.5 * Rms(Steps(measured.MeasuredLogLuminance)));
+
+ var wrongLength = await RenderPreparation.PrepareAsync(Input(source, project) with { Analysis = new PrecomputedAnalysis { LogLuminance = new double[3] } },
+ cancellationToken: _context.Cancellation);
+ Assert.Equal(30, wrongLength.Report.MeasuredFrames);
+ Assert.SequenceEqual(measured.ExposureEv, wrongLength.ExposureEv);
+
+ var nothing = await RenderPreparation.PrepareAsync(Input(source), cancellationToken: _context.Cancellation);
+ Assert.Equal(0, nothing.Report.MeasuredFrames);
+ Assert.True(nothing.ExposureEv.All(e => e == 0));
+ }
+
+ [Test]
+ public async Task HeldFramesKeepTheirDurationOnConstantRateOutputs()
+ {
+ var source = Source(10, configure: o => o with { TimeShifts = [new SyntheticTimeShift(5, 20)] });
+ var project = With(timing: new TimingSettings { Mode = On(TimingMode.Adaptive) });
+ var export = Preset("mjpeg-avi");
+ var dir = _context.CreateTempDirectory();
+ var result = await Pipeline().RenderAsync(Input(source, project), Target(dir, export), cancellationToken: _context.Cancellation);
+ var avi = AviReader.Read(File.ReadAllBytes(result.OutputPath));
+ Assert.Equal(10, result.FrameCount);
+ Assert.Equal(12, avi.Frames.Count); // frame 4 lasts three periods (30 s ÷ 10 s)
+ Assert.Approximately(12 / 25.0, result.DurationSeconds, 1e-9);
+ }
+
+ [Test]
+ public void SetupReportsGeometryEncoderPlanAndEstimates()
+ {
+ var source = Source(48, width: 480, height: 320);
+ var input = Input(source, With(new ExposureSettings { Deflicker = On(true) }, motion: new MotionSettings { MotionBlur = On(true) }));
+ var setup = Pipeline().Setup(input, Target("/exports", Preset("gif-preview", 480, 270)));
+ Assert.True(setup.Encoder.IsReady);
+ Assert.Equal((480, 270), (setup.Geometry.OutputWidth, setup.Geometry.OutputHeight));
+ Assert.Equal(48, setup.Plan.Frames.Count);
+ Assert.True(setup.NeedsPreparation);
+ var workload = setup.Workload();
+ Assert.Equal(48, workload.FlowFrames);
+ Assert.Equal(48, workload.AnalysisFrames);
+ Assert.Equal(480L * 320, workload.WorkingPixels);
+ var estimate = setup.Estimate();
+ Assert.Greater(estimate.Bytes, 0);
+ Assert.Greater(estimate.Time.TotalSeconds, 0);
+ }
+
+ /// Adds a bright square to one frame (a passing aircraft light).
+ private sealed class TransientSource(IRenderFrameSource inner, int frame) : IRenderFrameSource
+ {
+ public int FrameCount => inner.FrameCount;
+ public int Width => inner.Width;
+ public int Height => inner.Height;
+
+ public async ValueTask GetFrameAsync(int index, int maxLongEdge, DecodePurpose purpose, CancellationToken cancellationToken)
+ {
+ var image = await inner.GetFrameAsync(index, maxLongEdge, purpose, cancellationToken);
+ if (index != frame) return image;
+ for (var c = 0; c < 3; c++)
+ {
+ for (var y = 20; y < 30; y++)
+ {
+ for (var x = 40; x < 50; x++) image[c, x, y] = 1;
+ }
+ }
+ return image;
+ }
+ }
+}
diff --git a/tests/Titano.Core.Tests/Render/SelfTestTests.cs b/tests/Titano.Core.Tests/Render/SelfTestTests.cs
new file mode 100644
index 00000000..38017c76
--- /dev/null
+++ b/tests/Titano.Core.Tests/Render/SelfTestTests.cs
@@ -0,0 +1,68 @@
+using Titano.Core.Render.Diagnostics;
+using Titano.Core.Video;
+using Titano.Testing;
+
+namespace Titano.Core.Tests.Render;
+
+public sealed class SelfTestTests
+{
+ private static readonly string[] Groups = ["plan", "export", "select", "codec", "render", "proc", "robust"];
+
+ private readonly TestContext _context;
+
+ public SelfTestTests(TestContext context) => _context = context;
+
+ [Test]
+ public void ChecksAreUniqueAndGrouped()
+ {
+ Assert.GreaterOrEqual(SelfTest.Checks.Count, 60);
+ Assert.Equal(SelfTest.Checks.Count, SelfTest.Checks.Select(c => c.Id).Distinct().Count());
+ Assert.True(SelfTest.Checks.All(c => Groups.Contains(c.Group) && c.Id.StartsWith(c.Group + ".", StringComparison.Ordinal) && c.Description.Length > 0));
+ Assert.True(Groups.All(g => SelfTest.Checks.Any(c => c.Group == g)));
+ }
+
+ [Test]
+ public async Task FastGroupsPassAndCleanUp()
+ {
+ var work = _context.CreateTempDirectory();
+ var reported = new List();
+ var results = await SelfTest.RunAsync(new SelfTestOptions { WorkDirectory = work, Filters = ["plan.", "export.", "select.", "codec."] },
+ new RenderFixture.Sink(reported.Add), _context.Cancellation);
+ foreach (var r in results.Where(r => r.Outcome != SelfTestOutcome.Passed)) _context.Log($"{r.Id}: {r.Outcome} {r.Detail}");
+ Assert.Equal(SelfTest.Checks.Count(c => c.Group is "plan" or "export" or "select" or "codec"), results.Count);
+ Assert.True(results.All(r => r.Outcome == SelfTestOutcome.Passed));
+ Assert.SequenceEqual(results.Select(r => r.Id), reported.Select(r => r.Id));
+ Assert.Empty(Directory.GetFileSystemEntries(work));
+ }
+
+ [Test]
+ public async Task RenderGroupPassesWithManagedEncoders()
+ {
+ var results = await SelfTest.RunAsync(new SelfTestOptions { WorkDirectory = _context.CreateTempDirectory(), Filters = ["render."] }, cancellationToken: _context.Cancellation);
+ foreach (var r in results) _context.Log($"{r.Id}: {r.Outcome} {r.Detail}");
+ Assert.Equal(SelfTestOutcome.Skipped, results.Single(r => r.Id == "render.mp4").Outcome);
+ Assert.True(results.Where(r => r.Id != "render.mp4").All(r => r.Outcome == SelfTestOutcome.Passed));
+ }
+
+ [Test]
+ public async Task FailuresAreReportedNotThrown()
+ {
+ // An "MP4 encoder" that writes nothing: the inspection of its missing file must fail the check, not the run.
+ var fake = new CapturingEncoderProvider("fake", new EncoderCapability(VideoCodec.H264, "Fake H.264", true, 4096, 4096, false));
+ var results = await SelfTest.RunAsync(new SelfTestOptions { WorkDirectory = _context.CreateTempDirectory(), Filters = ["render.mp4"], PlatformEncoders = [fake] },
+ cancellationToken: _context.Cancellation);
+ var result = results.Single();
+ Assert.Equal(SelfTestOutcome.Failed, result.Outcome);
+ Assert.Contains("FileNotFoundException", result.Detail);
+ }
+
+ [Test]
+ public async Task CancellationStopsTheRunAndCleansUp()
+ {
+ var work = _context.CreateTempDirectory();
+ using var cts = CancellationTokenSource.CreateLinkedTokenSource(_context.Cancellation);
+ var progress = new RenderFixture.Sink(_ => cts.Cancel());
+ await Assert.ThrowsAsync(() => SelfTest.RunAsync(new SelfTestOptions { WorkDirectory = work, Filters = ["plan."] }, progress, cts.Token));
+ Assert.Empty(Directory.GetFileSystemEntries(work));
+ }
+}