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., 51 Franklin St, Fifth Floor,
21 * Boston, MA 02110-1301, USA.
25 * SECTION:gsttypefindhelper
26 * @title: GstTypeFindHelper
27 * @short_description: Utility functions for typefinding
29 * Utility functions for elements doing typefinding:
30 * gst_type_find_helper() does typefinding in pull mode, while
31 * gst_type_find_helper_for_buffer() is useful for elements needing to do
32 * typefinding in push mode from a chain function.
42 #include "gsttypefindhelper.h"
44 /* ********************** typefinding in pull mode ************************ */
47 helper_find_suggest (gpointer data, guint probability, GstCaps * caps);
57 GSList *buffers; /* buffer cache */
60 GstTypeFindHelperGetRangeFunction func;
61 GstTypeFindProbability best_probability;
63 GstTypeFindFactory *factory; /* for logging */
64 GstObject *obj; /* for logging */
70 * @data: helper data struct
74 * Get data pointer within a stream. Keeps a cache of read buffers (partly
75 * for performance reasons, but mostly because pointers returned by us need
76 * to stay valid until typefinding has finished)
78 * Returns: (nullable): address of the data or %NULL if buffer does not cover
79 * the requested range.
82 helper_find_peek (gpointer data, gint64 offset, guint size)
84 GstTypeFindHelper *helper;
87 GSList *insert_pos = NULL;
90 GstMappedBuffer *bmap;
95 helper = (GstTypeFindHelper *) data;
97 GST_LOG_OBJECT (helper->obj, "'%s' called peek (%" G_GINT64_FORMAT
98 ", %u)", GST_OBJECT_NAME (helper->factory), offset, size);
104 if (helper->size == -1 || helper->size < -offset)
107 offset += helper->size;
110 /* see if we have a matching buffer already in our list */
111 if (size > 0 && offset <= helper->last_offset) {
114 for (walk = helper->buffers; walk; walk = walk->next) {
115 GstMappedBuffer *bmp = (GstMappedBuffer *) walk->data;
116 GstBuffer *buf = GST_BUFFER_CAST (bmp->buffer);
118 buf_offset = GST_BUFFER_OFFSET (buf);
119 buf_size = bmp->map.size;
121 /* buffers are kept sorted by end offset (highest first) in the list, so
122 * at this point we save the current position and stop searching if
123 * we're after the searched end offset */
124 if (buf_offset <= offset) {
125 if ((offset + size) < (buf_offset + buf_size)) {
126 /* must already have been mapped before */
127 return (guint8 *) bmp->map.data + (offset - buf_offset);
129 } else if (offset + size >= buf_offset + buf_size) {
137 /* some typefinders go in 1 byte steps over 1k of data and request
138 * small buffers. It is really inefficient to pull each time, and pulling
139 * a larger chunk is almost free. Trying to pull a larger chunk at the end
140 * of the file is also not a problem here, we'll just get a truncated buffer
141 * in that case (and we'll have to double-check the size we actually get
142 * anyway, see below) */
144 helper->func (helper->obj, helper->parent, offset, MAX (size, 4096),
147 if (ret != GST_FLOW_OK)
151 caps = GST_BUFFER_CAPS (buffer);
153 if (caps && !gst_caps_is_empty (caps) && !gst_caps_is_any (caps)) {
154 GST_DEBUG ("buffer has caps %" GST_PTR_FORMAT ", suggest max probability",
157 gst_caps_replace (&helper->caps, caps);
158 helper->best_probability = GST_TYPE_FIND_MAXIMUM;
160 gst_buffer_unref (buffer);
165 /* getrange might silently return shortened buffers at the end of a file,
166 * we must, however, always return either the full requested data or %NULL */
167 buf_offset = GST_BUFFER_OFFSET (buffer);
168 buf_size = gst_buffer_get_size (buffer);
170 if (buf_size < size) {
171 GST_DEBUG ("dropping short buffer of size %" G_GSIZE_FORMAT ","
172 "requested size was %u", buf_size, size);
173 gst_buffer_unref (buffer);
177 if (buf_offset != -1 && buf_offset != offset) {
178 GST_DEBUG ("dropping buffer with unexpected offset %" G_GUINT64_FORMAT ", "
179 "expected offset was %" G_GUINT64_FORMAT, buf_offset, offset);
180 gst_buffer_unref (buffer);
184 bmap = g_slice_new0 (GstMappedBuffer);
186 if (!gst_buffer_map (buffer, &bmap->map, GST_MAP_READ))
189 bmap->buffer = buffer;
192 helper->buffers = g_slist_insert_before (helper->buffers, insert_pos, bmap);
194 /* if insert_pos is not set, our offset is bigger than the largest offset
195 * we have so far; since we keep the list sorted with highest offsets
196 * first, we need to prepend the buffer to the list */
197 helper->last_offset = GST_BUFFER_OFFSET (buffer) + buf_size;
198 helper->buffers = g_slist_prepend (helper->buffers, bmap);
201 return bmap->map.data;
205 GST_INFO ("typefind function returned: %s", gst_flow_get_name (ret));
210 GST_ERROR ("map failed");
211 gst_buffer_unref (buffer);
212 g_slice_free (GstMappedBuffer, bmap);
218 * helper_find_suggest:
219 * @data: helper data struct
220 * @probability: probability of the match
221 * @caps: caps of the type
223 * If given @probability is higher, replace previously store caps.
226 helper_find_suggest (gpointer data, guint probability, GstCaps * caps)
228 GstTypeFindHelper *helper = (GstTypeFindHelper *) data;
230 GST_LOG_OBJECT (helper->obj,
231 "'%s' called suggest (%u, %" GST_PTR_FORMAT ")",
232 GST_OBJECT_NAME (helper->factory), probability, caps);
234 if (probability > helper->best_probability) {
235 gst_caps_replace (&helper->caps, caps);
236 helper->best_probability = probability;
241 helper_find_get_length (gpointer data)
243 GstTypeFindHelper *helper = (GstTypeFindHelper *) data;
245 GST_LOG_OBJECT (helper->obj, "'%s' called get_length, returning %"
246 G_GUINT64_FORMAT, GST_OBJECT_NAME (helper->factory), helper->size);
252 * gst_type_find_helper_get_range:
253 * @obj: A #GstObject that will be passed as first argument to @func
254 * @parent: (allow-none): the parent of @obj or %NULL
255 * @func: (scope call): A generic #GstTypeFindHelperGetRangeFunction that will
256 * be used to access data at random offsets when doing the typefinding
257 * @size: The length in bytes
258 * @extension: extension of the media
259 * @prob: (out) (allow-none): location to store the probability of the found
262 * Utility function to do pull-based typefinding. Unlike gst_type_find_helper()
263 * however, this function will use the specified function @func to obtain the
264 * data needed by the typefind functions, rather than operating on a given
265 * source pad. This is useful mostly for elements like tag demuxers which
266 * strip off data at the beginning and/or end of a file and want to typefind
267 * the stripped data stream before adding their own source pad (the specified
268 * callback can then call the upstream peer pad with offsets adjusted for the
269 * tag size, for example).
271 * When @extension is not %NULL, this function will first try the typefind
272 * functions for the given extension, which might speed up the typefinding
275 * Free-function: gst_caps_unref
277 * Returns: (transfer full) (nullable): the #GstCaps corresponding to the data
278 * stream. Returns %NULL if no #GstCaps matches the data stream.
281 gst_type_find_helper_get_range (GstObject * obj, GstObject * parent,
282 GstTypeFindHelperGetRangeFunction func, guint64 size,
283 const gchar * extension, GstTypeFindProbability * prob)
285 GstTypeFindHelper helper;
288 GList *l, *type_list;
289 GstCaps *result = NULL;
292 g_return_val_if_fail (GST_IS_OBJECT (obj), NULL);
293 g_return_val_if_fail (func != NULL, NULL);
295 helper.buffers = NULL;
297 helper.last_offset = 0;
299 helper.best_probability = GST_TYPE_FIND_NONE;
302 helper.parent = parent;
305 find.peek = helper_find_peek;
306 find.suggest = helper_find_suggest;
308 if (size == 0 || size == (guint64) - 1) {
309 find.get_length = NULL;
311 find.get_length = helper_find_get_length;
314 type_list = gst_type_find_factory_get_list ();
316 /* move the typefinders for the extension first in the list. The idea is that
317 * when one of them returns MAX we don't need to search further as there is a
318 * very high chance we got the right type. */
322 GST_LOG_OBJECT (obj, "sorting typefind for extension %s to head",
325 for (l = type_list; l; l = next) {
326 const gchar *const *ext;
327 GstTypeFindFactory *factory;
331 factory = GST_TYPE_FIND_FACTORY (l->data);
333 ext = gst_type_find_factory_get_extensions (factory);
337 GST_LOG_OBJECT (obj, "testing factory %s for extension %s",
338 GST_OBJECT_NAME (factory), extension);
340 while (*ext != NULL) {
341 if (strcmp (*ext, extension) == 0) {
342 /* found extension, move in front */
343 GST_LOG_OBJECT (obj, "moving typefind for extension %s to head",
345 /* remove entry from list */
346 type_list = g_list_delete_link (type_list, l);
347 /* insert at the position */
348 type_list = g_list_insert (type_list, factory, pos);
349 /* next element will be inserted after this one */
358 for (l = type_list; l; l = l->next) {
359 helper.factory = GST_TYPE_FIND_FACTORY (l->data);
360 gst_type_find_factory_call_function (helper.factory, &find);
361 if (helper.best_probability >= GST_TYPE_FIND_MAXIMUM)
364 gst_plugin_feature_list_free (type_list);
366 for (walk = helper.buffers; walk; walk = walk->next) {
367 GstMappedBuffer *bmap = (GstMappedBuffer *) walk->data;
369 gst_buffer_unmap (bmap->buffer, &bmap->map);
370 gst_buffer_unref (bmap->buffer);
371 g_slice_free (GstMappedBuffer, bmap);
373 g_slist_free (helper.buffers);
375 if (helper.best_probability > 0)
376 result = helper.caps;
379 *prob = helper.best_probability;
381 GST_LOG_OBJECT (obj, "Returning %" GST_PTR_FORMAT " (probability = %u)",
382 result, (guint) helper.best_probability);
388 * gst_type_find_helper:
389 * @src: A source #GstPad
390 * @size: The length in bytes
392 * Tries to find what type of data is flowing from the given source #GstPad.
394 * Free-function: gst_caps_unref
396 * Returns: (transfer full) (nullable): the #GstCaps corresponding to the data
397 * stream. Returns %NULL if no #GstCaps matches the data stream.
401 gst_type_find_helper (GstPad * src, guint64 size)
403 GstTypeFindHelperGetRangeFunction func;
405 g_return_val_if_fail (GST_IS_OBJECT (src), NULL);
406 g_return_val_if_fail (GST_PAD_GETRANGEFUNC (src) != NULL, NULL);
408 func = (GstTypeFindHelperGetRangeFunction) (GST_PAD_GETRANGEFUNC (src));
410 return gst_type_find_helper_get_range (GST_OBJECT (src),
411 GST_OBJECT_PARENT (src), func, size, NULL, NULL);
414 /* ********************** typefinding for buffers ************************* */
418 const guint8 *data; /* buffer data */
420 GstTypeFindProbability best_probability;
422 GstTypeFindFactory *factory; /* for logging */
423 GstObject *obj; /* for logging */
424 } GstTypeFindBufHelper;
427 * buf_helper_find_peek:
428 * @data: helper data struct
429 * @off: stream offset
432 * Get data pointer within a buffer.
434 * Returns: (nullable): address inside the buffer or %NULL if buffer does not
435 * cover the requested range.
437 static const guint8 *
438 buf_helper_find_peek (gpointer data, gint64 off, guint size)
440 GstTypeFindBufHelper *helper;
442 helper = (GstTypeFindBufHelper *) data;
443 GST_LOG_OBJECT (helper->obj, "'%s' called peek (%" G_GINT64_FORMAT ", %u)",
444 GST_OBJECT_NAME (helper->factory), off, size);
450 GST_LOG_OBJECT (helper->obj, "'%s' wanted to peek at end; not supported",
451 GST_OBJECT_NAME (helper->factory));
455 /* If we request beyond the available size, we're sure we can't return
456 * anything regardless of the requested offset */
457 if (size > helper->size)
460 /* Only return data if there's enough room left for the given offset.
461 * This is the same as "if (off + size <= helper->size)" except that
462 * it doesn't exceed type limits */
463 if (off <= helper->size - size)
464 return helper->data + off;
470 * buf_helper_find_suggest:
471 * @data: helper data struct
472 * @probability: probability of the match
473 * @caps: caps of the type
475 * If given @probability is higher, replace previously store caps.
478 buf_helper_find_suggest (gpointer data, guint probability, GstCaps * caps)
480 GstTypeFindBufHelper *helper = (GstTypeFindBufHelper *) data;
482 GST_LOG_OBJECT (helper->obj,
483 "'%s' called suggest (%u, %" GST_PTR_FORMAT ")",
484 GST_OBJECT_NAME (helper->factory), probability, caps);
486 /* Note: not >= as we call typefinders in order of rank, highest first */
487 if (probability > helper->best_probability) {
488 gst_caps_replace (&helper->caps, caps);
489 helper->best_probability = probability;
494 * gst_type_find_helper_for_data:
495 * @obj: (allow-none): object doing the typefinding, or %NULL (used for logging)
496 * @data: (in) (transfer none): a pointer with data to typefind
497 * @size: (in): the size of @data
498 * @prob: (out) (allow-none): location to store the probability of the found
501 * Tries to find what type of data is contained in the given @data, the
502 * assumption being that the data represents the beginning of the stream or
505 * All available typefinders will be called on the data in order of rank. If
506 * a typefinding function returns a probability of %GST_TYPE_FIND_MAXIMUM,
507 * typefinding is stopped immediately and the found caps will be returned
508 * right away. Otherwise, all available typefind functions will the tried,
509 * and the caps with the highest probability will be returned, or %NULL if
510 * the content of @data could not be identified.
512 * Free-function: gst_caps_unref
514 * Returns: (transfer full) (nullable): the #GstCaps corresponding to the data,
515 * or %NULL if no type could be found. The caller should free the caps
516 * returned with gst_caps_unref().
519 gst_type_find_helper_for_data (GstObject * obj, const guint8 * data, gsize size,
520 GstTypeFindProbability * prob)
522 GstTypeFindBufHelper helper;
524 GList *l, *type_list;
525 GstCaps *result = NULL;
527 g_return_val_if_fail (data != NULL, NULL);
531 helper.best_probability = GST_TYPE_FIND_NONE;
535 if (helper.data == NULL || helper.size == 0)
539 find.peek = buf_helper_find_peek;
540 find.suggest = buf_helper_find_suggest;
541 find.get_length = NULL;
543 type_list = gst_type_find_factory_get_list ();
545 for (l = type_list; l; l = l->next) {
546 helper.factory = GST_TYPE_FIND_FACTORY (l->data);
547 gst_type_find_factory_call_function (helper.factory, &find);
548 if (helper.best_probability >= GST_TYPE_FIND_MAXIMUM)
551 gst_plugin_feature_list_free (type_list);
553 if (helper.best_probability > 0)
554 result = helper.caps;
557 *prob = helper.best_probability;
559 GST_LOG_OBJECT (obj, "Returning %" GST_PTR_FORMAT " (probability = %u)",
560 result, (guint) helper.best_probability);
566 * gst_type_find_helper_for_buffer:
567 * @obj: (allow-none): object doing the typefinding, or %NULL (used for logging)
568 * @buf: (in) (transfer none): a #GstBuffer with data to typefind
569 * @prob: (out) (allow-none): location to store the probability of the found
572 * Tries to find what type of data is contained in the given #GstBuffer, the
573 * assumption being that the buffer represents the beginning of the stream or
576 * All available typefinders will be called on the data in order of rank. If
577 * a typefinding function returns a probability of %GST_TYPE_FIND_MAXIMUM,
578 * typefinding is stopped immediately and the found caps will be returned
579 * right away. Otherwise, all available typefind functions will the tried,
580 * and the caps with the highest probability will be returned, or %NULL if
581 * the content of the buffer could not be identified.
583 * Free-function: gst_caps_unref
585 * Returns: (transfer full) (nullable): the #GstCaps corresponding to the data,
586 * or %NULL if no type could be found. The caller should free the caps
587 * returned with gst_caps_unref().
590 gst_type_find_helper_for_buffer (GstObject * obj, GstBuffer * buf,
591 GstTypeFindProbability * prob)
596 g_return_val_if_fail (buf != NULL, NULL);
597 g_return_val_if_fail (GST_IS_BUFFER (buf), NULL);
598 g_return_val_if_fail (GST_BUFFER_OFFSET (buf) == 0 ||
599 GST_BUFFER_OFFSET (buf) == GST_BUFFER_OFFSET_NONE, NULL);
601 if (!gst_buffer_map (buf, &info, GST_MAP_READ))
603 result = gst_type_find_helper_for_data (obj, info.data, info.size, prob);
604 gst_buffer_unmap (buf, &info);
610 * gst_type_find_helper_for_extension:
611 * @obj: (allow-none): object doing the typefinding, or %NULL (used for logging)
612 * @extension: an extension
614 * Tries to find the best #GstCaps associated with @extension.
616 * All available typefinders will be checked against the extension in order
617 * of rank. The caps of the first typefinder that can handle @extension will be
620 * Free-function: gst_caps_unref
622 * Returns: (transfer full) (nullable): the #GstCaps corresponding to
623 * @extension, or %NULL if no type could be found. The caller should free
624 * the caps 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;
640 const gchar *const *ext;
642 factory = GST_TYPE_FIND_FACTORY (l->data);
644 /* we only want to check those factories without a function */
645 if (gst_type_find_factory_has_function (factory))
648 /* get the extension that this typefind factory can handle */
649 ext = gst_type_find_factory_get_extensions (factory);
653 /* there are extension, see if one of them matches the requested
655 while (*ext != NULL) {
656 if (strcmp (*ext, extension) == 0) {
657 /* we found a matching extension, take the caps */
658 if ((result = gst_type_find_factory_get_caps (factory))) {
659 gst_caps_ref (result);
667 gst_plugin_feature_list_free (type_list);
669 GST_LOG_OBJECT (obj, "Returning %" GST_PTR_FORMAT, result);