@UnstableApi
public final class NalUnitUtil

Utility methods for handling H.264/AVC and H.265/HEVC NAL units.

Summary

Nested types
public final class NalUnitUtil.H265LayerInfo

Holds data that maps NAL unit header layer ID to the internal layer info specified in VPS.
public final class NalUnitUtil.H265NalHeader

Holds data parsed from a H.265 NAL unit header.

Holds data parsed from a H.265 profile_tier_level() of either VPS or SPS.

Holds a list of H.265 profile_tier_level()s and a corresponding list of indices.
public final class NalUnitUtil.H265RepFormat

Holds data parsed from a H.265 rep_format() of VPS extension - vps_extension().

Holds a list of H.265 rep_format()s and a corresponding list of indices.

Holds data parsed from a H.265 3D reference displays information SEI message.
public final class NalUnitUtil.H265SpsData

Holds data parsed from a H.265 sequence parameter set NAL unit.

Holds data parsed from a H.265 video_signal_info() of vps_vui() of vps_extension().

Holds a list of H.265 video_signal_info()s and a corresponding list of indices.
public final class NalUnitUtil.H265VpsData

Holds data parsed from a H.265 video parameter set NAL unit.
public final class NalUnitUtil.PpsData

Holds data parsed from a picture parameter set NAL unit.
public final class NalUnitUtil.SpsData

Holds data parsed from a H.264 sequence parameter set NAL unit.

Constants
static final float[]

Aspect ratios indexed by aspect_ratio_idc, in H.264 and H.265 SPSs.
static final int

Value for aspect_ratio_idc indicating an extended aspect ratio, in H.264 and H.265 SPSs.
static final int

H.264 access unit delimiter.
static final int

H.264 coded slice of an IDR picture.
static final int

H.264 coded slice of a non-IDR picture.
static final int

H.264 coded slice data partition A.
static final int

H.264 picture parameter set.
static final int

H.264 prefix NAL unit.
static final int

H.264 supplemental enhancement information.
static final int

H.264 sequence parameter set.
static final int

H.265 access unit delimiter (AUD_NUT).
static final int

H.265 coded slice segment of a broken link access picture (BLA_W_LP).
static final int

H.265 coded slice segment of a clean random access picture (CRA_NUT).
static final int

H.265 picture parameter set (PPS_NUT).
static final int

H.265 prefixed supplemental enhancement information (PREFIX_SEI_NUT).
static final int

H.265 coded slice segment of a random access skipped leading picture (RASL_R).
static final int

H.265 sequence parameter set (SPS_NUT).
static final int

H.265 suffixed supplemental enhancement information (SUFFIX_SEI_NUT).
static final int

H.265 video parameter set (VPS_NUT).
static final byte[]

Four initial bytes that must prefix NAL units for decoding.
static final int

This field is deprecated.

Use H264_NAL_UNIT_TYPE_AUD
static final int

This field is deprecated.

Use H264_NAL_UNIT_TYPE_IDR
static final int

This field is deprecated.

Use H264_NAL_UNIT_TYPE_NON_IDR
static final int

This field is deprecated.

Use H264_NAL_UNIT_TYPE_PARTITION_A
static final int

This field is deprecated.

Use H264_NAL_UNIT_TYPE_PPS
static final int

This field is deprecated.

Use H264_NAL_UNIT_TYPE_PREFIX
static final int

This field is deprecated.

Use H264_NAL_UNIT_TYPE_SEI
static final int

This field is deprecated.

Use H264_NAL_UNIT_TYPE_SPS

Public methods
static void
clearPrefixFlags(boolean[] prefixFlags)

Clears prefix flags, as used by findNalUnit.
static void

Discards data from the buffer up to the first SPS, where data.position() is interpreted as the length of the buffer.
static int
findNalUnit(
    byte[] data,
    int startOffset,
    int endOffset,
    boolean[] prefixFlags
)

Finds the first NAL unit in data.
static @Nullable String
getH265BaseLayerCodecsString(List<byte[]> csdBuffers)

Returns a new RFC 6381 codecs description string specifically for the single-layer HEVC case.
static int
getH265NalUnitType(byte[] data, int offset)

Returns the type of the H.265 NAL unit in data that starts at offset.
static int
getNalUnitType(byte[] data, int offset)

Returns the type of the NAL unit in data that starts at offset.
static boolean
isH264NalUnitDependedOn(byte nalUnitHeaderFirstByte)

Returns whether the H.264 NAL unit can be depended on by subsequent NAL units in decoding order.
static boolean
isNalUnitSei(Format format, byte nalUnitHeaderFirstByte)

Returns whether the NAL unit with the specified header contains supplemental enhancement information.
static boolean
isNalUnitSei(@Nullable String mimeType, byte nalUnitHeaderFirstByte)

Returns whether the NAL unit with the specified header contains supplemental enhancement information.
static @Nullable NalUnitUtil.H265Sei3dRefDisplayInfoData
parseH265Sei3dRefDisplayInfo(
    byte[] nalData,
    int nalOffset,
    int nalLimit
)

Parses a H.265 3D reference displays information SEI message syntax defined in ITU-T Recommendation H.265 (2019) subsection G.14.2.3.
static NalUnitUtil.H265SpsData
parseH265SpsNalUnit(
    byte[] nalData,
    int nalOffset,
    int nalLimit,
    @Nullable NalUnitUtil.H265VpsData vpsData
)

Parses a H.265 SPS NAL unit using the syntax defined in ITU-T Recommendation H.265 (2019) subsections 7.3.2.2.1 and F.7.3.2.2.1.
static NalUnitUtil.H265SpsData
parseH265SpsNalUnitPayload(
    byte[] nalData,
    int nalOffset,
    int nalLimit,
    NalUnitUtil.H265NalHeader nalHeader,
    @Nullable NalUnitUtil.H265VpsData vpsData
)

Parses a H.265 SPS NAL unit payload (excluding the NAL unit header) using the syntax defined in ITU-T Recommendation H.265 (2019) subsections 7.3.2.2.1 and F.7.3.2.2.1.
static NalUnitUtil.H265VpsData
parseH265VpsNalUnit(byte[] nalData, int nalOffset, int nalLimit)

Parses a H.265 VPS NAL unit using the syntax defined in ITU-T Recommendation H.265 (2019) subsections 7.3.2.1 and F.7.3.2.1.
static NalUnitUtil.PpsData
parsePpsNalUnit(byte[] nalData, int nalOffset, int nalLimit)

Parses a PPS NAL unit using the syntax defined in ITU-T Recommendation H.264 (2013) subsection 7.3.2.2.
static NalUnitUtil.PpsData
parsePpsNalUnitPayload(byte[] nalData, int nalOffset, int nalLimit)

Parses a PPS NAL unit payload (excluding the NAL unit header) using the syntax defined in ITU-T Recommendation H.264 (2013) subsection 7.3.2.2.
static NalUnitUtil.SpsData
parseSpsNalUnit(byte[] nalData, int nalOffset, int nalLimit)

Parses a SPS NAL unit using the syntax defined in ITU-T Recommendation H.264 (2013) subsection 7.3.2.1.1.
static NalUnitUtil.SpsData
parseSpsNalUnitPayload(byte[] nalData, int nalOffset, int nalLimit)

Parses a SPS NAL unit payload (excluding the NAL unit header) using the syntax defined in ITU-T Recommendation H.264 (2013) subsection 7.3.2.1.1.
static int
unescapeStream(byte[] data, int limit)

Unescapes data up to the specified limit, replacing occurrences of [0, 0, 3] with [0, 0].

Constants

ASPECT_RATIO_IDC_VALUES

public static final float[] ASPECT_RATIO_IDC_VALUES

Aspect ratios indexed by aspect_ratio_idc, in H.264 and H.265 SPSs.

EXTENDED_SAR

public static final int EXTENDED_SAR = 255

Value for aspect_ratio_idc indicating an extended aspect ratio, in H.264 and H.265 SPSs.

H264_NAL_UNIT_TYPE_AUD

public static final int H264_NAL_UNIT_TYPE_AUD = 9

H.264 access unit delimiter.

H264_NAL_UNIT_TYPE_IDR

public static final int H264_NAL_UNIT_TYPE_IDR = 5

H.264 coded slice of an IDR picture.

H264_NAL_UNIT_TYPE_NON_IDR

public static final int H264_NAL_UNIT_TYPE_NON_IDR = 1

H.264 coded slice of a non-IDR picture.

H264_NAL_UNIT_TYPE_PARTITION_A

public static final int H264_NAL_UNIT_TYPE_PARTITION_A = 2

H.264 coded slice data partition A.

H264_NAL_UNIT_TYPE_PPS

public static final int H264_NAL_UNIT_TYPE_PPS = 8

H.264 picture parameter set.

H264_NAL_UNIT_TYPE_PREFIX

public static final int H264_NAL_UNIT_TYPE_PREFIX = 14

H.264 prefix NAL unit.

H264_NAL_UNIT_TYPE_SEI

public static final int H264_NAL_UNIT_TYPE_SEI = 6

H.264 supplemental enhancement information.

H264_NAL_UNIT_TYPE_SPS

public static final int H264_NAL_UNIT_TYPE_SPS = 7

H.264 sequence parameter set.

H265_NAL_UNIT_TYPE_AUD

public static final int H265_NAL_UNIT_TYPE_AUD = 35

H.265 access unit delimiter (AUD_NUT).

H265_NAL_UNIT_TYPE_BLA_W_LP

public static final int H265_NAL_UNIT_TYPE_BLA_W_LP = 16

H.265 coded slice segment of a broken link access picture (BLA_W_LP).

H265_NAL_UNIT_TYPE_CRA

public static final int H265_NAL_UNIT_TYPE_CRA = 21

H.265 coded slice segment of a clean random access picture (CRA_NUT).

H265_NAL_UNIT_TYPE_PPS

public static final int H265_NAL_UNIT_TYPE_PPS = 34

H.265 picture parameter set (PPS_NUT).

H265_NAL_UNIT_TYPE_PREFIX_SEI

public static final int H265_NAL_UNIT_TYPE_PREFIX_SEI = 39

H.265 prefixed supplemental enhancement information (PREFIX_SEI_NUT).

H265_NAL_UNIT_TYPE_RASL_R

public static final int H265_NAL_UNIT_TYPE_RASL_R = 9

H.265 coded slice segment of a random access skipped leading picture (RASL_R).

H265_NAL_UNIT_TYPE_SPS

public static final int H265_NAL_UNIT_TYPE_SPS = 33

H.265 sequence parameter set (SPS_NUT).

H265_NAL_UNIT_TYPE_SUFFIX_SEI

public static final int H265_NAL_UNIT_TYPE_SUFFIX_SEI = 40

H.265 suffixed supplemental enhancement information (SUFFIX_SEI_NUT).

H265_NAL_UNIT_TYPE_VPS

public static final int H265_NAL_UNIT_TYPE_VPS = 32

H.265 video parameter set (VPS_NUT).

NAL_START_CODE

public static final byte[] NAL_START_CODE

Four initial bytes that must prefix NAL units for decoding.

NAL_UNIT_TYPE_AUD

public static final int NAL_UNIT_TYPE_AUD = 9

NAL_UNIT_TYPE_IDR

public static final int NAL_UNIT_TYPE_IDR = 5

NAL_UNIT_TYPE_NON_IDR

public static final int NAL_UNIT_TYPE_NON_IDR = 1

NAL_UNIT_TYPE_PARTITION_A

public static final int NAL_UNIT_TYPE_PARTITION_A = 2

NAL_UNIT_TYPE_PPS

public static final int NAL_UNIT_TYPE_PPS = 8

NAL_UNIT_TYPE_PREFIX

public static final int NAL_UNIT_TYPE_PREFIX = 14

NAL_UNIT_TYPE_SEI

public static final int NAL_UNIT_TYPE_SEI = 6

NAL_UNIT_TYPE_SPS

public static final int NAL_UNIT_TYPE_SPS = 7

Public methods

clearPrefixFlags

public static void clearPrefixFlags(boolean[] prefixFlags)

Clears prefix flags, as used by findNalUnit.

Parameters
boolean[] prefixFlags

The flags to clear.

discardToSps

public static void discardToSps(ByteBuffer data)

Discards data from the buffer up to the first SPS, where data.position() is interpreted as the length of the buffer.

When the method returns, data.position() will contain the new length of the buffer. If the buffer is not empty it is guaranteed to start with an SPS.

Parameters
ByteBuffer data

Buffer containing start code delimited NAL units.

findNalUnit

public static int findNalUnit(
    byte[] data,
    int startOffset,
    int endOffset,
    boolean[] prefixFlags
)

Finds the first NAL unit in data.

If prefixFlags is null then the first three bytes of a NAL unit must be entirely contained within the part of the array being searched in order for it to be found.

When prefixFlags is non-null, this method supports finding NAL units whose first four bytes span data arrays passed to successive calls. To use this feature, pass the same prefixFlags parameter to successive calls. State maintained in this parameter enables the detection of such NAL units. Note that when using this feature, the return value may be 3, 2 or 1 less than startOffset, to indicate a NAL unit starting 3, 2 or 1 bytes before the first byte in the current array.

Parameters
byte[] data

The data to search.
int startOffset

The offset (inclusive) in the data to start the search.
int endOffset

The offset (exclusive) in the data to end the search.
boolean[] prefixFlags

A boolean array whose first three elements are used to store the state required to detect NAL units where the NAL unit prefix spans array boundaries. The array must be at least 3 elements long.
Returns
int

The offset of the NAL unit, or endOffset if a NAL unit was not found.

getH265BaseLayerCodecsString

public static @Nullable String getH265BaseLayerCodecsString(List<byte[]> csdBuffers)

Returns a new RFC 6381 codecs description string specifically for the single-layer HEVC case. When falling back to single-layer HEVC from L-HEVC, both profile and level should be adjusted for the base layer case and the codecs description string should represent that. For the single-layer HEVC case, the string is derived from the SPS of the base layer.

Parameters
List<byte[]> csdBuffers

The CSD buffers that include the SPS of the base layer.
Returns
@Nullable String

A RFC 6381 codecs string derived from the SPS of the base layer if such information is available, or null otherwise.

getH265NalUnitType

public static int getH265NalUnitType(byte[] data, int offset)

Returns the type of the H.265 NAL unit in data that starts at offset.

Parameters
byte[] data

The data to search.
int offset

The start offset of a NAL unit. Must lie between -3 (inclusive) and data.length - 3 (exclusive).
Returns
int

The type of the unit.

getNalUnitType

public static int getNalUnitType(byte[] data, int offset)

Returns the type of the NAL unit in data that starts at offset.

Parameters
byte[] data

The data to search.
int offset

The start offset of a NAL unit. Must lie between -3 (inclusive) and data.length - 3 (exclusive).
Returns
int

The type of the unit.

isH264NalUnitDependedOn

public static boolean isH264NalUnitDependedOn(byte nalUnitHeaderFirstByte)

Returns whether the H.264 NAL unit can be depended on by subsequent NAL units in decoding order.

Parameters
byte nalUnitHeaderFirstByte

The first byte of nal_unit().

isNalUnitSei

public static boolean isNalUnitSei(Format format, byte nalUnitHeaderFirstByte)

Returns whether the NAL unit with the specified header contains supplemental enhancement information.

Parameters
Format format

The sample Format.
byte nalUnitHeaderFirstByte

The first byte of nal_unit().
Returns
boolean

Whether the NAL unit with the specified header is an SEI NAL unit. False is returned if the MimeType is null.

isNalUnitSei

public static boolean isNalUnitSei(@Nullable String mimeType, byte nalUnitHeaderFirstByte)

Returns whether the NAL unit with the specified header contains supplemental enhancement information.

Parameters
@Nullable String mimeType

The sample MIME type, or null if unknown.
byte nalUnitHeaderFirstByte

The first byte of nal_unit().
Returns
boolean

Whether the NAL unit with the specified header is an SEI NAL unit. False is returned if the MimeType is null.

parseH265Sei3dRefDisplayInfo

public static @Nullable NalUnitUtil.H265Sei3dRefDisplayInfoData parseH265Sei3dRefDisplayInfo(
    byte[] nalData,
    int nalOffset,
    int nalLimit
)

Parses a H.265 3D reference displays information SEI message syntax defined in ITU-T Recommendation H.265 (2019) subsection G.14.2.3. Given a generic PREFIX_SEI NAL unit, only 3D reference displays information SEI is parsed, if exists.

Parameters
byte[] nalData

A buffer containing escaped prefix SEI data.
int nalOffset

The offset of the NAL unit header in nalData.
int nalLimit

The limit of the NAL unit in nalData.
Returns
@Nullable NalUnitUtil.H265Sei3dRefDisplayInfoData

A parsed representation of the PPS data.

parseH265SpsNalUnit

public static NalUnitUtil.H265SpsData parseH265SpsNalUnit(
    byte[] nalData,
    int nalOffset,
    int nalLimit,
    @Nullable NalUnitUtil.H265VpsData vpsData
)

Parses a H.265 SPS NAL unit using the syntax defined in ITU-T Recommendation H.265 (2019) subsections 7.3.2.2.1 and F.7.3.2.2.1.

Parameters
byte[] nalData

A buffer containing escaped SPS data.
int nalOffset

The offset of the NAL unit header in nalData.
int nalLimit

The limit of the NAL unit in nalData.
@Nullable NalUnitUtil.H265VpsData vpsData

The VPS that the SPS refers to or null if unavailable.
Returns
NalUnitUtil.H265SpsData

A parsed representation of the SPS data.

parseH265SpsNalUnitPayload

public static NalUnitUtil.H265SpsData parseH265SpsNalUnitPayload(
    byte[] nalData,
    int nalOffset,
    int nalLimit,
    NalUnitUtil.H265NalHeader nalHeader,
    @Nullable NalUnitUtil.H265VpsData vpsData
)

Parses a H.265 SPS NAL unit payload (excluding the NAL unit header) using the syntax defined in ITU-T Recommendation H.265 (2019) subsections 7.3.2.2.1 and F.7.3.2.2.1.

Parameters
byte[] nalData

A buffer containing escaped SPS data.
int nalOffset

The offset of the NAL unit payload in nalData.
int nalLimit

The limit of the NAL unit in nalData.
NalUnitUtil.H265NalHeader nalHeader

The parsed representation of the NAL header.
@Nullable NalUnitUtil.H265VpsData vpsData

The VPS that the SPS refers to or null if unavailable.
Returns
NalUnitUtil.H265SpsData

A parsed representation of the SPS data.

parseH265VpsNalUnit

public static NalUnitUtil.H265VpsData parseH265VpsNalUnit(byte[] nalData, int nalOffset, int nalLimit)

Parses a H.265 VPS NAL unit using the syntax defined in ITU-T Recommendation H.265 (2019) subsections 7.3.2.1 and F.7.3.2.1.

Parameters
byte[] nalData

A buffer containing escaped VPS data.
int nalOffset

The offset of the NAL unit header in nalData.
int nalLimit

The limit of the NAL unit in nalData.
Returns
NalUnitUtil.H265VpsData

A parsed representation of the VPS data.

parsePpsNalUnit

public static NalUnitUtil.PpsData parsePpsNalUnit(byte[] nalData, int nalOffset, int nalLimit)

Parses a PPS NAL unit using the syntax defined in ITU-T Recommendation H.264 (2013) subsection 7.3.2.2.

Parameters
byte[] nalData

A buffer containing escaped PPS data.
int nalOffset

The offset of the NAL unit header in nalData.
int nalLimit

The limit of the NAL unit in nalData.
Returns
NalUnitUtil.PpsData

A parsed representation of the PPS data.

parsePpsNalUnitPayload

public static NalUnitUtil.PpsData parsePpsNalUnitPayload(byte[] nalData, int nalOffset, int nalLimit)

Parses a PPS NAL unit payload (excluding the NAL unit header) using the syntax defined in ITU-T Recommendation H.264 (2013) subsection 7.3.2.2.

Parameters
byte[] nalData

A buffer containing escaped PPS data.
int nalOffset

The offset of the NAL unit payload in nalData.
int nalLimit

The limit of the NAL unit in nalData.
Returns
NalUnitUtil.PpsData

A parsed representation of the PPS data.

parseSpsNalUnit

public static NalUnitUtil.SpsData parseSpsNalUnit(byte[] nalData, int nalOffset, int nalLimit)

Parses a SPS NAL unit using the syntax defined in ITU-T Recommendation H.264 (2013) subsection 7.3.2.1.1.

Parameters
byte[] nalData

A buffer containing escaped SPS data.
int nalOffset

The offset of the NAL unit header in nalData.
int nalLimit

The limit of the NAL unit in nalData.
Returns
NalUnitUtil.SpsData

A parsed representation of the SPS data.

parseSpsNalUnitPayload

public static NalUnitUtil.SpsData parseSpsNalUnitPayload(byte[] nalData, int nalOffset, int nalLimit)

Parses a SPS NAL unit payload (excluding the NAL unit header) using the syntax defined in ITU-T Recommendation H.264 (2013) subsection 7.3.2.1.1.

Parameters
byte[] nalData

A buffer containing escaped SPS data.
int nalOffset

The offset of the NAL unit payload in nalData.
int nalLimit

The limit of the NAL unit in nalData.
Returns
NalUnitUtil.SpsData

A parsed representation of the SPS data.

unescapeStream

public static int unescapeStream(byte[] data, int limit)

Unescapes data up to the specified limit, replacing occurrences of [0, 0, 3] with [0, 0]. The unescaped data is returned in-place, with the return value indicating its length.

Executions of this method are mutually exclusive, so it should not be called with very large buffers.

Parameters
byte[] data

The data to unescape.
int limit

The limit (exclusive) of the data to unescape.
Returns
int

The length of the unescaped data.