From 63d1855f82b972666758b4674936aa37b1f3c3ec Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 2 Oct 2026 10:01:27 +0000 Subject: [PATCH] feat(core): project settings with Auto/manual values and export presets Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_012iLMBNwBE2GnphAsu4cjaC --- docs/DECISIONS.md | 1 + src/Titano.Core/Export/ExportPreset.cs | 131 ++++++++++++ src/Titano.Core/Project/Auto.cs | 31 +++ src/Titano.Core/Project/ProjectSettings.cs | 200 ++++++++++++++++++ .../Project/ProjectSettingsTests.cs | 60 ++++++ 5 files changed, 423 insertions(+) create mode 100644 src/Titano.Core/Export/ExportPreset.cs create mode 100644 src/Titano.Core/Project/Auto.cs create mode 100644 src/Titano.Core/Project/ProjectSettings.cs create mode 100644 tests/Titano.Core.Tests/Project/ProjectSettingsTests.cs diff --git a/docs/DECISIONS.md b/docs/DECISIONS.md index c43c94b9..b98dc3e8 100644 --- a/docs/DECISIONS.md +++ b/docs/DECISIONS.md @@ -44,3 +44,4 @@ One line per decision: date · decision · alternative · reason. | 2026-10-02 | Interpolation chooses velocities by forward–backward consistency with per-sample flow-agreement weights (τ = 3 px). | Super SloMo combination | Better at motion boundaries (36.8 vs 33 dB). | | 2026-10-02 | Virtual-camera zoom is interpolated geometrically; trail length L ↦ decay 0.01^(1/L). | Linear zoom / half-life | Even perceived speed; the trail is gone at its stated length. | | 2026-10-02 | Motion estimation, sharpness and noise use sRGB-encoded luminance. | Linear light | Shadows keep texture weight; less exposure dependence. | +| 2026-10-02 | Archive presets use 0.30 bpp (≈60 Mb/s at 4K24 HEVC 10-bit); share presets use the brief's per-codec defaults (0.10/0.07/0.05). | 0.07 bpp everywhere | An archive must survive later re-encoding; star fields are the hardest content. | diff --git a/src/Titano.Core/Export/ExportPreset.cs b/src/Titano.Core/Export/ExportPreset.cs new file mode 100644 index 00000000..8931e91a --- /dev/null +++ b/src/Titano.Core/Export/ExportPreset.cs @@ -0,0 +1,131 @@ +using Titano.Core.Video; + +namespace Titano.Core.Export; + +/// +/// A bundle of export values (BRIEF §11.4). Bit rate follows bits-per-pixel-per-frame +/// (≈ 0.10 H.264, 0.07 HEVC, 0.05 AV1) unless fixed. is the localized display name. +/// +public sealed record ExportPreset +{ + public required string Id { get; init; } + public required string NameKey { get; init; } + public required VideoCodec Codec { get; init; } + public ContainerFormat Container => VideoCodecInfo.DefaultContainer(Codec); + public CodecProfile Profile { get; init; } = CodecProfile.Auto; + public int BitDepth { get; init; } = 8; + + /// Output size; 0×0 = source size (image sequences). + public int Width { get; init; } + + public int Height { get; init; } + public Rational FrameRate { get; init; } = new(30, 1); + + /// Fixed bit rate in bit/s; 0 = derived from . + public long BitRate { get; init; } + + public double BitsPerPixel { get; init; } + + /// Key-frame distance in seconds. + public double GopSeconds { get; init; } = 1; + + public int BFrames { get; init; } = 2; + + /// JPEG/MJPEG/GIF quality 1–100. + public int Quality { get; init; } = 92; + + public bool IsBuiltIn { get; init; } = true; + + /// Category for grouping in the Export tab. + public string Group { get; init; } = "video"; + + /// Average bit rate in bit/s for the preset's size and frame rate. + public long EffectiveBitRate(int width, int height, Rational fps) + { + if (BitRate > 0) return BitRate; + var bpp = BitsPerPixel > 0 ? BitsPerPixel : DefaultBitsPerPixel(Codec); + return (long)Math.Round(bpp * width * height * fps.Value); + } + + public static double DefaultBitsPerPixel(VideoCodec codec) => codec switch + { + VideoCodec.H264 => 0.10, + VideoCodec.Hevc => 0.07, + VideoCodec.Av1 => 0.05, + _ => 0, + }; + + /// Encode settings for this preset at a given output size. + public EncodeSettings ToEncodeSettings(string outputPath, int width, int height, Rational? fps = null) + { + var rate = fps ?? FrameRate; + return new EncodeSettings + { + OutputPath = outputPath, + Codec = Codec, + Width = width, + Height = height, + FrameRate = rate, + Profile = Profile, + BitDepth = BitDepth, + RateControl = RateControl.Vbr, + BitRate = EffectiveBitRate(width, height, rate), + Quality = Quality, + GopLength = Math.Max(1, (int)Math.Round(GopSeconds * rate.Value)), + BFrames = BFrames, + }; + } +} + +/// The built-in presets of BRIEF §11.4. +public static class ExportPresets +{ + private static readonly Rational Fps24 = new(24, 1); + private static readonly Rational Fps25 = new(25, 1); + private static readonly Rational Fps30 = new(30, 1); + private static readonly Rational Fps60 = new(60, 1); + + /// Archive presets keep ~4× the share budget so star fields and gradients survive re-encoding. + public const double ArchiveBitsPerPixel = 0.30; + + public static IReadOnlyList BuiltIn { get; } = + [ + new() { Id = "8k-hevc10-archive", NameKey = "Export.Preset.8kArchive", Codec = VideoCodec.Hevc, Profile = CodecProfile.HevcMain10, BitDepth = 10, Width = 7680, Height = 4320, FrameRate = Fps24, BitsPerPixel = ArchiveBitsPerPixel }, + new() { Id = "4k-hevc10-archive", NameKey = "Export.Preset.4kArchive", Codec = VideoCodec.Hevc, Profile = CodecProfile.HevcMain10, BitDepth = 10, Width = 3840, Height = 2160, FrameRate = Fps24, BitsPerPixel = ArchiveBitsPerPixel }, + new() { Id = "4k-hevc", NameKey = "Export.Preset.4kHevc", Codec = VideoCodec.Hevc, Profile = CodecProfile.HevcMain, Width = 3840, Height = 2160, FrameRate = Fps30 }, + new() { Id = "4k-h264", NameKey = "Export.Preset.4kH264", Codec = VideoCodec.H264, Profile = CodecProfile.H264High, Width = 3840, Height = 2160, FrameRate = Fps24 }, + new() { Id = "dci4k-hevc", NameKey = "Export.Preset.Dci4k", Codec = VideoCodec.Hevc, Profile = CodecProfile.HevcMain10, BitDepth = 10, Width = 4096, Height = 2160, FrameRate = Fps24 }, + new() { Id = "cinema-21x9", NameKey = "Export.Preset.Cinema", Codec = VideoCodec.Hevc, Profile = CodecProfile.HevcMain10, BitDepth = 10, Width = 4096, Height = 1716, FrameRate = Fps24 }, + new() { Id = "4k60", NameKey = "Export.Preset.4k60", Codec = VideoCodec.Hevc, Profile = CodecProfile.HevcMain, Width = 3840, Height = 2160, FrameRate = Fps60 }, + new() { Id = "1440p-h264", NameKey = "Export.Preset.1440p", Codec = VideoCodec.H264, Profile = CodecProfile.H264High, Width = 2560, Height = 1440, FrameRate = Fps30 }, + new() { Id = "1080p-h264", NameKey = "Export.Preset.1080pShare", Codec = VideoCodec.H264, Profile = CodecProfile.H264High, Width = 1920, Height = 1080, FrameRate = Fps30 }, + new() { Id = "1080p60", NameKey = "Export.Preset.1080p60", Codec = VideoCodec.H264, Profile = CodecProfile.H264High, Width = 1920, Height = 1080, FrameRate = Fps60 }, + new() { Id = "vertical-1080x1920", NameKey = "Export.Preset.Vertical", Codec = VideoCodec.H264, Profile = CodecProfile.H264High, Width = 1080, Height = 1920, FrameRate = Fps30, Group = "social" }, + new() { Id = "portrait-1080x1350", NameKey = "Export.Preset.Portrait", Codec = VideoCodec.H264, Profile = CodecProfile.H264High, Width = 1080, Height = 1350, FrameRate = Fps30, Group = "social" }, + new() { Id = "square-1440", NameKey = "Export.Preset.Square", Codec = VideoCodec.H264, Profile = CodecProfile.H264High, Width = 1440, Height = 1440, FrameRate = Fps30, Group = "social" }, + new() { Id = "720p-preview", NameKey = "Export.Preset.Preview", Codec = VideoCodec.H264, Profile = CodecProfile.H264Main, Width = 1280, Height = 720, FrameRate = Fps30, GopSeconds = 1, BFrames = 0 }, + new() { Id = "4k-av1", NameKey = "Export.Preset.4kAv1", Codec = VideoCodec.Av1, Profile = CodecProfile.Av1Main, BitDepth = 10, Width = 3840, Height = 2160, FrameRate = Fps30 }, + new() { Id = "mjpeg-avi", NameKey = "Export.Preset.Mjpeg", Codec = VideoCodec.Mjpeg, Width = 3840, Height = 2160, FrameRate = Fps25, Quality = 95, Group = "intermediate" }, + new() { Id = "png-sequence", NameKey = "Export.Preset.Png", Codec = VideoCodec.PngSequence, FrameRate = Fps30, Group = "sequence" }, + new() { Id = "jpeg-sequence", NameKey = "Export.Preset.Jpeg", Codec = VideoCodec.JpegSequence, FrameRate = Fps30, Quality = 95, Group = "sequence" }, + new() { Id = "tiff16-sequence", NameKey = "Export.Preset.Tiff16", Codec = VideoCodec.Tiff16Sequence, BitDepth = 16, FrameRate = Fps30, Group = "sequence" }, + new() { Id = "dng-sequence", NameKey = "Export.Preset.LinearDng", Codec = VideoCodec.LinearDngSequence, BitDepth = 16, FrameRate = Fps30, Group = "sequence" }, + new() { Id = "gif-preview", NameKey = "Export.Preset.Gif", Codec = VideoCodec.Gif, Width = 480, Height = 270, FrameRate = new Rational(15, 1), Quality = 80, Group = "web" }, + new() { Id = "apng", NameKey = "Export.Preset.Apng", Codec = VideoCodec.Apng, Width = 960, Height = 540, FrameRate = new Rational(15, 1), Group = "web" }, + ]; + + public static ExportPreset? Find(string id) => BuiltIn.FirstOrDefault(p => p.Id.Equals(id, StringComparison.OrdinalIgnoreCase)); + + /// Standard resolutions offered in the Custom editor (BRIEF §11.4). + public static IReadOnlyList<(string Key, int Width, int Height)> Resolutions { get; } = + [ + ("720p", 1280, 720), ("1080p", 1920, 1080), ("1440p", 2560, 1440), ("4k", 3840, 2160), ("dci4k", 4096, 2160), + ("5k", 5120, 2880), ("6k", 6144, 3456), ("8k", 7680, 4320), + ]; + + /// Frame rates offered (BRIEF §11.4). + public static IReadOnlyList FrameRates { get; } = + [ + Rational.Fps23976, new(24, 1), new(25, 1), Rational.Fps2997, new(30, 1), new(48, 1), new(50, 1), Rational.Fps5994, new(60, 1), new(120, 1), + ]; +} diff --git a/src/Titano.Core/Project/Auto.cs b/src/Titano.Core/Project/Auto.cs new file mode 100644 index 00000000..469ce46c --- /dev/null +++ b/src/Titano.Core/Project/Auto.cs @@ -0,0 +1,31 @@ +namespace Titano.Core.Project; + +/// +/// A parameter the advisor can decide (BRIEF §10.4). In Auto the advisor's applies and +/// / explain it; touching the control stores a manual +/// value; reset returns to Auto. +/// +public sealed record Auto +{ + public bool IsAuto { get; init; } = true; + + /// The advisor's value (null until analysis provides one). + public T? AutoValue { get; init; } + + /// The user's value when is false. + public T? Manual { get; init; } + + /// Localization key of the reason shown in the Auto pill tooltip. + public string? ReasonKey { get; init; } + + public IReadOnlyList? ReasonArgs { get; init; } + + /// The value in force: manual when set by the user, otherwise the advisor's, otherwise . + public T Resolve(T fallback) => !IsAuto && Manual is not null ? Manual : AutoValue ?? fallback; + + public Auto WithManual(T value) => this with { IsAuto = false, Manual = value }; + + public Auto Reset() => this with { IsAuto = true, Manual = default }; + + public Auto WithAdvice(T value, string? reasonKey, params string[] args) => this with { AutoValue = value, ReasonKey = reasonKey, ReasonArgs = args }; +} diff --git a/src/Titano.Core/Project/ProjectSettings.cs b/src/Titano.Core/Project/ProjectSettings.cs new file mode 100644 index 00000000..82bffb78 --- /dev/null +++ b/src/Titano.Core/Project/ProjectSettings.cs @@ -0,0 +1,200 @@ +using System.Text.Json; +using System.Text.Json.Serialization; + +namespace Titano.Core.Project; + +public enum TimingMode +{ + /// Every source frame lasts one output frame. + Constant, + + /// Output time follows capture time (deliberate intervalometer pauses are kept short, gaps preserved). + Adaptive, + + /// Missing frames in sparse gaps are synthesised from motion. + Interpolated, + + /// A monotone curve maps output time to source position (speed ramps). + Remapped, +} + +public enum RegionMode +{ + Off, + Auto, + Horizon, + Luminance, +} + +public enum FlowQualitySetting +{ + Draft, + Balanced, + Best, +} + +public enum StackSetting +{ + None, + Median, + Mean, + StarTrails, +} + +/// A control point of the time-remap curve: output fraction → source fraction (both 0..1). +public sealed record CurvePoint(double X, double Y); + +/// Virtual-camera keyframe in normalised coordinates. +public sealed record CameraKey(int Frame, double CenterX, double CenterY, double Zoom, double Rotation, string Easing = "EaseInOut"); + +public sealed record TimingSettings +{ + public Auto Mode { get; init; } = new(); + + /// Output frame rate as "num/den" or an integer (e.g. "24000/1001", "30"). + public Auto FrameRate { get; init; } = new(); + + /// When set, the plan is scaled so the video lasts this many seconds. + public double? FitToSeconds { get; init; } + + public IReadOnlyList RemapCurve { get; init; } = [new(0, 0), new(1, 1)]; +} + +public sealed record ExposureSettings +{ + public Auto Deflicker { get; init; } = new(); + + /// Local-regression window in frames (odd). + public Auto DeflickerWindow { get; init; } = new(); + + /// 0..1: share of the flicker removed. + public Auto DeflickerStrength { get; init; } = new(); + + public Auto Regions { get; init; } = new(); + + public Auto HolyGrail { get; init; } = new(); + + /// Transition length in frames for redistributed exposure steps. + public Auto TransitionLength { get; init; } = new(); + + public Auto WhiteBalanceSmoothing { get; init; } = new(); + + /// Global exposure offset in EV applied after correction. + public double ExposureOffsetEv { get; init; } + + /// Soft highlight knee (linear), null = hard clip at the encoder. + public double? HighlightKnee { get; init; } = 0.9; +} + +public sealed record MotionSettings +{ + public Auto MotionBlur { get; init; } = new(); + + /// Target shutter angle in degrees (180 = film look). + public Auto TargetShutterAngle { get; init; } = new(); + + public Auto FlowQuality { get; init; } = new(); + + public Auto Stabilize { get; init; } = new(); + + /// Path smoothing in frames (Gaussian sigma). + public Auto StabilizeSmoothing { get; init; } = new(); +} + +public sealed record CameraSettings +{ + /// Normalised crop (0..1) or null for the full frame. + public double[]? Crop { get; init; } + + /// "source", "16:9", "21:9", "4:3", "3:2", "1:1", "9:16", "4:5" or "w:h". + public Auto Aspect { get; init; } = new(); + + public double OffsetX { get; init; } + public double OffsetY { get; init; } + public IReadOnlyList Keyframes { get; init; } = []; +} + +public sealed record StackSettings +{ + public StackSetting Mode { get; init; } = StackSetting.None; + + /// Window (median/mean) or trail length (star trails) in frames. + public int Length { get; init; } = 9; +} + +/// Values of an export; null fields take the preset's value (BRIEF §11.4: editing any value makes it "Custom"). +public sealed record ExportOverrides +{ + public string? Codec { get; init; } + public string? Container { get; init; } + public string? Profile { get; init; } + public int? BitDepth { get; init; } + public int? Width { get; init; } + public int? Height { get; init; } + public string? FrameRate { get; init; } + public long? BitRate { get; init; } + public int? GopFrames { get; init; } + public int? BFrames { get; init; } + public int? Quality { get; init; } + public string? RateControl { get; init; } + public string? Encoder { get; init; } +} + +public sealed record ExportSettings +{ + /// Id of the selected preset (built-in or user); "custom" when values differ from every preset. + public Auto Preset { get; init; } = new(); + + public ExportOverrides Overrides { get; init; } = new(); + + /// Output file name template (tokens: date, title, preset, width, height, fps, codec). + public string NameTemplate { get; init; } = "{date} {title} - {preset}"; + + /// Output folder; null = the sequence's exports folder. + public string? Folder { get; init; } + + /// Presets queued together by "Render another preset" / batch. + public IReadOnlyList Batch { get; init; } = []; +} + +/// +/// The "project" of a sequence (.titano/project.json, BRIEF §7): every render decision. Originals are +/// never modified; all edits live here. +/// +public sealed record ProjectSettings +{ + public const int CurrentVersion = 1; + + public int Version { get; init; } = CurrentVersion; + public TimingSettings Timing { get; init; } = new(); + public ExposureSettings Exposure { get; init; } = new(); + public MotionSettings Motion { get; init; } = new(); + public CameraSettings Camera { get; init; } = new(); + public StackSettings Stack { get; init; } = new(); + public ExportSettings Export { get; init; } = new(); + + /// Frame indices excluded from renders. + public IReadOnlyList ExcludedFrames { get; init; } = []; + + /// Index of the hero frame (sequence thumbnail). + public int? HeroFrame { get; init; } + + public string ToJson() => JsonSerializer.Serialize(this, ProjectJson.Default.ProjectSettings); + + public static ProjectSettings FromJson(string json) + { + var settings = JsonSerializer.Deserialize(json, ProjectJson.Default.ProjectSettings) ?? new ProjectSettings(); + if (settings.Version > CurrentVersion) + throw new InvalidDataException($"project.json version {settings.Version} is newer than this Titano ({CurrentVersion})."); + return settings; + } +} + +[JsonSourceGenerationOptions( + WriteIndented = true, + PropertyNamingPolicy = JsonKnownNamingPolicy.CamelCase, + DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull, + UseStringEnumConverter = true, + PropertyNameCaseInsensitive = true)] +[JsonSerializable(typeof(ProjectSettings))] +internal sealed partial class ProjectJson : JsonSerializerContext; diff --git a/tests/Titano.Core.Tests/Project/ProjectSettingsTests.cs b/tests/Titano.Core.Tests/Project/ProjectSettingsTests.cs new file mode 100644 index 00000000..99712dd2 --- /dev/null +++ b/tests/Titano.Core.Tests/Project/ProjectSettingsTests.cs @@ -0,0 +1,60 @@ +using Titano.Core.Export; +using Titano.Core.Project; +using Titano.Core.Video; +using Titano.Testing; + +namespace Titano.Core.Tests.Project; + +public sealed class ProjectSettingsTests +{ + [Test] + public void JsonRoundTripKeepsAutoAndManualValues() + { + var settings = new ProjectSettings + { + Exposure = new ExposureSettings + { + DeflickerWindow = new Auto().WithAdvice(41, "Advisor.Reason.FlickerPeriod", "10.2"), + DeflickerStrength = new Auto().WithManual(0.8), + }, + Timing = new TimingSettings { FrameRate = new Auto().WithAdvice("24", null) }, + ExcludedFrames = [3, 7], + }; + var back = ProjectSettings.FromJson(settings.ToJson()); + Assert.Equal(41, back.Exposure.DeflickerWindow.Resolve(0)); + Assert.True(back.Exposure.DeflickerWindow.IsAuto); + Assert.Equal("Advisor.Reason.FlickerPeriod", back.Exposure.DeflickerWindow.ReasonKey); + Assert.Equal(0.8, back.Exposure.DeflickerStrength.Resolve(1.0)); + Assert.False(back.Exposure.DeflickerStrength.IsAuto); + Assert.SequenceEqual(new[] { 3, 7 }, back.ExcludedFrames); + Assert.Contains("\"deflickerWindow\"", settings.ToJson()); + } + + [Test] + public void ResetReturnsToAdvice() + { + var a = new Auto().WithAdvice(41, null).WithManual(15); + Assert.Equal(15, a.Resolve(0)); + Assert.Equal(41, a.Reset().Resolve(0)); + } + + [Test] + public void NewerVersionIsRefused() => + Assert.Throws(() => ProjectSettings.FromJson("{\"version\": 99}")); + + [Test] + public void BuiltInPresetIdsAreUnique() => + Assert.Equal(ExportPresets.BuiltIn.Count, ExportPresets.BuiltIn.Select(p => p.Id).Distinct().Count()); + + [Test] + public void BitRateFollowsBitsPerPixel() + { + var p = Assert.NotNull(ExportPresets.Find("4k-hevc10-archive")); + // 0.30 × 3840 × 2160 × 24 ≈ 59.7 Mb/s (archive budget); share presets use the codec default. + Assert.Equal(59_719_680L, p.EffectiveBitRate(3840, 2160, new Rational(24, 1))); + Assert.Equal(19_906_560L, ExportPresets.Find("4k-h264")!.EffectiveBitRate(3840, 2160, new Rational(24, 1))); + var s = p.ToEncodeSettings("out.mp4", 3840, 2160); + Assert.Equal(24, s.GopLength); + Assert.Equal(10, s.BitDepth); + } +}