## GstTypeFind

GstTypeFind — Stream type detection

## Synopsis

    #include <gst/gst.h>

    struct              GstTypeFind;
    void                (*GstTypeFindFunction)              (GstTypeFind *find,
                                                             gpointer data);
    enum                GstTypeFindProbability;
    guint8 *            gst_type_find_peek                  (GstTypeFind *find,
                                                             gint64 offset,
                                                             guint size);
    void                gst_type_find_suggest               (GstTypeFind *find,
                                                             guint probability,
                                                             const GstCaps *caps);
    void                gst_type_find_suggest_simple        (GstTypeFind *find,
                                                             guint probability,
                                                             const char *media_type,
                                                             const char *fieldname,
                                                             ...);
    guint64             gst_type_find_get_length            (GstTypeFind *find);
    gboolean            gst_type_find_register              (GstPlugin *plugin,
                                                             const gchar *name,
                                                             guint rank,
                                                             GstTypeFindFunction func,
                                                             gchar **extensions,
                                                             const GstCaps *possible_caps,
                                                             gpointer data,
                                                             GDestroyNotify data_notify);

## Description

The following functions allow you to detect the media type of an unknown stream.

Last reviewed on 2005-11-09 (0.9.4)

## Details

### struct GstTypeFind

    struct GstTypeFind {
      /* private to the caller of the typefind function */
      guint8 *  (* peek)       (gpointer         data,
                                gint64           offset,
                                guint            size);

      void      (* suggest)    (gpointer         data,
                                guint            probability,
                                const GstCaps *  caps);

      gpointer     data;

      /* optional */
      guint64   (* get_length) (gpointer data);
    };

Object that stores typefind callbacks. To use with GstTypeFindFactory.

`peek` () | Method to peek data.
`suggest` () | Method to suggest GstCaps with a given probability.
gpointer `data`; | The data used by the caller of the typefinding function.
`get_length` () | Returns the length of current data.

### GstTypeFindFunction ()

    void                (*GstTypeFindFunction)              (GstTypeFind *find,
                                                             gpointer data);

A function that will be called by typefinding.

`find` : | A GstTypeFind structure
`data` : | optionnal data to pass to the function

### enum GstTypeFindProbability

    typedef enum {
      GST_TYPE_FIND_NONE = 0,
      GST_TYPE_FIND_MINIMUM = 1,
      GST_TYPE_FIND_POSSIBLE = 50,
      GST_TYPE_FIND_LIKELY = 80,
      GST_TYPE_FIND_NEARLY_CERTAIN = 99,
      GST_TYPE_FIND_MAXIMUM = 100
    } GstTypeFindProbability;

The probability of the typefind function. Higher values have more certainty in doing a reliable typefind.

`GST_TYPE_FIND_NONE` | type undetected. Since 0.10.36.
`GST_TYPE_FIND_MINIMUM` | unlikely typefind.
`GST_TYPE_FIND_POSSIBLE` | possible type detected.
`GST_TYPE_FIND_LIKELY` | likely a type was detected.
`GST_TYPE_FIND_NEARLY_CERTAIN` | nearly certain that a type was detected.
`GST_TYPE_FIND_MAXIMUM` | very certain a type was detected.

### gst_type_find_peek ()

    guint8 *            gst_type_find_peek                  (GstTypeFind *find,
                                                             gint64 offset,
                                                             guint size);

Returns the `size` bytes of the stream to identify beginning at offset. If offset is a positive number, the offset is relative to the beginning of the stream, if offset is a negative number the offset is relative to the end of the stream. The returned memory is valid until the typefinding function returns and must not be freed.

`find` : | The GstTypeFind object the function was called with
`offset` : | The offset
`size` : | The number of bytes to return
Returns : | the requested data, or NULL if that data is not available. [transfer none][array length=size]

### gst_type_find_suggest ()

    void                gst_type_find_suggest               (GstTypeFind *find,
                                                             guint probability,
                                                             const GstCaps *caps);

If a GstTypeFindFunction calls this function it suggests the caps with the given probability. A GstTypeFindFunction may supply different suggestions in one call. It is up to the caller of the GstTypeFindFunction to interpret these values.

`find` : | The GstTypeFind object the function was called with
`probability` : | The probability in percent that the suggestion is right
`caps` : | The fixed GstCaps to suggest

### gst_type_find_suggest_simple ()

    void                gst_type_find_suggest_simple        (GstTypeFind *find,
                                                             guint probability,
                                                             const char *media_type,
                                                             const char *fieldname,
                                                             ...);

If a GstTypeFindFunction calls this function it suggests the caps with the given probability. A GstTypeFindFunction may supply different suggestions in one call. It is up to the caller of the GstTypeFindFunction to interpret these values.

This function is similar to `gst_type_find_suggest()`, only that instead of passing a GstCaps argument you can create the caps on the fly in the same way as you can with `gst_caps_new_simple()`.

Make sure you terminate the list of arguments with a NULL argument and that the values passed have the correct type (in terms of width in bytes when passed to the vararg function - this applies particularly to gdouble and guint64 arguments).

`find` : | The GstTypeFind object the function was called with
`probability` : | The probability in percent that the suggestion is right
`media_type` : | the media type of the suggested caps
`fieldname` : | first field of the suggested caps, or NULL
`...` : | additional arguments to the suggested caps in the same format as the arguments passed to `gst_structure_new()` (ie. triplets of field name, field GType and field value)

Since 0.10.20

### gst_type_find_get_length ()

    guint64             gst_type_find_get_length            (GstTypeFind *find);

Get the length of the data stream.

`find` : | The GstTypeFind the function was called with
Returns : | The length of the data stream, or 0 if it is not available.

### gst_type_find_register ()

    gboolean            gst_type_find_register              (GstPlugin *plugin,
                                                             const gchar *name,
                                                             guint rank,
                                                             GstTypeFindFunction func,
                                                             gchar **extensions,
                                                             const GstCaps *possible_caps,
                                                             gpointer data,
                                                             GDestroyNotify data_notify);

Registers a new typefind function to be used for typefinding. After registering this function will be available for typefinding. This function is typically called during an element's plugin initialization.

`plugin` : | A GstPlugin, or NULL for a static typefind function (note that passing NULL only works in GStreamer 0.10.16 and later)
`name` : | The name for registering
`rank` : | The rank (or importance) of this typefind function
`func` : | The GstTypeFindFunction to use
`extensions` : | Optional extensions that could belong to this type. [transfer none][array zero-terminated=1][element-type utf8]
`possible_caps` : | Optionally the caps that could be returned when typefinding succeeds
`data` : | Optional user data. This user data must be available until the plugin is unloaded.
`data_notify` : | a GDestroyNotify that will be called on `data` when the plugin is unloaded.
Returns : | TRUE on success, FALSE otherwise