feat: phase 5 groundwork (playback format 3, videos contracts, migration 0010, strings)

Lays down every contract the later parcels of owner review 1 phase 5 build on,
so they compile against shared types without touching each other's files.

- Settings format 3: export.playback (direction, loops, fades, hold), omitted
  at its default and member by member; RequiredFormat is 3 only while used.
- OutputProgram public API with a forward-only body; still-frame job
  parameters (StillFrame, StillPhoto) routed to format-3 nodes only.
- Render.Sha256/Kind, RenderCopy, RenderKind; JobKind.VideoCopy = 24.
- Migration 0010 (sqlite, postgres): renders.sha256/kind, ix_renders_created,
  render_copies without a foreign key.
- Videos protocol DTOs, client calls, ServerCapabilities.Videos (declared,
  not announced yet), ServerSettingsDto.VideosPath.
- IVideoLibrary with a NotImplemented stub registered on the server;
  TrashKind.Videos, VideoTrashNames, VideoErrors.
- en and it strings for the whole phase, five icons, decisions 1-22 and the
  open-question defaults; tests that used format 3 as "newer" now use 4.

Refs #21

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Alby96andClaude Opus 5.5 committed 2026-11-05 01:48:33 +01:00
1 parent 86aa07c1d7
commit d472dfdec1
67 files changed
+2233 -244

No files matched your search

+69
View File
@@ -164,6 +164,75 @@ public sealed record Render
/// <summary>The project version rendered; null for a render of the sequence's settings.</summary>
public Guid? ProjectVersionId { get; init; }
/// <summary>
/// Lower-case hex SHA-256 of a single-file render (owner review 1, R9), hashed when it is recorded; null for an image
/// sequence's folder (verified file by file when copied) and for a render recorded before migration 0010, hashed the
/// first time it is copied, deleted or restored.
/// </summary>
public string? Sha256 { get; init; }
/// <summary>
/// What the render is beyond its codec (<see cref="RenderKind"/>): null for a video or an image sequence (told apart by
/// <see cref="Codec"/>), <see cref="RenderKind.Still"/> for one frame saved as an image. A text, so a newer Chronos can add
/// kinds.
/// </summary>
public string? Kind { get; init; }
}
/// <summary>The values of <see cref="Render.Kind"/> and of the videos library's kinds (owner review 1, R9).</summary>
public static class RenderKind
{
/// <summary>A video file (MP4, AVI, GIF, APNG): <see cref="Render.Kind"/> null and a video codec.</summary>
public const string Video = "video";
/// <summary>A folder of numbered images: <see cref="Render.Kind"/> null and an image-sequence codec.</summary>
public const string Sequence = "sequence";
/// <summary>One frame saved as one image ("Save frame"): fps 0 and duration 0.</summary>
public const string Still = "still";
/// <summary>
/// The library kind of a render: its <see cref="Render.Kind"/> when set (a kind of a newer Chronos as it is), else
/// <see cref="Sequence"/> for an image-sequence codec and <see cref="Video"/> otherwise.
/// </summary>
public static string Of(string? kind, string? codec) =>
kind is { Length: > 0 } ? kind
: codec is { } c && c.EndsWith("sequence", StringComparison.OrdinalIgnoreCase) ? Sequence
: Video;
/// <inheritdoc cref="Of(string?, string?)"/>
public static string Of(Render render)
{
ArgumentNullException.ThrowIfNull(render);
return Of(render.Kind, render.Codec);
}
}
/// <summary>
/// A verified copy of a render in a videos folder (owner review 1, R9; <c>render_copies</c>): recorded once the copy matched
/// its render. There is no link to <c>renders</c>, so the copy of a server render downloaded to a PC is recorded too, and a
/// copy outlives its render's deletion (copies are the user's files; Chronos never deletes them).
/// </summary>
public sealed record RenderCopy
{
public required Guid Id { get; init; }
/// <summary>The render copied (of this index, or of the server it was downloaded from).</summary>
public required Guid RenderId { get; init; }
/// <summary>Absolute path of the copy (a file, or a folder for an image sequence).</summary>
public required string Path { get; init; }
/// <summary>Lower-case hex SHA-256 the copy was verified against; null for an image sequence's folder (verified per file).</summary>
public string? Sha256 { get; init; }
public long Bytes { get; init; }
public DateTimeOffset CopiedAt { get; init; }
/// <summary>The user (server) or the PC (desktop) that copied it.</summary>
public string? CopiedBy { get; init; }
}
/// <summary>
+6
View File
@@ -123,6 +123,12 @@ public enum JobKind
/// source kept until every file is verified (owner review 2, R8, phase 5c); stored as 23.
/// </summary>
WorkspaceMove = 23,
/// <summary>
/// Copies renders into the videos folder (owner review 1, R9), each copy hash-verified against its render before it takes
/// its name, the render itself never touched; on the desktop a server-only render is downloaded into it; stored as 24.
/// </summary>
VideoCopy = 24,
}
/// <summary>Why a photo left a sequence (its tombstone, owner review 2, R6); stored as a number.</summary>
+128 -5
View File
@@ -278,6 +278,116 @@ public sealed record ExportSettings
/// </summary>
public bool SyncToServer { get; init; }
/// <summary>
/// How the rendered frames play (owner review 1, R8): direction, loops, fades and a hold at the end, applied by
/// <c>OutputProgram</c> between the plan and the encoder. Null at the default (forward, once, no fades, no hold), which
/// <see cref="ProjectSettings.ToJson"/> writes whenever <see cref="PlaybackSettings.IsDefault"/>. Settings format 3. It
/// lives in the export, so the batch presets of the export inherit it.
/// </summary>
public PlaybackSettings? Playback { get; init; }
/// <summary>Members this Chronos does not know (written by a newer one): kept as they are, so they survive a round trip.</summary>
[JsonExtensionData]
public Dictionary<string, JsonElement>? Extra { get; set; }
}
/// <summary>The directions of <see cref="PlaybackSettings.Direction"/>: texts, not an enum, so a newer Chronos can add one.</summary>
public static class PlaybackDirection
{
/// <summary>The plan as it is (the default, never written).</summary>
public const string Forward = "forward";
/// <summary>The plan from its last frame to its first.</summary>
public const string Reverse = "reverse";
/// <summary>Forward, then backward without repeating the turning frame.</summary>
public const string Boomerang = "boomerang";
/// <summary>The directions this Chronos renders, in the order the editor offers them.</summary>
public static IReadOnlyList<string> All { get; } = [Forward, Reverse, Boomerang];
/// <summary>Whether this Chronos renders <paramref name="direction"/> (null is forward); the comparison ignores case.</summary>
public static bool IsKnown(string? direction) =>
direction is null || All.Contains(direction, StringComparer.OrdinalIgnoreCase);
}
/// <summary>
/// The playback of an export (owner review 1, R8; settings format 3): each member null at its default and omitted then, so
/// a project that sets nothing here keeps its text. Values out of range are clamped when rendered
/// (<see cref="EffectiveLoops"/> and the other effective values); a direction this Chronos does not know renders forward
/// with the warning <c>Export.Render.DirectionUnknown</c>.
/// </summary>
public sealed record PlaybackSettings
{
/// <summary>The most passes a video plays (<see cref="Loops"/>).</summary>
public const int MaxLoops = 10;
/// <summary>The longest fade in or out, in seconds.</summary>
public const double MaxFadeSeconds = 30;
/// <summary>The longest hold of the last frame, in seconds.</summary>
public const double MaxHoldSeconds = 60;
/// <summary><see cref="PlaybackDirection"/>: null for forward; "reverse" or "boomerang".</summary>
public string? Direction { get; init; }
/// <summary>Passes of the whole video, 1..<see cref="MaxLoops"/>; null for 1.</summary>
public int? Loops { get; init; }
/// <summary>Seconds of fade from black at the start, 0..<see cref="MaxFadeSeconds"/>; null for 0.</summary>
public double? FadeIn { get; init; }
/// <summary>Seconds of fade to black at the end, 0..<see cref="MaxFadeSeconds"/>; null for 0.</summary>
public double? FadeOut { get; init; }
/// <summary>Seconds the last frame stays on screen after the last pass, 0..<see cref="MaxHoldSeconds"/>; null for 0.</summary>
public double? HoldEnd { get; init; }
/// <summary>The direction rendered: forward for null and for a direction this Chronos does not know.</summary>
[JsonIgnore]
public string EffectiveDirection => Direction is { } d && PlaybackDirection.IsKnown(d) ? d.ToLowerInvariant() : PlaybackDirection.Forward;
/// <summary>The passes rendered, clamped to 1..<see cref="MaxLoops"/>.</summary>
[JsonIgnore]
public int EffectiveLoops => Math.Clamp(Loops ?? 1, 1, MaxLoops);
/// <summary>The fade in rendered, in seconds, clamped (a value that is not finite counts as 0).</summary>
[JsonIgnore]
public double EffectiveFadeIn => Seconds(FadeIn, MaxFadeSeconds);
/// <summary>The fade out rendered, in seconds, clamped (a value that is not finite counts as 0).</summary>
[JsonIgnore]
public double EffectiveFadeOut => Seconds(FadeOut, MaxFadeSeconds);
/// <summary>The hold rendered, in seconds, clamped (a value that is not finite counts as 0).</summary>
[JsonIgnore]
public double EffectiveHoldEnd => Seconds(HoldEnd, MaxHoldSeconds);
/// <summary>
/// The playback renders as the default (forward, once, no fades, no hold) and holds nothing a newer Chronos wrote: the
/// export then writes no playback at all. A direction this Chronos does not know is not the default (it is a newer
/// Chronos's), so it is kept and raises the format.
/// </summary>
[JsonIgnore]
public bool IsDefault =>
(Direction is null || string.Equals(Direction, PlaybackDirection.Forward, StringComparison.OrdinalIgnoreCase))
&& EffectiveLoops == 1 && EffectiveFadeIn == 0 && EffectiveFadeOut == 0 && EffectiveHoldEnd == 0 && Extra is not { Count: > 0 };
/// <summary>
/// The same playback with each member at its default (forward, 1, 0) set to null, so it is not written; values out of
/// range and unknown directions stay as they are. <see cref="ProjectSettings.ToJson"/> writes the playback this way.
/// </summary>
public PlaybackSettings Normalized() => this with
{
Direction = string.Equals(Direction, PlaybackDirection.Forward, StringComparison.OrdinalIgnoreCase) ? null : Direction,
Loops = Loops == 1 ? null : Loops,
FadeIn = FadeIn == 0 ? null : FadeIn,
FadeOut = FadeOut == 0 ? null : FadeOut,
HoldEnd = HoldEnd == 0 ? null : HoldEnd,
};
private static double Seconds(double? value, double max) => value is { } v && double.IsFinite(v) ? Math.Clamp(v, 0, max) : 0;
/// <summary>Members this Chronos does not know (written by a newer one): kept as they are, so they survive a round trip.</summary>
[JsonExtensionData]
public Dictionary<string, JsonElement>? Extra { get; set; }
@@ -323,7 +433,10 @@ public sealed record LookSettings
public sealed record ProjectSettings
{
/// <summary>The highest settings format this Chronos reads; a project of a higher one opens read-only (<see cref="IsNewerFormat"/>).</summary>
public const int CurrentVersion = 2;
public const int CurrentVersion = 3;
/// <summary>The format of a project whose export plays other than forward once without fades (<see cref="ExportSettings.Playback"/>).</summary>
public const int PlaybackVersion = 3;
/// <summary>The format of a project that uses nothing added since the first one, which most projects are written as.</summary>
public const int BaseVersion = 1;
@@ -377,11 +490,13 @@ public sealed record ProjectSettings
public bool IsNewerFormat => Version > CurrentVersion;
/// <summary>
/// The lowest settings format that renders these settings the same: 2 while a turn, mirror, flip or straighten
/// The lowest settings format that renders these settings the same: 3 while the export's playback is not the default
/// (<see cref="PlaybackSettings.IsDefault"/>), 2 while a turn, mirror, flip or straighten
/// (<see cref="CameraSettings.IsOriented"/>) or a look other than the identity is set, otherwise <see cref="BaseVersion"/>.
/// </summary>
[JsonIgnore]
public int RequiredFormat => Camera.IsOriented || Look is { IsIdentity: false } ? 2 : BaseVersion;
public int RequiredFormat =>
Export.Playback is { IsDefault: false } ? PlaybackVersion : Camera.IsOriented || Look is { IsIdentity: false } ? 2 : BaseVersion;
/// <summary>The format <see cref="ToJson"/> writes: <see cref="RequiredFormat"/>, or a newer format read, kept as it is.</summary>
[JsonIgnore]
@@ -389,9 +504,16 @@ public sealed record ProjectSettings
/// <summary>
/// The settings as JSON, stamped with <see cref="WrittenFormat"/>. Every serialisation of a project goes through here,
/// so the version written always matches the members used.
/// so the version written always matches the members used; a playback at its default is written as none, and each of
/// its members at its default is left out (<see cref="PlaybackSettings.Normalized"/>).
/// </summary>
public string ToJson() => JsonSerializer.Serialize(Version == WrittenFormat ? this : this with { Version = WrittenFormat }, ProjectJson.Default.ProjectSettings);
public string ToJson()
{
var written = Export.Playback is { } playback
? this with { Export = Export with { Playback = playback.IsDefault ? null : playback.Normalized() } }
: this;
return JsonSerializer.Serialize(written.Version == WrittenFormat ? written : written with { Version = WrittenFormat }, ProjectJson.Default.ProjectSettings);
}
/// <summary>
/// Reads a project; members missing from <paramref name="json"/> (an API client's partial settings, an older file)
@@ -821,4 +943,5 @@ public sealed record ProjectSettings
UseStringEnumConverter = true,
PropertyNameCaseInsensitive = true)]
[JsonSerializable(typeof(ProjectSettings))]
[JsonSerializable(typeof(PlaybackSettings))]
internal sealed partial class ProjectJson : JsonSerializerContext;
+81
View File
@@ -0,0 +1,81 @@
using Chronos.Core.Project;
using Chronos.Core.Video;
namespace Chronos.Core.Render;
/// <summary>One frame the encoder receives, in emission order (<see cref="OutputProgram"/>).</summary>
/// <param name="PlanIndex">The frame of <see cref="RenderPlan.Frames"/> rendered for it.</param>
/// <param name="Duration90k">How long it shows, on the 90 kHz clock: the planned frame's duration, a share of it (a held
/// frame split per slot inside a fade), or longer (the hold at the end).</param>
/// <param name="Gain">The linear-light multiplier of the fade to and from black, applied after the look and the knee
/// (<c>FrameFinish</c>): 1 leaves the frame as it is, 0 is black. Already in linear light (the sRGB ramp converted), so a
/// fade looks even.</param>
public readonly record struct ProgramEntry(int PlanIndex, long Duration90k, double Gain);
/// <summary>
/// The output program of a render (owner review 1, R8): the plan's frames in the order and for the time they are emitted,
/// with the fade gain of each, from the export's <see cref="PlaybackSettings"/>. Reverse is the plan backwards; a boomerang
/// is forward then backward without repeating the turning frame; loops repeat the pass (a boomerang's later passes start at
/// its second frame, so the joint is not doubled); the hold extends the last emitted frame; fades longer than half of the
/// program are scaled to fit (warning <see cref="FadesShortenedWarning"/>). Every pass is rendered again, so the render
/// time grows with <see cref="Count"/>.
/// </summary>
/// <remarks>
/// Phase 5 groundwork: the API is final; <see cref="Build(IReadOnlyList{PlannedFrame}, PlaybackSettings?, Rational)"/> emits
/// the plan forward once, without fades or hold, until the output program parcel completes it.
/// </remarks>
public sealed class OutputProgram
{
/// <summary>Warning key: the fades were longer than half of the program and were scaled to fit.</summary>
public const string FadesShortenedWarning = "Export.Render.FadesShortened";
/// <summary>Warning key: the playback names a direction this Chronos does not know ({0}); the video plays forward.</summary>
public const string DirectionUnknownWarning = "Export.Render.DirectionUnknown";
/// <summary>Warning key: a boomerang is not rendered with star trails; the video plays forward.</summary>
public const string BoomerangStackWarning = "Export.Render.BoomerangStack";
private OutputProgram(IReadOnlyList<ProgramEntry> entries, IReadOnlyList<RenderWarning> warnings)
{
Entries = entries;
Warnings = warnings;
long total = 0;
foreach (var entry in entries) total += entry.Duration90k;
Duration90k = total;
}
/// <summary>The emitted frames, in order.</summary>
public IReadOnlyList<ProgramEntry> Entries { get; }
/// <summary>Frames the encoder receives (and the render renders).</summary>
public int Count => Entries.Count;
/// <summary>Exact total duration on the 90 kHz clock, holds included.</summary>
public long Duration90k { get; }
/// <summary>The duration in seconds.</summary>
public double DurationSeconds => Duration90k / 90000.0;
/// <summary>What the program changed of the playback asked for (fades shortened, an unknown direction played forward).</summary>
public IReadOnlyList<RenderWarning> Warnings { get; }
/// <summary>The program of <paramref name="plan"/>'s frames played as <paramref name="playback"/> says (null: forward once).</summary>
public static OutputProgram Build(RenderPlan plan, PlaybackSettings? playback, Rational frameRate)
{
ArgumentNullException.ThrowIfNull(plan);
return Build(plan.Frames, playback, frameRate);
}
/// <summary>The program of the planned <paramref name="frames"/> played as <paramref name="playback"/> says (null: forward once).</summary>
/// <param name="frameRate">The output frame rate: the grid a held frame is split on inside a fade.</param>
public static OutputProgram Build(IReadOnlyList<PlannedFrame> frames, PlaybackSettings? playback, Rational frameRate)
{
ArgumentNullException.ThrowIfNull(frames);
if (frameRate.Numerator <= 0 || frameRate.Denominator <= 0) throw new ArgumentOutOfRangeException(nameof(frameRate));
var warnings = new List<RenderWarning>();
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);
}
}
+20
View File
@@ -1,5 +1,6 @@
using Chronos.Core.Export;
using Chronos.Core.Project;
using Chronos.Core.Video;
namespace Chronos.Core.Render;
@@ -9,6 +10,25 @@ namespace Chronos.Core.Render;
/// </summary>
public static class RenderRules
{
/// <summary>
/// The settings format a still job needs (owner review 1, R8, "Save frame"): an older program reads the job as a render
/// of the whole video, so it must never claim one.
/// </summary>
public const int StillFormat = 3;
/// <summary>The codecs a still frame is saved with, in the order "Save frame" offers them: PNG, JPEG and TIFF 16-bit.</summary>
public static IReadOnlyList<VideoCodec> StillCodecs { get; } = [VideoCodec.PngSequence, VideoCodec.JpegSequence, VideoCodec.Tiff16Sequence];
/// <summary>
/// <see cref="RequiredFormat(ProjectSettings, ResolvedExport, int, int)"/>, and at least <see cref="StillFormat"/> for a
/// still job (<paramref name="still"/>: one frame saved as an image).
/// </summary>
public static int RequiredFormat(ProjectSettings settings, ResolvedExport export, int sourceWidth, int sourceHeight, bool still)
{
var format = RequiredFormat(settings, export, sourceWidth, sourceHeight);
return still ? int.Max(format, StillFormat) : format;
}
/// <summary>
/// The settings format a render of <paramref name="settings"/> with <paramref name="export"/> on a source of the given
/// (Exif-oriented) size needs: the format the settings are written in (<see cref="ProjectSettings.WrittenFormat"/>), and