diff --git a/src/Titano.Core/Export/EncoderSelector.cs b/src/Titano.Core/Export/EncoderSelector.cs new file mode 100644 index 00000000..a318a06d --- /dev/null +++ b/src/Titano.Core/Export/EncoderSelector.cs @@ -0,0 +1,227 @@ +using System.Globalization; +using Titano.Core.Video; +using Titano.Core.Video.Managed; + +namespace Titano.Core.Export; + +/// Where a render runs: clients have platform encoders, the server only managed ones (BRIEF §4.2, §14.7). +public enum EncoderHost +{ + Client, + Server, +} + +public enum EncoderSelectionStatus +{ + /// An encoder accepts the (possibly adjusted) settings. + Ready, + + /// The codec needs a platform encoder: delegate the job to a render node (server). + NeedsRenderNode, + + /// No encoder on this machine can produce the codec. + Unavailable, +} + +/// A localisable explanation of a selection decision; arguments are invariant-culture strings. +public sealed record EncoderNotice(string Key, IReadOnlyList Args) +{ + public EncoderNotice(string key, params string[] args) : this(key, (IReadOnlyList)args) + { + } +} + +/// Result of . +public sealed record EncoderSelection +{ + public required EncoderSelectionStatus Status { get; init; } + + /// The settings to open the encoder with (codec, size, bit depth or bit rate may differ from the request). + public required EncodeSettings Settings { get; init; } + + public IVideoEncoderProvider? Provider { get; init; } + + /// The capability expected to serve the encode (the provider makes the final choice). + public EncoderCapability? Capability { get; init; } + + /// Lowest codec level the final settings fit (video codecs only). + public CodecLevel? Level { get; init; } + + public IReadOnlyList Notices { get; init; } = []; + + public bool IsReady => Status == EncoderSelectionStatus.Ready; + + /// Opens the session; only valid when . + public IVideoEncoderSession Open() => + Provider is not null && IsReady ? Provider.Open(Settings) : throw new InvalidOperationException($"No encoder is ready ({Status})"); +} + +/// Notice keys produced by . +public static class EncoderNotices +{ + public const string NeedsRenderNode = "Export.Encoder.NeedsRenderNode"; + public const string NoEncoder = "Export.Encoder.NoEncoder"; + public const string FallbackToH264 = "Export.Encoder.FallbackToH264"; + public const string SoftwareOnly = "Export.Encoder.SoftwareOnly"; + public const string TenBitUnavailable = "Export.Encoder.TenBitUnavailable"; + public const string BitDepthAdjusted = "Export.Encoder.BitDepthAdjusted"; + public const string ResolutionCappedByLevel = "Export.Encoder.ResolutionCappedByLevel"; + public const string ResolutionCappedByEncoder = "Export.Encoder.ResolutionCappedByEncoder"; + public const string BitRateCapped = "Export.Encoder.BitRateCapped"; +} + +/// +/// Picks the encoder for an export (BRIEF §11.3). Providers are given in priority order (client: Media Foundation, then +/// managed; server: managed only). +/// +/// Managed codecs go to the first provider that accepts them; an unsupported bit depth becomes the shallowest +/// supported depth that keeps all its precision (or the deepest available). +/// H.264/HEVC/AV1 on the server need a render node. On a client the capability is chosen by named encoder, then +/// 10-bit support when asked, then hardware (or software) as preferred, then provider order. HEVC and AV1 without any +/// encoder fall back to H.264 8-bit (bit rate scaled by the bits-per-pixel defaults), 10-bit without a 10-bit encoder +/// drops to 8-bit, and the size is capped to the highest codec level and to the encoder's maximum (aspect kept, even +/// sizes), the bit rate to the level's ceiling. Every adjustment carries a notice. +/// +/// +public static class EncoderSelector +{ + public static EncoderSelection Select(EncodeSettings requested, IReadOnlyList providers, EncoderHost host) + { + ArgumentNullException.ThrowIfNull(requested); + ArgumentNullException.ThrowIfNull(providers); + var notices = new List(); + return VideoCodecInfo.IsManaged(requested.Codec) + ? SelectManaged(requested, providers, notices) + : SelectVideo(requested, providers, host, notices); + } + + private static EncoderSelection SelectManaged(EncodeSettings settings, IReadOnlyList providers, List notices) + { + var depths = ManagedEncoderProvider.BitDepths(settings.Codec); + if (depths.Count > 0 && !depths.Contains(settings.BitDepth)) + { + var deeper = depths.Where(d => d >= settings.BitDepth).ToList(); + var depth = deeper.Count > 0 ? deeper.Min() : depths.Max(); + notices.Add(new EncoderNotice(EncoderNotices.BitDepthAdjusted, Invariant(settings.BitDepth), Invariant(depth))); + settings = settings with { BitDepth = depth }; + } + foreach (var provider in providers) + { + if (!provider.CanEncode(settings)) continue; + return new EncoderSelection + { + Status = EncoderSelectionStatus.Ready, + Settings = settings, + Provider = provider, + Capability = provider.Capabilities.FirstOrDefault(c => c.Codec == settings.Codec), + Notices = notices, + }; + } + notices.Add(new EncoderNotice(EncoderNotices.NoEncoder, settings.Codec.ToString())); + return new EncoderSelection { Status = EncoderSelectionStatus.Unavailable, Settings = settings, Notices = notices }; + } + + private static EncoderSelection SelectVideo(EncodeSettings settings, IReadOnlyList providers, EncoderHost host, List notices) + { + if (host == EncoderHost.Server) + { + notices.Add(new EncoderNotice(EncoderNotices.NeedsRenderNode, settings.Codec.ToString())); + return new EncoderSelection { Status = EncoderSelectionStatus.NeedsRenderNode, Settings = settings, Notices = notices }; + } + if (settings.Codec != VideoCodec.H264 && Candidates(providers, settings.Codec).Count == 0) + { + notices.Add(new EncoderNotice(EncoderNotices.FallbackToH264, settings.Codec.ToString())); + var factor = ExportPreset.DefaultBitsPerPixel(VideoCodec.H264) / ExportPreset.DefaultBitsPerPixel(settings.Codec); + settings = settings with + { + Codec = VideoCodec.H264, + Profile = CodecProfile.H264High, + BitDepth = 8, + BitRate = (long)double.Round(settings.BitRate * factor), + }; + } + if (settings.Codec == VideoCodec.H264 && settings.BitDepth != 8) + { + notices.Add(new EncoderNotice(EncoderNotices.BitDepthAdjusted, Invariant(settings.BitDepth), "8")); + settings = settings with { BitDepth = 8 }; + } + + var candidates = Candidates(providers, settings.Codec); + if (candidates.Count == 0) + { + notices.Add(new EncoderNotice(EncoderNotices.NoEncoder, settings.Codec.ToString())); + return new EncoderSelection { Status = EncoderSelectionStatus.Unavailable, Settings = settings, Notices = notices }; + } + var wantsTenBit = settings.BitDepth > 8; + var ordered = candidates + .Select((c, order) => (c.Provider, c.Capability, Order: order)) + .OrderByDescending(c => settings.EncoderName is not null && c.Capability.Name == settings.EncoderName) + .ThenByDescending(c => wantsTenBit && c.Capability.SupportsTenBit) + .ThenByDescending(c => c.Capability.Hardware == settings.PreferHardware) + .ThenBy(c => c.Order) + .ToList(); + + foreach (var (provider, capability, _) in ordered) + { + var local = new List(notices); + var adjusted = Fit(settings, capability, local); + if (!provider.CanEncode(adjusted)) continue; + if (settings.PreferHardware && !capability.Hardware) local.Add(new EncoderNotice(EncoderNotices.SoftwareOnly, capability.Name)); + var check = CodecLimits.Check(adjusted.Codec, adjusted.Width, adjusted.Height, adjusted.FrameRate.Value, adjusted.BitRate, adjusted.Profile); + return new EncoderSelection + { + Status = EncoderSelectionStatus.Ready, + Settings = adjusted, + Provider = provider, + Capability = capability, + Level = check.Level, + Notices = local, + }; + } + notices.Add(new EncoderNotice(EncoderNotices.NoEncoder, settings.Codec.ToString())); + return new EncoderSelection { Status = EncoderSelectionStatus.Unavailable, Settings = settings, Notices = notices }; + } + + private static List<(IVideoEncoderProvider Provider, EncoderCapability Capability)> Candidates(IReadOnlyList providers, VideoCodec codec) => + [.. providers.SelectMany(p => p.Capabilities.Where(c => c.Codec == codec).Select(c => (p, c)))]; + + /// Applies bit-depth, level and encoder-size limits for one capability. + private static EncodeSettings Fit(EncodeSettings s, EncoderCapability capability, List notices) + { + if (s.BitDepth > 8 && !capability.SupportsTenBit) + { + notices.Add(new EncoderNotice(EncoderNotices.TenBitUnavailable, capability.Name)); + s = s with { BitDepth = 8, Profile = s.Profile == CodecProfile.HevcMain10 ? CodecProfile.HevcMain : s.Profile }; + } + var even = (Width: s.Width & ~1, Height: s.Height & ~1); + s = s with { Width = int.Max(2, even.Width), Height = int.Max(2, even.Height) }; + + var fps = s.FrameRate.Value; + var check = CodecLimits.Check(s.Codec, s.Width, s.Height, fps, 0, s.Profile); + if (!check.Fits && check.SuggestedWidth > 0) + { + s = s with { Width = check.SuggestedWidth, Height = check.SuggestedHeight }; + notices.Add(new EncoderNotice(EncoderNotices.ResolutionCappedByLevel, check.HighestLevel.Name, Size(s))); + } + if (s.Width > capability.MaxWidth || s.Height > capability.MaxHeight) + { + var scale = double.Min((double)capability.MaxWidth / s.Width, (double)capability.MaxHeight / s.Height); + var width = int.Max(2, (int)(s.Width * scale) & ~1); + var height = int.Max(2, (int)double.Round(width * (double)s.Height / s.Width / 2) * 2); + if (height > capability.MaxHeight) height = capability.MaxHeight & ~1; + s = s with { Width = width, Height = height }; + notices.Add(new EncoderNotice(EncoderNotices.ResolutionCappedByEncoder, capability.Name, Size(s))); + } + var limits = CodecLimits.Check(s.Codec, s.Width, s.Height, fps, 0, s.Profile); + if (s.BitRate > limits.MaxBitRate) + { + s = s with { BitRate = limits.MaxBitRate }; + notices.Add(new EncoderNotice(EncoderNotices.BitRateCapped, limits.HighestLevel.Name, Invariant(limits.MaxBitRate))); + } + return s; + } + + private static string Size(EncodeSettings s) => string.Create(CultureInfo.InvariantCulture, $"{s.Width}×{s.Height}"); + + private static string Invariant(long value) => value.ToString(CultureInfo.InvariantCulture); +} diff --git a/tests/Titano.Core.Tests/Export/EncoderSelectorTests.cs b/tests/Titano.Core.Tests/Export/EncoderSelectorTests.cs new file mode 100644 index 00000000..31af272f --- /dev/null +++ b/tests/Titano.Core.Tests/Export/EncoderSelectorTests.cs @@ -0,0 +1,146 @@ +using Titano.Core.Export; +using Titano.Core.Tests.Render; +using Titano.Core.Video; +using Titano.Core.Video.Managed; +using Titano.Testing; + +namespace Titano.Core.Tests.Export; + +public sealed class EncoderSelectorTests +{ + private static readonly EncoderCapability SoftwareH264 = new(VideoCodec.H264, "Microsoft H.264", false, 4096, 2304, false); + private static readonly EncoderCapability HardwareH264 = new(VideoCodec.H264, "NVENC H.264", true, 4096, 4096, false, "NVIDIA"); + private static readonly EncoderCapability HardwareHevc = new(VideoCodec.Hevc, "NVENC HEVC", true, 8192, 8192, true, "NVIDIA"); + private static readonly EncoderCapability HardwareHevc8 = new(VideoCodec.Hevc, "QSV HEVC", true, 8192, 8192, false, "Intel"); + + private static EncodeSettings Request(VideoCodec codec, int width = 3840, int height = 2160, int bitDepth = 8, long bitRate = 20_000_000, Rational? fps = null) => new() + { + OutputPath = "/exports/out" + VideoCodecInfo.FileExtension(codec), + Codec = codec, + Width = width, + Height = height, + FrameRate = fps ?? new Rational(30, 1), + BitDepth = bitDepth, + BitRate = bitRate, + Profile = bitDepth == 10 ? CodecProfile.HevcMain10 : CodecProfile.Auto, + }; + + private static IVideoEncoderProvider[] Client(params EncoderCapability[] capabilities) => + [new CapturingEncoderProvider("Media Foundation", capabilities), new ManagedEncoderProvider()]; + + [Test] + public void ManagedCodecsUseTheManagedProviderEverywhere() + { + foreach (var host in new[] { EncoderHost.Client, EncoderHost.Server }) + { + var selection = EncoderSelector.Select(Request(VideoCodec.Mjpeg, bitDepth: 8), Client(HardwareH264), host); + Assert.True(selection.IsReady); + Assert.Equal(ManagedEncoderProvider.ProviderName, selection.Provider!.Name); + Assert.Equal("Managed MJPEG", selection.Capability!.Name); + Assert.Empty(selection.Notices); + } + } + + [Test] + public void ManagedBitDepthsAreAdjustedWithANotice() + { + var png = EncoderSelector.Select(Request(VideoCodec.PngSequence, bitDepth: 10), [new ManagedEncoderProvider()], EncoderHost.Server); + Assert.Equal(16, png.Settings.BitDepth); + Assert.Equal(EncoderNotices.BitDepthAdjusted, png.Notices.Single().Key); + Assert.SequenceEqual(new[] { "10", "16" }, png.Notices.Single().Args); + var jpeg = EncoderSelector.Select(Request(VideoCodec.JpegSequence, bitDepth: 16), [new ManagedEncoderProvider()], EncoderHost.Server); + Assert.Equal(8, jpeg.Settings.BitDepth); + } + + [Test] + public void ServerNeedsARenderNodeForMp4() + { + var selection = EncoderSelector.Select(Request(VideoCodec.H264), [new ManagedEncoderProvider()], EncoderHost.Server); + Assert.Equal(EncoderSelectionStatus.NeedsRenderNode, selection.Status); + Assert.Null(selection.Provider); + Assert.Equal(EncoderNotices.NeedsRenderNode, selection.Notices.Single().Key); + Assert.Throws(() => selection.Open()); + } + + [Test] + public void HardwareIsPreferredUnlessSoftwareIsAsked() + { + var providers = Client(SoftwareH264, HardwareH264); + var hardware = EncoderSelector.Select(Request(VideoCodec.H264), providers, EncoderHost.Client); + Assert.True(hardware.IsReady); + Assert.Equal("NVENC H.264", hardware.Capability!.Name); + Assert.Empty(hardware.Notices); + Assert.Equal(new CodecLevel(VideoCodec.H264, 5, 1), hardware.Level); + + var software = EncoderSelector.Select(Request(VideoCodec.H264) with { PreferHardware = false }, providers, EncoderHost.Client); + Assert.Equal("Microsoft H.264", software.Capability!.Name); + + var named = EncoderSelector.Select(Request(VideoCodec.H264) with { EncoderName = "Microsoft H.264" }, providers, EncoderHost.Client); + Assert.Equal("Microsoft H.264", named.Capability!.Name); + Assert.Equal(EncoderNotices.SoftwareOnly, named.Notices.Single().Key); + } + + [Test] + public void HevcFallsBackToH264WhenNoEncoderExists() + { + var selection = EncoderSelector.Select(Request(VideoCodec.Hevc, bitDepth: 10, bitRate: 14_000_000), Client(SoftwareH264), EncoderHost.Client); + Assert.True(selection.IsReady); + Assert.Equal(VideoCodec.H264, selection.Settings.Codec); + Assert.Equal(8, selection.Settings.BitDepth); + Assert.Equal(CodecProfile.H264High, selection.Settings.Profile); + Assert.Equal(20_000_000L, selection.Settings.BitRate); + Assert.Equal(EncoderNotices.FallbackToH264, selection.Notices[0].Key); + Assert.SequenceEqual(new[] { "Hevc" }, selection.Notices[0].Args); + Assert.Contains(selection.Notices, n => n.Key == EncoderNotices.SoftwareOnly); + Assert.Equal(".mp4", Path.GetExtension(selection.Settings.OutputPath)); + } + + [Test] + public void TenBitNeedsATenBitEncoder() + { + var eightOnly = EncoderSelector.Select(Request(VideoCodec.Hevc, bitDepth: 10), Client(HardwareHevc8), EncoderHost.Client); + Assert.Equal(8, eightOnly.Settings.BitDepth); + Assert.Equal(CodecProfile.HevcMain, eightOnly.Settings.Profile); + Assert.Equal(EncoderNotices.TenBitUnavailable, eightOnly.Notices.Single().Key); + + var tenBit = EncoderSelector.Select(Request(VideoCodec.Hevc, bitDepth: 10), Client(HardwareHevc8, HardwareHevc), EncoderHost.Client); + Assert.Equal("NVENC HEVC", tenBit.Capability!.Name); + Assert.Equal(10, tenBit.Settings.BitDepth); + Assert.Empty(tenBit.Notices); + } + + [Test] + public void SizeIsCappedByEncoderAndLevel() + { + var encoder = EncoderSelector.Select(Request(VideoCodec.H264, 7680, 4320), Client(HardwareH264), EncoderHost.Client); + Assert.Equal((4096, 2304), (encoder.Settings.Width, encoder.Settings.Height)); + Assert.Equal(EncoderNotices.ResolutionCappedByEncoder, encoder.Notices.Single().Key); + Assert.SequenceEqual(new[] { "NVENC H.264", "4096×2304" }, encoder.Notices.Single().Args); + + var level = EncoderSelector.Select(Request(VideoCodec.Hevc, 7680, 4320, fps: new Rational(240, 1)), Client(HardwareHevc), EncoderHost.Client); + Assert.Equal(EncoderNotices.ResolutionCappedByLevel, level.Notices[0].Key); + Assert.Less(level.Settings.Width, 7680); + Assert.Equal(0, level.Settings.Width % 2); + Assert.Approximately(16.0 / 9, level.Settings.Width / (double)level.Settings.Height, 0.01); + Assert.True(CodecLimits.Check(VideoCodec.Hevc, level.Settings.Width, level.Settings.Height, 240, level.Settings.BitRate).Fits); + + var odd = EncoderSelector.Select(Request(VideoCodec.H264, 1081, 607), Client(HardwareH264), EncoderHost.Client); + Assert.Equal((1080, 606), (odd.Settings.Width, odd.Settings.Height)); + } + + [Test] + public void BitRateIsCappedByTheHighestLevel() + { + var selection = EncoderSelector.Select(Request(VideoCodec.H264, 1920, 1080, bitRate: 2_000_000_000), Client(HardwareH264), EncoderHost.Client); + Assert.Equal(1_000_000_000L, selection.Settings.BitRate); + Assert.Equal(EncoderNotices.BitRateCapped, selection.Notices.Single().Key); + } + + [Test] + public void NoVideoEncoderMeansUnavailable() + { + var selection = EncoderSelector.Select(Request(VideoCodec.Av1), [new ManagedEncoderProvider()], EncoderHost.Client); + Assert.Equal(EncoderSelectionStatus.Unavailable, selection.Status); + Assert.SequenceEqual(new[] { EncoderNotices.FallbackToH264, EncoderNotices.NoEncoder }, selection.Notices.Select(n => n.Key)); + } +} diff --git a/tests/Titano.Core.Tests/Render/CapturingEncoderProvider.cs b/tests/Titano.Core.Tests/Render/CapturingEncoderProvider.cs new file mode 100644 index 00000000..cd5e3404 --- /dev/null +++ b/tests/Titano.Core.Tests/Render/CapturingEncoderProvider.cs @@ -0,0 +1,57 @@ +using Titano.Core.Imaging; +using Titano.Core.Video; + +namespace Titano.Core.Tests.Render; + +/// One encode recorded by . +internal sealed class CapturedEncode(EncodeSettings settings) +{ + public EncodeSettings Settings { get; } = settings; + public List Frames { get; } = []; + public List Durations { get; } = []; + public bool Completed { get; set; } + public bool Disposed { get; set; } +} + +/// Test encoder: keeps a copy of every frame, can pretend to be hardware or to fail at a given frame. +internal sealed class CapturingEncoderProvider(string name, params EncoderCapability[] capabilities) : IVideoEncoderProvider +{ + public string Name => name; + + public IReadOnlyList Capabilities => capabilities; + + public List Encodes { get; } = []; + + /// When set, WriteFrame throws this for the frame with that zero-based index. + public (int Frame, Exception Error)? FailAt { get; set; } + + public bool CanEncode(EncodeSettings settings) => capabilities.Any(c => + c.Codec == settings.Codec && settings.Width <= c.MaxWidth && settings.Height <= c.MaxHeight && (settings.BitDepth == 8 || c.SupportsTenBit)); + + public IVideoEncoderSession Open(EncodeSettings settings) + { + var encode = new CapturedEncode(settings); + Encodes.Add(encode); + var capability = capabilities.First(c => c.Codec == settings.Codec); + return new Session(this, encode, capability); + } + + private sealed class Session(CapturingEncoderProvider owner, CapturedEncode encode, EncoderCapability capability) : IVideoEncoderSession + { + public string EncoderName => capability.Name; + + public bool IsHardware => capability.Hardware; + + public void WriteFrame(ImageBuffer frame, long duration90k) + { + if (owner.FailAt is { } fail && fail.Frame == encode.Frames.Count) throw fail.Error; + if (frame.Width != encode.Settings.Width || frame.Height != encode.Settings.Height) throw new ArgumentException("size"); + encode.Frames.Add(frame.Clone()); + encode.Durations.Add(duration90k); + } + + public void Complete() => encode.Completed = true; + + public void Dispose() => encode.Disposed = true; + } +}