## Descriptions

Descriptions — Provides human-readable descriptions for caps/codecs and encoder, decoder, URI source and URI sink elements

## Functions

gchar * | gst_pb_utils_get_source_description ()
gchar * | gst_pb_utils_get_sink_description ()
gchar * | gst_pb_utils_get_decoder_description ()
gchar * | gst_pb_utils_get_encoder_description ()
gchar * | gst_pb_utils_get_element_description ()
gboolean | gst_pb_utils_add_codec_description_to_tag_list ()
gchar * | gst_pb_utils_get_codec_description ()

## Includes

    #include <gst/pbutils/pbutils.h>

## Description

The above functions provide human-readable strings for media formats and decoder/demuxer/depayloader/encoder/muxer/payloader elements for use in error dialogs or other messages shown to users.

gst_pb_utils_add_codec_description_to_tag_list() is a utility function for demuxer and decoder elements to add audio/video codec tags from a given (fixed) GstCaps.

## Functions

### gst_pb_utils_get_source_description ()

    gchar *
    gst_pb_utils_get_source_description (const gchar *protocol);

Returns a localised string describing a source element handling the protocol specified in `protocol` , for use in error dialogs or other messages to be seen by the user. Should never return NULL unless `protocol` is invalid.

This function is mainly for internal use, applications would typically use `gst_missing_plugin_message_get_description()` to get a description of a missing feature from a missing-plugin message.

#### Parameters

protocol | the protocol the source element needs to handle, e.g. "http" |

#### Returns

a newly-allocated description string, or NULL on error. Free string with `g_free()` when not needed any longer.

### gst_pb_utils_get_sink_description ()

    gchar *
    gst_pb_utils_get_sink_description (const gchar *protocol);

Returns a localised string describing a sink element handling the protocol specified in `protocol` , for use in error dialogs or other messages to be seen by the user. Should never return NULL unless `protocol` is invalid.

This function is mainly for internal use, applications would typically use `gst_missing_plugin_message_get_description()` to get a description of a missing feature from a missing-plugin message.

#### Parameters

protocol | the protocol the sink element needs to handle, e.g. "http" |

#### Returns

a newly-allocated description string, or NULL on error. Free string with `g_free()` when not needed any longer.

### gst_pb_utils_get_decoder_description ()

    gchar *
    gst_pb_utils_get_decoder_description (const GstCaps *caps);

Returns a localised string describing an decoder for the format specified in `caps` , for use in error dialogs or other messages to be seen by the user. Should never return NULL unless `factory_name` or `caps` are invalid.

This function is mainly for internal use, applications would typically use `gst_missing_plugin_message_get_description()` to get a description of a missing feature from a missing-plugin message.

#### Parameters

caps | the (fixed) GstCaps for which an decoder description is needed |

#### Returns

a newly-allocated description string, or NULL on error. Free string with `g_free()` when not needed any longer.

### gst_pb_utils_get_encoder_description ()

    gchar *
    gst_pb_utils_get_encoder_description (const GstCaps *caps);

Returns a localised string describing an encoder for the format specified in `caps` , for use in error dialogs or other messages to be seen by the user. Should never return NULL unless `factory_name` or `caps` are invalid.

This function is mainly for internal use, applications would typically use `gst_missing_plugin_message_get_description()` to get a description of a missing feature from a missing-plugin message.

#### Parameters

caps | the (fixed) GstCaps for which an encoder description is needed |

#### Returns

a newly-allocated description string, or NULL on error. Free string with `g_free()` when not needed any longer.

### gst_pb_utils_get_element_description ()

    gchar *
    gst_pb_utils_get_element_description (const gchar *factory_name);

Returns a localised string describing the given element, for use in error dialogs or other messages to be seen by the user. Should never return NULL unless `factory_name` is invalid.

This function is mainly for internal use, applications would typically use `gst_missing_plugin_message_get_description()` to get a description of a missing feature from a missing-plugin message.

#### Parameters

factory_name | the name of the element, e.g. "giosrc" |

#### Returns

a newly-allocated description string, or NULL on error. Free string with `g_free()` when not needed any longer.

### gst_pb_utils_add_codec_description_to_tag_list ()

    gboolean
    gst_pb_utils_add_codec_description_to_tag_list
                                   (GstTagList *taglist,
                                    const gchar *codec_tag,
                                    const GstCaps *caps);

Adds a codec tag describing the format specified by `caps` to `taglist` .

#### Parameters

taglist | a GstTagList |
codec_tag | a GStreamer codec tag such as GST_TAG_AUDIO_CODEC, GST_TAG_VIDEO_CODEC or GST_TAG_CODEC. If none is specified, the function will attempt to detect the appropriate category. | [allow-none]
caps | the (fixed) GstCaps for which a codec tag should be added. |

#### Returns

TRUE if a codec tag was added, FALSE otherwise.

### gst_pb_utils_get_codec_description ()

    gchar *
    gst_pb_utils_get_codec_description (const GstCaps *caps);

Returns a localised (as far as this is possible) string describing the media format specified in `caps` , for use in error dialogs or other messages to be seen by the user. Should never return NULL unless `caps` is invalid.

Also see the convenience function `gst_pb_utils_add_codec_description_to_tag_list()`.

#### Parameters

caps | the (fixed) GstCaps for which an format description is needed |

#### Returns

a newly-allocated description string, or NULL on error. Free string with `g_free()` when not needed any longer.