## GstTypefind

GstTypefind — Stream type detection

## Functions

void | (*GstTypeFindFunction) ()
const guint8 * | gst_type_find_peek ()
void | gst_type_find_suggest ()
void | gst_type_find_suggest_simple ()
guint64 | gst_type_find_get_length ()
gboolean | gst_type_find_register ()

## Types and Values

struct | GstTypeFind
enum | GstTypeFindProbability

## Includes

    #include <gst/gst.h>

## Description

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

## Functions

### GstTypeFindFunction ()

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

A function that will be called by typefinding.

#### Parameters

find | A GstTypeFind structure |
user_data | optional data to pass to the function |

### gst_type_find_peek ()

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

#### Parameters

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][nullable]

### gst_type_find_suggest ()

    void
    gst_type_find_suggest (GstTypeFind *find,
                           guint probability,
                           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.

#### Parameters

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

#### Parameters

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`. | [allow-none]
... | 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) |

### gst_type_find_get_length ()

    guint64
    gst_type_find_get_length (GstTypeFind *find);

Get the length of the data stream.

#### Parameters

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,
                            const gchar *extensions,
                            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.

#### Parameters

plugin | A GstPlugin, or `NULL` for a static typefind function. | [allow-none]
name | The name for registering |
rank | The rank (or importance) of this typefind function |
func | The GstTypeFindFunction to use |
extensions | Optional comma-separated list of extensions that could belong to this type. | [allow-none]
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

## Types and Values

### struct GstTypeFind

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

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

      gpointer         data;

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

Object that stores typefind callbacks. To use with GstTypeFindFactory.

#### Members

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

### enum GstTypeFindProbability

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

#### Members

GST_TYPE_FIND_NONE | type undetected. |
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. |