diff --git a/src/Chronos.Core/Export/ExportNaming.cs b/src/Chronos.Core/Export/ExportNaming.cs
index a780255c..eee6331a 100644
--- a/src/Chronos.Core/Export/ExportNaming.cs
+++ b/src/Chronos.Core/Export/ExportNaming.cs
@@ -126,6 +126,37 @@ public static class ExportNaming
return OutputPath(string.IsNullOrWhiteSpace(settings.Folder) ? sequenceExportsFolder : settings.Folder, settings.NameTemplate, context, taken);
}
+ ///
+ /// The name of a still (owner review 1, R8, "Save frame"): the expanded , " - " and the 1-based
+ /// number of source frame in at least four digits, "2026-09-28 Harbour - 4K HEVC - 0123".
+ ///
+ public static string StillName(string template, ExportNameContext context, int frameIndex)
+ {
+ ArgumentOutOfRangeException.ThrowIfNegative(frameIndex);
+ var name = Expand(template, context).Name;
+ return PathTemplate.SanitizeSegment(string.Create(CultureInfo.InvariantCulture, $"{name} - {frameIndex + 1:D4}"));
+ }
+
+ ///
+ /// Full path of a still inside : plus the image extension of the codec
+ /// (one file, never a folder), made unique like .
+ ///
+ public static string StillPath(string folder, string template, ExportNameContext context, int frameIndex, Func? taken = null)
+ {
+ ArgumentException.ThrowIfNullOrWhiteSpace(folder);
+ return Unique(folder, StillName(template, context, frameIndex), VideoCodecInfo.FileExtension(context.Codec), taken);
+ }
+
+ ///
+ /// Path of a still of a project's export: or, when unset, the sequence's exports
+ /// folder, named by and the frame number.
+ ///
+ public static string StillPath(ExportSettings settings, string sequenceExportsFolder, ExportNameContext context, int frameIndex, Func? taken = null)
+ {
+ ArgumentNullException.ThrowIfNull(settings);
+ return StillPath(string.IsNullOrWhiteSpace(settings.Folder) ? sequenceExportsFolder : settings.Folder, settings.NameTemplate, context, frameIndex, taken);
+ }
+
/// "name.ext", or "name (2).ext", "name (3).ext"… when a file or folder of that name exists or is .
public static string Unique(string folder, string name, string extension, Func? taken = null)
{
diff --git a/src/Chronos.Core/Render/FrameFinish.cs b/src/Chronos.Core/Render/FrameFinish.cs
index 757267ed..5044ff8f 100644
--- a/src/Chronos.Core/Render/FrameFinish.cs
+++ b/src/Chronos.Core/Render/FrameFinish.cs
@@ -1,4 +1,6 @@
using System.Globalization;
+using System.Numerics;
+using System.Runtime.InteropServices;
using Chronos.Core.Analysis;
using Chronos.Core.Imaging;
using Chronos.Core.Imaging.Color;
@@ -58,4 +60,27 @@ public static class FrameFinish
if (look is { IsIdentity: false } && LookFilter.IsKnown(look.Filter)) LookFilter.Apply(frame, look.Filter, Strength(look));
if (knee is > 0 and < 1 and var k) ExposureProcessor.Apply(frame, 0, null, k);
}
+
+ ///
+ /// The fade to and from black of the output program (owner review 1, R8; ): every sample
+ /// of the finished linear-light multiplied by , in place. It runs after
+ /// , so neither the look nor the knee sees a darkened frame. A gain of 1 or more (or not finite)
+ /// leaves the frame as it is; 0 or less makes it black.
+ ///
+ public static void Fade(ImageBuffer frame, double gain)
+ {
+ ArgumentNullException.ThrowIfNull(frame);
+ if (!double.IsFinite(gain) || gain >= 1) return;
+ var data = frame.Data;
+ if (gain <= 0)
+ {
+ data.Clear();
+ return;
+ }
+ var factor = (float)gain;
+ var vectors = MemoryMarshal.Cast>(data);
+ var scale = new Vector(factor);
+ for (var i = 0; i < vectors.Length; i++) vectors[i] *= scale;
+ for (var i = vectors.Length * Vector.Count; i < data.Length; i++) data[i] *= factor;
+ }
}
diff --git a/src/Chronos.Core/Render/OutputProgram.cs b/src/Chronos.Core/Render/OutputProgram.cs
index 2e447414..1221d21d 100644
--- a/src/Chronos.Core/Render/OutputProgram.cs
+++ b/src/Chronos.Core/Render/OutputProgram.cs
@@ -1,3 +1,4 @@
+using Chronos.Core.Imaging;
using Chronos.Core.Project;
using Chronos.Core.Video;
@@ -21,8 +22,9 @@ public readonly record struct ProgramEntry(int PlanIndex, long Duration90k, doub
/// time grows with .
///
///
-/// Phase 5 groundwork: the API is final; emits
-/// the plan forward once, without fades or hold, until the output program parcel completes it.
+/// Durations stay on the plan's 90 kHz values: a pass sums to the plan's duration and the hold is a whole number of output
+/// periods, so constant-rate outputs keep their grid. The fade gain of an entry is taken at its start inside the fade in and
+/// at its end inside the fade out, so the first and the last emitted frames are black.
///
public sealed class OutputProgram
{
@@ -73,9 +75,96 @@ public sealed class OutputProgram
ArgumentNullException.ThrowIfNull(frames);
if (frameRate.Numerator <= 0 || frameRate.Denominator <= 0) throw new ArgumentOutOfRangeException(nameof(frameRate));
var warnings = new List();
- if (playback?.Direction is { } direction && !PlaybackDirection.IsKnown(direction)) warnings.Add(new RenderWarning(DirectionUnknownWarning, direction));
- var entries = new ProgramEntry[frames.Count];
- for (var i = 0; i < frames.Count; i++) entries[i] = new ProgramEntry(i, frames[i].Duration90k, 1);
- return new OutputProgram(entries, warnings);
+ if (playback?.Direction is { } unknown && !PlaybackDirection.IsKnown(unknown)) warnings.Add(new RenderWarning(DirectionUnknownWarning, unknown));
+ if (frames.Count == 0) return new OutputProgram([], warnings);
+ playback ??= new PlaybackSettings();
+
+ // The passes: plan indices in emission order, each frame for its planned duration.
+ var entries = new List(frames.Count * playback.EffectiveLoops);
+ var direction = frames.Count == 1 ? PlaybackDirection.Forward : playback.EffectiveDirection;
+ for (var pass = 0; pass < playback.EffectiveLoops; pass++)
+ {
+ switch (direction)
+ {
+ case PlaybackDirection.Reverse:
+ for (var i = frames.Count - 1; i >= 0; i--) entries.Add(new ProgramEntry(i, frames[i].Duration90k, 1));
+ break;
+ case PlaybackDirection.Boomerang:
+ // The turning frame plays once, and a later pass starts after the first frame the previous one ended on.
+ for (var i = pass == 0 ? 0 : 1; i < frames.Count; i++) entries.Add(new ProgramEntry(i, frames[i].Duration90k, 1));
+ for (var i = frames.Count - 2; i >= 0; i--) entries.Add(new ProgramEntry(i, frames[i].Duration90k, 1));
+ break;
+ default:
+ for (var i = 0; i < frames.Count; i++) entries.Add(new ProgramEntry(i, frames[i].Duration90k, 1));
+ break;
+ }
+ }
+
+ // The hold: whole output periods added to the last frame.
+ if (playback.EffectiveHoldEnd > 0)
+ {
+ var periods = long.Max(1, (long)double.Round(playback.EffectiveHoldEnd * frameRate.Value));
+ var last = entries[^1];
+ entries[^1] = last with { Duration90k = last.Duration90k + RenderPlan.TicksAt(frameRate, periods) };
+ }
+
+ long total = 0;
+ foreach (var entry in entries) total += entry.Duration90k;
+ var fadeIn = (long)double.Round(playback.EffectiveFadeIn * 90000);
+ var fadeOut = (long)double.Round(playback.EffectiveFadeOut * 90000);
+ if (fadeIn + fadeOut == 0) return new OutputProgram(entries, warnings);
+ if (fadeIn + fadeOut > total / 2)
+ {
+ // Both fades shrink by the same factor until together they take half of the program.
+ var scale = (double)(total / 2) / (fadeIn + fadeOut);
+ fadeIn = (long)double.Floor(fadeIn * scale);
+ fadeOut = (long)double.Floor(fadeOut * scale);
+ warnings.Add(new RenderWarning(FadesShortenedWarning));
+ }
+ return new OutputProgram(Faded(entries, total, fadeIn, fadeOut, frameRate), warnings);
+ }
+
+ ///
+ /// The entries with the fade gains: an entry that reaches into a fade is split into its output periods (a held frame
+ /// otherwise keeps one gain for its whole time), and each part takes the gain of its own time.
+ ///
+ private static List Faded(List entries, long total, long fadeIn, long fadeOut, Rational frameRate)
+ {
+ var period = 90000.0 * frameRate.Denominator / frameRate.Numerator;
+ var faded = new List(entries.Count);
+ long start = 0;
+ foreach (var entry in entries)
+ {
+ var end = start + entry.Duration90k;
+ if (start >= fadeIn && end <= total - fadeOut)
+ {
+ faded.Add(entry);
+ start = end;
+ continue;
+ }
+ var parts = int.Max(1, (int)double.Round(entry.Duration90k / period));
+ long previous = 0;
+ for (var part = 1; part <= parts; part++)
+ {
+ var boundary = (long)double.Round((double)entry.Duration90k * part / parts);
+ if (boundary == previous) continue;
+ faded.Add(new ProgramEntry(entry.PlanIndex, boundary - previous, Gain(start + previous, start + boundary, total, fadeIn, fadeOut)));
+ previous = boundary;
+ }
+ start = end;
+ }
+ return faded;
+ }
+
+ ///
+ /// The linear gain of the time from to : the fade in at its start, the fade
+ /// out at its end, the darker of the two, through the sRGB curve so the ramp looks even.
+ ///
+ private static double Gain(long start, long end, long total, long fadeIn, long fadeOut)
+ {
+ var level = 1.0;
+ if (fadeIn > 0 && start < fadeIn) level = double.Min(level, (double)start / fadeIn);
+ if (fadeOut > 0 && end > total - fadeOut) level = double.Min(level, (double)(total - end) / fadeOut);
+ return level >= 1 ? 1 : ColorSpace.SrgbToLinear(double.Clamp(level, 0, 1));
}
}
diff --git a/src/Chronos.Core/Render/RenderModels.cs b/src/Chronos.Core/Render/RenderModels.cs
index 00b4691a..2348b46a 100644
--- a/src/Chronos.Core/Render/RenderModels.cs
+++ b/src/Chronos.Core/Render/RenderModels.cs
@@ -21,8 +21,18 @@ public sealed record RenderInput
}
/// 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);
+/// Full path of the file, or of the folder for image sequences (see );
+/// for a still, the image file ().
+///
+/// Owner review 1, R8, "Save frame": the source frame saved as one image (PNG, JPEG or TIFF, )
+/// at the export's output size, with every correction and look, without stacking, interpolation, motion blur or playback;
+/// null renders the video.
+///
+public sealed record RenderTarget(ResolvedExport Export, string OutputPath, int? StillFrame = null)
+{
+ /// The target saves one frame as an image ().
+ public bool IsStill => StillFrame is not null;
+}
/// Tuning of a render that is not part of the project.
public sealed record RenderOptions
diff --git a/src/Chronos.Core/Render/RenderPipeline.cs b/src/Chronos.Core/Render/RenderPipeline.cs
index 1728a7f9..c5e70dd4 100644
--- a/src/Chronos.Core/Render/RenderPipeline.cs
+++ b/src/Chronos.Core/Render/RenderPipeline.cs
@@ -16,7 +16,9 @@ namespace Chronos.Core.Render;
/// 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 finish (look, then highlight knee: ) come last, then the encoder. Encoding of a
+/// composition; stacking (median, mean, star trails) and the finish (look, then highlight knee, then the fade:
+/// ) come last, then the encoder. Frames are rendered in the order of the
+/// (direction, loops, hold, fades); a still target renders one source frame into one image. 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.
///
@@ -60,7 +62,7 @@ public sealed class RenderPipeline(IReadOnlyList encoders
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.");
+ if (setup.Still is null && setup.Program.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);
}
@@ -104,6 +106,7 @@ internal sealed class RenderRun : IDisposable
private readonly RenderOptions _options;
private readonly IProgress? _progress;
private readonly RenderPlan _plan;
+ private readonly OutputProgram _program;
private readonly RenderGeometry _geometry;
private readonly PreparedFrameCache _prepared;
private readonly FlowCache _flows = new(2);
@@ -129,6 +132,7 @@ internal sealed class RenderRun : IDisposable
_options = options;
_progress = progress;
_plan = setup.Plan;
+ _program = setup.Program;
_geometry = setup.Geometry;
_prepared = new PreparedFrameCache(int.Max(3, options.CacheFrames));
_workingEdge = _geometry.WorkingLongEdge;
@@ -148,13 +152,16 @@ internal sealed class RenderRun : IDisposable
{
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}");
+ if (_setup.Still is { } still)
+ Log.Info(RenderPipeline.LogCategory, $"Saving frame {still.From} as {settings.Codec} {settings.Width}×{settings.Height}: {settings.OutputPath}");
+ else
+ Log.Info(RenderPipeline.LogCategory, $"Rendering {_program.Count} frames of a {_plan.Frames.Count}-frame plan ({_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));
+ _progress?.Report(new RenderProgress(RenderStage.Finishing, _done, _program.Count, Fps(), _clock.Elapsed, TimeSpan.Zero));
session.Complete();
}
catch
@@ -178,8 +185,9 @@ internal sealed class RenderRun : IDisposable
Width = settings.Width,
Height = settings.Height,
FrameRate = settings.FrameRate,
- DurationSeconds = _plan.DurationSeconds,
- FrameCount = _plan.Frames.Count,
+ DurationSeconds = _setup.Still is null ? _program.DurationSeconds : 0,
+ FrameCount = _program.Count,
+ Kind = _setup.Still is null ? null : Model.RenderKind.Still,
Bytes = RenderResult.SizeOf(settings.OutputPath),
EncoderName = session.EncoderName,
Hardware = session.IsHardware,
@@ -199,6 +207,13 @@ internal sealed class RenderRun : IDisposable
private async Task RenderFramesAsync(CancellationToken cancellationToken)
{
+ if (_setup.Still is { } still)
+ {
+ // Save frame: the one source frame, whole, with every correction and the finish; no stacking and no playback.
+ var picture = await RenderFrameAsync(still, blur: false, cancellationToken).ConfigureAwait(false);
+ await EmitAsync(picture, new ProgramEntry(0, still.Duration90k, 1)).ConfigureAwait(false);
+ return;
+ }
var stack = _input.Project.Stack;
switch (stack.Mode)
{
@@ -206,58 +221,117 @@ internal sealed class RenderRun : IDisposable
await RenderWindowStackAsync(stack, cancellationToken).ConfigureAwait(false);
break;
case StackSetting.StarTrails:
+ // The trails accumulate in program order: a reversed video grows its trails from the end.
using (var trails = new StarTrailStacker(StarTrailStacker.DecayForTrailLength(stack.Length > 0 ? stack.Length : double.PositiveInfinity)))
{
- foreach (var planned in _plan.Frames)
+ await RenderProgramAsync(async (index, token) =>
{
- 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);
- }
+ using (var frame = await RenderFrameAsync(_plan.Frames[index], blur: false, token).ConfigureAwait(false)) trails.Add(frame);
+ return trails.Result!.Clone();
+ }, cancellationToken).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);
- }
+ await RenderProgramAsync((index, token) => RenderFrameAsync(_plan.Frames[index], _setup.MotionBlur, token), cancellationToken).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).
+ ///
+ /// Emits the program's entries in order, each rendered by from its plan index. Consecutive
+ /// entries of one plan frame (a held frame split over the periods of a fade) share one rendering, so a stack folds it
+ /// in once; every other entry is rendered again (a boomerang's way back, each loop).
+ ///
+ private async Task RenderProgramAsync(Func> render, CancellationToken cancellationToken)
+ {
+ var entries = _program.Entries;
+ ImageBuffer? kept = null;
+ try
+ {
+ for (var i = 0; i < entries.Count; i++)
+ {
+ cancellationToken.ThrowIfCancellationRequested();
+ var entry = entries[i];
+ var frame = kept ?? await render(entry.PlanIndex, cancellationToken).ConfigureAwait(false);
+ kept = null;
+ if (i + 1 < entries.Count && entries[i + 1].PlanIndex == entry.PlanIndex)
+ {
+ try
+ {
+ kept = frame.Clone();
+ }
+ catch
+ {
+ frame.Dispose();
+ throw;
+ }
+ }
+ await EmitAsync(frame, entry).ConfigureAwait(false);
+ }
+ }
+ finally
+ {
+ kept?.Dispose();
+ }
+ }
+
+ ///
+ /// Median/mean stacks, one centred window per plan frame whatever the program's order: frame k combines plan frames
+ /// k − half … k + half, cut to the plan at the start and shifted inside it at the end (as a forward render always did).
+ /// Stepping to the next frame in the direction the program travels pushes one frame; a turn or the shrinking window at the
+ /// plan's start fills the window again.
+ ///
private async Task RenderWindowStackAsync(StackSettings stack, CancellationToken cancellationToken)
{
var window = int.Max(1, stack.Length);
var half = (window - 1) / 2;
+ var last = _plan.Frames.Count - 1;
using var stacker = new TemporalStacker(window, stack.Mode == StackSetting.Median ? StackMode.Median : StackMode.Mean);
- var pending = new Queue();
- foreach (var planned in _plan.Frames)
+ // Plan indices in the stacker, oldest (the next evicted) first.
+ var held = new List(window + 1);
+ var previous = -1;
+ await RenderProgramAsync(async (index, token) =>
{
- 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);
+ var hi = int.Min(index + half, last);
+ var lo = int.Max(0, hi - window + 1);
+ await WindowAsync(stacker, held, lo, hi, index >= previous, token).ConfigureAwait(false);
+ previous = index;
+ var output = new ImageBuffer(_geometry.OutputWidth, _geometry.OutputHeight, 3, clear: false);
+ try
+ {
+ stacker.Render(output, token);
+ return output;
+ }
+ catch
+ {
+ output.Dispose();
+ throw;
+ }
+ }, cancellationToken).ConfigureAwait(false);
}
- private async Task EmitStackAsync(TemporalStacker stacker, PlannedFrame planned, CancellationToken cancellationToken)
+ /// Makes the stacker hold exactly plan frames ….
+ private async Task WindowAsync(TemporalStacker stacker, List held, int lo, int hi, bool forward, CancellationToken cancellationToken)
{
- var output = new ImageBuffer(_geometry.OutputWidth, _geometry.OutputHeight, 3, clear: false);
- try
+ bool Holds(IEnumerable frames) => frames.Count() == hi - lo + 1 && frames.All(i => i >= lo && i <= hi);
+ if (Holds(held)) return;
+ var missing = Enumerable.Range(lo, hi - lo + 1).Where(i => !held.Contains(i)).ToList();
+ if (missing.Count == 1 && Holds(held.Skip(held.Count == stacker.Window ? 1 : 0).Append(missing[0])))
{
- stacker.Render(output, cancellationToken);
+ await PushAsync(stacker, held, missing[0], cancellationToken).ConfigureAwait(false);
+ return;
}
- catch
- {
- output.Dispose();
- throw;
- }
- await EmitAsync(output, planned.Duration90k).ConfigureAwait(false);
+ stacker.Clear();
+ held.Clear();
+ // Pushed in the direction of travel, so the next step evicts the frame it leaves behind.
+ for (var k = 0; k <= hi - lo; k++) await PushAsync(stacker, held, forward ? lo + k : hi - k, cancellationToken).ConfigureAwait(false);
+ }
+
+ private async Task PushAsync(TemporalStacker stacker, List held, int index, CancellationToken cancellationToken)
+ {
+ using (var frame = await RenderFrameAsync(_plan.Frames[index], blur: false, cancellationToken).ConfigureAwait(false)) stacker.Push(frame);
+ held.Add(index);
+ if (held.Count > stacker.Window) held.RemoveAt(0);
}
/// The picture of one planned frame at the output size (a new buffer owned by the caller).
@@ -400,14 +474,19 @@ internal sealed class RenderRun : IDisposable
if (ev != 0 || (gains is { } g && g != ChannelGains.Identity)) ExposureProcessor.Apply(frame, ev, gains);
}
- /// Finishes the frame (look, then knee) and hands it to the encoder once the previous frame is encoded; owns .
- private async Task EmitAsync(ImageBuffer frame, long duration90k)
+ ///
+ /// Finishes the frame (look, then knee, then the entry's fade) and hands it to the encoder for the entry's duration once
+ /// the previous frame is encoded; owns .
+ ///
+ private async Task EmitAsync(ImageBuffer frame, ProgramEntry entry)
{
ImageBuffer? preview = null;
+ var duration90k = entry.Duration90k;
try
{
await FlushEncodingAsync().ConfigureAwait(false);
FrameFinish.Apply(frame, _look, _knee);
+ if (entry.Gain < 1) FrameFinish.Fade(frame, entry.Gain);
_done++;
if (_options.PreviewInterval > 0 && (_done - 1) % _options.PreviewInterval == 0) preview = Resampler.Thumbnail(frame, _options.PreviewLongEdge);
}
@@ -424,8 +503,8 @@ internal sealed class RenderRun : IDisposable
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));
+ _progress.Report(new RenderProgress(RenderStage.Rendering, _done, _program.Count, fps, _clock.Elapsed,
+ fps > 0 ? TimeSpan.FromSeconds((_program.Count - _done) / fps) : null, preview));
}
else
{
diff --git a/src/Chronos.Core/Render/RenderResult.cs b/src/Chronos.Core/Render/RenderResult.cs
index c28f1509..b6905d7a 100644
--- a/src/Chronos.Core/Render/RenderResult.cs
+++ b/src/Chronos.Core/Render/RenderResult.cs
@@ -17,11 +17,19 @@ public sealed record RenderResult
public required int Width { get; init; }
public required int Height { get; init; }
public required Rational FrameRate { get; init; }
+
+ /// The video's duration, holds included (); 0 for a still.
public required double DurationSeconds { get; init; }
- /// Output pictures rendered (held frames count once).
+ ///
+ /// Pictures the encoder received (): every pass and loop, a held frame once, or once per
+ /// output period inside a fade; 1 for a still.
+ ///
public required int FrameCount { get; init; }
+ /// : for one frame saved as an image, else null.
+ public string? Kind { get; init; }
+
/// Size of the file, or of every file of a sequence.
public required long Bytes { get; init; }
@@ -46,11 +54,13 @@ public sealed record RenderResult
Codec = Codec.ToString(),
Width = Width,
Height = Height,
- Fps = FrameRate.Value,
- DurationSeconds = DurationSeconds,
+ // A still is recorded with no frame rate and no duration (DECISIONS 2026-11-05, phase 5 (12)).
+ Fps = Kind == Model.RenderKind.Still ? 0 : FrameRate.Value,
+ DurationSeconds = Kind == Model.RenderKind.Still ? 0 : DurationSeconds,
Bytes = Bytes,
Created = DateTimeOffset.UtcNow,
ProducedBy = producedBy,
+ Kind = Kind,
};
/// Bytes of a file, or the total of the files in a folder.
diff --git a/src/Chronos.Core/Render/RenderRules.cs b/src/Chronos.Core/Render/RenderRules.cs
index f89af38e..3d3216c5 100644
--- a/src/Chronos.Core/Render/RenderRules.cs
+++ b/src/Chronos.Core/Render/RenderRules.cs
@@ -29,11 +29,22 @@ public static class RenderRules
return still ? int.Max(format, StillFormat) : format;
}
+ ///
+ /// The settings format a render of needs:
+ /// for its export, a still when is set.
+ ///
+ public static int RequiredFormat(ProjectSettings settings, RenderTarget target, int sourceWidth, int sourceHeight)
+ {
+ ArgumentNullException.ThrowIfNull(target);
+ return RequiredFormat(settings, target.Export, sourceWidth, sourceHeight, target.IsStill);
+ }
+
///
/// The settings format a render of with on a source of the given
- /// (Exif-oriented) size needs: the format the settings are written in (), and
- /// at least 2 when the chosen proportions change a fixed-size preset's size (), which a format-1
- /// program would render at the preset's own ratio.
+ /// (Exif-oriented) size needs: the format the settings are written in (, 3 when
+ /// plays other than forward once, so the settings must carry the export the job
+ /// renders), and at least 2 when the chosen proportions change a fixed-size preset's size (), which
+ /// a format-1 program would render at the preset's own ratio.
///
public static int RequiredFormat(ProjectSettings settings, ResolvedExport export, int sourceWidth, int sourceHeight)
{
diff --git a/src/Chronos.Core/Render/RenderSetup.cs b/src/Chronos.Core/Render/RenderSetup.cs
index 6058b31f..7be7cfd3 100644
--- a/src/Chronos.Core/Render/RenderSetup.cs
+++ b/src/Chronos.Core/Render/RenderSetup.cs
@@ -5,27 +5,44 @@ using Chronos.Core.Video;
namespace Chronos.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.
+/// What a render will do, decided before its first frame: output geometry, encoder (with its adjustments), plan and output
+/// program. The Export tab uses it for the output size, encoder notices, plan chart and estimates; is
+/// what the encoder receives (owner review 1, R8).
///
public sealed record RenderSetup
{
+ private readonly OutputProgram? _program;
+
public required RenderTarget Target { get; init; }
public required RenderGeometry Geometry { get; init; }
public required EncoderSelection Encoder { get; init; }
public required RenderPlan Plan { get; init; }
+ ///
+ /// The frames in the order and for the time they are emitted (owner review 1, R8): the plan played as the export's
+ /// says. A still's program is its one frame. Defaults to the plan forward once.
+ ///
+ public OutputProgram Program
+ {
+ get => _program ?? OutputProgram.Build(Plan, null, Plan.FrameRate);
+ init => _program = value;
+ }
+
+ /// The frame a still target saves (): whole, never interpolated; null for a video.
+ public PlannedFrame? Still { 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.
+ /// Geometry, plan, program and encoder remarks.
public IReadOnlyList Warnings { get; init; } = [];
- /// Decides geometry, encoder and plan for one target.
+ /// Decides geometry, encoder, plan and program for one target.
/// Prepared corrections when available (their stabilisation zoom affects the decode size).
+ /// A still target names a frame the sequence does not have.
public static RenderSetup Create(RenderInput input, RenderTarget target, IReadOnlyList encoders, EncoderHost host,
RenderOptions? options = null, RenderCorrections? corrections = null)
{
@@ -34,21 +51,49 @@ public sealed record RenderSetup
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));
+ if (target.StillFrame is { } wanted && (wanted < 0 || wanted >= input.Source.FrameCount))
+ throw new RenderException("Tooltips.Export.StillNeedsFrame", $"Frame {wanted} is not in the sequence of {input.Source.FrameCount} frames.");
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);
+ var requested = target.Export.ToEncodeSettings(target.OutputPath, geometry.OutputWidth, geometry.OutputHeight);
+ // "TIFF 16-bit" is what Save frame offers, whatever depth the export's video has.
+ if (target.IsStill) requested = requested with { SingleImage = true, BitDepth = requested.Codec == VideoCodec.Tiff16Sequence ? 16 : requested.BitDepth };
+ var selection = EncoderSelector.Select(requested, 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 rate = selection.Settings.FrameRate;
+ var plan = RenderPlan.Build(times, project, rate, 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 = project.Motion.MotionBlur.Resolve(false);
- if (blur && stacking) warnings.Add(new RenderWarning("Export.Render.BlurOffWhileStacking"));
+ OutputProgram program;
+ PlannedFrame? still = null;
+ if (target.StillFrame is { } index)
+ {
+ // One source frame, whole: no stacking, interpolation, blur or playback, so no plan remark applies.
+ still = new PlannedFrame(index, index, index, 0, 0, RenderPlan.TicksAt(rate, 1), 0, 1, 0, PlannedFrameFlags.None);
+ program = OutputProgram.Build([still.Value], null, rate);
+ warnings.AddRange(selection.Notices.Select(n => new RenderWarning(n.Key, n.Args)));
+ blur = false;
+ }
+ else
+ {
+ warnings.AddRange(plan.Warnings.Select(k => new RenderWarning(k)));
+ warnings.AddRange(selection.Notices.Select(n => new RenderWarning(n.Key, n.Args)));
+ if (blur && stacking) warnings.Add(new RenderWarning("Export.Render.BlurOffWhileStacking"));
+ var playback = project.Export.Playback;
+ if (project.Stack.Mode == StackSetting.StarTrails && playback?.EffectiveDirection == PlaybackDirection.Boomerang)
+ {
+ // Trails cannot shrink on the way back, so the video plays forward (DECISIONS 2026-11-05, phase 5 (11)).
+ warnings.Add(new RenderWarning(OutputProgram.BoomerangStackWarning));
+ playback = playback with { Direction = null };
+ }
+ program = OutputProgram.Build(plan, playback, rate);
+ warnings.AddRange(program.Warnings);
+ }
var exposure = project.Exposure;
var measuring = exposure.Deflicker.Resolve(false) || exposure.HolyGrail.Resolve(false)
|| exposure.WhiteBalanceSmoothing.Resolve(false) || project.Motion.Stabilize.Resolve(false);
@@ -58,20 +103,38 @@ public sealed record RenderSetup
Geometry = geometry,
Encoder = selection,
Plan = plan,
+ Program = program,
+ Still = still,
MotionBlur = blur && !stacking,
NeedsPreparation = corrections is null && measuring,
Warnings = warnings,
};
}
- /// The render's workload in the units of .
+ ///
+ /// The render's workload in the units of , from the output program: every pass and loop is
+ /// rendered again, so the time grows with them, and the duration includes the hold. A still is one picture of no duration.
+ ///
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);
+ var program = Program;
+ var flowFrames = 0;
+ if (Still is null)
+ {
+ // A frame split over the periods of a fade is rendered once; every other entry is rendered again.
+ for (var i = 0; i < program.Count; i++)
+ {
+ var entry = program.Entries[i];
+ if (i > 0 && program.Entries[i - 1].PlanIndex == entry.PlanIndex) continue;
+ if (MotionBlur || Plan.Frames[entry.PlanIndex].IsInterpolated) flowFrames++;
+ }
+ }
+ var rate = Encoder.Settings.FrameRate;
+ var periods = Still is null ? (int)double.Round(program.Duration90k * (double)rate.Numerator / (90000.0 * rate.Denominator)) : 1;
+ return new ExportWorkload(program.Count, periods, Still is null ? program.DurationSeconds : 0, 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.
diff --git a/src/Chronos.Core/Video/Encoding.cs b/src/Chronos.Core/Video/Encoding.cs
index 0fb29da0..83d01d51 100644
--- a/src/Chronos.Core/Video/Encoding.cs
+++ b/src/Chronos.Core/Video/Encoding.cs
@@ -107,6 +107,12 @@ public sealed record EncodeSettings
/// Optional specific encoder name from .
public string? EncoderName { get; init; }
+
+ ///
+ /// One frame saved as one image file at (owner review 1, R8, "Save frame") instead of a numbered
+ /// sequence in a folder: the image-sequence codecs PNG, JPEG and TIFF only, and exactly one frame.
+ ///
+ public bool SingleImage { get; init; }
}
/// One open encode. Frames are linear-light buffers at the output size.
diff --git a/src/Chronos.Core/Video/Managed/ManagedEncoderProvider.cs b/src/Chronos.Core/Video/Managed/ManagedEncoderProvider.cs
index 9fc57a8a..cd97e623 100644
--- a/src/Chronos.Core/Video/Managed/ManagedEncoderProvider.cs
+++ b/src/Chronos.Core/Video/Managed/ManagedEncoderProvider.cs
@@ -2,7 +2,8 @@ namespace Chronos.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
+/// sequences, animated GIF and APNG, and one PNG, JPEG or TIFF still (), 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.
@@ -44,6 +45,7 @@ public sealed class ManagedEncoderProvider : IVideoEncoderProvider
ArgumentNullException.ThrowIfNull(settings);
if (Problem(settings) is { } problem) throw new NotSupportedException(problem);
var name = Capabilities.First(c => c.Codec == settings.Codec).Name;
+ if (settings.SingleImage) return new StillImageSession(settings, name);
return settings.Codec switch
{
VideoCodec.Mjpeg => new AviMjpegSession(settings, name),
@@ -59,6 +61,7 @@ public sealed class ManagedEncoderProvider : IVideoEncoderProvider
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";
+ if (s.SingleImage && !StillImageSession.Takes(s.Codec)) return $"{s.Codec} cannot be saved as a single image";
return string.IsNullOrWhiteSpace(s.OutputPath) ? "No output path" : null;
}
}
diff --git a/src/Chronos.Core/Video/Managed/ManagedSessions.cs b/src/Chronos.Core/Video/Managed/ManagedSessions.cs
index 7fe336ce..1cdad631 100644
--- a/src/Chronos.Core/Video/Managed/ManagedSessions.cs
+++ b/src/Chronos.Core/Video/Managed/ManagedSessions.cs
@@ -201,6 +201,37 @@ internal sealed class ApngSession : SingleFileSession
protected override void Finish() => _encoder.Complete();
}
+///
+/// One frame saved as one image file (owner review 1, R8, "Save frame"; ): PNG (8 or
+/// 16-bit), JPEG or TIFF (16 or 8-bit) at , written to a temporary sibling and renamed
+/// into place on completion like the other single files. A second frame is refused.
+///
+internal sealed class StillImageSession(EncodeSettings settings, string encoderName) : SingleFileSession(settings, encoderName)
+{
+ private bool _written;
+
+ /// The codecs a still is saved with.
+ public static bool Takes(VideoCodec codec) => codec is VideoCodec.PngSequence or VideoCodec.JpegSequence or VideoCodec.Tiff16Sequence;
+
+ protected override void Write(ImageBuffer frame, long duration90k)
+ {
+ if (_written) throw new InvalidOperationException("A still holds one frame");
+ var bytes = Settings.Codec switch
+ {
+ VideoCodec.JpegSequence => JpegEncoder.Encode(frame, JpegOptions(Settings.Quality)),
+ VideoCodec.PngSequence => PngEncoder.Encode(frame, Settings.BitDepth == 16 ? 16 : 8, CompressionLevel.Optimal),
+ VideoCodec.Tiff16Sequence => TiffWriter.Write(frame, new TiffWriteOptions { BitsPerSample = Settings.BitDepth == 8 ? 8 : 16 }),
+ _ => throw new NotSupportedException($"{Settings.Codec} cannot be saved as a single image"),
+ };
+ File.Write(bytes);
+ _written = true;
+ }
+
+ protected override void Finish()
+ {
+ }
+}
+
///
/// 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
diff --git a/tests/Chronos.Core.Tests/Render/OutputProgramPlaybackTests.cs b/tests/Chronos.Core.Tests/Render/OutputProgramPlaybackTests.cs
new file mode 100644
index 00000000..ca22b6a5
--- /dev/null
+++ b/tests/Chronos.Core.Tests/Render/OutputProgramPlaybackTests.cs
@@ -0,0 +1,145 @@
+using Chronos.Core.Imaging;
+using Chronos.Core.Project;
+using Chronos.Core.Render;
+using Chronos.Core.Video;
+using Chronos.Testing;
+
+namespace Chronos.Core.Tests.Render;
+
+/// The output program of the playback settings (owner review 1, R8): order, loops, hold and fades.
+public sealed class OutputProgramPlaybackTests
+{
+ private static readonly Rational Fps25 = new(25, 1);
+
+ [Theory]
+ [Case("forward", 1, new[] { 0, 1, 2, 3 })]
+ [Case("forward", 2, new[] { 0, 1, 2, 3, 0, 1, 2, 3 })]
+ [Case("forward", 3, new[] { 0, 1, 2, 3, 0, 1, 2, 3, 0, 1, 2, 3 })]
+ [Case("reverse", 1, new[] { 3, 2, 1, 0 })]
+ [Case("reverse", 2, new[] { 3, 2, 1, 0, 3, 2, 1, 0 })]
+ [Case("reverse", 3, new[] { 3, 2, 1, 0, 3, 2, 1, 0, 3, 2, 1, 0 })]
+ [Case("boomerang", 1, new[] { 0, 1, 2, 3, 2, 1, 0 })]
+ [Case("boomerang", 2, new[] { 0, 1, 2, 3, 2, 1, 0, 1, 2, 3, 2, 1, 0 })]
+ [Case("boomerang", 3, new[] { 0, 1, 2, 3, 2, 1, 0, 1, 2, 3, 2, 1, 0, 1, 2, 3, 2, 1, 0 })]
+ public void DirectionsAndLoopsGiveThePlanIndicesInOrder(string direction, int loops, int[] expected)
+ {
+ var frames = Frames(3600, 3600, 3600, 7200);
+ var program = OutputProgram.Build(frames, new PlaybackSettings { Direction = direction, Loops = loops }, Fps25);
+ Assert.SequenceEqual(expected, program.Entries.Select(e => e.PlanIndex));
+ // No frame is emitted twice in a row: neither the turn of a boomerang nor the joint of two passes.
+ for (var i = 1; i < program.Count; i++) Assert.NotEqual(program.Entries[i - 1].PlanIndex, program.Entries[i].PlanIndex);
+ Assert.True(program.Entries.All(e => e.Gain == 1 && e.Duration90k == frames[e.PlanIndex].Duration90k));
+ Assert.Equal(expected.Sum(i => frames[i].Duration90k), program.Duration90k);
+ Assert.Equal(0, program.Warnings.Count);
+ }
+
+ [Test]
+ public void ASingleFrameBoomerangPlaysOncePerLoop()
+ {
+ var program = OutputProgram.Build(Frames(3600), new PlaybackSettings { Direction = PlaybackDirection.Boomerang, Loops = 3 }, Fps25);
+ Assert.SequenceEqual([0, 0, 0], program.Entries.Select(e => e.PlanIndex));
+ }
+
+ [Test]
+ public void ValuesOutOfRangeAreClamped()
+ {
+ var program = OutputProgram.Build(Frames(3600, 3600), new PlaybackSettings { Loops = 50 }, Fps25);
+ Assert.Equal(2 * PlaybackSettings.MaxLoops, program.Count);
+ var negative = OutputProgram.Build(Frames(3600, 3600), new PlaybackSettings { Loops = -3, FadeIn = -1, HoldEnd = double.NaN }, Fps25);
+ Assert.Equal((2, 7200L), (negative.Count, negative.Duration90k));
+ }
+
+ [Test]
+ public void TheHoldExtendsTheLastFrameByWholePeriods()
+ {
+ var program = OutputProgram.Build(Frames(3600, 3600, 3600), new PlaybackSettings { Direction = PlaybackDirection.Reverse, HoldEnd = 2 }, Fps25);
+ Assert.SequenceEqual([2, 1, 0], program.Entries.Select(e => e.PlanIndex));
+ Assert.SequenceEqual([3600L, 3600, 3600 + 180000], program.Entries.Select(e => e.Duration90k));
+ Assert.Approximately(2.12, program.DurationSeconds, 1e-12);
+ // A hold shorter than a period still shows one more period.
+ var brief = OutputProgram.Build(Frames(3600), new PlaybackSettings { HoldEnd = 0.001 }, Fps25);
+ Assert.Equal(7200L, brief.Duration90k);
+ }
+
+ [Test]
+ public void AHeldFrameInsideAFadeIsSplitPerPeriod()
+ {
+ // The first frame is held for ten periods (0.4 s) and the fade in lasts 0.2 s (five periods).
+ var program = OutputProgram.Build(Frames(36000, 3600, 3600), new PlaybackSettings { FadeIn = 0.2 }, Fps25);
+ Assert.Equal(12, program.Count);
+ Assert.True(program.Entries.Take(10).All(e => e.PlanIndex == 0 && e.Duration90k == 3600));
+ Assert.SequenceEqual([1, 2], program.Entries.Skip(10).Select(e => e.PlanIndex));
+ for (var k = 0; k < 10; k++)
+ Assert.Approximately(ColorSpace.SrgbToLinear(double.Min(1, k / 5.0)), program.Entries[k].Gain, 1e-12, $"period {k}");
+ Assert.Equal(0.0, program.Entries[0].Gain);
+ Assert.Equal(43200L, program.Duration90k);
+
+ // The fade out reaches into the hold at the end: the hold is split as well, the last period black.
+ var fadeOut = OutputProgram.Build(Frames(3600, 3600), new PlaybackSettings { FadeOut = 0.2, HoldEnd = 0.4 }, Fps25);
+ Assert.Equal(1 + 11, fadeOut.Count);
+ Assert.Equal(1.0, fadeOut.Entries[0].Gain);
+ Assert.Equal(0.0, fadeOut.Entries[^1].Gain);
+ Assert.Monotonic(fadeOut.Entries.Select(e => e.Gain), decreasing: true);
+ Assert.Equal(7200L + 36000, fadeOut.Duration90k);
+ }
+
+ [Test]
+ public void FadesLongerThanHalfTheProgramAreShortenedWithAWarning()
+ {
+ // 0.4 s of video with two 1 s fades: together they get half of it, 0.1 s each.
+ var program = OutputProgram.Build(Frames(Enumerable.Repeat(3600L, 10).ToArray()), new PlaybackSettings { FadeIn = 1, FadeOut = 1 }, Fps25);
+ Assert.Count(1, program.Warnings);
+ Assert.Equal(OutputProgram.FadesShortenedWarning, program.Warnings[0].Key);
+ Assert.Equal(10, program.Count);
+ Assert.Equal(0.0, program.Entries[0].Gain);
+ Assert.Equal(0.0, program.Entries[^1].Gain);
+ // 0.1 s is two and a half periods: the ramps take three frames each, the four between play as they are.
+ Assert.Approximately(ColorSpace.SrgbToLinear(0.4), program.Entries[1].Gain, 1e-12);
+ Assert.Approximately(ColorSpace.SrgbToLinear(0.8), program.Entries[2].Gain, 1e-12);
+ Assert.SequenceEqual([1.0, 1, 1, 1], program.Entries.Skip(3).Take(4).Select(e => e.Gain));
+ Assert.Approximately(ColorSpace.SrgbToLinear(0.8), program.Entries[7].Gain, 1e-12);
+ // Fades that fit leave no warning.
+ Assert.Equal(0, OutputProgram.Build(Frames(Enumerable.Repeat(3600L, 10).ToArray()), new PlaybackSettings { FadeIn = 0.08, FadeOut = 0.12 }, Fps25).Warnings.Count);
+ }
+
+ [Test]
+ public void TheTotalDurationIsExactOnTheNinetyKilohertzClock()
+ {
+ var rate = Rational.Fps2997;
+ var frames = Frames(Enumerable.Repeat(3003L, 7).ToArray());
+ var playback = new PlaybackSettings { Direction = PlaybackDirection.Boomerang, Loops = 2, HoldEnd = 0.5 };
+ var plain = OutputProgram.Build(frames, playback, rate);
+ // (7 + 6) + (6 + 6) frames of 3003 ticks, then 15 periods of hold at 30000/1001 (45045 ticks).
+ Assert.Equal(25, plain.Count);
+ Assert.Equal(25 * 3003L + RenderPlan.TicksAt(rate, 15), plain.Duration90k);
+ Assert.Equal(120120L, plain.Duration90k);
+ var faded = OutputProgram.Build(frames, playback with { FadeIn = 0.5, FadeOut = 0.5 }, rate);
+ Assert.Equal(plain.Duration90k, faded.Duration90k);
+ Assert.Equal(faded.Duration90k, faded.Entries.Sum(e => e.Duration90k));
+ Assert.Greater(faded.Count, plain.Count);
+ Assert.True(faded.Entries.All(e => e.Duration90k > 0));
+ }
+
+ [Test]
+ public void TheProgramOfAPlanUsesItsFrames()
+ {
+ var times = Enumerable.Range(0, 5).Select(i => (DateTime?)new DateTime(2026, 1, 1).AddSeconds(10 * i)).ToArray();
+ var plan = RenderPlan.Build(times, new ProjectSettings(), Fps25);
+ var program = OutputProgram.Build(plan, new PlaybackSettings { Direction = PlaybackDirection.Reverse }, Fps25);
+ Assert.Equal(plan.Frames.Count, program.Count);
+ Assert.Equal(plan.Duration90k, program.Duration90k);
+ Assert.Equal(plan.Frames.Count - 1, program.Entries[0].PlanIndex);
+ }
+
+ private static PlannedFrame[] Frames(params long[] durations)
+ {
+ var frames = new PlannedFrame[durations.Length];
+ long start = 0;
+ for (var i = 0; i < durations.Length; i++)
+ {
+ frames[i] = new PlannedFrame(i, i, i, 0, start, durations[i], i, (int)(durations[i] / 3600), 1, PlannedFrameFlags.None);
+ start += durations[i];
+ }
+ return frames;
+ }
+}
diff --git a/tests/Chronos.Core.Tests/Render/PlaybackRenderTests.cs b/tests/Chronos.Core.Tests/Render/PlaybackRenderTests.cs
new file mode 100644
index 00000000..ffd70072
--- /dev/null
+++ b/tests/Chronos.Core.Tests/Render/PlaybackRenderTests.cs
@@ -0,0 +1,231 @@
+using Chronos.Core.Codecs.Jpeg;
+using Chronos.Core.Codecs.Png;
+using Chronos.Core.Codecs.Tiff;
+using Chronos.Core.Export;
+using Chronos.Core.Imaging;
+using Chronos.Core.Model;
+using Chronos.Core.Project;
+using Chronos.Core.Render;
+using Chronos.Core.Video;
+using Chronos.Testing;
+using static Chronos.Core.Tests.Render.RenderFixture;
+
+namespace Chronos.Core.Tests.Render;
+
+/// Renders of the output program (owner review 1, R8) and of a still ("Save frame").
+public sealed class PlaybackRenderTests
+{
+ private readonly TestContext _context;
+
+ public PlaybackRenderTests(TestContext context) => _context = context;
+
+ [Test]
+ public async Task TheResultCountsTheFramesAndTheDurationOfTheProgram()
+ {
+ var source = Source(6);
+ var input = Input(source, Playing(new PlaybackSettings { Direction = PlaybackDirection.Boomerang, Loops = 2, HoldEnd = 1 }));
+ var setup = Pipeline().Setup(input, new RenderTarget(Preset("png-sequence"), "out"));
+ // 6 + 5 frames, then 5 + 5 from the second frame on.
+ Assert.Equal(21, setup.Program.Count);
+ Assert.SequenceEqual([0, 1, 2, 3, 4, 5, 4, 3, 2, 1, 0, 1, 2, 3, 4, 5, 4, 3, 2, 1, 0], setup.Program.Entries.Select(e => e.PlanIndex));
+
+ var (encode, result) = await CaptureAsync(input, cancellationToken: _context.Cancellation);
+ Assert.Equal(21, result.FrameCount);
+ Assert.Equal(21, encode.Frames.Count);
+ Assert.Equal(setup.Program.Duration90k, encode.Durations.Sum());
+ Assert.Approximately((21 + 30) / 30.0, result.DurationSeconds, 1e-9);
+ Assert.Equal(3000L + 90000, encode.Durations[^1]);
+ Assert.Null(result.Kind);
+ // The way back shows the very pictures of the way out.
+ Assert.True(double.IsPositiveInfinity(Psnr(encode.Frames[4], encode.Frames[6])));
+ }
+
+ [Test]
+ public async Task FadesStartAndEndInBlackAndLeaveTheMiddleAlone()
+ {
+ var source = Source(12);
+ var (plain, _) = await CaptureAsync(Input(source), cancellationToken: _context.Cancellation);
+ var (faded, result) = await CaptureAsync(Input(source, Playing(new PlaybackSettings { FadeIn = 0.1, FadeOut = 0.1 })), cancellationToken: _context.Cancellation);
+ Assert.Equal(12, faded.Frames.Count);
+ Assert.Equal(0, result.Warnings.Count(w => w.Key == OutputProgram.FadesShortenedWarning));
+ Assert.LessOrEqual(Peak(faded.Frames[0]), 1e-6);
+ Assert.LessOrEqual(Peak(faded.Frames[^1]), 1e-6);
+ Assert.Less(Mean(faded.Frames[1]), Mean(plain.Frames[1]));
+ Assert.True(double.IsPositiveInfinity(Psnr(plain.Frames[6], faded.Frames[6])));
+ // The ramp brightens in and darkens out.
+ Assert.Monotonic(faded.Frames.Take(4).Select(Mean));
+ Assert.Monotonic(faded.Frames.TakeLast(4).Select(Mean), decreasing: true);
+ }
+
+ [Test]
+ public async Task ReversedStarTrailsGrowFromTheEnd()
+ {
+ var stars = Source(10, motion: i => (1.0 * i, 0), configure: o => o with { StarField = true, StartEv = 0, EndEv = 0, StarCount = 60 });
+ var trails = new StackSettings { Mode = StackSetting.StarTrails, Length = 0 };
+ var (plain, _) = await CaptureAsync(Input(stars), cancellationToken: _context.Cancellation);
+ var (reversed, _) = await CaptureAsync(Input(stars, Playing(new PlaybackSettings { Direction = PlaybackDirection.Reverse }) with { Stack = trails }),
+ cancellationToken: _context.Cancellation);
+ Assert.Equal(10, reversed.Frames.Count);
+ // The first picture is the last frame alone; every later one only adds trails.
+ Assert.True(double.IsPositiveInfinity(Psnr(plain.Frames[^1], reversed.Frames[0])));
+ for (var k = 1; k < reversed.Frames.Count; k++)
+ {
+ var previous = reversed.Frames[k - 1].Data;
+ var current = reversed.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}");
+ }
+
+ // A boomerang with trails plays forward and says so.
+ var (boomerang, result) = await CaptureAsync(Input(stars, Playing(new PlaybackSettings { Direction = PlaybackDirection.Boomerang }) with { Stack = trails }),
+ cancellationToken: _context.Cancellation);
+ Assert.Equal(10, boomerang.Frames.Count);
+ Assert.Contains(result.Warnings, w => w.Key == OutputProgram.BoomerangStackWarning);
+ }
+
+ [Test]
+ public async Task AMedianWindowIsTheSameFrameInEitherDirection()
+ {
+ var source = Source(9);
+ var median = new StackSettings { Mode = StackSetting.Median, Length = 5 };
+ var (forward, _) = await CaptureAsync(Input(source, Plain with { Stack = median }), cancellationToken: _context.Cancellation);
+ var (boomerang, _) = await CaptureAsync(Input(source, Playing(new PlaybackSettings { Direction = PlaybackDirection.Boomerang, Loops = 2 }) with { Stack = median }),
+ cancellationToken: _context.Cancellation);
+ int[] order = [0, 1, 2, 3, 4, 5, 6, 7, 8, 7, 6, 5, 4, 3, 2, 1, 0, 1, 2, 3, 4, 5, 6, 7, 8, 7, 6, 5, 4, 3, 2, 1, 0];
+ Assert.Equal(order.Length, boomerang.Frames.Count);
+ for (var k = 0; k < order.Length; k++)
+ Assert.True(double.IsPositiveInfinity(Psnr(forward.Frames[order[k]], boomerang.Frames[k])), $"program frame {k} (plan frame {order[k]})");
+ }
+
+ [Test]
+ public void TheEstimateGrowsWithTheLoopsAndTheHold()
+ {
+ var source = Source(12);
+ var export = Preset("png-sequence");
+ var once = Pipeline().Setup(Input(source), new RenderTarget(export, "out"));
+ var thrice = Pipeline().Setup(Input(source, Playing(new PlaybackSettings { Loops = 3, HoldEnd = 1 })), new RenderTarget(export, "out"));
+ Assert.Equal(3 * once.Workload().OutputFrames, thrice.Workload().OutputFrames);
+ Assert.Equal(3 * 12 + 30, thrice.Workload().OutputPeriods);
+ Assert.Approximately(once.Workload().DurationSeconds * 3 + 1, thrice.Workload().DurationSeconds, 1e-9);
+ Assert.Greater(thrice.Estimate().Time.TotalSeconds, once.Estimate().Time.TotalSeconds);
+ Assert.Greater(thrice.Estimate().Bytes, 3 * once.Estimate().Bytes);
+ }
+
+ [Theory]
+ [Case("png-sequence", 8)]
+ [Case("jpeg-sequence", 8)]
+ [Case("tiff16-sequence", 8)]
+ public async Task AStillWritesOneImageAtTheOutputSize(string presetId, int bitDepth)
+ {
+ var dir = _context.CreateTempDirectory();
+ var source = Source(8);
+ var export = Preset(presetId) with { BitDepth = bitDepth };
+ var context = new ExportNameContext { Date = new DateTime(2026, 9, 28), Title = "Harbour", PresetName = "Still", Codec = export.Codec };
+ var path = ExportNaming.StillPath(dir, "{date} {title}", context, 4);
+ Assert.Equal("2026-09-28 Harbour - 0005" + VideoCodecInfo.FileExtension(export.Codec), Path.GetFileName(path));
+ // Playback never reaches a still.
+ var input = Input(source, Playing(new PlaybackSettings { Direction = PlaybackDirection.Reverse, FadeIn = 5 }));
+ var target = new RenderTarget(export, path, StillFrame: 4);
+ var setup = Pipeline().Setup(input, target);
+ Assert.Equal(1, setup.Program.Count);
+ Assert.True(setup.Encoder.Settings.SingleImage);
+ Assert.Equal(export.Codec == VideoCodec.Tiff16Sequence ? 16 : 8, setup.Encoder.Settings.BitDepth);
+ Assert.Equal((1, 1, 0.0), (setup.Workload().OutputFrames, setup.Workload().OutputPeriods, setup.Workload().DurationSeconds));
+
+ var result = await Pipeline().RenderAsync(input, target, cancellationToken: _context.Cancellation);
+ Assert.SequenceEqual([Path.GetFileName(path)], Directory.GetFileSystemEntries(dir).Select(Path.GetFileName));
+ Assert.Equal((1, 0.0, RenderKind.Still), (result.FrameCount, result.DurationSeconds, result.Kind));
+ Assert.Equal(new FileInfo(path).Length, result.Bytes);
+ var entity = result.ToEntity(Guid.NewGuid(), "PNG", null, "test");
+ Assert.Equal((RenderKind.Still, 0.0, 0.0), (entity.Kind, entity.Fps, entity.DurationSeconds));
+
+ var bytes = File.ReadAllBytes(path);
+ using var decoded = export.Codec switch
+ {
+ VideoCodec.JpegSequence => JpegDecoder.DecodeToLinear(bytes),
+ VideoCodec.PngSequence => PngDecoder.DecodeToLinear(bytes),
+ _ => TiffImageReader.Decode(bytes),
+ };
+ Assert.Equal((96, 64), (decoded.Width, decoded.Height));
+ using var expected = source.Sequence.Render(4);
+ _context.Log($"{presetId}: {result.Bytes} bytes, PSNR {Psnr(expected, decoded):F1} dB");
+ Assert.Greater(Psnr(expected, decoded), 25);
+ }
+
+ [Test]
+ public async Task AStillRendersTheFrameItNames()
+ {
+ var source = Source(8);
+ var (plain, _) = await CaptureAsync(Input(source), cancellationToken: _context.Cancellation);
+ var capture = new CapturingEncoderProvider("capture", new EncoderCapability(VideoCodec.PngSequence, "Capture", false, 8192, 8192, true));
+ var result = await Pipeline(capture).RenderAsync(Input(source), new RenderTarget(Preset("png-sequence"), "still.png", 6), cancellationToken: _context.Cancellation);
+ var encode = capture.Encodes.Single();
+ Assert.True(encode.Settings.SingleImage);
+ Assert.Equal(1, encode.Frames.Count);
+ Assert.True(double.IsPositiveInfinity(Psnr(plain.Frames[6], encode.Frames[0])));
+ Assert.Equal(RenderKind.Still, result.Kind);
+ }
+
+ [Test]
+ public async Task AStillOfAFrameTheSequenceDoesNotHaveIsARenderError()
+ {
+ var source = Source(4);
+ var error = await Assert.ThrowsAsync(() => Pipeline().RenderAsync(Input(source), new RenderTarget(Preset("png-sequence"), "x.png", 4)));
+ Assert.Equal("Tooltips.Export.StillNeedsFrame", error.ReasonKey);
+ Assert.Throws(() => Pipeline().Setup(Input(source), new RenderTarget(Preset("png-sequence"), "x.png", -1)));
+ }
+
+ [Test]
+ public void AStillIsOneFileWhateverTheSequenceCodec()
+ {
+ var provider = new Chronos.Core.Video.Managed.ManagedEncoderProvider();
+ EncodeSettings Still(VideoCodec codec, int depth) => new() { OutputPath = "x", Codec = codec, Width = 8, Height = 8, FrameRate = new Rational(30, 1), BitDepth = depth, SingleImage = true };
+ Assert.True(provider.CanEncode(Still(VideoCodec.PngSequence, 16)));
+ Assert.True(provider.CanEncode(Still(VideoCodec.JpegSequence, 8)));
+ Assert.True(provider.CanEncode(Still(VideoCodec.Tiff16Sequence, 16)));
+ Assert.False(provider.CanEncode(Still(VideoCodec.LinearDngSequence, 16)));
+ Assert.False(provider.CanEncode(Still(VideoCodec.Gif, 8)));
+ Assert.False(provider.CanEncode(Still(VideoCodec.Mjpeg, 8)));
+ }
+
+ [Test]
+ public void AStillTargetNeedsFormatThree()
+ {
+ var export = ExportResolver.Resolve(new ExportSettings());
+ Assert.Equal(1, RenderRules.RequiredFormat(new ProjectSettings(), new RenderTarget(export, "x"), 6000, 4000));
+ Assert.Equal(RenderRules.StillFormat, RenderRules.RequiredFormat(new ProjectSettings(), new RenderTarget(export, "x", 3), 6000, 4000));
+ // The playback a job renders raises the settings it carries to format 3.
+ var playing = new ProjectSettings { Export = new ExportSettings { Playback = new PlaybackSettings { Direction = PlaybackDirection.Reverse } } };
+ Assert.Equal(ProjectSettings.PlaybackVersion, RenderRules.RequiredFormat(playing, new RenderTarget(export, "x"), 6000, 4000));
+ }
+
+ [Test]
+ public void AFadeScalesEverySampleInPlace()
+ {
+ using var frame = new ImageBuffer(7, 5, 3);
+ frame.Data.Fill(0.5f);
+ FrameFinish.Fade(frame, 1);
+ Assert.True(frame.Data.ToArray().All(v => v == 0.5f));
+ FrameFinish.Fade(frame, 0.5);
+ Assert.True(frame.Data.ToArray().All(v => v == 0.25f));
+ FrameFinish.Fade(frame, double.NaN);
+ Assert.True(frame.Data.ToArray().All(v => v == 0.25f));
+ FrameFinish.Fade(frame, 0);
+ Assert.True(frame.Data.ToArray().All(v => v == 0));
+ }
+
+ private static ProjectSettings Playing(PlaybackSettings playback) => Plain with { Export = Plain.Export with { Playback = playback } };
+
+ private static double Peak(ImageBuffer frame)
+ {
+ var peak = 0f;
+ foreach (var v in frame.Data) peak = float.Max(peak, v);
+ return peak;
+ }
+
+ private static double Mean(ImageBuffer frame)
+ {
+ double sum = 0;
+ foreach (var v in frame.Data) sum += v;
+ return sum / frame.Data.Length;
+ }
+}