feat(core): project settings with Auto/manual values and export presets

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012iLMBNwBE2GnphAsu4cjaC
This commit is contained in:
Claude committed 2026-10-02 10:01:27 +00:00
1 parent db672af3ca
commit 63d1855f82
5 files changed
+423

No files matched your search

+1
View File
@@ -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. |
+131
View File
@@ -0,0 +1,131 @@
using Titano.Core.Video;
namespace Titano.Core.Export;
/// <summary>
/// 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. <see cref="NameKey"/> is the localized display name.
/// </summary>
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;
/// <summary>Output size; 0×0 = source size (image sequences).</summary>
public int Width { get; init; }
public int Height { get; init; }
public Rational FrameRate { get; init; } = new(30, 1);
/// <summary>Fixed bit rate in bit/s; 0 = derived from <see cref="BitsPerPixel"/>.</summary>
public long BitRate { get; init; }
public double BitsPerPixel { get; init; }
/// <summary>Key-frame distance in seconds.</summary>
public double GopSeconds { get; init; } = 1;
public int BFrames { get; init; } = 2;
/// <summary>JPEG/MJPEG/GIF quality 1–100.</summary>
public int Quality { get; init; } = 92;
public bool IsBuiltIn { get; init; } = true;
/// <summary>Category for grouping in the Export tab.</summary>
public string Group { get; init; } = "video";
/// <summary>Average bit rate in bit/s for the preset's size and frame rate.</summary>
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,
};
/// <summary>Encode settings for this preset at a given output size.</summary>
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,
};
}
}
/// <summary>The built-in presets of BRIEF §11.4.</summary>
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);
/// <summary>Archive presets keep ~4× the share budget so star fields and gradients survive re-encoding.</summary>
public const double ArchiveBitsPerPixel = 0.30;
public static IReadOnlyList<ExportPreset> 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));
/// <summary>Standard resolutions offered in the Custom editor (BRIEF §11.4).</summary>
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),
];
/// <summary>Frame rates offered (BRIEF §11.4).</summary>
public static IReadOnlyList<Rational> 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),
];
}
+31
View File
@@ -0,0 +1,31 @@
namespace Titano.Core.Project;
/// <summary>
/// A parameter the advisor can decide (BRIEF §10.4). In Auto the advisor's <see cref="AutoValue"/> applies and
/// <see cref="ReasonKey"/>/<see cref="ReasonArgs"/> explain it; touching the control stores a manual
/// <see cref="Manual"/> value; reset returns to Auto.
/// </summary>
public sealed record Auto<T>
{
public bool IsAuto { get; init; } = true;
/// <summary>The advisor's value (null until analysis provides one).</summary>
public T? AutoValue { get; init; }
/// <summary>The user's value when <see cref="IsAuto"/> is false.</summary>
public T? Manual { get; init; }
/// <summary>Localization key of the reason shown in the Auto pill tooltip.</summary>
public string? ReasonKey { get; init; }
public IReadOnlyList<string>? ReasonArgs { get; init; }
/// <summary>The value in force: manual when set by the user, otherwise the advisor's, otherwise <paramref name="fallback"/>.</summary>
public T Resolve(T fallback) => !IsAuto && Manual is not null ? Manual : AutoValue ?? fallback;
public Auto<T> WithManual(T value) => this with { IsAuto = false, Manual = value };
public Auto<T> Reset() => this with { IsAuto = true, Manual = default };
public Auto<T> WithAdvice(T value, string? reasonKey, params string[] args) => this with { AutoValue = value, ReasonKey = reasonKey, ReasonArgs = args };
}
+200
View File
@@ -0,0 +1,200 @@
using System.Text.Json;
using System.Text.Json.Serialization;
namespace Titano.Core.Project;
public enum TimingMode
{
/// <summary>Every source frame lasts one output frame.</summary>
Constant,
/// <summary>Output time follows capture time (deliberate intervalometer pauses are kept short, gaps preserved).</summary>
Adaptive,
/// <summary>Missing frames in sparse gaps are synthesised from motion.</summary>
Interpolated,
/// <summary>A monotone curve maps output time to source position (speed ramps).</summary>
Remapped,
}
public enum RegionMode
{
Off,
Auto,
Horizon,
Luminance,
}
public enum FlowQualitySetting
{
Draft,
Balanced,
Best,
}
public enum StackSetting
{
None,
Median,
Mean,
StarTrails,
}
/// <summary>A control point of the time-remap curve: output fraction → source fraction (both 0..1).</summary>
public sealed record CurvePoint(double X, double Y);
/// <summary>Virtual-camera keyframe in normalised coordinates.</summary>
public sealed record CameraKey(int Frame, double CenterX, double CenterY, double Zoom, double Rotation, string Easing = "EaseInOut");
public sealed record TimingSettings
{
public Auto<TimingMode> Mode { get; init; } = new();
/// <summary>Output frame rate as "num/den" or an integer (e.g. "24000/1001", "30").</summary>
public Auto<string> FrameRate { get; init; } = new();
/// <summary>When set, the plan is scaled so the video lasts this many seconds.</summary>
public double? FitToSeconds { get; init; }
public IReadOnlyList<CurvePoint> RemapCurve { get; init; } = [new(0, 0), new(1, 1)];
}
public sealed record ExposureSettings
{
public Auto<bool> Deflicker { get; init; } = new();
/// <summary>Local-regression window in frames (odd).</summary>
public Auto<int> DeflickerWindow { get; init; } = new();
/// <summary>0..1: share of the flicker removed.</summary>
public Auto<double> DeflickerStrength { get; init; } = new();
public Auto<RegionMode> Regions { get; init; } = new();
public Auto<bool> HolyGrail { get; init; } = new();
/// <summary>Transition length in frames for redistributed exposure steps.</summary>
public Auto<int> TransitionLength { get; init; } = new();
public Auto<bool> WhiteBalanceSmoothing { get; init; } = new();
/// <summary>Global exposure offset in EV applied after correction.</summary>
public double ExposureOffsetEv { get; init; }
/// <summary>Soft highlight knee (linear), null = hard clip at the encoder.</summary>
public double? HighlightKnee { get; init; } = 0.9;
}
public sealed record MotionSettings
{
public Auto<bool> MotionBlur { get; init; } = new();
/// <summary>Target shutter angle in degrees (180 = film look).</summary>
public Auto<double> TargetShutterAngle { get; init; } = new();
public Auto<FlowQualitySetting> FlowQuality { get; init; } = new();
public Auto<bool> Stabilize { get; init; } = new();
/// <summary>Path smoothing in frames (Gaussian sigma).</summary>
public Auto<double> StabilizeSmoothing { get; init; } = new();
}
public sealed record CameraSettings
{
/// <summary>Normalised crop (0..1) or null for the full frame.</summary>
public double[]? Crop { get; init; }
/// <summary>"source", "16:9", "21:9", "4:3", "3:2", "1:1", "9:16", "4:5" or "w:h".</summary>
public Auto<string> Aspect { get; init; } = new();
public double OffsetX { get; init; }
public double OffsetY { get; init; }
public IReadOnlyList<CameraKey> Keyframes { get; init; } = [];
}
public sealed record StackSettings
{
public StackSetting Mode { get; init; } = StackSetting.None;
/// <summary>Window (median/mean) or trail length (star trails) in frames.</summary>
public int Length { get; init; } = 9;
}
/// <summary>Values of an export; null fields take the preset's value (BRIEF §11.4: editing any value makes it "Custom").</summary>
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
{
/// <summary>Id of the selected preset (built-in or user); "custom" when values differ from every preset.</summary>
public Auto<string> Preset { get; init; } = new();
public ExportOverrides Overrides { get; init; } = new();
/// <summary>Output file name template (tokens: date, title, preset, width, height, fps, codec).</summary>
public string NameTemplate { get; init; } = "{date} {title} - {preset}";
/// <summary>Output folder; null = the sequence's exports folder.</summary>
public string? Folder { get; init; }
/// <summary>Presets queued together by "Render another preset" / batch.</summary>
public IReadOnlyList<string> Batch { get; init; } = [];
}
/// <summary>
/// The "project" of a sequence (<c>.titano/project.json</c>, BRIEF §7): every render decision. Originals are
/// never modified; all edits live here.
/// </summary>
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();
/// <summary>Frame indices excluded from renders.</summary>
public IReadOnlyList<int> ExcludedFrames { get; init; } = [];
/// <summary>Index of the hero frame (sequence thumbnail).</summary>
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;
@@ -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<int>().WithAdvice(41, "Advisor.Reason.FlickerPeriod", "10.2"),
DeflickerStrength = new Auto<double>().WithManual(0.8),
},
Timing = new TimingSettings { FrameRate = new Auto<string>().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<int>().WithAdvice(41, null).WithManual(15);
Assert.Equal(15, a.Resolve(0));
Assert.Equal(41, a.Reset().Resolve(0));
}
[Test]
public void NewerVersionIsRefused() =>
Assert.Throws<InvalidDataException>(() => 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);
}
}