From bc543f99b6c50d3320cf9760e31039b1c7d9728f Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 2 Oct 2026 09:35:00 +0000 Subject: [PATCH] feat(video): add H.264/HEVC/AV1 level tables with level selection and size capping Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_012iLMBNwBE2GnphAsu4cjaC --- src/Titano.Core/Video/CodecLimits.cs | 214 ++++++++++++++++++ .../Video/CodecLimitsTests.cs | 70 ++++++ 2 files changed, 284 insertions(+) create mode 100644 src/Titano.Core/Video/CodecLimits.cs create mode 100644 tests/Titano.Core.Tests/Video/CodecLimitsTests.cs diff --git a/src/Titano.Core/Video/CodecLimits.cs b/src/Titano.Core/Video/CodecLimits.cs new file mode 100644 index 00000000..4c95e39c --- /dev/null +++ b/src/Titano.Core/Video/CodecLimits.cs @@ -0,0 +1,214 @@ +using System.Globalization; + +namespace Titano.Core.Video; + +/// A codec level such as H.264 4.1, HEVC 5.1 or AV1 5.0. +public readonly record struct CodecLevel(VideoCodec Codec, int Major, int Minor) +{ + public string Name => string.Create(CultureInfo.InvariantCulture, $"{Major}.{Minor}"); + + /// H.264 level_idc (10 × level), also the eAVEncH264VLevel value. + public int H264LevelIdc => Major * 10 + Minor; + + /// HEVC general_level_idc (30 × level), also the eAVEncH265VLevel value. + public int HevcLevelIdc => Major * 30 + Minor * 3; + + /// AV1 seq_level_idx. + public int Av1SeqLevelIdx => (Major - 2) * 4 + Minor; + + public override string ToString() => Name; +} + +/// Level constraints a configuration can break. +[Flags] +public enum LevelLimit +{ + None = 0, + PictureSize = 1, + Dimension = 2, + SampleRate = 4, + BitRate = 8, +} + +/// Outcome of . +/// Lowest level that fits, or null when even the highest level is exceeded. +/// Highest level defined for the codec. +/// Limits the highest level violates ( when a level fits). +/// Largest even width with the same aspect ratio that fits the highest level at this frame rate. +/// Height matching . +/// Bit-rate ceiling of the highest level for the profile, in bits per second. +public sealed record LevelCheck(CodecLevel? Level, CodecLevel HighestLevel, LevelLimit Exceeded, int SuggestedWidth, int SuggestedHeight, long MaxBitRate) +{ + public bool Fits => Level is not null; +} + +/// +/// Level tables for H.264 (Table A-1), HEVC (Tables A.8/A.9, Main/Main10, main tier) and AV1 (Annex A.3, main tier): +/// picks the lowest level for a size, frame rate and bit rate, and proposes a capped size when none fits. +/// +public static class CodecLimits +{ + // Major, Minor, max luma picture samples, max luma samples per second, max bit rate (kbit/s, before the profile factor), + // max width, max height (0 = derived from the picture size as sqrt(8 × size)). + private readonly record struct Limits(int Major, int Minor, long PictureSamples, long SampleRate, long BitRateKbps, int MaxWidth, int MaxHeight); + + // H.264 limits are in macroblocks: MaxFS × 256 samples, MaxMBPS × 256 samples/s. + private static readonly Limits[] H264 = + [ + new(1, 0, 99 * 256L, 1485 * 256L, 64, 0, 0), + new(1, 1, 396 * 256L, 3000 * 256L, 192, 0, 0), + new(1, 2, 396 * 256L, 6000 * 256L, 384, 0, 0), + new(1, 3, 396 * 256L, 11880 * 256L, 768, 0, 0), + new(2, 0, 396 * 256L, 11880 * 256L, 2000, 0, 0), + new(2, 1, 792 * 256L, 19800 * 256L, 4000, 0, 0), + new(2, 2, 1620 * 256L, 20250 * 256L, 4000, 0, 0), + new(3, 0, 1620 * 256L, 40500 * 256L, 10000, 0, 0), + new(3, 1, 3600 * 256L, 108000 * 256L, 14000, 0, 0), + new(3, 2, 5120 * 256L, 216000 * 256L, 20000, 0, 0), + new(4, 0, 8192 * 256L, 245760 * 256L, 20000, 0, 0), + new(4, 1, 8192 * 256L, 245760 * 256L, 50000, 0, 0), + new(4, 2, 8704 * 256L, 522240 * 256L, 50000, 0, 0), + new(5, 0, 22080 * 256L, 589824 * 256L, 135000, 0, 0), + new(5, 1, 36864 * 256L, 983040 * 256L, 240000, 0, 0), + new(5, 2, 36864 * 256L, 2073600 * 256L, 240000, 0, 0), + new(6, 0, 139264 * 256L, 4177920 * 256L, 240000, 0, 0), + new(6, 1, 139264 * 256L, 8355840 * 256L, 480000, 0, 0), + new(6, 2, 139264 * 256L, 16711680 * 256L, 800000, 0, 0), + ]; + + private static readonly Limits[] Hevc = + [ + new(1, 0, 36864, 552960, 128, 0, 0), + new(2, 0, 122880, 3686400, 1500, 0, 0), + new(2, 1, 245760, 7372800, 3000, 0, 0), + new(3, 0, 552960, 16588800, 6000, 0, 0), + new(3, 1, 983040, 33177600, 10000, 0, 0), + new(4, 0, 2228224, 66846720, 12000, 0, 0), + new(4, 1, 2228224, 133693440, 20000, 0, 0), + new(5, 0, 8912896, 267386880, 25000, 0, 0), + new(5, 1, 8912896, 534773760, 40000, 0, 0), + new(5, 2, 8912896, 1069547520, 60000, 0, 0), + new(6, 0, 35651584, 1069547520, 60000, 0, 0), + new(6, 1, 35651584, 2139095040, 120000, 0, 0), + new(6, 2, 35651584, 4278190080, 240000, 0, 0), + ]; + + // AV1: MaxPicSize, MaxDisplayRate, main-tier MaxBitrate, MaxHSize, MaxVSize. + private static readonly Limits[] Av1 = + [ + new(2, 0, 147456, 4423680, 1500, 2048, 1152), + new(2, 1, 278784, 8363520, 3000, 2816, 1584), + new(3, 0, 665856, 19975680, 6000, 4352, 2448), + new(3, 1, 1065024, 31950720, 10000, 5504, 3096), + new(4, 0, 2359296, 70778880, 12000, 6144, 3456), + new(4, 1, 2359296, 141557760, 20000, 6144, 3456), + new(5, 0, 8912896, 267386880, 30000, 8192, 4352), + new(5, 1, 8912896, 534773760, 40000, 8192, 4352), + new(5, 2, 8912896, 1069547520, 60000, 8192, 4352), + new(5, 3, 8912896, 1069547520, 60000, 8192, 4352), + new(6, 0, 35651584, 1069547520, 60000, 16384, 8704), + new(6, 1, 35651584, 2139095040, 100000, 16384, 8704), + new(6, 2, 35651584, 4278190080, 160000, 16384, 8704), + new(6, 3, 35651584, 4278190080, 160000, 16384, 8704), + ]; + + /// Levels defined for , lowest first. + public static IReadOnlyList Levels(VideoCodec codec) => [.. Table(codec).Select(l => new CodecLevel(codec, l.Major, l.Minor))]; + + /// Finds the lowest level for the configuration; ≤ 0 skips the bit-rate check. + public static LevelCheck Check(VideoCodec codec, int width, int height, double fps, long bitRate, CodecProfile profile = CodecProfile.Auto) + { + ArgumentOutOfRangeException.ThrowIfNegativeOrZero(width); + ArgumentOutOfRangeException.ThrowIfNegativeOrZero(height); + if (!(fps > 0)) throw new ArgumentOutOfRangeException(nameof(fps)); + var table = Table(codec); + var factor = BitRateFactor(codec, profile); + foreach (var limits in table) + { + if (Violations(codec, limits, width, height, fps, bitRate, factor) == LevelLimit.None) + return new LevelCheck(new CodecLevel(codec, limits.Major, limits.Minor), Highest(codec), LevelLimit.None, width, height, MaxBitRate(table[^1], factor)); + } + var top = table[^1]; + var exceeded = Violations(codec, top, width, height, fps, bitRate, factor); + var (w, h) = Cap(codec, top, width, height, fps); + return new LevelCheck(null, Highest(codec), exceeded, w, h, MaxBitRate(top, factor)); + } + + /// Largest even size with the aspect ratio of × that fits the highest level. + public static (int Width, int Height) CapResolution(VideoCodec codec, int width, int height, double fps) + { + var check = Check(codec, width, height, fps, 0); + return (check.SuggestedWidth, check.SuggestedHeight); + } + + private static (int Width, int Height) Cap(VideoCodec codec, Limits top, int width, int height, double fps) + { + // Fitting is monotonic in the scale, so bisect on half the width (keeps sizes even). + int lo = 0, hi = width / 2; + while (lo < hi) + { + var mid = (lo + hi + 1) / 2; + var (w, h) = Scaled(width, height, mid * 2); + if ((Violations(codec, top, w, h, fps, 0, 1) & ~LevelLimit.BitRate) == LevelLimit.None) lo = mid; + else hi = mid - 1; + } + return lo == 0 ? (0, 0) : Scaled(width, height, lo * 2); + } + + private static (int Width, int Height) Scaled(int width, int height, int newWidth) + { + var h = (int)Math.Max(2, Math.Round(newWidth * (double)height / width / 2) * 2); + return (newWidth, h); + } + + private static LevelLimit Violations(VideoCodec codec, Limits l, int width, int height, double fps, long bitRate, double factor) + { + long w = width, h = height; + if (codec == VideoCodec.H264) + { + w = (width + 15) / 16 * 16; + h = (height + 15) / 16 * 16; + } + else if (codec == VideoCodec.Hevc) + { + w = (width + 7) / 8 * 8; // MinCbSizeY of 8 + h = (height + 7) / 8 * 8; + } + var size = w * h; + var result = LevelLimit.None; + if (size > l.PictureSamples) result |= LevelLimit.PictureSize; + if (l.MaxWidth > 0) + { + if (w > l.MaxWidth || h > l.MaxHeight) result |= LevelLimit.Dimension; + } + else + { + // H.264 A.3.1 / HEVC A.4.1: each side at most sqrt(8 × maximum picture size). + var side = Math.Sqrt(8.0 * l.PictureSamples); + if (w > side || h > side) result |= LevelLimit.Dimension; + } + if (size * fps > l.SampleRate * (1 + 1e-9)) result |= LevelLimit.SampleRate; + if (bitRate > 0 && bitRate > MaxBitRate(l, factor)) result |= LevelLimit.BitRate; + return result; + } + + private static long MaxBitRate(Limits l, double factor) => (long)(l.BitRateKbps * 1000 * factor); + + /// cpbBrVclFactor relative to 1000: H.264 High is 1250 (A.3.3.2); Baseline/Main, HEVC Main/Main10 and AV1 main are 1000. + private static double BitRateFactor(VideoCodec codec, CodecProfile profile) => + codec == VideoCodec.H264 && profile is CodecProfile.H264High or CodecProfile.Auto ? 1.25 : 1.0; + + private static CodecLevel Highest(VideoCodec codec) + { + var top = Table(codec)[^1]; + return new CodecLevel(codec, top.Major, top.Minor); + } + + private static Limits[] Table(VideoCodec codec) => codec switch + { + VideoCodec.H264 => H264, + VideoCodec.Hevc => Hevc, + VideoCodec.Av1 => Av1, + _ => throw new ArgumentException($"No level table for {codec}", nameof(codec)), + }; +} diff --git a/tests/Titano.Core.Tests/Video/CodecLimitsTests.cs b/tests/Titano.Core.Tests/Video/CodecLimitsTests.cs new file mode 100644 index 00000000..27cc9521 --- /dev/null +++ b/tests/Titano.Core.Tests/Video/CodecLimitsTests.cs @@ -0,0 +1,70 @@ +using Titano.Core.Video; +using Titano.Testing; + +namespace Titano.Core.Tests.Video; + +public sealed class CodecLimitsTests +{ + [Theory] + [Case(VideoCodec.H264, 1920, 1080, 30.0, 6_220_800L, "4.0", Name = "1080p30 H.264 (0.10 bpp)")] + [Case(VideoCodec.H264, 1920, 1080, 60.0, 12_441_600L, "4.2")] + [Case(VideoCodec.H264, 1280, 720, 30.0, 0L, "3.1")] + [Case(VideoCodec.H264, 3840, 2160, 30.0, 24_883_200L, "5.1")] + [Case(VideoCodec.H264, 1920, 1080, 30.0, 40_000_000L, "4.1", Name = "1080p30 H.264 at 40 Mbit/s")] + [Case(VideoCodec.Hevc, 3840, 2160, 60.0, 34_836_480L, "5.1", Name = "4K60 HEVC (0.07 bpp)")] + [Case(VideoCodec.Hevc, 7680, 4320, 30.0, 69_672_960L, "6.1", Name = "8K30 HEVC (0.07 bpp)")] + [Case(VideoCodec.Hevc, 7680, 4320, 30.0, 50_000_000L, "6.0")] + [Case(VideoCodec.Hevc, 1920, 1080, 30.0, 0L, "4.0")] + [Case(VideoCodec.Av1, 1920, 1080, 30.0, 0L, "4.0")] + [Case(VideoCodec.Av1, 3840, 2160, 60.0, 29_859_840L, "5.1")] + [Case(VideoCodec.Av1, 640, 360, 24.0, 0L, "2.1")] + public void ChoosesLowestFittingLevel(VideoCodec codec, int width, int height, double fps, long bitRate, string level) + { + var check = CodecLimits.Check(codec, width, height, fps, bitRate); + Assert.True(check.Fits); + Assert.Equal(level, check.Level!.Value.Name); + Assert.Equal(LevelLimit.None, check.Exceeded); + Assert.Equal(width, check.SuggestedWidth); + } + + [Test] + public void LevelIdentifiersMatchTheBitstreamCodes() + { + Assert.Equal(41, new CodecLevel(VideoCodec.H264, 4, 1).H264LevelIdc); + Assert.Equal(153, new CodecLevel(VideoCodec.Hevc, 5, 1).HevcLevelIdc); + Assert.Equal(186, new CodecLevel(VideoCodec.Hevc, 6, 2).HevcLevelIdc); + Assert.Equal(13, new CodecLevel(VideoCodec.Av1, 5, 1).Av1SeqLevelIdx); + Assert.Equal(19, CodecLimits.Levels(VideoCodec.H264).Count); + Assert.Equal("6.3", CodecLimits.Levels(VideoCodec.Av1)[^1].Name); + } + + [Theory] + [Case(VideoCodec.H264, 16384, 8640, 30.0)] + [Case(VideoCodec.Hevc, 15360, 8640, 60.0)] + [Case(VideoCodec.Av1, 20000, 10000, 30.0)] + public void OversizedConfigurationsGetACappedSuggestion(VideoCodec codec, int width, int height, double fps) + { + var check = CodecLimits.Check(codec, width, height, fps, 0); + Assert.False(check.Fits); + Assert.True((check.Exceeded & (LevelLimit.PictureSize | LevelLimit.SampleRate | LevelLimit.Dimension)) != 0); + Assert.True(check.SuggestedWidth % 2 == 0 && check.SuggestedHeight % 2 == 0); + Assert.Approximately(width / (double)height, check.SuggestedWidth / (double)check.SuggestedHeight, 0.01); + Assert.True(CodecLimits.Check(codec, check.SuggestedWidth, check.SuggestedHeight, fps, 0).Fits); + // The suggestion is tight: a slightly larger size no longer fits. + var w = check.SuggestedWidth + 64; + var h = (int)Math.Round(w * (double)height / width); + Assert.False(CodecLimits.Check(codec, w, h, fps, 0).Fits); + } + + [Test] + public void ExcessiveBitRateIsReportedWithoutResizing() + { + var check = CodecLimits.Check(VideoCodec.H264, 1920, 1080, 30, 2_000_000_000, CodecProfile.H264High); + Assert.False(check.Fits); + Assert.Equal(LevelLimit.BitRate, check.Exceeded); + Assert.Equal(1920, check.SuggestedWidth); + Assert.Equal(1080, check.SuggestedHeight); + Assert.Equal(1_000_000_000L, check.MaxBitRate); + Assert.Equal(800_000_000L, CodecLimits.Check(VideoCodec.H264, 64, 64, 30, 0, CodecProfile.H264Main).MaxBitRate); + } +}