Files
Chronos/src/Titano.Core/Export/EncoderSelector.cs
T
Claude f9c83af609 feat(export): encoder selection with hardware preference, fallbacks and level caps
Client renders prefer hardware Media Foundation encoders, fall back from
HEVC/AV1 to H.264, drop to 8-bit and cap size/bit rate with reason keys;
the server reports that MP4 codecs need a render node.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012iLMBNwBE2GnphAsu4cjaC
2026-10-02 10:48:34 +00:00

228 lines
11 KiB
C#
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
using System.Globalization;
using Titano.Core.Video;
using Titano.Core.Video.Managed;
namespace Titano.Core.Export;
/// <summary>Where a render runs: clients have platform encoders, the server only managed ones (BRIEF §4.2, §14.7).</summary>
public enum EncoderHost
{
Client,
Server,
}
public enum EncoderSelectionStatus
{
/// <summary>An encoder accepts the (possibly adjusted) settings.</summary>
Ready,
/// <summary>The codec needs a platform encoder: delegate the job to a render node (server).</summary>
NeedsRenderNode,
/// <summary>No encoder on this machine can produce the codec.</summary>
Unavailable,
}
/// <summary>A localisable explanation of a selection decision; arguments are invariant-culture strings.</summary>
public sealed record EncoderNotice(string Key, IReadOnlyList<string> Args)
{
public EncoderNotice(string key, params string[] args) : this(key, (IReadOnlyList<string>)args)
{
}
}
/// <summary>Result of <see cref="EncoderSelector.Select"/>.</summary>
public sealed record EncoderSelection
{
public required EncoderSelectionStatus Status { get; init; }
/// <summary>The settings to open the encoder with (codec, size, bit depth or bit rate may differ from the request).</summary>
public required EncodeSettings Settings { get; init; }
public IVideoEncoderProvider? Provider { get; init; }
/// <summary>The capability expected to serve the encode (the provider makes the final choice).</summary>
public EncoderCapability? Capability { get; init; }
/// <summary>Lowest codec level the final settings fit (video codecs only).</summary>
public CodecLevel? Level { get; init; }
public IReadOnlyList<EncoderNotice> Notices { get; init; } = [];
public bool IsReady => Status == EncoderSelectionStatus.Ready;
/// <summary>Opens the session; only valid when <see cref="IsReady"/>.</summary>
public IVideoEncoderSession Open() =>
Provider is not null && IsReady ? Provider.Open(Settings) : throw new InvalidOperationException($"No encoder is ready ({Status})");
}
/// <summary>Notice keys produced by <see cref="EncoderSelector"/>.</summary>
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";
}
/// <summary>
/// Picks the encoder for an export (BRIEF §11.3). Providers are given in priority order (client: Media Foundation, then
/// managed; server: managed only).
/// <list type="bullet">
/// <item>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).</item>
/// <item>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.</item>
/// </list>
/// </summary>
public static class EncoderSelector
{
public static EncoderSelection Select(EncodeSettings requested, IReadOnlyList<IVideoEncoderProvider> providers, EncoderHost host)
{
ArgumentNullException.ThrowIfNull(requested);
ArgumentNullException.ThrowIfNull(providers);
var notices = new List<EncoderNotice>();
return VideoCodecInfo.IsManaged(requested.Codec)
? SelectManaged(requested, providers, notices)
: SelectVideo(requested, providers, host, notices);
}
private static EncoderSelection SelectManaged(EncodeSettings settings, IReadOnlyList<IVideoEncoderProvider> providers, List<EncoderNotice> 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<IVideoEncoderProvider> providers, EncoderHost host, List<EncoderNotice> 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<EncoderNotice>(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<IVideoEncoderProvider> providers, VideoCodec codec) =>
[.. providers.SelectMany(p => p.Capabilities.Where(c => c.Codec == codec).Select(c => (p, c)))];
/// <summary>Applies bit-depth, level and encoder-size limits for one capability.</summary>
private static EncodeSettings Fit(EncodeSettings s, EncoderCapability capability, List<EncoderNotice> 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);
}