Writing typefind functions

Writing typefind functions — Using the type finding subsystem from plugins

Synopsis


#include <gst/gst.h>


struct      GstTypeFind;
void        (*GstTypeFindFunction)          (GstTypeFind *find,
                                             gpointer data);
guint8*     gst_type_find_peek              (GstTypeFind *find,
                                             gint64 offset,
                                             guint size);
void        gst_type_find_suggest           (GstTypeFind *find,
                                             guint probability,
                                             GstCaps *caps);
guint64     gst_type_find_get_length        (GstTypeFind *find);

Description

The typefinding subsystem in GStreamer is used to find the matching GstCaps for an unidentified stream. This works similar to the unix file command.

There are a number of elements which output unidentified data streams, such as a file source. Some other elements such as an autoplugger require a proper identification of the data, so they can create the right pipeline. To find the right type, they use typefinding elements, the most notable being the typefind element. These elements take a list of all registered typefind functions and try them on the data to see if any of these functions can identify the data.

The functions in this section provide the simple framework for writing these typefind functions. The job of a typefind function is to identify the type of the data good enough so that plugins using this type can understand them while make sure no other type is misidentified.

Example 2. a typefind function for Ogg data

static void
ogg_type_find (GstTypeFind *tf, gpointer unused)
{
  guint8 *data = gst_type_find_peek (tf, 0, 4);
  
  if (data && memcmp (data, "OggS", 4) == 0) {
    gst_type_find_suggest (tf, GST_TYPE_FIND_MAXIMUM, 
	    gst_caps_new ("ogg_type_find", "application/ogg", NULL));
  }
};

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,
							 GstCaps *		caps);
  
  gpointer			data;
  
  /* optional */
  guint64		(* get_length)			(gpointer		data);

};

This structure is filled by the caller of the typefind function. Typefind functions must treat this as an opaque structure.

guint8* (*peek) (gpointer data, gint64 offset, guint size)function called to get data. See gst_type_find_peek()
void (*suggest) (gpointer data, guint probability, GstCaps * caps)function called to suggest a caps. See gst_type_find_suggest()
gpointer datacaller defined data, that is passed when calling the functions
guint64 (*get_length) (gpointer data)function called to query the length of the stream. See gst_type_find_get_length(). Providing this function is optional.

GstTypeFindFunction ()

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

This is the prototype for a typefind function.

find :The GstTypeFind data
data :the user defined data that was provided on gst_type_find_factory_register()

gst_type_find_peek ()

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

Returns 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. If NULL is returned, that data is not available.

find : the find 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.

gst_type_find_suggest ()

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

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

find : the find object the function was called with
probability : the probability in percent that the suggestion is right
caps : the fixed caps to suggest

gst_type_find_get_length ()

guint64     gst_type_find_get_length        (GstTypeFind *find);

Get the length of the data stream.

find : the find object the function was called with
Returns : the length of the data stream or 0 if it is not available.

See Also

GstTypeFactory - querying registered typefind functions