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:
1 parent
86aa07c1d7
commit
d472dfdec1
67 files changed
+2233
-244
No files matched your search
@@ -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>
|
||||
|
||||
@@ -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>
|
||||
|
||||
@@ -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;
|
||||
@@ -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);
|
||||
}
|
||||
}
|
||||
@@ -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
|
||||
|
||||
Reference in new issue
Block a user