05f4bd5e703f6525cc223823d6805a2cfbc72d60
1 /* GStreamer
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>
5 *
6 * gsttypefindhelper.c:
7 *
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.
12 *
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.
17 *
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.
22 */
24 /**
25 * SECTION:gsttypefindhelper
26 * @short_description: Utility functions for typefinding
27 *
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.
32 */
34 #ifdef HAVE_CONFIG_H
35 # include "config.h"
36 #endif
38 #include <stdlib.h>
39 #include <string.h>
41 #include "gsttypefindhelper.h"
43 /* ********************** typefinding in pull mode ************************ */
45 static void
46 helper_find_suggest (gpointer data, guint probability, const GstCaps * caps);
48 typedef struct
49 {
50 GSList *buffers; /* buffer cache */
51 guint64 size;
52 guint64 last_offset;
53 GstTypeFindHelperGetRangeFunction func;
54 GstTypeFindProbability best_probability;
55 GstCaps *caps;
56 GstTypeFindFactory *factory; /* for logging */
57 GstObject *obj; /* for logging */
58 } GstTypeFindHelper;
60 /*
61 * helper_find_peek:
62 * @data: helper data struct
63 * @off: stream offset
64 * @size: block size
65 *
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)
69 *
70 * Returns: address of the data or %NULL if buffer does not cover the
71 * requested range.
72 */
73 static guint8 *
74 helper_find_peek (gpointer data, gint64 offset, guint size)
75 {
76 GstTypeFindHelper *helper;
77 GstBuffer *buffer;
78 GstFlowReturn ret;
79 GSList *insert_pos = NULL;
80 guint buf_size;
81 guint64 buf_offset;
82 GstCaps *caps;
84 helper = (GstTypeFindHelper *) data;
86 GST_LOG_OBJECT (helper->obj, "'%s' called peek (%" G_GINT64_FORMAT
87 ", %u)", GST_PLUGIN_FEATURE_NAME (helper->factory), offset, size);
89 if (size == 0)
90 return NULL;
92 if (offset < 0) {
93 if (helper->size == -1 || helper->size < -offset)
94 return NULL;
96 offset += helper->size;
97 }
99 /* see if we have a matching buffer already in our list */
100 if (size > 0 && offset <= helper->last_offset) {
101 GSList *walk;
103 for (walk = helper->buffers; walk; walk = walk->next) {
104 GstBuffer *buf = GST_BUFFER_CAST (walk->data);
105 guint64 buf_offset = GST_BUFFER_OFFSET (buf);
106 guint buf_size = GST_BUFFER_SIZE (buf);
108 /* buffers are kept sorted by end offset (highest first) in the list, so
109 * at this point we save the current position and stop searching if
110 * we're after the searched end offset */
111 if (buf_offset <= offset) {
112 if ((offset + size) < (buf_offset + buf_size)) {
113 return GST_BUFFER_DATA (buf) + (offset - buf_offset);
114 }
115 } else if (offset + size >= buf_offset + buf_size) {
116 insert_pos = walk;
117 break;
118 }
119 }
120 }
122 buffer = NULL;
123 /* some typefinders go in 1 byte steps over 1k of data and request
124 * small buffers. It is really inefficient to pull each time, and pulling
125 * a larger chunk is almost free. Trying to pull a larger chunk at the end
126 * of the file is also not a problem here, we'll just get a truncated buffer
127 * in that case (and we'll have to double-check the size we actually get
128 * anyway, see below) */
129 ret = helper->func (helper->obj, offset, MAX (size, 4096), &buffer);
131 if (ret != GST_FLOW_OK)
132 goto error;
134 caps = GST_BUFFER_CAPS (buffer);
136 if (caps && !gst_caps_is_empty (caps) && !gst_caps_is_any (caps)) {
137 GST_DEBUG ("buffer has caps %" GST_PTR_FORMAT ", suggest max probability",
138 caps);
140 gst_caps_replace (&helper->caps, caps);
141 helper->best_probability = GST_TYPE_FIND_MAXIMUM;
143 gst_buffer_unref (buffer);
144 return NULL;
145 }
147 /* getrange might silently return shortened buffers at the end of a file,
148 * we must, however, always return either the full requested data or NULL */
149 buf_offset = GST_BUFFER_OFFSET (buffer);
150 buf_size = GST_BUFFER_SIZE (buffer);
152 if ((buf_offset != -1 && buf_offset != offset) || buf_size < size) {
153 GST_DEBUG ("droping short buffer: %" G_GUINT64_FORMAT "-%" G_GUINT64_FORMAT
154 " instead of %" G_GUINT64_FORMAT "-%" G_GUINT64_FORMAT,
155 buf_offset, buf_offset + buf_size - 1, offset, offset + size - 1);
156 gst_buffer_unref (buffer);
157 return NULL;
158 }
160 if (insert_pos) {
161 helper->buffers =
162 g_slist_insert_before (helper->buffers, insert_pos, buffer);
163 } else {
164 /* if insert_pos is not set, our offset is bigger than the largest offset
165 * we have so far; since we keep the list sorted with highest offsets
166 * first, we need to prepend the buffer to the list */
167 helper->last_offset = GST_BUFFER_OFFSET (buffer) + GST_BUFFER_SIZE (buffer);
168 helper->buffers = g_slist_prepend (helper->buffers, buffer);
169 }
170 return GST_BUFFER_DATA (buffer);
172 error:
173 {
174 GST_INFO ("typefind function returned: %s", gst_flow_get_name (ret));
175 return NULL;
176 }
177 }
179 /*
180 * helper_find_suggest:
181 * @data: helper data struct
182 * @probability: probability of the match
183 * @caps: caps of the type
184 *
185 * If given @probability is higher, replace previously store caps.
186 */
187 static void
188 helper_find_suggest (gpointer data, GstTypeFindProbability probability,
189 const GstCaps * caps)
190 {
191 GstTypeFindHelper *helper = (GstTypeFindHelper *) data;
193 GST_LOG_OBJECT (helper->obj,
194 "'%s' called called suggest (%u, %" GST_PTR_FORMAT ")",
195 GST_PLUGIN_FEATURE_NAME (helper->factory), probability, caps);
197 if (probability > helper->best_probability) {
198 GstCaps *copy = gst_caps_copy (caps);
200 gst_caps_replace (&helper->caps, copy);
201 gst_caps_unref (copy);
202 helper->best_probability = probability;
203 }
204 }
206 static guint64
207 helper_find_get_length (gpointer data)
208 {
209 GstTypeFindHelper *helper = (GstTypeFindHelper *) data;
211 GST_LOG_OBJECT (helper->obj, "'%s' called called get_length, returning %"
212 G_GUINT64_FORMAT, GST_PLUGIN_FEATURE_NAME (helper->factory),
213 helper->size);
215 return helper->size;
216 }
218 /**
219 * gst_type_find_helper_get_range_ext:
220 * @obj: A #GstObject that will be passed as first argument to @func
221 * @func: (scope call): A generic #GstTypeFindHelperGetRangeFunction that will
222 * be used to access data at random offsets when doing the typefinding
223 * @size: The length in bytes
224 * @extension: extension of the media
225 * @prob: (out) (allow-none): location to store the probability of the found
226 * caps, or #NULL
227 *
228 * Utility function to do pull-based typefinding. Unlike gst_type_find_helper()
229 * however, this function will use the specified function @func to obtain the
230 * data needed by the typefind functions, rather than operating on a given
231 * source pad. This is useful mostly for elements like tag demuxers which
232 * strip off data at the beginning and/or end of a file and want to typefind
233 * the stripped data stream before adding their own source pad (the specified
234 * callback can then call the upstream peer pad with offsets adjusted for the
235 * tag size, for example).
236 *
237 * When @extension is not NULL, this function will first try the typefind
238 * functions for the given extension, which might speed up the typefinding
239 * in many cases.
240 *
241 * Free-function: gst_caps_unref
242 *
243 * Returns: (transfer full): the #GstCaps corresponding to the data stream.
244 * Returns #NULL if no #GstCaps matches the data stream.
245 *
246 * Since: 0.10.26
247 */
248 GstCaps *
249 gst_type_find_helper_get_range_ext (GstObject * obj,
250 GstTypeFindHelperGetRangeFunction func, guint64 size,
251 const gchar * extension, GstTypeFindProbability * prob)
252 {
253 GstTypeFindHelper helper;
254 GstTypeFind find;
255 GSList *walk;
256 GList *l, *type_list;
257 GstCaps *result = NULL;
258 gint pos = 0;
260 g_return_val_if_fail (GST_IS_OBJECT (obj), NULL);
261 g_return_val_if_fail (func != NULL, NULL);
263 helper.buffers = NULL;
264 helper.size = size;
265 helper.last_offset = 0;
266 helper.func = func;
267 helper.best_probability = GST_TYPE_FIND_NONE;
268 helper.caps = NULL;
269 helper.obj = obj;
271 find.data = &helper;
272 find.peek = helper_find_peek;
273 find.suggest = helper_find_suggest;
275 if (size == 0 || size == (guint64) - 1) {
276 find.get_length = NULL;
277 } else {
278 find.get_length = helper_find_get_length;
279 }
281 type_list = gst_type_find_factory_get_list ();
283 /* move the typefinders for the extension first in the list. The idea is that
284 * when one of them returns MAX we don't need to search further as there is a
285 * very high chance we got the right type. */
286 if (extension) {
287 GList *next;
289 GST_LOG_OBJECT (obj, "sorting typefind for extension %s to head",
290 extension);
292 for (l = type_list; l; l = next) {
293 GstTypeFindFactory *factory;
294 gint i;
295 gchar **ext;
297 next = l->next;
299 factory = GST_TYPE_FIND_FACTORY (l->data);
301 ext = gst_type_find_factory_get_extensions (factory);
302 if (ext == NULL)
303 continue;
305 GST_LOG_OBJECT (obj, "testing factory %s for extension %s",
306 GST_PLUGIN_FEATURE_NAME (factory), extension);
308 for (i = 0; ext[i]; i++) {
309 if (strcmp (ext[i], extension) == 0) {
310 /* found extension, move in front */
311 GST_LOG_OBJECT (obj, "moving typefind for extension %s to head",
312 extension);
313 /* remove entry from list */
314 type_list = g_list_delete_link (type_list, l);
315 /* insert at the position */
316 type_list = g_list_insert (type_list, factory, pos);
317 /* next element will be inserted after this one */
318 pos++;
319 break;
320 }
321 }
322 }
323 }
325 for (l = type_list; l; l = l->next) {
326 helper.factory = GST_TYPE_FIND_FACTORY (l->data);
327 gst_type_find_factory_call_function (helper.factory, &find);
328 if (helper.best_probability >= GST_TYPE_FIND_MAXIMUM)
329 break;
330 }
331 gst_plugin_feature_list_free (type_list);
333 for (walk = helper.buffers; walk; walk = walk->next)
334 gst_buffer_unref (GST_BUFFER_CAST (walk->data));
335 g_slist_free (helper.buffers);
337 if (helper.best_probability > 0)
338 result = helper.caps;
340 if (prob)
341 *prob = helper.best_probability;
343 GST_LOG_OBJECT (obj, "Returning %" GST_PTR_FORMAT " (probability = %u)",
344 result, (guint) helper.best_probability);
346 return result;
347 }
349 /**
350 * gst_type_find_helper_get_range:
351 * @obj: A #GstObject that will be passed as first argument to @func
352 * @func: (scope call): A generic #GstTypeFindHelperGetRangeFunction that will
353 * be used to access data at random offsets when doing the typefinding
354 * @size: The length in bytes
355 * @prob: (out) (allow-none): location to store the probability of the found
356 * caps, or #NULL
357 *
358 * Utility function to do pull-based typefinding. Unlike gst_type_find_helper()
359 * however, this function will use the specified function @func to obtain the
360 * data needed by the typefind functions, rather than operating on a given
361 * source pad. This is useful mostly for elements like tag demuxers which
362 * strip off data at the beginning and/or end of a file and want to typefind
363 * the stripped data stream before adding their own source pad (the specified
364 * callback can then call the upstream peer pad with offsets adjusted for the
365 * tag size, for example).
366 *
367 * Free-function: gst_caps_unref
368 *
369 * Returns: (transfer full): the #GstCaps corresponding to the data stream.
370 * Returns #NULL if no #GstCaps matches the data stream.
371 */
372 GstCaps *
373 gst_type_find_helper_get_range (GstObject * obj,
374 GstTypeFindHelperGetRangeFunction func, guint64 size,
375 GstTypeFindProbability * prob)
376 {
377 return gst_type_find_helper_get_range_ext (obj, func, size, NULL, prob);
378 }
380 /**
381 * gst_type_find_helper:
382 * @src: A source #GstPad
383 * @size: The length in bytes
384 *
385 * Tries to find what type of data is flowing from the given source #GstPad.
386 *
387 * Free-function: gst_caps_unref
388 *
389 * Returns: (transfer full): the #GstCaps corresponding to the data stream.
390 * Returns #NULL if no #GstCaps matches the data stream.
391 */
393 GstCaps *
394 gst_type_find_helper (GstPad * src, guint64 size)
395 {
396 GstTypeFindHelperGetRangeFunction func;
398 g_return_val_if_fail (GST_IS_OBJECT (src), NULL);
399 g_return_val_if_fail (GST_PAD_GETRANGEFUNC (src) != NULL, NULL);
401 func = (GstTypeFindHelperGetRangeFunction) (GST_PAD_GETRANGEFUNC (src));
403 return gst_type_find_helper_get_range (GST_OBJECT (src), func, size, NULL);
404 }
406 /* ********************** typefinding for buffers ************************* */
408 typedef struct
409 {
410 guint8 *data; /* buffer data */
411 guint size;
412 GstTypeFindProbability best_probability;
413 GstCaps *caps;
414 GstTypeFindFactory *factory; /* for logging */
415 GstObject *obj; /* for logging */
416 } GstTypeFindBufHelper;
418 /*
419 * buf_helper_find_peek:
420 * @data: helper data struct
421 * @off: stream offset
422 * @size: block size
423 *
424 * Get data pointer within a buffer.
425 *
426 * Returns: address inside the buffer or %NULL if buffer does not cover the
427 * requested range.
428 */
429 static guint8 *
430 buf_helper_find_peek (gpointer data, gint64 off, guint size)
431 {
432 GstTypeFindBufHelper *helper;
434 helper = (GstTypeFindBufHelper *) data;
435 GST_LOG_OBJECT (helper->obj, "'%s' called peek (%" G_GINT64_FORMAT ", %u)",
436 GST_PLUGIN_FEATURE_NAME (helper->factory), off, size);
438 if (size == 0)
439 return NULL;
441 if (off < 0) {
442 GST_LOG_OBJECT (helper->obj, "'%s' wanted to peek at end; not supported",
443 GST_PLUGIN_FEATURE_NAME (helper->factory));
444 return NULL;
445 }
447 if ((off + size) <= helper->size)
448 return helper->data + off;
450 return NULL;
451 }
453 /*
454 * buf_helper_find_suggest:
455 * @data: helper data struct
456 * @probability: probability of the match
457 * @caps: caps of the type
458 *
459 * If given @probability is higher, replace previously store caps.
460 */
461 static void
462 buf_helper_find_suggest (gpointer data, GstTypeFindProbability probability,
463 const GstCaps * caps)
464 {
465 GstTypeFindBufHelper *helper = (GstTypeFindBufHelper *) data;
467 GST_LOG_OBJECT (helper->obj,
468 "'%s' called called suggest (%u, %" GST_PTR_FORMAT ")",
469 GST_PLUGIN_FEATURE_NAME (helper->factory), probability, caps);
471 /* Note: not >= as we call typefinders in order of rank, highest first */
472 if (probability > helper->best_probability) {
473 GstCaps *copy = gst_caps_copy (caps);
475 gst_caps_replace (&helper->caps, copy);
476 gst_caps_unref (copy);
477 helper->best_probability = probability;
478 }
479 }
481 /**
482 * gst_type_find_helper_for_buffer:
483 * @obj: object doing the typefinding, or NULL (used for logging)
484 * @buf: (in) (transfer none): a #GstBuffer with data to typefind
485 * @prob: (out) (allow-none): location to store the probability of the found
486 * caps, or #NULL
487 *
488 * Tries to find what type of data is contained in the given #GstBuffer, the
489 * assumption being that the buffer represents the beginning of the stream or
490 * file.
491 *
492 * All available typefinders will be called on the data in order of rank. If
493 * a typefinding function returns a probability of #GST_TYPE_FIND_MAXIMUM,
494 * typefinding is stopped immediately and the found caps will be returned
495 * right away. Otherwise, all available typefind functions will the tried,
496 * and the caps with the highest probability will be returned, or #NULL if
497 * the content of the buffer could not be identified.
498 *
499 * Free-function: gst_caps_unref
500 *
501 * Returns: (transfer full): the #GstCaps corresponding to the data, or #NULL
502 * if no type could be found. The caller should free the caps returned
503 * with gst_caps_unref().
504 */
505 GstCaps *
506 gst_type_find_helper_for_buffer (GstObject * obj, GstBuffer * buf,
507 GstTypeFindProbability * prob)
508 {
509 GstTypeFindBufHelper helper;
510 GstTypeFind find;
511 GList *l, *type_list;
512 GstCaps *result = NULL;
514 g_return_val_if_fail (buf != NULL, NULL);
515 g_return_val_if_fail (GST_IS_BUFFER (buf), NULL);
516 g_return_val_if_fail (GST_BUFFER_OFFSET (buf) == 0 ||
517 GST_BUFFER_OFFSET (buf) == GST_BUFFER_OFFSET_NONE, NULL);
519 helper.data = GST_BUFFER_DATA (buf);
520 helper.size = GST_BUFFER_SIZE (buf);
521 helper.best_probability = GST_TYPE_FIND_NONE;
522 helper.caps = NULL;
523 helper.obj = obj;
525 if (helper.data == NULL || helper.size == 0)
526 return NULL;
528 find.data = &helper;
529 find.peek = buf_helper_find_peek;
530 find.suggest = buf_helper_find_suggest;
531 find.get_length = NULL;
533 type_list = gst_type_find_factory_get_list ();
535 for (l = type_list; l; l = l->next) {
536 helper.factory = GST_TYPE_FIND_FACTORY (l->data);
537 gst_type_find_factory_call_function (helper.factory, &find);
538 if (helper.best_probability >= GST_TYPE_FIND_MAXIMUM)
539 break;
540 }
541 gst_plugin_feature_list_free (type_list);
543 if (helper.best_probability > 0)
544 result = helper.caps;
546 if (prob)
547 *prob = helper.best_probability;
549 GST_LOG_OBJECT (obj, "Returning %" GST_PTR_FORMAT " (probability = %u)",
550 result, (guint) helper.best_probability);
552 return result;
553 }
555 /**
556 * gst_type_find_helper_for_extension:
557 * @obj: (allow-none): object doing the typefinding, or NULL (used for logging)
558 * @extension: an extension
559 *
560 * Tries to find the best #GstCaps associated with @extension.
561 *
562 * All available typefinders will be checked against the extension in order
563 * of rank. The caps of the first typefinder that can handle @extension will be
564 * returned.
565 *
566 * Free-function: gst_caps_unref
567 *
568 * Returns: (transfer full): the #GstCaps corresponding to @extension, or
569 * #NULL if no type could be found. The caller should free the caps
570 * returned with gst_caps_unref().
571 *
572 * Since: 0.10.23
573 */
574 GstCaps *
575 gst_type_find_helper_for_extension (GstObject * obj, const gchar * extension)
576 {
577 GList *l, *type_list;
578 GstCaps *result = NULL;
580 g_return_val_if_fail (extension != NULL, NULL);
582 GST_LOG_OBJECT (obj, "finding caps for extension %s", extension);
584 type_list = gst_type_find_factory_get_list ();
586 for (l = type_list; l; l = g_list_next (l)) {
587 GstTypeFindFactory *factory;
588 gchar **ext;
589 gint i;
591 factory = GST_TYPE_FIND_FACTORY (l->data);
593 /* we only want to check those factories without a function */
594 if (factory->function != NULL)
595 continue;
597 /* get the extension that this typefind factory can handle */
598 ext = gst_type_find_factory_get_extensions (factory);
599 if (ext == NULL)
600 continue;
602 /* there are extension, see if one of them matches the requested
603 * extension */
604 for (i = 0; ext[i]; i++) {
605 if (strcmp (ext[i], extension) == 0) {
606 /* we found a matching extension, take the caps */
607 if ((result = gst_type_find_factory_get_caps (factory))) {
608 gst_caps_ref (result);
609 goto done;
610 }
611 }
612 }
613 }
614 done:
615 gst_plugin_feature_list_free (type_list);
617 GST_LOG_OBJECT (obj, "Returning %" GST_PTR_FORMAT, result);
619 return result;
620 }