Merge pull request #279 from SubtitleEdit/feature/plugin-contract-settings-version-and-video

Mirror SE5 contract: settingsVersion + video duration/resolution

Author: niksedk

se5/Haxor/PluginContract.cs

@@ -24,6 +24,16 @@ public sealed class PluginRequest
 
     public string VideoFileName { get; set; } = string.Empty;
     public double FrameRate { get; set; }
+
+    /// <summary>Total video duration in seconds. Null when no video is loaded or on older SE versions.</summary>
+    public double? VideoDurationSeconds { get; set; }
+
+    /// <summary>Video frame width in pixels. Null when no video is loaded or on older SE versions.</summary>
+    public int? VideoWidth { get; set; }
+
+    /// <summary>Video frame height in pixels. Null when no video is loaded or on older SE versions.</summary>
+    public int? VideoHeight { get; set; }
+
     public string UiLanguage { get; set; } = string.Empty;
     public string Theme { get; set; } = string.Empty;
 
@@ -34,6 +44,12 @@ public sealed class PluginRequest
 
     /// <summary>This plugin's settings as last persisted by Subtitle Edit (null on first run).</summary>
     public JsonElement? Settings { get; set; }
+
+    /// <summary>
+    /// Schema version this plugin attached to <see cref="Settings"/> in its last response.
+    /// Null on first run, when settings were saved without a version, or on older SE versions.
+    /// </summary>
+    public int? SettingsVersion { get; set; }
 }
 
 /// <summary>Active theme colors. All values are <c>#AARRGGBB</c> hex strings.</summary>
@@ -78,5 +94,11 @@ public sealed class PluginResponse
     /// <summary>Settings to persist; handed back unchanged in the next request.</summary>
     public JsonElement? Settings { get; set; }
 
+    /// <summary>
+    /// Schema version for <see cref="Settings"/>. Bump when you change the shape of your
+    /// settings so you can migrate or reset on the next run. Optional; null = "unversioned".
+    /// </summary>
+    public int? SettingsVersion { get; set; }
+
     public string? UndoDescription { get; set; }
 }

se5/Plugin-Shared/PluginContract.cs

@@ -16,6 +16,16 @@ public sealed class PluginRequest
     public List<int> SelectedIndices { get; set; } = new();
     public string VideoFileName { get; set; } = string.Empty;
     public double FrameRate { get; set; }
+
+    /// <summary>Total video duration in seconds. Null when no video is loaded or on older SE versions.</summary>
+    public double? VideoDurationSeconds { get; set; }
+
+    /// <summary>Video frame width in pixels. Null when no video is loaded or on older SE versions.</summary>
+    public int? VideoWidth { get; set; }
+
+    /// <summary>Video frame height in pixels. Null when no video is loaded or on older SE versions.</summary>
+    public int? VideoHeight { get; set; }
+
     public string UiLanguage { get; set; } = string.Empty;
     public string Theme { get; set; } = string.Empty;
 
@@ -24,6 +34,13 @@ public sealed class PluginRequest
 
     public string SeVersion { get; set; } = string.Empty;
     public JsonElement? Settings { get; set; }
+
+    /// <summary>
+    /// Schema version this plugin attached to <see cref="Settings"/> in its last response.
+    /// Null on first run, when settings were saved without a version, or on older SE versions.
+    /// Use it to migrate or reset settings written by an older build of this plugin.
+    /// </summary>
+    public int? SettingsVersion { get; set; }
 }
 
 /// <summary>Active theme colors. All values are <c>#AARRGGBB</c> hex strings.</summary>
@@ -53,6 +70,14 @@ public sealed class PluginResponse
     public string? Message { get; set; }
     public PluginSubtitle? Subtitle { get; set; }
     public JsonElement? Settings { get; set; }
+
+    /// <summary>
+    /// Schema version for <see cref="Settings"/>. Bump when you change the shape of your
+    /// settings so you can detect (and migrate or reset) stale data on the next run via
+    /// <see cref="PluginRequest.SettingsVersion"/>. Optional; null = "unversioned".
+    /// </summary>
+    public int? SettingsVersion { get; set; }
+
     public string? UndoDescription { get; set; }
 }
 

se5/TypewriterEffect/PluginContract.cs

@@ -15,6 +15,16 @@ public sealed class PluginRequest
     public List<int> SelectedIndices { get; set; } = new();
     public string VideoFileName { get; set; } = string.Empty;
     public double FrameRate { get; set; }
+
+    /// <summary>Total video duration in seconds. Null when no video is loaded or on older SE versions.</summary>
+    public double? VideoDurationSeconds { get; set; }
+
+    /// <summary>Video frame width in pixels. Null when no video is loaded or on older SE versions.</summary>
+    public int? VideoWidth { get; set; }
+
+    /// <summary>Video frame height in pixels. Null when no video is loaded or on older SE versions.</summary>
+    public int? VideoHeight { get; set; }
+
     public string UiLanguage { get; set; } = string.Empty;
     public string Theme { get; set; } = string.Empty;
 
@@ -23,6 +33,12 @@ public sealed class PluginRequest
 
     public string SeVersion { get; set; } = string.Empty;
     public JsonElement? Settings { get; set; }
+
+    /// <summary>
+    /// Schema version this plugin attached to <see cref="Settings"/> in its last response.
+    /// Null on first run, when settings were saved without a version, or on older SE versions.
+    /// </summary>
+    public int? SettingsVersion { get; set; }
 }
 
 /// <summary>Active theme colors. All values are <c>#AARRGGBB</c> hex strings.</summary>
@@ -52,5 +68,12 @@ public sealed class PluginResponse
     public string? Message { get; set; }
     public PluginSubtitle? Subtitle { get; set; }
     public JsonElement? Settings { get; set; }
+
+    /// <summary>
+    /// Schema version for <see cref="Settings"/>. Bump when you change the shape of your
+    /// settings so you can migrate or reset on the next run. Optional; null = "unversioned".
+    /// </summary>
+    public int? SettingsVersion { get; set; }
+
     public string? UndoDescription { get; set; }
 }