feat(video): add bitstream readers for Annex-B, H.264/HEVC SPS and AV1 OBUs

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012iLMBNwBE2GnphAsu4cjaC
This commit is contained in:
Claude committed 2026-10-02 09:24:38 +00:00
1 parent 800843d2ae
commit bb7bc6490d
8 files changed
+1630

No files matched your search

@@ -0,0 +1,214 @@
using System.Buffers.Binary;
namespace Titano.Core.Video.Bitstream;
/// <summary>H.264 nal_unit_type values (ITU-T H.264 Table 7-1).</summary>
public enum H264NalUnitType : byte
{
Unspecified = 0,
NonIdrSlice = 1,
SliceDataPartitionA = 2,
SliceDataPartitionB = 3,
SliceDataPartitionC = 4,
IdrSlice = 5,
Sei = 6,
Sps = 7,
Pps = 8,
AccessUnitDelimiter = 9,
EndOfSequence = 10,
EndOfStream = 11,
FillerData = 12,
SpsExtension = 13,
PrefixNal = 14,
SubsetSps = 15,
}
/// <summary>HEVC nal_unit_type values (ITU-T H.265 Table 7-1).</summary>
public enum HevcNalUnitType : byte
{
TrailN = 0,
TrailR = 1,
TsaN = 2,
TsaR = 3,
StsaN = 4,
StsaR = 5,
RadlN = 6,
RadlR = 7,
RaslN = 8,
RaslR = 9,
BlaWLp = 16,
BlaWRadl = 17,
BlaNLp = 18,
IdrWRadl = 19,
IdrNLp = 20,
Cra = 21,
Vps = 32,
Sps = 33,
Pps = 34,
AccessUnitDelimiter = 35,
EndOfSequence = 36,
EndOfBitstream = 37,
FillerData = 38,
PrefixSei = 39,
SuffixSei = 40,
}
/// <summary>Location of one NAL unit (header included, start code or length prefix excluded) inside a buffer.</summary>
public readonly record struct NalUnit(int Offset, int Length)
{
public ReadOnlySpan<byte> Slice(ReadOnlySpan<byte> buffer) => buffer.Slice(Offset, Length);
}
/// <summary>Annex-B byte streams and ISO/IEC 14496-15 length-prefixed samples of H.264/HEVC NAL units.</summary>
public static class AnnexBParser
{
private static ReadOnlySpan<byte> StartCode => [0, 0, 1];
/// <summary>True when the data begins with a 3- or 4-byte start code.</summary>
public static bool StartsWithStartCode(ReadOnlySpan<byte> data) =>
data.Length >= 3 && data[0] == 0 && data[1] == 0 && (data[2] == 1 || (data.Length >= 4 && data[2] == 0 && data[3] == 1));
/// <summary>
/// Splits an Annex-B stream at 3/4-byte start codes. Bytes before the first start code are ignored and
/// trailing zero bytes (trailing_zero_8bits, the leading zero of a 4-byte start code) are not part of a unit.
/// </summary>
public static List<NalUnit> Split(ReadOnlySpan<byte> data)
{
var units = new List<NalUnit>();
var first = data.IndexOf(StartCode);
if (first < 0) return units;
var start = first + 3;
while (true)
{
var next = data[start..].IndexOf(StartCode);
var end = next < 0 ? data.Length : start + next;
var nalEnd = end;
while (nalEnd > start && data[nalEnd - 1] == 0) nalEnd--;
if (nalEnd > start) units.Add(new NalUnit(start, nalEnd - start));
if (next < 0) return units;
start = end + 3;
}
}
/// <summary>
/// Splits big-endian length-prefixed NAL units. Returns false (with the units read so far) when a length
/// is zero, runs past the end or the buffer does not end exactly after the last unit.
/// </summary>
public static bool TrySplitLengthPrefixed(ReadOnlySpan<byte> data, int lengthSize, out List<NalUnit> units)
{
if (lengthSize is not (1 or 2 or 4)) throw new ArgumentOutOfRangeException(nameof(lengthSize));
units = [];
var pos = 0;
while (pos < data.Length)
{
if (data.Length - pos < lengthSize) return false;
var length = lengthSize switch
{
1 => data[pos],
2 => BinaryPrimitives.ReadUInt16BigEndian(data[pos..]),
_ => (long)BinaryPrimitives.ReadUInt32BigEndian(data[pos..]),
};
pos += lengthSize;
if (length == 0 || length > data.Length - pos) return false;
units.Add(new NalUnit(pos, (int)length));
pos += (int)length;
}
return units.Count > 0;
}
/// <summary>
/// Splits one access unit given either with 4-byte length prefixes or as Annex-B. The length-prefixed reading
/// wins only when it covers the buffer exactly with valid NAL headers, which an Annex-B stream practically never does.
/// </summary>
public static List<NalUnit> SplitAccessUnit(ReadOnlySpan<byte> data, out bool wasAnnexB)
{
if (TrySplitLengthPrefixed(data, 4, out var units) && HeadersValid(data, units))
{
wasAnnexB = false;
return units;
}
wasAnnexB = true;
return Split(data);
}
private static bool HeadersValid(ReadOnlySpan<byte> data, List<NalUnit> units)
{
foreach (var u in units)
{
if ((data[u.Offset] & 0x80) != 0) return false; // forbidden_zero_bit
}
return true;
}
/// <summary>Removes emulation_prevention_three_byte (00 00 03 → 00 00) to obtain the RBSP.</summary>
public static byte[] RemoveEmulationPrevention(ReadOnlySpan<byte> nal)
{
var output = new byte[nal.Length];
var n = 0;
var zeros = 0;
foreach (var b in nal)
{
if (zeros >= 2 && b == 3)
{
zeros = 0;
continue;
}
output[n++] = b;
zeros = b == 0 ? zeros + 1 : 0;
}
return n == output.Length ? output : output.AsSpan(0, n).ToArray();
}
/// <summary>Inserts emulation prevention bytes so the payload contains no start-code prefix.</summary>
public static byte[] AddEmulationPrevention(ReadOnlySpan<byte> rbsp)
{
var output = new List<byte>(rbsp.Length + rbsp.Length / 64 + 2);
var zeros = 0;
foreach (var b in rbsp)
{
if (zeros >= 2 && b <= 3)
{
output.Add(3);
zeros = 0;
}
output.Add(b);
zeros = b == 0 ? zeros + 1 : 0;
}
// A payload ending in 0x00 (cabac_zero_word) gets a final 0x03 (H.264 7.4.1).
if (rbsp.Length > 0 && rbsp[^1] == 0) output.Add(3);
return [.. output];
}
public static H264NalUnitType H264Type(byte header) => (H264NalUnitType)(header & 0x1F);
public static HevcNalUnitType HevcType(byte header) => (HevcNalUnitType)((header >> 1) & 0x3F);
/// <summary>Converts an Annex-B stream to 4-byte big-endian length prefixes.</summary>
public static byte[] ToLengthPrefixed(ReadOnlySpan<byte> annexB)
{
var units = Split(annexB);
var total = 0;
foreach (var u in units) total += 4 + u.Length;
var output = new byte[total];
var pos = 0;
foreach (var u in units)
{
BinaryPrimitives.WriteInt32BigEndian(output.AsSpan(pos), u.Length);
annexB.Slice(u.Offset, u.Length).CopyTo(output.AsSpan(pos + 4));
pos += 4 + u.Length;
}
return output;
}
/// <summary>Concatenates NAL units with 4-byte start codes.</summary>
public static byte[] ToAnnexB(IEnumerable<byte[]> nalUnits)
{
using var ms = new MemoryStream();
foreach (var nal in nalUnits)
{
ms.Write([0, 0, 0, 1]);
ms.Write(nal);
}
return ms.ToArray();
}
}
@@ -0,0 +1,321 @@
namespace Titano.Core.Video.Bitstream;
/// <summary>AV1 obu_type values (AV1 specification 6.2.2).</summary>
public enum Av1ObuType : byte
{
SequenceHeader = 1,
TemporalDelimiter = 2,
FrameHeader = 3,
TileGroup = 4,
Metadata = 5,
Frame = 6,
RedundantFrameHeader = 7,
TileList = 8,
Padding = 15,
}
/// <summary>One OBU inside a buffer: header (with extension and size field) followed by the payload.</summary>
public readonly record struct Av1Obu(Av1ObuType Type, int Offset, int HeaderLength, int PayloadLength, bool HasSizeField, bool HasExtension, byte TemporalId, byte SpatialId)
{
public int TotalLength => HeaderLength + PayloadLength;
public ReadOnlySpan<byte> Payload(ReadOnlySpan<byte> buffer) => buffer.Slice(Offset + HeaderLength, PayloadLength);
}
/// <summary>Sequence header fields needed by av1C, level checks and diagnostics.</summary>
public sealed record Av1SequenceHeader
{
public required int SeqProfile { get; init; }
public required bool StillPicture { get; init; }
public required bool ReducedStillPictureHeader { get; init; }
public required int SeqLevelIdx { get; init; }
public required bool SeqTier { get; init; }
public required bool HighBitDepth { get; init; }
public required bool TwelveBit { get; init; }
public required int BitDepth { get; init; }
public required bool MonoChrome { get; init; }
public required bool ChromaSubsamplingX { get; init; }
public required bool ChromaSubsamplingY { get; init; }
public required int ChromaSamplePosition { get; init; }
public required int MaxFrameWidth { get; init; }
public required int MaxFrameHeight { get; init; }
public required int ColorPrimaries { get; init; }
public required int TransferCharacteristics { get; init; }
public required int MatrixCoefficients { get; init; }
public required bool FullRange { get; init; }
/// <summary>initial_display_delay_minus_1 + 1 of operating point 0, when signalled.</summary>
public int? InitialDisplayDelay { get; init; }
}
/// <summary>AV1 low-overhead bitstream (OBU) parsing. Never throws on malformed input.</summary>
public static class Av1ObuParser
{
/// <summary>Reads the OBU at <paramref name="offset"/>; one without obu_size extends to the end of the buffer.</summary>
public static bool TryReadObu(ReadOnlySpan<byte> data, int offset, out Av1Obu obu)
{
obu = default;
if (offset < 0 || offset >= data.Length) return false;
var header = data[offset];
if ((header & 0x80) != 0) return false; // obu_forbidden_bit
var type = (Av1ObuType)((header >> 3) & 0x0F);
var hasExtension = (header & 0x04) != 0;
var hasSize = (header & 0x02) != 0;
var pos = offset + 1;
byte temporalId = 0, spatialId = 0;
if (hasExtension)
{
if (pos >= data.Length) return false;
temporalId = (byte)(data[pos] >> 5);
spatialId = (byte)((data[pos] >> 3) & 3);
pos++;
}
long payload;
if (hasSize)
{
if (!TryReadLeb128(data[pos..], out var size, out var sizeLength)) return false;
pos += sizeLength;
payload = (long)Math.Min(size, int.MaxValue);
}
else
{
payload = data.Length - pos;
}
if (payload > data.Length - pos) return false;
obu = new Av1Obu(type, offset, pos - offset, (int)payload, hasSize, hasExtension, temporalId, spatialId);
return true;
}
/// <summary>Splits a buffer into OBUs, stopping at the first malformed one.</summary>
public static List<Av1Obu> Split(ReadOnlySpan<byte> data)
{
var list = new List<Av1Obu>();
var pos = 0;
while (pos < data.Length && TryReadObu(data, pos, out var obu))
{
list.Add(obu);
pos += obu.TotalLength;
}
return list;
}
/// <summary>Splits a low-overhead stream into temporal units, each starting at a temporal delimiter OBU.</summary>
public static List<(int Offset, int Length)> SplitTemporalUnits(ReadOnlySpan<byte> stream)
{
var units = new List<(int Offset, int Length)>();
var start = -1;
var end = 0;
foreach (var obu in Split(stream))
{
if (obu.Type == Av1ObuType.TemporalDelimiter)
{
if (start >= 0) units.Add((start, obu.Offset - start));
start = obu.Offset;
}
else if (start < 0)
{
start = obu.Offset; // stream without a leading delimiter
}
end = obu.Offset + obu.TotalLength;
}
if (start >= 0 && end > start) units.Add((start, end - start));
return units;
}
public static bool TryReadLeb128(ReadOnlySpan<byte> data, out ulong value, out int length)
{
value = 0;
for (length = 0; length < 8 && length < data.Length; length++)
{
var b = data[length];
value |= (ulong)(b & 0x7F) << (7 * length);
if ((b & 0x80) == 0)
{
length++;
return value <= uint.MaxValue;
}
}
return false;
}
public static int Leb128Size(ulong value)
{
var n = 1;
while ((value >>= 7) != 0) n++;
return n;
}
public static int WriteLeb128(Span<byte> destination, ulong value)
{
var n = 0;
do
{
var b = (byte)(value & 0x7F);
value >>= 7;
destination[n++] = value != 0 ? (byte)(b | 0x80) : b;
}
while (value != 0);
return n;
}
/// <summary>Parses a sequence_header_obu() payload (AV1 5.5).</summary>
public static bool TryParseSequenceHeader(ReadOnlySpan<byte> payload, out Av1SequenceHeader header)
{
header = null!;
var r = new BitReader(payload);
var profile = (int)r.ReadBits(3);
if (profile > 2) return false;
var still = r.ReadFlag();
var reduced = r.ReadFlag();
int levelIdx;
var tier = false;
int? initialDelay = null;
if (reduced)
{
levelIdx = (int)r.ReadBits(5);
}
else
{
var decoderModelInfo = false;
var bufferDelayLength = 0;
if (r.ReadFlag())
{
r.ReadBits(32); // num_units_in_display_tick
r.ReadBits(32); // time_scale
if (r.ReadFlag()) r.ReadUvlc(); // equal_picture_interval, num_ticks_per_picture_minus_1
decoderModelInfo = r.ReadFlag();
if (decoderModelInfo)
{
bufferDelayLength = (int)r.ReadBits(5) + 1;
r.ReadBits(32); // num_units_in_decoding_tick
r.ReadBits(5); // buffer_removal_time_length_minus_1
r.ReadBits(5); // frame_presentation_time_length_minus_1
}
}
var initialDisplayDelayPresent = r.ReadFlag();
var operatingPoints = (int)r.ReadBits(5) + 1;
levelIdx = 0;
for (var i = 0; i < operatingPoints && !r.IsOverrun; i++)
{
r.ReadBits(12); // operating_point_idc
var level = (int)r.ReadBits(5);
var opTier = level > 7 && r.ReadFlag();
if (decoderModelInfo && r.ReadFlag())
{
r.Skip(bufferDelayLength * 2L + 1); // decoder/encoder buffer delay, low_delay_mode_flag
}
int? delay = null;
if (initialDisplayDelayPresent && r.ReadFlag()) delay = (int)r.ReadBits(4) + 1;
if (i == 0)
{
levelIdx = level;
tier = opTier;
initialDelay = delay;
}
}
}
var widthBits = (int)r.ReadBits(4) + 1;
var heightBits = (int)r.ReadBits(4) + 1;
var maxWidth = (int)r.ReadBits(widthBits) + 1;
var maxHeight = (int)r.ReadBits(heightBits) + 1;
if (!reduced && r.ReadFlag())
{
r.ReadBits(4); // delta_frame_id_length_minus_2
r.ReadBits(3); // additional_frame_id_length_minus_1
}
r.ReadBits(3); // use_128x128_superblock, enable_filter_intra, enable_intra_edge_filter
if (!reduced)
{
r.ReadBits(4); // interintra, masked compound, warped motion, dual filter
var orderHint = r.ReadFlag();
if (orderHint) r.ReadBits(2); // enable_jnt_comp, enable_ref_frame_mvs
var forceScreenContent = r.ReadFlag() ? 2 : (int)r.ReadBits(1);
if (forceScreenContent > 0 && !r.ReadFlag()) r.ReadBits(1); // seq_force_integer_mv
if (orderHint) r.ReadBits(3); // order_hint_bits_minus_1
}
r.ReadBits(3); // enable_superres, enable_cdef, enable_restoration
// color_config()
var highBitDepth = r.ReadFlag();
var twelveBit = false;
var bitDepth = 8;
if (profile == 2 && highBitDepth)
{
twelveBit = r.ReadFlag();
bitDepth = twelveBit ? 12 : 10;
}
else if (highBitDepth)
{
bitDepth = 10;
}
var mono = profile != 1 && r.ReadFlag();
int primaries = 2, transfer = 2, matrix = 2;
if (r.ReadFlag())
{
primaries = (int)r.ReadBits(8);
transfer = (int)r.ReadBits(8);
matrix = (int)r.ReadBits(8);
}
bool fullRange, subX, subY;
var samplePosition = 0;
if (mono)
{
fullRange = r.ReadFlag();
subX = subY = true;
}
else if (primaries == 1 && transfer == 13 && matrix == 0)
{
fullRange = true;
subX = subY = false;
}
else
{
fullRange = r.ReadFlag();
if (profile == 0)
{
subX = subY = true;
}
else if (profile == 1)
{
subX = subY = false;
}
else if (bitDepth == 12)
{
subX = r.ReadFlag();
subY = subX && r.ReadFlag();
}
else
{
subX = true;
subY = false;
}
if (subX && subY) samplePosition = (int)r.ReadBits(2);
}
if (r.IsOverrun) return false;
header = new Av1SequenceHeader
{
SeqProfile = profile,
StillPicture = still,
ReducedStillPictureHeader = reduced,
SeqLevelIdx = levelIdx,
SeqTier = tier,
HighBitDepth = highBitDepth,
TwelveBit = twelveBit,
BitDepth = bitDepth,
MonoChrome = mono,
ChromaSubsamplingX = subX,
ChromaSubsamplingY = subY,
ChromaSamplePosition = samplePosition,
MaxFrameWidth = maxWidth,
MaxFrameHeight = maxHeight,
ColorPrimaries = primaries,
TransferCharacteristics = transfer,
MatrixCoefficients = matrix,
FullRange = fullRange,
InitialDisplayDelay = initialDelay,
};
return true;
}
}
@@ -0,0 +1,113 @@
namespace Titano.Core.Video.Bitstream;
/// <summary>
/// MSB-first bit reader over an RBSP (emulation prevention already removed). Reading past the end yields zero
/// bits and sets <see cref="IsOverrun"/>, so parsers finish a pass over truncated input and reject it afterwards
/// instead of throwing.
/// </summary>
public ref struct BitReader
{
private readonly ReadOnlySpan<byte> _data;
private long _position;
public BitReader(ReadOnlySpan<byte> data)
{
_data = data;
_position = 0;
IsOverrun = false;
}
/// <summary>Bit offset from the start of the data.</summary>
public readonly long Position => _position;
public readonly long BitsRemaining => Math.Max(0, (long)_data.Length * 8 - _position);
public readonly bool IsByteAligned => (_position & 7) == 0;
/// <summary>True once a read went past the end or an Exp-Golomb code exceeded 32 bits.</summary>
public bool IsOverrun { get; private set; }
public uint ReadBit()
{
var index = _position >> 3;
if (index >= _data.Length)
{
IsOverrun = true;
_position++;
return 0;
}
var bit = (uint)(_data[(int)index] >> (7 - (int)(_position & 7))) & 1;
_position++;
return bit;
}
public bool ReadFlag() => ReadBit() != 0;
/// <summary>Reads 0–32 bits, most significant first.</summary>
public uint ReadBits(int count)
{
ArgumentOutOfRangeException.ThrowIfGreaterThan((uint)count, 32u, nameof(count));
uint value = 0;
// Whole bytes when aligned keep long fields (32-bit timing values) cheap.
while (count >= 8 && IsByteAligned && (_position >> 3) < _data.Length)
{
value = (value << 8) | _data[(int)(_position >> 3)];
_position += 8;
count -= 8;
}
for (var i = 0; i < count; i++) value = (value << 1) | ReadBit();
return value;
}
/// <summary>Reads 0–64 bits, most significant first.</summary>
public ulong ReadBits64(int count)
{
ArgumentOutOfRangeException.ThrowIfGreaterThan((uint)count, 64u, nameof(count));
if (count <= 32) return ReadBits(count);
var high = (ulong)ReadBits(count - 32);
return (high << 32) | ReadBits(32);
}
public void Skip(long bits)
{
_position += bits;
if (_position > (long)_data.Length * 8) IsOverrun = true;
}
public void AlignToByte() => _position = (_position + 7) & ~7L;
/// <summary>Unsigned Exp-Golomb ue(v).</summary>
public uint ReadUe()
{
var zeros = 0;
while (ReadBit() == 0)
{
if (++zeros > 31 || IsOverrun)
{
IsOverrun = true;
return 0;
}
}
return zeros == 0 ? 0 : (uint)((1UL << zeros) - 1 + ReadBits(zeros));
}
/// <summary>Signed Exp-Golomb se(v).</summary>
public int ReadSe()
{
var k = ReadUe();
return (k & 1) != 0 ? (int)((k + 1) / 2) : -(int)(k / 2);
}
/// <summary>AV1 uvlc(): returns <see cref="uint.MaxValue"/> for 32 or more leading zeros.</summary>
public uint ReadUvlc()
{
var zeros = 0;
while (ReadBit() == 0)
{
if (IsOverrun) return 0;
zeros++;
}
if (zeros >= 32) return uint.MaxValue;
return ReadBits(zeros) + (uint)((1UL << zeros) - 1);
}
}
@@ -0,0 +1,80 @@
using System.Numerics;
namespace Titano.Core.Video.Bitstream;
/// <summary>MSB-first bit writer with Exp-Golomb and AV1 leb128 helpers (used to synthesise parameter sets).</summary>
public sealed class BitWriter
{
private byte[] _buffer = new byte[64];
private long _bitLength;
public long BitLength => _bitLength;
public bool IsByteAligned => (_bitLength & 7) == 0;
public void WriteBit(bool bit) => WriteBits(bit ? 1UL : 0UL, 1);
/// <summary>Writes the low <paramref name="count"/> bits (0–64) of <paramref name="value"/>, most significant first.</summary>
public void WriteBits(ulong value, int count)
{
ArgumentOutOfRangeException.ThrowIfGreaterThan((uint)count, 64u, nameof(count));
EnsureCapacity(_bitLength + count);
for (var i = count - 1; i >= 0; i--)
{
if (((value >> i) & 1) != 0) _buffer[_bitLength >> 3] |= (byte)(0x80 >> (int)(_bitLength & 7));
_bitLength++;
}
}
/// <summary>Unsigned Exp-Golomb ue(v); values up to 2³² − 2 are readable by <see cref="BitReader"/>.</summary>
public void WriteUe(uint value)
{
var v = (ulong)value + 1;
var bits = 64 - BitOperations.LeadingZeroCount(v);
WriteBits(0, bits - 1);
WriteBits(v, bits);
}
/// <summary>Signed Exp-Golomb se(v).</summary>
public void WriteSe(int value) => WriteUe(value > 0 ? (uint)(2L * value - 1) : (uint)(-2L * value));
/// <summary>rbsp_trailing_bits(): a stop bit followed by zero bits up to the byte boundary.</summary>
public void WriteTrailingBits()
{
WriteBit(true);
AlignWithZeros();
}
public void AlignWithZeros()
{
var pad = (int)((8 - (_bitLength & 7)) & 7);
WriteBits(0, pad);
}
public void WriteBytes(ReadOnlySpan<byte> bytes)
{
foreach (var b in bytes) WriteBits(b, 8);
}
/// <summary>AV1 leb128() (byte aligned).</summary>
public void WriteLeb128(ulong value)
{
do
{
var b = (byte)(value & 0x7F);
value >>= 7;
WriteBits(value != 0 ? b | 0x80u : b, 8);
}
while (value != 0);
}
/// <summary>The written bytes; a partial last byte is zero padded.</summary>
public byte[] ToArray() => _buffer.AsSpan(0, (int)((_bitLength + 7) >> 3)).ToArray();
private void EnsureCapacity(long bits)
{
var bytes = (bits + 7) >> 3;
if (bytes <= _buffer.Length) return;
Array.Resize(ref _buffer, (int)Math.Max(bytes, _buffer.Length * 2L));
}
}
@@ -0,0 +1,230 @@
namespace Titano.Core.Video.Bitstream;
/// <summary>Fields of an H.264 sequence parameter set needed for containers and diagnostics.</summary>
public sealed record H264Sps
{
public required int ProfileIdc { get; init; }
/// <summary>constraint_set0..5 flags plus the two reserved bits, as the byte stored in avcC.</summary>
public required byte ConstraintFlags { get; init; }
public required int LevelIdc { get; init; }
public required int SpsId { get; init; }
public required int ChromaFormatIdc { get; init; }
public required int BitDepthLuma { get; init; }
public required int BitDepthChroma { get; init; }
/// <summary>Displayed width after frame cropping.</summary>
public required int Width { get; init; }
/// <summary>Displayed height after frame cropping.</summary>
public required int Height { get; init; }
public required int CodedWidth { get; init; }
public required int CodedHeight { get; init; }
public required bool FrameMbsOnly { get; init; }
public required int PicOrderCntType { get; init; }
public required int MaxNumRefFrames { get; init; }
public bool HasVui { get; init; }
public int SarWidth { get; init; } = 1;
public int SarHeight { get; init; } = 1;
public bool? FullRange { get; init; }
public int? ColourPrimaries { get; init; }
public int? TransferCharacteristics { get; init; }
public int? MatrixCoefficients { get; init; }
/// <summary>VUI num_units_in_tick (0 when timing info is absent).</summary>
public uint NumUnitsInTick { get; init; }
/// <summary>VUI time_scale (0 when timing info is absent).</summary>
public uint TimeScale { get; init; }
public bool FixedFrameRate { get; init; }
/// <summary>Frame rate from VUI timing (time_scale / 2·num_units_in_tick), or null.</summary>
public double? FrameRate => NumUnitsInTick > 0 && TimeScale > 0 ? TimeScale / (2.0 * NumUnitsInTick) : null;
}
/// <summary>Parses H.264 SPS NAL units (ITU-T H.264 7.3.2.1.1). Never throws on malformed input.</summary>
public static class H264SpsParser
{
/// <summary>Parses an SPS NAL unit (header byte included, emulation prevention present).</summary>
public static bool TryParse(ReadOnlySpan<byte> nal, out H264Sps sps)
{
sps = null!;
if (nal.Length < 4 || AnnexBParser.H264Type(nal[0]) != H264NalUnitType.Sps) return false;
var rbsp = AnnexBParser.RemoveEmulationPrevention(nal[1..]);
var r = new BitReader(rbsp);
var profile = (int)r.ReadBits(8);
var constraints = (byte)r.ReadBits(8);
var level = (int)r.ReadBits(8);
var spsId = r.ReadUe();
if (spsId > 31) return false;
int chroma = 1, depthLuma = 8, depthChroma = 8;
var separateColourPlane = false;
if (profile is 100 or 110 or 122 or 244 or 44 or 83 or 86 or 118 or 128 or 138 or 139 or 134 or 135)
{
chroma = (int)r.ReadUe();
if (chroma > 3) return false;
if (chroma == 3) separateColourPlane = r.ReadFlag();
depthLuma = 8 + (int)r.ReadUe();
depthChroma = 8 + (int)r.ReadUe();
if (depthLuma > 14 || depthChroma > 14) return false;
r.ReadFlag(); // qpprime_y_zero_transform_bypass_flag
if (r.ReadFlag())
{
var lists = chroma != 3 ? 8 : 12;
for (var i = 0; i < lists && !r.IsOverrun; i++)
{
if (r.ReadFlag()) SkipScalingList(ref r, i < 6 ? 16 : 64);
}
}
}
r.ReadUe(); // log2_max_frame_num_minus4
var pocType = (int)r.ReadUe();
if (pocType == 0)
{
r.ReadUe(); // log2_max_pic_order_cnt_lsb_minus4
}
else if (pocType == 1)
{
r.ReadFlag(); // delta_pic_order_always_zero_flag
r.ReadSe(); // offset_for_non_ref_pic
r.ReadSe(); // offset_for_top_to_bottom_field
var cycle = r.ReadUe();
if (cycle > 255) return false;
for (var i = 0; i < cycle; i++) r.ReadSe();
}
else if (pocType != 2)
{
return false;
}
var maxRefFrames = (int)r.ReadUe();
r.ReadFlag(); // gaps_in_frame_num_value_allowed_flag
var widthMbs = r.ReadUe() + 1L;
var heightMapUnits = r.ReadUe() + 1L;
var frameMbsOnly = r.ReadFlag();
if (!frameMbsOnly) r.ReadFlag(); // mb_adaptive_frame_field_flag
r.ReadFlag(); // direct_8x8_inference_flag
long cropLeft = 0, cropRight = 0, cropTop = 0, cropBottom = 0;
if (r.ReadFlag())
{
cropLeft = r.ReadUe();
cropRight = r.ReadUe();
cropTop = r.ReadUe();
cropBottom = r.ReadUe();
}
var codedWidth = widthMbs * 16;
var codedHeight = (2 - (frameMbsOnly ? 1 : 0)) * heightMapUnits * 16;
var chromaArrayType = separateColourPlane ? 0 : chroma;
var cropUnitX = chromaArrayType == 0 ? 1 : (chromaArrayType == 3 ? 1 : 2);
var cropUnitY = (chromaArrayType == 0 ? 1 : (chromaArrayType == 1 ? 2 : 1)) * (frameMbsOnly ? 1 : 2);
var width = codedWidth - cropUnitX * (cropLeft + cropRight);
var height = codedHeight - cropUnitY * (cropTop + cropBottom);
if (r.IsOverrun || width <= 0 || height <= 0 || codedWidth > 65536 || codedHeight > 65536) return false;
var result = new H264Sps
{
ProfileIdc = profile,
ConstraintFlags = constraints,
LevelIdc = level,
SpsId = (int)spsId,
ChromaFormatIdc = chroma,
BitDepthLuma = depthLuma,
BitDepthChroma = depthChroma,
Width = (int)width,
Height = (int)height,
CodedWidth = (int)codedWidth,
CodedHeight = (int)codedHeight,
FrameMbsOnly = frameMbsOnly,
PicOrderCntType = pocType,
MaxNumRefFrames = maxRefFrames,
};
if (r.ReadFlag()) result = ParseVui(ref r, result);
// VUI is optional detail: a truncated VUI still yields the core fields.
sps = result;
return true;
}
private static H264Sps ParseVui(ref BitReader r, H264Sps sps)
{
int sarW = 1, sarH = 1;
if (r.ReadFlag())
{
var idc = (int)r.ReadBits(8);
if (idc == 255)
{
sarW = (int)r.ReadBits(16);
sarH = (int)r.ReadBits(16);
}
else if (idc > 0 && idc < SarTable.Length / 2)
{
sarW = SarTable[idc * 2];
sarH = SarTable[idc * 2 + 1];
}
}
if (r.ReadFlag()) r.ReadFlag(); // overscan_info_present_flag, overscan_appropriate_flag
bool? fullRange = null;
int? primaries = null, transfer = null, matrix = null;
if (r.ReadFlag())
{
r.ReadBits(3); // video_format
fullRange = r.ReadFlag();
if (r.ReadFlag())
{
primaries = (int)r.ReadBits(8);
transfer = (int)r.ReadBits(8);
matrix = (int)r.ReadBits(8);
}
}
if (r.ReadFlag())
{
r.ReadUe(); // chroma_sample_loc_type_top_field
r.ReadUe(); // chroma_sample_loc_type_bottom_field
}
uint units = 0, scale = 0;
var fixedRate = false;
if (r.ReadFlag())
{
units = r.ReadBits(32);
scale = r.ReadBits(32);
fixedRate = r.ReadFlag();
}
if (r.IsOverrun) return sps with { HasVui = true };
return sps with
{
HasVui = true,
SarWidth = sarW == 0 ? 1 : sarW,
SarHeight = sarH == 0 ? 1 : sarH,
FullRange = fullRange,
ColourPrimaries = primaries,
TransferCharacteristics = transfer,
MatrixCoefficients = matrix,
NumUnitsInTick = units,
TimeScale = scale,
FixedFrameRate = fixedRate,
};
}
private static void SkipScalingList(ref BitReader r, int size)
{
int last = 8, next = 8;
for (var j = 0; j < size && !r.IsOverrun; j++)
{
if (next != 0) next = (last + r.ReadSe() + 256) % 256;
last = next == 0 ? last : next;
}
}
// Table E-1 sample aspect ratios for aspect_ratio_idc 1..16 (index 0 unused).
private static ReadOnlySpan<byte> SarTable =>
[
0, 0, 1, 1, 12, 11, 10, 11, 16, 11, 40, 33, 24, 11, 20, 11, 32, 11, 80, 33, 18, 11, 15, 11, 64, 33, 160, 99, 4, 3, 3, 2, 2, 1,
];
}
@@ -0,0 +1,120 @@
namespace Titano.Core.Video.Bitstream;
/// <summary>general_profile_tier_level fields of an HEVC SPS (ITU-T H.265 7.3.3), as stored in hvcC.</summary>
public sealed record HevcProfileTierLevel(
int ProfileSpace,
bool HighTier,
int ProfileIdc,
uint ProfileCompatibilityFlags,
ulong ConstraintIndicatorFlags,
int LevelIdc);
/// <summary>Fields of an HEVC sequence parameter set needed for containers and diagnostics.</summary>
public sealed record HevcSps
{
public required int VpsId { get; init; }
public required int MaxSubLayers { get; init; }
public required bool TemporalIdNesting { get; init; }
public required HevcProfileTierLevel ProfileTierLevel { get; init; }
public required int SpsId { get; init; }
public required int ChromaFormatIdc { get; init; }
public required int BitDepthLuma { get; init; }
public required int BitDepthChroma { get; init; }
public required int CodedWidth { get; init; }
public required int CodedHeight { get; init; }
/// <summary>Width after the conformance window.</summary>
public required int Width { get; init; }
/// <summary>Height after the conformance window.</summary>
public required int Height { get; init; }
}
/// <summary>Parses HEVC SPS NAL units up to the bit depths. Never throws on malformed input.</summary>
public static class HevcSpsParser
{
/// <summary>Parses an SPS NAL unit (2-byte header included, emulation prevention present).</summary>
public static bool TryParse(ReadOnlySpan<byte> nal, out HevcSps sps)
{
sps = null!;
if (nal.Length < 6 || AnnexBParser.HevcType(nal[0]) != HevcNalUnitType.Sps) return false;
var rbsp = AnnexBParser.RemoveEmulationPrevention(nal[2..]);
var r = new BitReader(rbsp);
var vpsId = (int)r.ReadBits(4);
var maxSubLayersMinus1 = (int)r.ReadBits(3);
if (maxSubLayersMinus1 > 6) return false;
var nesting = r.ReadFlag();
var ptl = ReadProfileTierLevel(ref r, maxSubLayersMinus1);
var spsId = r.ReadUe();
if (spsId > 15) return false;
var chroma = (int)r.ReadUe();
if (chroma > 3) return false;
if (chroma == 3) r.ReadFlag(); // separate_colour_plane_flag
var codedWidth = (long)r.ReadUe();
var codedHeight = (long)r.ReadUe();
long left = 0, right = 0, top = 0, bottom = 0;
if (r.ReadFlag())
{
left = r.ReadUe();
right = r.ReadUe();
top = r.ReadUe();
bottom = r.ReadUe();
}
var depthLuma = 8 + (int)r.ReadUe();
var depthChroma = 8 + (int)r.ReadUe();
var subWidth = chroma is 1 or 2 ? 2 : 1;
var subHeight = chroma == 1 ? 2 : 1;
var width = codedWidth - subWidth * (left + right);
var height = codedHeight - subHeight * (top + bottom);
if (r.IsOverrun || depthLuma > 16 || depthChroma > 16 || width <= 0 || height <= 0 || codedWidth > 65536 || codedHeight > 65536)
return false;
sps = new HevcSps
{
VpsId = vpsId,
MaxSubLayers = maxSubLayersMinus1 + 1,
TemporalIdNesting = nesting,
ProfileTierLevel = ptl,
SpsId = (int)spsId,
ChromaFormatIdc = chroma,
BitDepthLuma = depthLuma,
BitDepthChroma = depthChroma,
CodedWidth = (int)codedWidth,
CodedHeight = (int)codedHeight,
Width = (int)width,
Height = (int)height,
};
return true;
}
/// <summary>profile_tier_level(1, maxNumSubLayersMinus1); sub-layer fields are skipped.</summary>
internal static HevcProfileTierLevel ReadProfileTierLevel(ref BitReader r, int maxSubLayersMinus1)
{
var space = (int)r.ReadBits(2);
var tier = r.ReadFlag();
var profile = (int)r.ReadBits(5);
var compatibility = r.ReadBits(32);
var constraints = r.ReadBits64(48);
var level = (int)r.ReadBits(8);
Span<bool> profilePresent = stackalloc bool[8];
Span<bool> levelPresent = stackalloc bool[8];
for (var i = 0; i < maxSubLayersMinus1; i++)
{
profilePresent[i] = r.ReadFlag();
levelPresent[i] = r.ReadFlag();
}
if (maxSubLayersMinus1 > 0)
{
for (var i = maxSubLayersMinus1; i < 8; i++) r.ReadBits(2); // reserved_zero_2bits
}
for (var i = 0; i < maxSubLayersMinus1; i++)
{
if (profilePresent[i]) r.Skip(88);
if (levelPresent[i]) r.Skip(8);
}
return new HevcProfileTierLevel(space, tier, profile, compatibility, constraints, level);
}
}
@@ -0,0 +1,229 @@
using Titano.Core.Video.Bitstream;
using Titano.Testing;
namespace Titano.Core.Tests.Video;
public sealed class BitstreamTests
{
[Test]
public void ExpGolombRoundTrip()
{
uint[] unsigned = [0, 1, 2, 3, 7, 8, 254, 255, 256, 65535, 1_000_000, uint.MaxValue - 1];
int[] signed = [0, 1, -1, 2, -2, 100, -100, int.MaxValue, -int.MaxValue];
var w = new BitWriter();
foreach (var v in unsigned) w.WriteUe(v);
foreach (var v in signed) w.WriteSe(v);
w.WriteBits(0b101, 3);
var r = new BitReader(w.ToArray());
foreach (var v in unsigned) Assert.Equal(v, r.ReadUe());
foreach (var v in signed) Assert.Equal(v, r.ReadSe());
Assert.Equal(0b101u, r.ReadBits(3));
Assert.False(r.IsOverrun);
}
[Test]
public void ReadingPastTheEndSetsOverrunWithoutThrowing()
{
var r = new BitReader([0xFF]);
Assert.Equal(0xFFu, r.ReadBits(8));
Assert.Equal(0u, r.ReadBits(16));
Assert.True(r.IsOverrun);
var zeros = new BitReader(new byte[8]);
Assert.Equal(0u, zeros.ReadUe());
Assert.True(zeros.IsOverrun);
}
[Test]
public void Leb128RoundTrip()
{
Span<byte> buffer = stackalloc byte[8];
foreach (var v in new ulong[] { 0, 1, 127, 128, 16383, 16384, uint.MaxValue })
{
var n = Av1ObuParser.WriteLeb128(buffer, v);
Assert.Equal(Av1ObuParser.Leb128Size(v), n);
Assert.True(Av1ObuParser.TryReadLeb128(buffer[..n], out var back, out var length));
Assert.Equal(v, back);
Assert.Equal(n, length);
}
}
[Test]
public void SplitsThreeAndFourByteStartCodes()
{
byte[] stream = [0xAA, 0, 0, 0, 1, 0x67, 1, 2, 0, 0, 1, 0x68, 3, 0, 0, 0, 0, 1, 0x65, 4, 5, 6, 0, 0];
var units = AnnexBParser.Split(stream);
Assert.Count(3, units);
Assert.BytesEqual([0x67, 1, 2], units[0].Slice(stream));
Assert.BytesEqual([0x68, 3], units[1].Slice(stream));
Assert.BytesEqual([0x65, 4, 5, 6], units[2].Slice(stream));
Assert.Equal(H264NalUnitType.Sps, AnnexBParser.H264Type(stream[units[0].Offset]));
Assert.Equal(H264NalUnitType.IdrSlice, AnnexBParser.H264Type(stream[units[2].Offset]));
}
[Test]
public void ConvertsAnnexBToLengthPrefixedAndDetectsBoth()
{
var annexB = AnnexBParser.ToAnnexB([SyntheticStreams.H264Sps(), SyntheticStreams.H264Pps(), SyntheticStreams.H264Slice(true, 300, 1)]);
var prefixed = AnnexBParser.ToLengthPrefixed(annexB);
var fromAnnexB = AnnexBParser.SplitAccessUnit(annexB, out var wasAnnexB);
var fromPrefixed = AnnexBParser.SplitAccessUnit(prefixed, out var wasAnnexB2);
Assert.True(wasAnnexB);
Assert.False(wasAnnexB2);
Assert.Equal(3, fromAnnexB.Count);
Assert.Equal(3, fromPrefixed.Count);
for (var i = 0; i < 3; i++)
Assert.BytesEqual(fromAnnexB[i].Slice(annexB), fromPrefixed[i].Slice(prefixed));
}
[Test]
public void LengthPrefixedSplitRejectsInconsistentLengths()
{
Assert.False(AnnexBParser.TrySplitLengthPrefixed([0, 0, 0, 9, 1, 2], 4, out _));
Assert.False(AnnexBParser.TrySplitLengthPrefixed([0, 0, 0, 0], 4, out _));
Assert.True(AnnexBParser.TrySplitLengthPrefixed([0, 2, 0x41, 9, 0, 1, 0x41], 2, out var units));
Assert.Count(2, units);
}
[Test]
public void EmulationPreventionRoundTrip()
{
var rng = new Random(7);
for (var trial = 0; trial < 200; trial++)
{
var data = new byte[rng.Next(1, 200)];
for (var i = 0; i < data.Length; i++) data[i] = rng.Next(4) == 0 ? (byte)rng.Next(4) : (byte)0;
var escaped = AnnexBParser.AddEmulationPrevention(data);
for (var i = 2; i < escaped.Length; i++)
Assert.False(escaped[i - 2] == 0 && escaped[i - 1] == 0 && escaped[i] <= 2, "start code prefix survived escaping");
var back = AnnexBParser.RemoveEmulationPrevention(escaped);
// After a lone trailing 0x00 the appended 0x03 is not preceded by two zeros, so it stays.
if (back.Length == data.Length + 1) back = back[..^1];
Assert.BytesEqual(data, back);
}
Assert.BytesEqual([0, 0, 3, 1, 0, 0, 3, 0], AnnexBParser.AddEmulationPrevention([0, 0, 1, 0, 0, 0]).AsSpan(0, 8));
}
[Test]
public void ParsesH264HighProfileSps()
{
var nal = SyntheticStreams.H264Sps(1920, 1080, 100, 41);
Assert.True(H264SpsParser.TryParse(nal, out var sps));
Assert.Equal(100, sps.ProfileIdc);
Assert.Equal(41, sps.LevelIdc);
Assert.Equal(1, sps.ChromaFormatIdc);
Assert.Equal(8, sps.BitDepthLuma);
Assert.Equal(1920, sps.Width);
Assert.Equal(1080, sps.Height);
Assert.Equal(1088, sps.CodedHeight);
Assert.Equal(1, sps.ColourPrimaries);
Assert.Equal(false, sps.FullRange);
Assert.Approximately(29.97, sps.FrameRate!.Value, 0.01);
}
[Theory]
[Case(1280, 720, 77, 31)]
[Case(3840, 2160, 100, 51)]
[Case(642, 482, 66, 30)]
public void ParsesH264SizesWithCropping(int width, int height, int profile, int level)
{
Assert.True(H264SpsParser.TryParse(SyntheticStreams.H264Sps(width, height, profile, level), out var sps));
Assert.Equal(width, sps.Width);
Assert.Equal(height, sps.Height);
Assert.Equal(profile, sps.ProfileIdc);
}
[Test]
public void ParsesHevcMain10Sps()
{
Assert.True(HevcSpsParser.TryParse(SyntheticStreams.HevcSps(1920, 1080, 10, 153), out var sps));
Assert.Equal(1920, sps.Width);
Assert.Equal(1080, sps.Height);
Assert.Equal(1080, sps.CodedHeight);
Assert.Equal(10, sps.BitDepthLuma);
Assert.Equal(10, sps.BitDepthChroma);
Assert.Equal(1, sps.ChromaFormatIdc);
Assert.Equal(2, sps.ProfileTierLevel.ProfileIdc);
Assert.Equal(153, sps.ProfileTierLevel.LevelIdc);
Assert.Equal(0x2000_0000u, sps.ProfileTierLevel.ProfileCompatibilityFlags);
Assert.Equal(0x9000_0000_0000UL, sps.ProfileTierLevel.ConstraintIndicatorFlags);
Assert.False(sps.ProfileTierLevel.HighTier);
Assert.True(sps.TemporalIdNesting);
}
[Test]
public void AppliesHevcConformanceWindow()
{
Assert.True(HevcSpsParser.TryParse(SyntheticStreams.HevcSps(1916, 1076, 8, 120), out var sps));
Assert.Equal(1920, sps.CodedWidth);
Assert.Equal(1080, sps.CodedHeight);
Assert.Equal(1916, sps.Width);
Assert.Equal(1076, sps.Height);
Assert.Equal(1, sps.ProfileTierLevel.ProfileIdc);
}
[Test]
public void ParsesAv1SequenceHeader()
{
var obuBytes = SyntheticStreams.Av1SequenceHeaderObu(3840, 2160, 12, tenBit: true);
Assert.True(Av1ObuParser.TryReadObu(obuBytes, 0, out var obu));
Assert.Equal(Av1ObuType.SequenceHeader, obu.Type);
Assert.True(obu.HasSizeField);
Assert.Equal(obuBytes.Length, obu.TotalLength);
Assert.True(Av1ObuParser.TryParseSequenceHeader(obu.Payload(obuBytes), out var header));
Assert.Equal(3840, header.MaxFrameWidth);
Assert.Equal(2160, header.MaxFrameHeight);
Assert.Equal(12, header.SeqLevelIdx);
Assert.Equal(10, header.BitDepth);
Assert.True(header.ChromaSubsamplingX && header.ChromaSubsamplingY);
Assert.Equal(1, header.ColorPrimaries);
Assert.False(header.FullRange);
}
[Test]
public void ReadsObuWithoutSizeFieldAndSplitsTemporalUnits()
{
byte[] lastWithoutSize = [(byte)Av1ObuType.Frame << 3, 9, 8, 7];
Assert.True(Av1ObuParser.TryReadObu(lastWithoutSize, 0, out var obu));
Assert.False(obu.HasSizeField);
Assert.Equal(3, obu.PayloadLength);
var stream = SyntheticStreams.Concat(
SyntheticStreams.Av1TemporalDelimiter(), SyntheticStreams.Av1SequenceHeaderObu(), SyntheticStreams.Av1Frame(50, 1),
SyntheticStreams.Av1TemporalDelimiter(), SyntheticStreams.Av1Frame(40, 2),
SyntheticStreams.Av1TemporalDelimiter(), SyntheticStreams.Av1Frame(30, 3));
var units = Av1ObuParser.SplitTemporalUnits(stream);
Assert.Count(3, units);
Assert.Equal(0, units[0].Offset);
Assert.Equal(stream.Length, units[2].Offset + units[2].Length);
Assert.Equal(units[0].Length, units[1].Offset);
}
[Test]
public void ParsersSurviveTruncationAndGarbage()
{
byte[][] inputs = [SyntheticStreams.H264Sps(), SyntheticStreams.HevcSps(), SyntheticStreams.Av1SequenceHeaderObu()];
var rng = new Random(3);
foreach (var input in inputs)
{
for (var length = 0; length < input.Length; length++)
{
var slice = input.AsSpan(0, length);
H264SpsParser.TryParse(slice, out _);
HevcSpsParser.TryParse(slice, out _);
Av1ObuParser.Split(slice);
if (length > 2) Av1ObuParser.TryParseSequenceHeader(slice[2..], out _);
}
for (var trial = 0; trial < 300; trial++)
{
var corrupt = (byte[])input.Clone();
corrupt[rng.Next(corrupt.Length)] ^= (byte)(1 << rng.Next(8));
H264SpsParser.TryParse(corrupt, out _);
HevcSpsParser.TryParse(corrupt, out _);
Av1ObuParser.SplitTemporalUnits(corrupt);
Av1ObuParser.TryParseSequenceHeader(corrupt, out _);
AnnexBParser.SplitAccessUnit(corrupt, out _);
}
}
Assert.False(H264SpsParser.TryParse(SyntheticStreams.H264Sps().AsSpan(0, 5), out _));
}
}
@@ -0,0 +1,323 @@
using Titano.Core.Video.Bitstream;
namespace Titano.Core.Tests.Video;
/// <summary>Builds syntactically valid H.264/HEVC parameter sets, AV1 sequence headers and slice stubs.</summary>
internal static class SyntheticStreams
{
/// <summary>H.264 SPS NAL (header included) for 4:2:0 8-bit with cropping to the requested size and VUI timing.</summary>
public static byte[] H264Sps(int width = 1920, int height = 1080, int profileIdc = 100, int levelIdc = 41, uint timeScale = 60000, uint unitsInTick = 1001)
{
var w = new BitWriter();
w.WriteBits((ulong)profileIdc, 8);
w.WriteBits(0, 8); // constraint flags
w.WriteBits((ulong)levelIdc, 8);
w.WriteUe(0); // seq_parameter_set_id
if (profileIdc == 100)
{
w.WriteUe(1); // chroma_format_idc
w.WriteUe(0); // bit_depth_luma_minus8
w.WriteUe(0); // bit_depth_chroma_minus8
w.WriteBit(false); // qpprime_y_zero_transform_bypass_flag
w.WriteBit(false); // seq_scaling_matrix_present_flag
}
w.WriteUe(0); // log2_max_frame_num_minus4
w.WriteUe(0); // pic_order_cnt_type
w.WriteUe(2); // log2_max_pic_order_cnt_lsb_minus4
w.WriteUe(4); // max_num_ref_frames
w.WriteBit(false); // gaps_in_frame_num_value_allowed_flag
var mbW = (width + 15) / 16;
var mbH = (height + 15) / 16;
w.WriteUe((uint)mbW - 1);
w.WriteUe((uint)mbH - 1);
w.WriteBit(true); // frame_mbs_only_flag
w.WriteBit(true); // direct_8x8_inference_flag
var cropRight = (mbW * 16 - width) / 2;
var cropBottom = (mbH * 16 - height) / 2;
var crop = cropRight > 0 || cropBottom > 0;
w.WriteBit(crop);
if (crop)
{
w.WriteUe(0);
w.WriteUe((uint)cropRight);
w.WriteUe(0);
w.WriteUe((uint)cropBottom);
}
w.WriteBit(true); // vui_parameters_present_flag
w.WriteBit(true); // aspect_ratio_info_present_flag
w.WriteBits(1, 8); // aspect_ratio_idc 1:1
w.WriteBit(false); // overscan_info_present_flag
w.WriteBit(true); // video_signal_type_present_flag
w.WriteBits(5, 3); // video_format
w.WriteBit(false); // video_full_range_flag
w.WriteBit(true); // colour_description_present_flag
w.WriteBits(1, 8);
w.WriteBits(1, 8);
w.WriteBits(1, 8);
w.WriteBit(false); // chroma_loc_info_present_flag
w.WriteBit(true); // timing_info_present_flag
w.WriteBits(unitsInTick, 32);
w.WriteBits(timeScale, 32);
w.WriteBit(true); // fixed_frame_rate_flag
w.WriteBit(false); // nal_hrd_parameters_present_flag
w.WriteBit(false); // vcl_hrd_parameters_present_flag
w.WriteBit(false); // pic_struct_present_flag
w.WriteBit(false); // bitstream_restriction_flag
w.WriteTrailingBits();
return Nal([0x67], w.ToArray());
}
public static byte[] H264Pps()
{
var w = new BitWriter();
w.WriteUe(0); // pic_parameter_set_id
w.WriteUe(0); // seq_parameter_set_id
w.WriteBit(true); // entropy_coding_mode_flag
w.WriteBit(false); // bottom_field_pic_order_in_frame_present_flag
w.WriteUe(0); // num_slice_groups_minus1
w.WriteUe(0); // num_ref_idx_l0_default_active_minus1
w.WriteUe(0); // num_ref_idx_l1_default_active_minus1
w.WriteBit(false); // weighted_pred_flag
w.WriteBits(0, 2); // weighted_bipred_idc
w.WriteSe(0); // pic_init_qp_minus26
w.WriteSe(0); // pic_init_qs_minus26
w.WriteSe(0); // chroma_qp_index_offset
w.WriteBit(true); // deblocking_filter_control_present_flag
w.WriteBit(false); // constrained_intra_pred_flag
w.WriteBit(false); // redundant_pic_cnt_present_flag
w.WriteBit(true); // transform_8x8_mode_flag
w.WriteBit(false); // pic_scaling_matrix_present_flag
w.WriteSe(0); // second_chroma_qp_index_offset
w.WriteTrailingBits();
return Nal([0x68], w.ToArray());
}
/// <summary>A slice NAL with a plausible header and pseudo-random payload.</summary>
public static byte[] H264Slice(bool idr, int payloadBytes, int seed)
{
var w = new BitWriter();
w.WriteUe(0); // first_mb_in_slice
w.WriteUe(idr ? 7u : 5u); // slice_type I / P
w.WriteUe(0); // pic_parameter_set_id
w.WriteBytes(Random(payloadBytes, seed));
w.WriteTrailingBits();
return Nal([idr ? (byte)0x65 : (byte)0x41], w.ToArray());
}
public static byte[] H264AccessUnitDelimiter() => [0x09, 0xF0];
public static byte[] HevcVps()
{
var w = new BitWriter();
w.WriteBits(0, 4); // vps_video_parameter_set_id
w.WriteBit(true); // vps_base_layer_internal_flag
w.WriteBit(true); // vps_base_layer_available_flag
w.WriteBits(0, 6); // vps_max_layers_minus1
w.WriteBits(0, 3); // vps_max_sub_layers_minus1
w.WriteBit(true); // vps_temporal_id_nesting_flag
w.WriteBits(0xFFFF, 16);
WriteHevcProfileTierLevel(w, 2, 153);
w.WriteBit(true); // vps_sub_layer_ordering_info_present_flag
w.WriteUe(4);
w.WriteUe(0);
w.WriteUe(0);
w.WriteBits(0, 6); // vps_max_layer_id
w.WriteUe(0); // vps_num_layer_sets_minus1
w.WriteBit(false); // vps_timing_info_present_flag
w.WriteBit(false); // vps_extension_flag
w.WriteTrailingBits();
return Nal([0x40, 0x01], w.ToArray());
}
/// <summary>HEVC SPS for 4:2:0 with the given bit depth, coded in 8×8 units with a conformance window.</summary>
public static byte[] HevcSps(int width = 1920, int height = 1080, int bitDepth = 10, int levelIdc = 153)
{
var w = new BitWriter();
w.WriteBits(0, 4); // sps_video_parameter_set_id
w.WriteBits(0, 3); // sps_max_sub_layers_minus1
w.WriteBit(true); // sps_temporal_id_nesting_flag
WriteHevcProfileTierLevel(w, bitDepth == 10 ? 2 : 1, levelIdc);
w.WriteUe(0); // sps_seq_parameter_set_id
w.WriteUe(1); // chroma_format_idc
var codedW = (width + 7) / 8 * 8;
var codedH = (height + 7) / 8 * 8;
w.WriteUe((uint)codedW);
w.WriteUe((uint)codedH);
var window = codedW != width || codedH != height;
w.WriteBit(window);
if (window)
{
w.WriteUe(0);
w.WriteUe((uint)(codedW - width) / 2);
w.WriteUe(0);
w.WriteUe((uint)(codedH - height) / 2);
}
w.WriteUe((uint)bitDepth - 8);
w.WriteUe((uint)bitDepth - 8);
w.WriteUe(4); // log2_max_pic_order_cnt_lsb_minus4
w.WriteBit(true); // sps_sub_layer_ordering_info_present_flag
w.WriteUe(4);
w.WriteUe(0);
w.WriteUe(0);
w.WriteUe(0); // log2_min_luma_coding_block_size_minus3
w.WriteUe(3); // log2_diff_max_min_luma_coding_block_size
w.WriteUe(0); // log2_min_luma_transform_block_size_minus2
w.WriteUe(3); // log2_diff_max_min_luma_transform_block_size
w.WriteUe(1); // max_transform_hierarchy_depth_inter
w.WriteUe(1); // max_transform_hierarchy_depth_intra
w.WriteBit(false); // scaling_list_enabled_flag
w.WriteBit(true); // amp_enabled_flag
w.WriteBit(true); // sample_adaptive_offset_enabled_flag
w.WriteBit(false); // pcm_enabled_flag
w.WriteUe(0); // num_short_term_ref_pic_sets
w.WriteBit(false); // long_term_ref_pics_present_flag
w.WriteBit(true); // sps_temporal_mvp_enabled_flag
w.WriteBit(true); // strong_intra_smoothing_enabled_flag
w.WriteBit(false); // vui_parameters_present_flag
w.WriteBit(false); // sps_extension_present_flag
w.WriteTrailingBits();
return Nal([0x42, 0x01], w.ToArray());
}
public static byte[] HevcPps()
{
var w = new BitWriter();
w.WriteUe(0); // pps_pic_parameter_set_id
w.WriteUe(0); // pps_seq_parameter_set_id
w.WriteBit(false); // dependent_slice_segments_enabled_flag
w.WriteBit(false); // output_flag_present_flag
w.WriteBits(0, 3); // num_extra_slice_header_bits
w.WriteBit(false); // sign_data_hiding_enabled_flag
w.WriteBit(true); // cabac_init_present_flag
w.WriteUe(0);
w.WriteUe(0);
w.WriteSe(0); // init_qp_minus26
w.WriteBit(false); // constrained_intra_pred_flag
w.WriteBit(false); // transform_skip_enabled_flag
w.WriteBit(false); // cu_qp_delta_enabled_flag
w.WriteSe(0);
w.WriteSe(0);
w.WriteBit(false); // pps_slice_chroma_qp_offsets_present_flag
w.WriteBit(false); // weighted_pred_flag
w.WriteBit(false); // weighted_bipred_flag
w.WriteBit(false); // transquant_bypass_enabled_flag
w.WriteBit(false); // tiles_enabled_flag
w.WriteBit(false); // entropy_coding_sync_enabled_flag
w.WriteBit(true); // pps_loop_filter_across_slices_enabled_flag
w.WriteBit(false); // deblocking_filter_control_present_flag
w.WriteBit(false); // pps_scaling_list_data_present_flag
w.WriteBit(false); // lists_modification_present_flag
w.WriteUe(0); // log2_parallel_merge_level_minus2
w.WriteBit(false); // slice_segment_header_extension_present_flag
w.WriteBit(false); // pps_extension_present_flag
w.WriteTrailingBits();
return Nal([0x44, 0x01], w.ToArray());
}
public static byte[] HevcSlice(bool idr, int payloadBytes, int seed)
{
var type = idr ? HevcNalUnitType.IdrWRadl : HevcNalUnitType.TrailR;
var w = new BitWriter();
w.WriteBit(true); // first_slice_segment_in_pic_flag
w.WriteBytes(Random(payloadBytes, seed));
w.WriteTrailingBits();
return Nal([(byte)((byte)type << 1), 0x01], w.ToArray());
}
/// <summary>AV1 sequence header OBU (with size field) for profile 0 4:2:0.</summary>
public static byte[] Av1SequenceHeaderObu(int width = 1920, int height = 1080, int levelIdx = 8, bool tenBit = false)
{
var w = new BitWriter();
w.WriteBits(0, 3); // seq_profile
w.WriteBit(false); // still_picture
w.WriteBit(false); // reduced_still_picture_header
w.WriteBit(false); // timing_info_present_flag
w.WriteBit(false); // initial_display_delay_present_flag
w.WriteBits(0, 5); // operating_points_cnt_minus_1
w.WriteBits(0, 12); // operating_point_idc[0]
w.WriteBits((ulong)levelIdx, 5);
if (levelIdx > 7) w.WriteBit(false); // seq_tier[0]
const int bits = 16;
w.WriteBits(bits - 1, 4);
w.WriteBits(bits - 1, 4);
w.WriteBits((ulong)width - 1, bits);
w.WriteBits((ulong)height - 1, bits);
w.WriteBit(false); // frame_id_numbers_present_flag
w.WriteBit(false); // use_128x128_superblock
w.WriteBit(true); // enable_filter_intra
w.WriteBit(true); // enable_intra_edge_filter
w.WriteBits(0, 4); // interintra, masked, warped, dual filter
w.WriteBit(true); // enable_order_hint
w.WriteBits(0, 2); // enable_jnt_comp, enable_ref_frame_mvs
w.WriteBit(true); // seq_choose_screen_content_tools
w.WriteBit(true); // seq_choose_integer_mv
w.WriteBits(6, 3); // order_hint_bits_minus_1
w.WriteBits(0, 3); // superres, cdef, restoration
w.WriteBit(tenBit); // high_bitdepth
w.WriteBit(false); // mono_chrome
w.WriteBit(true); // color_description_present_flag
w.WriteBits(1, 8);
w.WriteBits(1, 8);
w.WriteBits(1, 8);
w.WriteBit(false); // color_range
w.WriteBits(0, 2); // chroma_sample_position
w.WriteBit(false); // separate_uv_delta_q
w.WriteBit(false); // film_grain_params_present
w.WriteTrailingBits();
return Obu(Av1ObuType.SequenceHeader, w.ToArray());
}
public static byte[] Av1TemporalDelimiter() => Obu(Av1ObuType.TemporalDelimiter, []);
public static byte[] Av1Frame(int payloadBytes, int seed) => Obu(Av1ObuType.Frame, Random(payloadBytes, seed));
/// <summary>An OBU with obu_has_size_field set.</summary>
public static byte[] Obu(Av1ObuType type, ReadOnlySpan<byte> payload)
{
var w = new BitWriter();
w.WriteBits((ulong)((byte)type << 3 | 0x02), 8);
w.WriteLeb128((ulong)payload.Length);
w.WriteBytes(payload);
return w.ToArray();
}
public static byte[] Concat(params byte[][] parts)
{
var total = 0;
foreach (var p in parts) total += p.Length;
var result = new byte[total];
var pos = 0;
foreach (var p in parts)
{
p.CopyTo(result, pos);
pos += p.Length;
}
return result;
}
public static byte[] Random(int length, int seed)
{
var bytes = new byte[length];
new Random(seed).NextBytes(bytes);
return bytes;
}
private static void WriteHevcProfileTierLevel(BitWriter w, int profileIdc, int levelIdc)
{
w.WriteBits(0, 2); // general_profile_space
w.WriteBit(false); // general_tier_flag
w.WriteBits((ulong)profileIdc, 5);
w.WriteBits(1UL << (31 - profileIdc), 32); // general_profile_compatibility_flag[profileIdc]
w.WriteBits(0x9000_0000_0000UL, 48); // progressive_source + frame_only_constraint
w.WriteBits((ulong)levelIdc, 8);
}
private static byte[] Nal(ReadOnlySpan<byte> header, byte[] rbsp)
{
var escaped = AnnexBParser.AddEmulationPrevention(rbsp);
var nal = new byte[header.Length + escaped.Length];
header.CopyTo(nal);
escaped.CopyTo(nal, header.Length);
return nal;
}
}