libs/gst/base/gsttypefindhelper.c

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