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);
}