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

## Synopsis

    #include <gst/pbutils/descriptions.h>

    gchar *             gst_pb_utils_get_source_description (const gchar *protocol);
    gchar *             gst_pb_utils_get_sink_description   (const gchar *protocol);
    gchar *             gst_pb_utils_get_decoder_description
                                                            (const GstCaps *caps);
    gchar *             gst_pb_utils_get_encoder_description
                                                            (const GstCaps *caps);
    gchar *             gst_pb_utils_get_element_description
                                                            (const gchar *factory_name);

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

## 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.

## Details

### 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.

`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.

`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.

`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.

`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.

`factory_name` : | the name of the element, e.g. "gnomevfssrc"
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`.

`taglist` : | a GstTagList
`codec_tag` : | a GStreamer codec tag such as GST_TAG_AUDIO_CODEC, GST_TAG_VIDEO_CODEC or GST_TAG_CODEC
`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()`.

`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.