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

+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;