Codec utilities: GStreamer Base Plugins 1.0 Library Reference Manual

## Codec utilities Codec utilities — Miscellaneous codec-specific utility functions |

## Functions

guint | gst_codec_utils_aac_get_sample_rate_from_index ()
gint | gst_codec_utils_aac_get_index_from_sample_rate ()
const gchar * | gst_codec_utils_aac_get_profile ()
const gchar * | gst_codec_utils_aac_get_level ()
guint | gst_codec_utils_aac_get_channels ()
guint | gst_codec_utils_aac_get_sample_rate ()
gboolean | gst_codec_utils_aac_caps_set_level_and_profile ()
const gchar * | gst_codec_utils_h264_get_profile ()
const gchar * | gst_codec_utils_h264_get_level ()
gboolean | gst_codec_utils_h264_caps_set_level_and_profile ()
guint8 | gst_codec_utils_h264_get_level_idc ()
const gchar * | gst_codec_utils_h265_get_profile ()
const gchar * | gst_codec_utils_h265_get_tier ()
const gchar * | gst_codec_utils_h265_get_level ()
guint8 | gst_codec_utils_h265_get_level_idc ()
gboolean | gst_codec_utils_h265_caps_set_level_tier_and_profile ()
const gchar * | gst_codec_utils_mpeg4video_get_profile ()
const gchar * | gst_codec_utils_mpeg4video_get_level ()
gboolean | gst_codec_utils_mpeg4video_caps_set_level_and_profile ()
GstCaps * | gst_codec_utils_opus_create_caps ()
GstCaps * | gst_codec_utils_opus_create_caps_from_header ()
gboolean | gst_codec_utils_opus_parse_caps ()
GstBuffer * | gst_codec_utils_opus_create_header ()
gboolean | gst_codec_utils_opus_parse_header ()

## Includes

    #include <gst/pbutils/pbutils.h>

## Description

Provides codec-specific ulility functions such as functions to provide the codec profile and level in human-readable string form from header data.

## Functions

### gst_codec_utils_aac_get_sample_rate_from_index ()

    guint
    gst_codec_utils_aac_get_sample_rate_from_index
                                   (guint sr_idx);

Translates the sample rate index found in AAC headers to the actual sample rate.

#### Parameters

sr_idx | Sample rate index as from the AudioSpecificConfig (MPEG-4 container) or ADTS frame header |

#### Returns

The sample rate if `sr_idx` is valid, 0 otherwise.

### gst_codec_utils_aac_get_index_from_sample_rate ()

    gint
    gst_codec_utils_aac_get_index_from_sample_rate
                                   (guint rate);

Translates the sample rate to the index corresponding to it in AAC spec.

#### Parameters

rate | Sample rate |

#### Returns

The AAC index for this sample rate, -1 if the rate is not a valid AAC sample rate.

### gst_codec_utils_aac_get_profile ()

    const gchar *
    gst_codec_utils_aac_get_profile (const guint8 *audio_config,
                                     guint len);

Returns the profile of the given AAC stream as a string. The profile is normally determined using the AudioObjectType field which is in the first 5 bits of `audio_config`

#### Parameters

audio_config | a pointer to the AudioSpecificConfig as specified in the Elementary Stream Descriptor (esds) in ISO/IEC 14496-1. | [array length=len]
len | Length of `audio_config` in bytes |

#### Returns

The profile as a const string and `NULL` if the profile could not be determined.

### gst_codec_utils_aac_get_level ()

    const gchar *
    gst_codec_utils_aac_get_level (const guint8 *audio_config,
                                   guint len);

Determines the level of a stream as defined in ISO/IEC 14496-3. For AAC LC streams, the constraints from the AAC audio profile are applied. For AAC Main, LTP, SSR and others, the Main profile is used.

The `audio_config` parameter follows the following format, starting from the most significant bit of the first byte:

- Bit 0:4 contains the AudioObjectType (if this is 0x5, then the real AudioObjectType is carried after the rate and channel data)

- Bit 5:8 contains the sample frequency index (if this is 0xf, then the next 24 bits define the actual sample frequency, and subsequent fields are appropriately shifted).

- Bit 9:12 contains the channel configuration

#### Parameters

audio_config | a pointer to the AudioSpecificConfig as specified in the Elementary Stream Descriptor (esds) in ISO/IEC 14496-1. | [array length=len]
len | Length of `audio_config` in bytes |

#### Returns

The level as a const string and `NULL` if the level could not be determined.

### gst_codec_utils_aac_get_channels ()

    guint
    gst_codec_utils_aac_get_channels (const guint8 *audio_config,
                                      guint len);

Returns the channels of the given AAC stream.

#### Parameters

audio_config | a pointer to the AudioSpecificConfig as specified in the Elementary Stream Descriptor (esds) in ISO/IEC 14496-1. | [array length=len]
len | Length of `audio_config` in bytes |

#### Returns

The channels or 0 if the channel could not be determined.

Since: 1.10

### gst_codec_utils_aac_get_sample_rate ()

    guint
    gst_codec_utils_aac_get_sample_rate (const guint8 *audio_config,
                                         guint len);

Translates the sample rate index found in AAC headers to the actual sample rate.

#### Parameters

audio_config | a pointer to the AudioSpecificConfig as specified in the Elementary Stream Descriptor (esds) in ISO/IEC 14496-1. | [array length=len]
len | Length of `audio_config` |

#### Returns

The sample rate if sr_idx is valid, 0 otherwise.

Since: 1.10

### gst_codec_utils_aac_caps_set_level_and_profile ()

    gboolean
    gst_codec_utils_aac_caps_set_level_and_profile
                                   (GstCaps *caps,
                                    const guint8 *audio_config,
                                    guint len);

Sets the level and profile on `caps` if it can be determined from `audio_config` . See `gst_codec_utils_aac_get_level()` and `gst_codec_utils_aac_get_profile()` for more details on the parameters. `caps` must be audio/mpeg caps with an "mpegversion" field of either 2 or 4. If mpegversion is 4, the "base-profile" field is also set in `caps` .

#### Parameters

caps | the GstCaps to which level and profile fields are to be added |
audio_config | a pointer to the AudioSpecificConfig as specified in the Elementary Stream Descriptor (esds) in ISO/IEC 14496-1. (See below for more details). | [array length=len]
len | Length of `audio_config` in bytes |

#### Returns

`TRUE` if the level and profile could be set, `FALSE` otherwise.

### gst_codec_utils_h264_get_profile ()

    const gchar *
    gst_codec_utils_h264_get_profile (const guint8 *sps,
                                      guint len);

Converts the profile indication (profile_idc) in the stream's sequence parameter set into a string. The SPS is expected to have the following format, as defined in the H.264 specification. The SPS is viewed as a bitstream here, with bit 0 being the most significant bit of the first byte.

- Bit 0:7 - Profile indication

- Bit 8 - constraint_set0_flag

- Bit 9 - constraint_set1_flag

- Bit 10 - constraint_set2_flag

- Bit 11 - constraint_set3_flag

- Bit 12 - constraint_set3_flag

- Bit 13:15 - Reserved

- Bit 16:24 - Level indication

#### Parameters

sps | Pointer to the sequence parameter set for the stream. | [array length=len]
len | Length of the data available in `sps` . |

#### Returns

The profile as a const string, or `NULL` if there is an error.

### gst_codec_utils_h264_get_level ()

    const gchar *
    gst_codec_utils_h264_get_level (const guint8 *sps,
                                    guint len);

Converts the level indication (level_idc) in the stream's sequence parameter set into a string. The SPS is expected to have the same format as for `gst_codec_utils_h264_get_profile()`.

#### Parameters

sps | Pointer to the sequence parameter set for the stream. | [array length=len]
len | Length of the data available in `sps` . |

#### Returns

The level as a const string, or `NULL` if there is an error.

### gst_codec_utils_h264_caps_set_level_and_profile ()

    gboolean
    gst_codec_utils_h264_caps_set_level_and_profile
                                   (GstCaps *caps,
                                    const guint8 *sps,
                                    guint len);

Sets the level and profile in `caps` if it can be determined from `sps` . See `gst_codec_utils_h264_get_level()` and `gst_codec_utils_h264_get_profile()` for more details on the parameters.

#### Parameters

caps | the GstCaps to which the level and profile are to be added |
sps | Pointer to the sequence parameter set for the stream. | [array length=len]
len | Length of the data available in `sps` . |

#### Returns

`TRUE` if the level and profile could be set, `FALSE` otherwise.

### gst_codec_utils_h264_get_level_idc ()

    guint8
    gst_codec_utils_h264_get_level_idc (const gchar *level);

Transform a level string from the caps into the level_idc

#### Parameters

level | A level string from caps |

#### Returns

the level_idc or 0 if the level is unknown

### gst_codec_utils_h265_get_profile ()

    const gchar *
    gst_codec_utils_h265_get_profile (const guint8 *profile_tier_level,
                                      guint len);

Converts the profile indication (general_profile_idc) in the stream's profile_level_tier structure into a string. The profile_tier_level is expected to have the following format, as defined in the H.265 specification. The profile_tier_level is viewed as a bitstream here, with bit 0 being the most significant bit of the first byte.

- Bit 0:1 - general_profile_space

- Bit 2 - general_tier_flag

- Bit 3:7 - general_profile_idc

- Bit 8:39 - gernal_profile_compatibility_flags

- Bit 40 - general_progressive_source_flag

- Bit 41 - general_interlaced_source_flag

- Bit 42 - general_non_packed_constraint_flag

- Bit 43 - general_frame_only_constraint_flag

- Bit 44:87 - general_reserved_zero_44bits

- Bit 88:95 - general_level_idc

#### Parameters

profile_tier_level | Pointer to the profile_tier_level structure for the stream. | [array length=len]
len | Length of the data available in `profile_tier_level` |

#### Returns

The profile as a const string, or `NULL` if there is an error.

Since: 1.4

### gst_codec_utils_h265_get_tier ()

    const gchar *
    gst_codec_utils_h265_get_tier (const guint8 *profile_tier_level,
                                   guint len);

Converts the tier indication (general_tier_flag) in the stream's profile_tier_level structure into a string. The profile_tier_level is expected to have the same format as for `gst_codec_utils_h264_get_profile()`.

#### Parameters

profile_tier_level | Pointer to the profile_tier_level for the stream. | [array length=len]
len | Length of the data available in `profile_tier_level` . |

#### Returns

The tier as a const string, or `NULL` if there is an error.

Since: 1.4

### gst_codec_utils_h265_get_level ()

    const gchar *
    gst_codec_utils_h265_get_level (const guint8 *profile_tier_level,
                                    guint len);

Converts the level indication (general_level_idc) in the stream's profile_tier_level structure into a string. The profiel_tier_level is expected to have the same format as for `gst_codec_utils_h264_get_profile()`.

#### Parameters

profile_tier_level | Pointer to the profile_tier_level for the stream. | [array length=len]
len | Length of the data available in `profile_tier_level` . |

#### Returns

The level as a const string, or `NULL` if there is an error.

Since: 1.4

### gst_codec_utils_h265_get_level_idc ()

    guint8
    gst_codec_utils_h265_get_level_idc (const gchar *level);

Transform a level string from the caps into the level_idc

#### Parameters

level | A level string from caps |

#### Returns

the level_idc or 0 if the level is unknown

Since: 1.4

### gst_codec_utils_h265_caps_set_level_tier_and_profile ()

    gboolean
    gst_codec_utils_h265_caps_set_level_tier_and_profile
                                   (GstCaps *caps,
                                    const guint8 *profile_tier_level,
                                    guint len);

Sets the level, tier and profile in `caps` if it can be determined from `profile_tier_level` . See `gst_codec_utils_h265_get_level()`, `gst_codec_utils_h265_get_tier()` and `gst_codec_utils_h265_get_profile()` for more details on the parameters.

#### Parameters

caps | the GstCaps to which the level, tier and profile are to be added |
profile_tier_level | Pointer to the profile_tier_level struct. | [array length=len]
len | Length of the data available in `profile_tier_level` . |

#### Returns

`TRUE` if the level, tier, profile could be set, `FALSE` otherwise.

Since: 1.4

### gst_codec_utils_mpeg4video_get_profile ()

    const gchar *
    gst_codec_utils_mpeg4video_get_profile
                                   (const guint8 *vis_obj_seq,
                                    guint len);

Converts the profile indication in the stream's visual object sequence into a string. `vis_obj_seq` is expected to be the data following the visual object sequence start code. Only the first byte (profile_and_level_indication) is used.

#### Parameters

vis_obj_seq | Pointer to the visual object sequence for the stream. | [array length=len]
len | Length of the data available in `sps` . |

#### Returns

The profile as a const string, or NULL if there is an error.

### gst_codec_utils_mpeg4video_get_level ()

    const gchar *
    gst_codec_utils_mpeg4video_get_level (const guint8 *vis_obj_seq,
                                          guint len);

Converts the level indication in the stream's visual object sequence into a string. `vis_obj_seq` is expected to be the data following the visual object sequence start code. Only the first byte (profile_and_level_indication) is used.

#### Parameters

vis_obj_seq | Pointer to the visual object sequence for the stream. | [array length=len]
len | Length of the data available in `sps` . |

#### Returns

The level as a const string, or NULL if there is an error.

### gst_codec_utils_mpeg4video_caps_set_level_and_profile ()

    gboolean
    gst_codec_utils_mpeg4video_caps_set_level_and_profile
                                   (GstCaps *caps,
                                    const guint8 *vis_obj_seq,
                                    guint len);

Sets the level and profile in `caps` if it can be determined from `vis_obj_seq` . See `gst_codec_utils_mpeg4video_get_level()` and `gst_codec_utils_mpeg4video_get_profile()` for more details on the parameters.

#### Parameters

caps | the GstCaps to which the level and profile are to be added |
vis_obj_seq | Pointer to the visual object sequence for the stream. | [array length=len]
len | Length of the data available in `sps` . |

#### Returns

`TRUE` if the level and profile could be set, `FALSE` otherwise.

### gst_codec_utils_opus_create_caps ()

    GstCaps *
    gst_codec_utils_opus_create_caps (guint32 rate,
                                      guint8 channels,
                                      guint8 channel_mapping_family,
                                      guint8 stream_count,
                                      guint8 coupled_count,
                                      const guint8 *channel_mapping);

Creates Opus caps from the given parameters.

#### Parameters

rate | the sample rate |
channels | the number of channels |
channel_mapping_family | the channel mapping family |
stream_count | the number of independent streams |
coupled_count | the number of stereo streams |
channel_mapping | the mapping between the streams. | [allow-none][array]

#### Returns

The GstCaps, or `NULL` if the parameters would lead to invalid Opus caps.

Since: 1.8

### gst_codec_utils_opus_create_caps_from_header ()

    GstCaps *
    gst_codec_utils_opus_create_caps_from_header
                                   (GstBuffer *header,
                                    GstBuffer *comments);

Creates Opus caps from the given OpusHead `header` and comment header `comments` .

#### Parameters

header | OpusHead header |
comments | Comment header or NULL. | [allow-none]

#### Returns

The GstCaps.

Since: 1.8

### gst_codec_utils_opus_parse_caps ()

    gboolean
    gst_codec_utils_opus_parse_caps (GstCaps *caps,
                                     guint32 *rate,
                                     guint8 *channels,
                                     guint8 *channel_mapping_family,
                                     guint8 *stream_count,
                                     guint8 *coupled_count,
                                     guint8 channel_mapping[256]);

Parses Opus caps and fills the different fields with defaults if possible.

#### Parameters

caps | the GstCaps to parse the data from |
rate | the sample rate. | [out]
channels | the number of channels. | [out]
channel_mapping_family | the channel mapping family. | [out]
stream_count | the number of independent streams. | [out]
coupled_count | the number of stereo streams. | [out]
channel_mapping | the mapping between the streams. | [out][array fixed-size=256]

#### Returns

`TRUE` if parsing was successful, `FALSE` otherwise.

Since: 1.8

### gst_codec_utils_opus_create_header ()

    GstBuffer *
    gst_codec_utils_opus_create_header (guint32 rate,
                                        guint8 channels,
                                        guint8 channel_mapping_family,
                                        guint8 stream_count,
                                        guint8 coupled_count,
                                        const guint8 *channel_mapping,
                                        guint16 pre_skip,
                                        gint16 output_gain);

Creates OpusHead header from the given parameters.

#### Parameters

rate | the sample rate |
channels | the number of channels |
channel_mapping_family | the channel mapping family |
stream_count | the number of independent streams |
coupled_count | the number of stereo streams |
channel_mapping | the mapping between the streams. | [allow-none][array]
pre_skip | Pre-skip in 48kHz samples or 0 |
output_gain | Output gain or 0 |

#### Returns

The GstBuffer containing the OpusHead.

Since: 1.8

### gst_codec_utils_opus_parse_header ()

    gboolean
    gst_codec_utils_opus_parse_header (GstBuffer *header,
                                       guint32 *rate,
                                       guint8 *channels,
                                       guint8 *channel_mapping_family,
                                       guint8 *stream_count,
                                       guint8 *coupled_count,
                                       guint8 channel_mapping[256],
                                       guint16 *pre_skip,
                                       gint16 *output_gain);

Parses the OpusHead header.

#### Parameters

header | the OpusHead GstBuffer |
rate | the sample rate. | [out]
channels | the number of channels. | [out]
channel_mapping_family | the channel mapping family. | [out]
stream_count | the number of independent streams. | [out]
coupled_count | the number of stereo streams. | [out]
channel_mapping | the mapping between the streams. | [out][array fixed-size=256]
pre_skip | Pre-skip in 48kHz samples or 0. | [out]
output_gain | Output gain or 0. | [out]

#### Returns

`TRUE` if parsing was successful, `FALSE` otherwise.

Since: 1.8

## Types and Values