2 * Copyright (C) 1999,2000 Erik Walthinsen <omega@cse.ogi.edu>
3 * Copyright (C) 2000,2005 Wim Taymans <wim@fluendo.com>
4 * Copyright (C) 2006 Tim-Philipp Müller <tim centricular net>
8 * This library is free software; you can redistribute it and/or
9 * modify it under the terms of the GNU Library General Public
10 * License as published by the Free Software Foundation; either
11 * version 2 of the License, or (at your option) any later version.
13 * This library is distributed in the hope that it will be useful,
14 * but WITHOUT ANY WARRANTY; without even the implied warranty of
15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
16 * Library General Public License for more details.
18 * You should have received a copy of the GNU Library General Public
19 * License along with this library; if not, write to the
20 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
21 * Boston, MA 02111-1307, USA.
25 * SECTION:gsttypefindhelper
26 * @short_description: Utility functions for typefinding
28 * Utility functions for elements doing typefinding:
29 * gst_type_find_helper() does typefinding in pull mode, while
30 * gst_type_find_helper_for_buffer() is useful for elements needing to do
31 * typefinding in push mode from a chain function.
41 #include "gsttypefindhelper.h"
43 /* ********************** typefinding in pull mode ************************ */
46 helper_find_suggest (gpointer data, guint probability, const GstCaps * caps);
50 GSList *buffers; /* buffer cache */
53 GstTypeFindHelperGetRangeFunction func;
54 GstTypeFindProbability best_probability;
56 GstTypeFindFactory *factory; /* for logging */
57 GstObject *obj; /* for logging */
62 * @data: helper data struct
66 * Get data pointer within a stream. Keeps a cache of read buffers (partly
67 * for performance reasons, but mostly because pointers returned by us need
68 * to stay valid until typefinding has finished)
70 * Returns: address of the data or %NULL if buffer does not cover the
74 helper_find_peek (gpointer data, gint64 offset, guint size)
76 GstTypeFindHelper *helper;
79 GSList *insert_pos = NULL;
86 helper = (GstTypeFindHelper *) data;
88 GST_LOG_OBJECT (helper->obj, "'%s' called peek (%" G_GINT64_FORMAT
89 ", %u)", GST_OBJECT_NAME (helper->factory), offset, size);
95 if (helper->size == -1 || helper->size < -offset)
98 offset += helper->size;
101 /* see if we have a matching buffer already in our list */
102 if (size > 0 && offset <= helper->last_offset) {
105 for (walk = helper->buffers; walk; walk = walk->next) {
106 GstBuffer *buf = GST_BUFFER_CAST (walk->data);
107 guint64 buf_offset = GST_BUFFER_OFFSET (buf);
108 guint buf_size = gst_buffer_get_size (buf);
110 /* buffers are kept sorted by end offset (highest first) in the list, so
111 * at this point we save the current position and stop searching if
112 * we're after the searched end offset */
113 if (buf_offset <= offset) {
114 if ((offset + size) < (buf_offset + buf_size)) {
117 /* FIXME, unmap after usage */
118 data = gst_buffer_map (buf, NULL, NULL, GST_MAP_READ);
120 return data + (offset - buf_offset);
122 } else if (offset + size >= buf_offset + buf_size) {
130 /* some typefinders go in 1 byte steps over 1k of data and request
131 * small buffers. It is really inefficient to pull each time, and pulling
132 * a larger chunk is almost free. Trying to pull a larger chunk at the end
133 * of the file is also not a problem here, we'll just get a truncated buffer
134 * in that case (and we'll have to double-check the size we actually get
135 * anyway, see below) */
136 ret = helper->func (helper->obj, offset, MAX (size, 4096), &buffer);
138 if (ret != GST_FLOW_OK)
142 caps = GST_BUFFER_CAPS (buffer);
144 if (caps && !gst_caps_is_empty (caps) && !gst_caps_is_any (caps)) {
145 GST_DEBUG ("buffer has caps %" GST_PTR_FORMAT ", suggest max probability",
148 gst_caps_replace (&helper->caps, caps);
149 helper->best_probability = GST_TYPE_FIND_MAXIMUM;
151 gst_buffer_unref (buffer);
156 /* getrange might silently return shortened buffers at the end of a file,
157 * we must, however, always return either the full requested data or NULL */
158 buf_offset = GST_BUFFER_OFFSET (buffer);
159 buf_size = gst_buffer_get_size (buffer);
161 if ((buf_offset != -1 && buf_offset != offset) || buf_size < size) {
162 GST_DEBUG ("dropping short buffer: %" G_GUINT64_FORMAT "-%" G_GUINT64_FORMAT
163 " instead of %" G_GUINT64_FORMAT "-%" G_GUINT64_FORMAT,
164 buf_offset, buf_offset + buf_size - 1, offset, offset + size - 1);
165 gst_buffer_unref (buffer);
171 g_slist_insert_before (helper->buffers, insert_pos, buffer);
173 /* if insert_pos is not set, our offset is bigger than the largest offset
174 * we have so far; since we keep the list sorted with highest offsets
175 * first, we need to prepend the buffer to the list */
176 helper->last_offset = GST_BUFFER_OFFSET (buffer) + buf_size;
177 helper->buffers = g_slist_prepend (helper->buffers, buffer);
181 return gst_buffer_map (buffer, NULL, NULL, GST_MAP_READ);
185 GST_INFO ("typefind function returned: %s", gst_flow_get_name (ret));
191 * helper_find_suggest:
192 * @data: helper data struct
193 * @probability: probability of the match
194 * @caps: caps of the type
196 * If given @probability is higher, replace previously store caps.
199 helper_find_suggest (gpointer data, GstTypeFindProbability probability,
200 const GstCaps * caps)
202 GstTypeFindHelper *helper = (GstTypeFindHelper *) data;
204 GST_LOG_OBJECT (helper->obj,
205 "'%s' called suggest (%u, %" GST_PTR_FORMAT ")",
206 GST_OBJECT_NAME (helper->factory), probability, caps);
208 if (probability > helper->best_probability) {
209 GstCaps *copy = gst_caps_copy (caps);
211 gst_caps_replace (&helper->caps, copy);
212 gst_caps_unref (copy);
213 helper->best_probability = probability;
218 helper_find_get_length (gpointer data)
220 GstTypeFindHelper *helper = (GstTypeFindHelper *) data;
222 GST_LOG_OBJECT (helper->obj, "'%s' called get_length, returning %"
223 G_GUINT64_FORMAT, GST_OBJECT_NAME (helper->factory), helper->size);
229 * gst_type_find_helper_get_range_ext:
230 * @obj: A #GstObject that will be passed as first argument to @func
231 * @func: (scope call): A generic #GstTypeFindHelperGetRangeFunction that will
232 * be used to access data at random offsets when doing the typefinding
233 * @size: The length in bytes
234 * @extension: extension of the media
235 * @prob: (out) (allow-none): location to store the probability of the found
238 * Utility function to do pull-based typefinding. Unlike gst_type_find_helper()
239 * however, this function will use the specified function @func to obtain the
240 * data needed by the typefind functions, rather than operating on a given
241 * source pad. This is useful mostly for elements like tag demuxers which
242 * strip off data at the beginning and/or end of a file and want to typefind
243 * the stripped data stream before adding their own source pad (the specified
244 * callback can then call the upstream peer pad with offsets adjusted for the
245 * tag size, for example).
247 * When @extension is not NULL, this function will first try the typefind
248 * functions for the given extension, which might speed up the typefinding
251 * Free-function: gst_caps_unref
253 * Returns: (transfer full): the #GstCaps corresponding to the data stream.
254 * Returns #NULL if no #GstCaps matches the data stream.
259 gst_type_find_helper_get_range_ext (GstObject * obj,
260 GstTypeFindHelperGetRangeFunction func, guint64 size,
261 const gchar * extension, GstTypeFindProbability * prob)
263 GstTypeFindHelper helper;
266 GList *l, *type_list;
267 GstCaps *result = NULL;
270 g_return_val_if_fail (GST_IS_OBJECT (obj), NULL);
271 g_return_val_if_fail (func != NULL, NULL);
273 helper.buffers = NULL;
275 helper.last_offset = 0;
277 helper.best_probability = GST_TYPE_FIND_NONE;
282 find.peek = helper_find_peek;
283 find.suggest = helper_find_suggest;
285 if (size == 0 || size == (guint64) - 1) {
286 find.get_length = NULL;
288 find.get_length = helper_find_get_length;
291 type_list = gst_type_find_factory_get_list ();
293 /* move the typefinders for the extension first in the list. The idea is that
294 * when one of them returns MAX we don't need to search further as there is a
295 * very high chance we got the right type. */
299 GST_LOG_OBJECT (obj, "sorting typefind for extension %s to head",
302 for (l = type_list; l; l = next) {
303 GstTypeFindFactory *factory;
309 factory = GST_TYPE_FIND_FACTORY (l->data);
311 ext = gst_type_find_factory_get_extensions (factory);
315 GST_LOG_OBJECT (obj, "testing factory %s for extension %s",
316 GST_OBJECT_NAME (factory), extension);
318 for (i = 0; ext[i]; i++) {
319 if (strcmp (ext[i], extension) == 0) {
320 /* found extension, move in front */
321 GST_LOG_OBJECT (obj, "moving typefind for extension %s to head",
323 /* remove entry from list */
324 type_list = g_list_delete_link (type_list, l);
325 /* insert at the position */
326 type_list = g_list_insert (type_list, factory, pos);
327 /* next element will be inserted after this one */
335 for (l = type_list; l; l = l->next) {
336 helper.factory = GST_TYPE_FIND_FACTORY (l->data);
337 gst_type_find_factory_call_function (helper.factory, &find);
338 if (helper.best_probability >= GST_TYPE_FIND_MAXIMUM)
341 gst_plugin_feature_list_free (type_list);
343 for (walk = helper.buffers; walk; walk = walk->next)
344 gst_buffer_unref (GST_BUFFER_CAST (walk->data));
345 g_slist_free (helper.buffers);
347 if (helper.best_probability > 0)
348 result = helper.caps;
351 *prob = helper.best_probability;
353 GST_LOG_OBJECT (obj, "Returning %" GST_PTR_FORMAT " (probability = %u)",
354 result, (guint) helper.best_probability);
360 * gst_type_find_helper_get_range:
361 * @obj: A #GstObject that will be passed as first argument to @func
362 * @func: (scope call): A generic #GstTypeFindHelperGetRangeFunction that will
363 * be used to access data at random offsets when doing the typefinding
364 * @size: The length in bytes
365 * @prob: (out) (allow-none): location to store the probability of the found
368 * Utility function to do pull-based typefinding. Unlike gst_type_find_helper()
369 * however, this function will use the specified function @func to obtain the
370 * data needed by the typefind functions, rather than operating on a given
371 * source pad. This is useful mostly for elements like tag demuxers which
372 * strip off data at the beginning and/or end of a file and want to typefind
373 * the stripped data stream before adding their own source pad (the specified
374 * callback can then call the upstream peer pad with offsets adjusted for the
375 * tag size, for example).
377 * Free-function: gst_caps_unref
379 * Returns: (transfer full): the #GstCaps corresponding to the data stream.
380 * Returns #NULL if no #GstCaps matches the data stream.
383 gst_type_find_helper_get_range (GstObject * obj,
384 GstTypeFindHelperGetRangeFunction func, guint64 size,
385 GstTypeFindProbability * prob)
387 return gst_type_find_helper_get_range_ext (obj, func, size, NULL, prob);
391 * gst_type_find_helper:
392 * @src: A source #GstPad
393 * @size: The length in bytes
395 * Tries to find what type of data is flowing from the given source #GstPad.
397 * Free-function: gst_caps_unref
399 * Returns: (transfer full): the #GstCaps corresponding to the data stream.
400 * Returns #NULL if no #GstCaps matches the data stream.
404 gst_type_find_helper (GstPad * src, guint64 size)
406 GstTypeFindHelperGetRangeFunction func;
408 g_return_val_if_fail (GST_IS_OBJECT (src), NULL);
409 g_return_val_if_fail (GST_PAD_GETRANGEFUNC (src) != NULL, NULL);
411 func = (GstTypeFindHelperGetRangeFunction) (GST_PAD_GETRANGEFUNC (src));
413 return gst_type_find_helper_get_range (GST_OBJECT (src), func, size, NULL);
416 /* ********************** typefinding for buffers ************************* */
420 const guint8 *data; /* buffer data */
422 GstTypeFindProbability best_probability;
424 GstTypeFindFactory *factory; /* for logging */
425 GstObject *obj; /* for logging */
426 } GstTypeFindBufHelper;
429 * buf_helper_find_peek:
430 * @data: helper data struct
431 * @off: stream offset
434 * Get data pointer within a buffer.
436 * Returns: address inside the buffer or %NULL if buffer does not cover the
439 static const guint8 *
440 buf_helper_find_peek (gpointer data, gint64 off, guint size)
442 GstTypeFindBufHelper *helper;
444 helper = (GstTypeFindBufHelper *) data;
445 GST_LOG_OBJECT (helper->obj, "'%s' called peek (%" G_GINT64_FORMAT ", %u)",
446 GST_OBJECT_NAME (helper->factory), off, size);
452 GST_LOG_OBJECT (helper->obj, "'%s' wanted to peek at end; not supported",
453 GST_OBJECT_NAME (helper->factory));
457 if ((off + size) <= helper->size)
458 return helper->data + off;
464 * buf_helper_find_suggest:
465 * @data: helper data struct
466 * @probability: probability of the match
467 * @caps: caps of the type
469 * If given @probability is higher, replace previously store caps.
472 buf_helper_find_suggest (gpointer data, GstTypeFindProbability probability,
473 const GstCaps * caps)
475 GstTypeFindBufHelper *helper = (GstTypeFindBufHelper *) data;
477 GST_LOG_OBJECT (helper->obj,
478 "'%s' called suggest (%u, %" GST_PTR_FORMAT ")",
479 GST_OBJECT_NAME (helper->factory), probability, caps);
481 /* Note: not >= as we call typefinders in order of rank, highest first */
482 if (probability > helper->best_probability) {
483 GstCaps *copy = gst_caps_copy (caps);
485 gst_caps_replace (&helper->caps, copy);
486 gst_caps_unref (copy);
487 helper->best_probability = probability;
492 * gst_type_find_helper_for_data:
493 * @obj: object doing the typefinding, or NULL (used for logging)
494 * @data: (in) (transfer none): a pointer with data to typefind
495 * @size: (in) (transfer none): the size of @data
496 * @prob: (out) (allow-none): location to store the probability of the found
499 * Tries to find what type of data is contained in the given @data, the
500 * assumption being that the data represents the beginning of the stream or
503 * All available typefinders will be called on the data in order of rank. If
504 * a typefinding function returns a probability of #GST_TYPE_FIND_MAXIMUM,
505 * typefinding is stopped immediately and the found caps will be returned
506 * right away. Otherwise, all available typefind functions will the tried,
507 * and the caps with the highest probability will be returned, or #NULL if
508 * the content of @data could not be identified.
510 * Free-function: gst_caps_unref
512 * Returns: (transfer full): the #GstCaps corresponding to the data, or #NULL
513 * if no type could be found. The caller should free the caps returned
514 * with gst_caps_unref().
517 gst_type_find_helper_for_data (GstObject * obj, const guint8 * data, gsize size,
518 GstTypeFindProbability * prob)
520 GstTypeFindBufHelper helper;
522 GList *l, *type_list;
523 GstCaps *result = NULL;
525 g_return_val_if_fail (data != NULL, NULL);
529 helper.best_probability = GST_TYPE_FIND_NONE;
533 if (helper.data == NULL || helper.size == 0)
537 find.peek = buf_helper_find_peek;
538 find.suggest = buf_helper_find_suggest;
539 find.get_length = NULL;
541 type_list = gst_type_find_factory_get_list ();
543 for (l = type_list; l; l = l->next) {
544 helper.factory = GST_TYPE_FIND_FACTORY (l->data);
545 gst_type_find_factory_call_function (helper.factory, &find);
546 if (helper.best_probability >= GST_TYPE_FIND_MAXIMUM)
549 gst_plugin_feature_list_free (type_list);
551 if (helper.best_probability > 0)
552 result = helper.caps;
555 *prob = helper.best_probability;
557 GST_LOG_OBJECT (obj, "Returning %" GST_PTR_FORMAT " (probability = %u)",
558 result, (guint) helper.best_probability);
564 * gst_type_find_helper_for_buffer:
565 * @obj: object doing the typefinding, or NULL (used for logging)
566 * @buf: (in) (transfer none): a #GstBuffer with data to typefind
567 * @prob: (out) (allow-none): location to store the probability of the found
570 * Tries to find what type of data is contained in the given #GstBuffer, the
571 * assumption being that the buffer represents the beginning of the stream or
574 * All available typefinders will be called on the data in order of rank. If
575 * a typefinding function returns a probability of #GST_TYPE_FIND_MAXIMUM,
576 * typefinding is stopped immediately and the found caps will be returned
577 * right away. Otherwise, all available typefind functions will the tried,
578 * and the caps with the highest probability will be returned, or #NULL if
579 * the content of the buffer could not be identified.
581 * Free-function: gst_caps_unref
583 * Returns: (transfer full): the #GstCaps corresponding to the data, or #NULL
584 * if no type could be found. The caller should free the caps returned
585 * with gst_caps_unref().
588 gst_type_find_helper_for_buffer (GstObject * obj, GstBuffer * buf,
589 GstTypeFindProbability * prob)
595 g_return_val_if_fail (buf != NULL, NULL);
596 g_return_val_if_fail (GST_IS_BUFFER (buf), NULL);
597 g_return_val_if_fail (GST_BUFFER_OFFSET (buf) == 0 ||
598 GST_BUFFER_OFFSET (buf) == GST_BUFFER_OFFSET_NONE, NULL);
600 data = gst_buffer_map (buf, &size, NULL, GST_MAP_READ);
601 result = gst_type_find_helper_for_data (obj, data, size, prob);
602 gst_buffer_unmap (buf, data, size);
608 * gst_type_find_helper_for_extension:
609 * @obj: (allow-none): object doing the typefinding, or NULL (used for logging)
610 * @extension: an extension
612 * Tries to find the best #GstCaps associated with @extension.
614 * All available typefinders will be checked against the extension in order
615 * of rank. The caps of the first typefinder that can handle @extension will be
618 * Free-function: gst_caps_unref
620 * Returns: (transfer full): the #GstCaps corresponding to @extension, or
621 * #NULL if no type could be found. The caller should free the caps
622 * returned with gst_caps_unref().
627 gst_type_find_helper_for_extension (GstObject * obj, const gchar * extension)
629 GList *l, *type_list;
630 GstCaps *result = NULL;
632 g_return_val_if_fail (extension != NULL, NULL);
634 GST_LOG_OBJECT (obj, "finding caps for extension %s", extension);
636 type_list = gst_type_find_factory_get_list ();
638 for (l = type_list; l; l = g_list_next (l)) {
639 GstTypeFindFactory *factory;
643 factory = GST_TYPE_FIND_FACTORY (l->data);
645 /* we only want to check those factories without a function */
646 if (factory->function != NULL)
649 /* get the extension that this typefind factory can handle */
650 ext = gst_type_find_factory_get_extensions (factory);
654 /* there are extension, see if one of them matches the requested
656 for (i = 0; ext[i]; i++) {
657 if (strcmp (ext[i], extension) == 0) {
658 /* we found a matching extension, take the caps */
659 if ((result = gst_type_find_factory_get_caps (factory))) {
660 gst_caps_ref (result);
667 gst_plugin_feature_list_free (type_list);
669 GST_LOG_OBJECT (obj, "Returning %" GST_PTR_FORMAT, result);