gst-libs/gst/pbutils/gstdiscoverer.h

   1 /* GStreamer
   2  * Copyright (C) 2009 Edward Hervey <edward.hervey@collabora.co.uk>
   3  *               2009 Nokia Corporation
   4  *
   5  * This library is free software; you can redistribute it and/or
   6  * modify it under the terms of the GNU Library General Public
   7  * License as published by the Free Software Foundation; either
   8  * version 2 of the License, or (at your option) any later version.
   9  *
  10  * This library is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13  * Library General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU Library General Public
  16  * License along with this library; if not, write to the
  17  * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
  18  * Boston, MA 02110-1301, USA.
  19  */
  20
  21 #ifndef _GST_DISCOVERER_H_
  22 #define _GST_DISCOVERER_H_
  23
  24 #include <gst/gst.h>
  25
  26 G_BEGIN_DECLS
  27
  28 #define GST_TYPE_DISCOVERER_STREAM_INFO \
  29   (gst_discoverer_stream_info_get_type ())
  30 #define GST_DISCOVERER_STREAM_INFO(obj) \
  31   (G_TYPE_CHECK_INSTANCE_CAST((obj),GST_TYPE_DISCOVERER_STREAM_INFO, GstDiscovererStreamInfo))
  32 #define GST_IS_DISCOVERER_STREAM_INFO(obj) \
  33   (G_TYPE_CHECK_INSTANCE_TYPE((obj),GST_TYPE_DISCOVERER_STREAM_INFO))
  34 typedef struct _GstDiscovererStreamInfo GstDiscovererStreamInfo;
  35 typedef GObjectClass GstDiscovererStreamInfoClass;
  36 GType gst_discoverer_stream_info_get_type (void);
  37
  38 /**
  39  * GstDiscovererStreamInfo:
  40  *
  41  * Base structure for information concerning a media stream. Depending on the
  42  * stream type, one can find more media-specific information in
  43  * #GstDiscovererAudioInfo, #GstDiscovererVideoInfo, and
  44  * #GstDiscovererContainerInfo.
  45  *
  46  * The #GstDiscovererStreamInfo represents the topology of the stream. Siblings
  47  * can be iterated over with gst_discoverer_stream_info_get_next() and
  48  * gst_discoverer_stream_info_get_previous(). Children (sub-streams) of a
  49  * stream can be accessed using the #GstDiscovererContainerInfo API.
  50  *
  51  * As a simple example, if you run #GstDiscoverer on an AVI file with one audio
  52  * and one video stream, you will get a #GstDiscovererContainerInfo
  53  * corresponding to the AVI container, which in turn will have a
  54  * #GstDiscovererAudioInfo sub-stream and a #GstDiscovererVideoInfo sub-stream
  55  * for the audio and video streams respectively.
  56  */
  57 #define gst_discoverer_stream_info_ref(info) ((GstDiscovererStreamInfo*) g_object_ref((GObject*) info))
  58 #define gst_discoverer_stream_info_unref(info) (g_object_unref((GObject*) info))
  59
  60 GstDiscovererStreamInfo* gst_discoverer_stream_info_get_previous(GstDiscovererStreamInfo* info);
  61 GstDiscovererStreamInfo* gst_discoverer_stream_info_get_next(GstDiscovererStreamInfo* info);
  62 GstCaps*                 gst_discoverer_stream_info_get_caps(GstDiscovererStreamInfo* info);
  63 const GstTagList*        gst_discoverer_stream_info_get_tags(GstDiscovererStreamInfo* info);
  64 const GstToc*            gst_discoverer_stream_info_get_toc(GstDiscovererStreamInfo* info);
  65 const gchar*             gst_discoverer_stream_info_get_stream_id(GstDiscovererStreamInfo* info);
  66 const GstStructure*      gst_discoverer_stream_info_get_misc(GstDiscovererStreamInfo* info);
  67 const gchar *            gst_discoverer_stream_info_get_stream_type_nick(GstDiscovererStreamInfo* info);
  68
  69 /**
  70  * GstDiscovererContainerInfo:
  71  *
  72  * #GstDiscovererStreamInfo specific to container streams.
  73  */
  74 #define GST_TYPE_DISCOVERER_CONTAINER_INFO \
  75   (gst_discoverer_container_info_get_type ())
  76 #define GST_DISCOVERER_CONTAINER_INFO(obj) \
  77   (G_TYPE_CHECK_INSTANCE_CAST((obj),GST_TYPE_DISCOVERER_CONTAINER_INFO, GstDiscovererContainerInfo))
  78 #define GST_IS_DISCOVERER_CONTAINER_INFO(obj) \
  79   (G_TYPE_CHECK_INSTANCE_TYPE((obj),GST_TYPE_DISCOVERER_CONTAINER_INFO))
  80 typedef struct _GstDiscovererContainerInfo GstDiscovererContainerInfo;
  81 typedef GObjectClass GstDiscovererContainerInfoClass;
  82
  83 GType gst_discoverer_container_info_get_type (void);
  84
  85 GList *gst_discoverer_container_info_get_streams(GstDiscovererContainerInfo *info);
  86
  87
  88 /**
  89  * GstDiscovererAudioInfo:
  90  *
  91  * #GstDiscovererStreamInfo specific to audio streams.
  92  */
  93 #define GST_TYPE_DISCOVERER_AUDIO_INFO \
  94   (gst_discoverer_audio_info_get_type ())
  95 #define GST_DISCOVERER_AUDIO_INFO(obj) \
  96   (G_TYPE_CHECK_INSTANCE_CAST((obj),GST_TYPE_DISCOVERER_AUDIO_INFO, GstDiscovererAudioInfo))
  97 #define GST_IS_DISCOVERER_AUDIO_INFO(obj) \
  98   (G_TYPE_CHECK_INSTANCE_TYPE((obj),GST_TYPE_DISCOVERER_AUDIO_INFO))
  99 typedef struct _GstDiscovererAudioInfo GstDiscovererAudioInfo;
 100 typedef GObjectClass GstDiscovererAudioInfoClass;
 101
 102 GType gst_discoverer_audio_info_get_type (void);
 103
 104 guint gst_discoverer_audio_info_get_channels(const GstDiscovererAudioInfo* info);
 105 guint gst_discoverer_audio_info_get_sample_rate(const GstDiscovererAudioInfo* info);
 106 guint gst_discoverer_audio_info_get_depth(const GstDiscovererAudioInfo* info);
 107 guint gst_discoverer_audio_info_get_bitrate(const GstDiscovererAudioInfo* info);
 108 guint gst_discoverer_audio_info_get_max_bitrate(const GstDiscovererAudioInfo* info);
 109 const gchar * gst_discoverer_audio_info_get_language(const GstDiscovererAudioInfo* info);
 110
 111 /**
 112  * GstDiscovererVideoInfo:
 113  *
 114  * #GstDiscovererStreamInfo specific to video streams (this includes images).
 115  */
 116 #define GST_TYPE_DISCOVERER_VIDEO_INFO \
 117   (gst_discoverer_video_info_get_type ())
 118 #define GST_DISCOVERER_VIDEO_INFO(obj) \
 119   (G_TYPE_CHECK_INSTANCE_CAST((obj),GST_TYPE_DISCOVERER_VIDEO_INFO, GstDiscovererVideoInfo))
 120 #define GST_IS_DISCOVERER_VIDEO_INFO(obj) \
 121   (G_TYPE_CHECK_INSTANCE_TYPE((obj),GST_TYPE_DISCOVERER_VIDEO_INFO))
 122 typedef struct _GstDiscovererVideoInfo GstDiscovererVideoInfo;
 123 typedef GObjectClass GstDiscovererVideoInfoClass;
 124 GType gst_discoverer_video_info_get_type (void);
 125
 126 guint           gst_discoverer_video_info_get_width(const GstDiscovererVideoInfo* info);
 127 guint           gst_discoverer_video_info_get_height(const GstDiscovererVideoInfo* info);
 128 guint           gst_discoverer_video_info_get_depth(const GstDiscovererVideoInfo* info);
 129 guint           gst_discoverer_video_info_get_framerate_num(const GstDiscovererVideoInfo* info);
 130 guint           gst_discoverer_video_info_get_framerate_denom(const GstDiscovererVideoInfo* info);
 131 guint           gst_discoverer_video_info_get_par_num(const GstDiscovererVideoInfo* info);
 132 guint           gst_discoverer_video_info_get_par_denom(const GstDiscovererVideoInfo* info);
 133 gboolean        gst_discoverer_video_info_is_interlaced(const GstDiscovererVideoInfo* info);
 134 guint           gst_discoverer_video_info_get_bitrate(const GstDiscovererVideoInfo* info);
 135 guint           gst_discoverer_video_info_get_max_bitrate(const GstDiscovererVideoInfo* info);
 136 gboolean        gst_discoverer_video_info_is_image(const GstDiscovererVideoInfo* info);
 137
 138 /**
 139  * GstDiscovererSubtitleInfo:
 140  *
 141  * #GstDiscovererStreamInfo specific to subtitle streams (this includes text and
 142  * image based ones).
 143  */
 144 #define GST_TYPE_DISCOVERER_SUBTITLE_INFO \
 145   (gst_discoverer_subtitle_info_get_type ())
 146 #define GST_DISCOVERER_SUBTITLE_INFO(obj) \
 147   (G_TYPE_CHECK_INSTANCE_CAST((obj),GST_TYPE_DISCOVERER_SUBTITLE_INFO, GstDiscovererSubtitleInfo))
 148 #define GST_IS_DISCOVERER_SUBTITLE_INFO(obj) \
 149   (G_TYPE_CHECK_INSTANCE_TYPE((obj),GST_TYPE_DISCOVERER_SUBTITLE_INFO))
 150 typedef struct _GstDiscovererSubtitleInfo GstDiscovererSubtitleInfo;
 151 typedef GObjectClass GstDiscovererSubtitleInfoClass;
 152 GType gst_discoverer_subtitle_info_get_type (void);
 153
 154 const gchar *   gst_discoverer_subtitle_info_get_language(const GstDiscovererSubtitleInfo* info);
 155
 156 /**
 157  * GstDiscovererResult:
 158  * @GST_DISCOVERER_OK: The discovery was successful
 159  * @GST_DISCOVERER_URI_INVALID: the URI is invalid
 160  * @GST_DISCOVERER_ERROR: an error happened and the GError is set
 161  * @GST_DISCOVERER_TIMEOUT: the discovery timed-out
 162  * @GST_DISCOVERER_BUSY: the discoverer was already discovering a file
 163  * @GST_DISCOVERER_MISSING_PLUGINS: Some plugins are missing for full discovery
 164  *
 165  * Result values for the discovery process.
 166  */
 167 typedef enum {
 168   GST_DISCOVERER_OK               = 0,
 169   GST_DISCOVERER_URI_INVALID      = 1,
 170   GST_DISCOVERER_ERROR            = 2,
 171   GST_DISCOVERER_TIMEOUT          = 3,
 172   GST_DISCOVERER_BUSY             = 4,
 173   GST_DISCOVERER_MISSING_PLUGINS  = 5
 174 } GstDiscovererResult;
 175
 176 /**
 177  * GstDiscovererSerializeFlags:
 178  * @GST_DISCOVERER_SERIALIZE_BASIC: Serialize only basic information, excluding
 179  * caps, tags and miscellaneous information
 180  * @GST_DISCOVERER_SERIALIZE_CAPS: Serialize the caps for each stream
 181  * @GST_DISCOVERER_SERIALIZE_TAGS: Serialize the tags for each stream
 182  * @GST_DISCOVERER_SERIALIZE_MISC: Serialize miscellaneous information for each stream
 183  * @GST_DISCOVERER_SERIALIZE_ALL: Serialize all the available info, including
 184  * caps, tags and miscellaneous information
 185  *
 186  * You can use these flags to control what is serialized by
 187  * gst_discoverer_info_to_variant()
 188  *
 189  * Since: 1.6
 190  */
 191
 192 typedef enum {
 193   GST_DISCOVERER_SERIALIZE_BASIC = 0,
 194   GST_DISCOVERER_SERIALIZE_CAPS  = 1 << 0,
 195   GST_DISCOVERER_SERIALIZE_TAGS  = 1 << 1,
 196   GST_DISCOVERER_SERIALIZE_MISC  = 1 << 2,
 197   GST_DISCOVERER_SERIALIZE_ALL   = GST_DISCOVERER_SERIALIZE_CAPS | GST_DISCOVERER_SERIALIZE_TAGS | GST_DISCOVERER_SERIALIZE_MISC
 198 } GstDiscovererSerializeFlags;
 199
 200 /**
 201  * GstDiscovererInfo:
 202  *
 203  * Structure containing the information of a URI analyzed by #GstDiscoverer.
 204  */
 205 typedef struct _GstDiscovererInfo GstDiscovererInfo;
 206
 207 #define GST_TYPE_DISCOVERER_INFO \
 208   (gst_discoverer_info_get_type ())
 209 #define GST_DISCOVERER_INFO(obj) \
 210   (G_TYPE_CHECK_INSTANCE_CAST((obj),GST_TYPE_DISCOVERER_INFO, GstDiscovererInfo))
 211 #define GST_IS_DISCOVERER_INFO(obj) \
 212   (G_TYPE_CHECK_INSTANCE_TYPE((obj),GST_TYPE_DISCOVERER_INFO))
 213 typedef GObjectClass GstDiscovererInfoClass;
 214 GType gst_discoverer_info_get_type (void);
 215
 216 #define gst_discoverer_info_unref(info) (g_object_unref((GObject*)info))
 217 #define gst_discoverer_info_ref(info) (g_object_ref((GObject*)info))
 218
 219 GstDiscovererInfo*        gst_discoverer_info_copy (GstDiscovererInfo * ptr);
 220
 221 const gchar*              gst_discoverer_info_get_uri(const GstDiscovererInfo* info);
 222 GstDiscovererResult       gst_discoverer_info_get_result(const GstDiscovererInfo* info);
 223 GstDiscovererStreamInfo*  gst_discoverer_info_get_stream_info(GstDiscovererInfo* info);
 224 GList*                    gst_discoverer_info_get_stream_list(GstDiscovererInfo* info);
 225 GstClockTime              gst_discoverer_info_get_duration(const GstDiscovererInfo* info);
 226 gboolean                  gst_discoverer_info_get_seekable(const GstDiscovererInfo* info);
 227 const GstStructure*       gst_discoverer_info_get_misc(const GstDiscovererInfo* info);
 228 const GstTagList*         gst_discoverer_info_get_tags(const GstDiscovererInfo* info);
 229 const GstToc*             gst_discoverer_info_get_toc(const GstDiscovererInfo* info);
 230 const gchar**             gst_discoverer_info_get_missing_elements_installer_details(const GstDiscovererInfo* info);
 231
 232 GList *                   gst_discoverer_info_get_streams (GstDiscovererInfo *info,
 233                                                            GType streamtype);
 234 GList *                   gst_discoverer_info_get_audio_streams (GstDiscovererInfo *info);
 235 GList *                   gst_discoverer_info_get_video_streams (GstDiscovererInfo *info);
 236 GList *                   gst_discoverer_info_get_subtitle_streams (GstDiscovererInfo *info);
 237 GList *                   gst_discoverer_info_get_container_streams (GstDiscovererInfo *info);
 238
 239 GVariant *                gst_discoverer_info_to_variant (GstDiscovererInfo *info,
 240                                                           GstDiscovererSerializeFlags flags);
 241 GstDiscovererInfo *       gst_discoverer_info_from_variant (GVariant *variant);
 242
 243 void                      gst_discoverer_stream_info_list_free (GList *infos);
 244
 245 #define GST_TYPE_DISCOVERER \
 246   (gst_discoverer_get_type())
 247 #define GST_DISCOVERER(obj) \
 248   (G_TYPE_CHECK_INSTANCE_CAST((obj),GST_TYPE_DISCOVERER,GstDiscoverer))
 249 #define GST_DISCOVERER_CLASS(klass) \
 250   (G_TYPE_CHECK_CLASS_CAST((klass),GST_TYPE_DISCOVERER,GstDiscovererClass))
 251 #define GST_IS_DISCOVERER(obj) \
 252   (G_TYPE_CHECK_INSTANCE_TYPE((obj),GST_TYPE_DISCOVERER))
 253 #define GST_IS_DISCOVERER_CLASS(klass) \
 254   (G_TYPE_CHECK_CLASS_TYPE((klass),GST_TYPE_DISCOVERER))
 255
 256 typedef struct _GstDiscoverer GstDiscoverer;
 257 typedef struct _GstDiscovererClass GstDiscovererClass;
 258 typedef struct _GstDiscovererPrivate GstDiscovererPrivate;
 259
 260 /**
 261  * GstDiscoverer:
 262  *
 263  * The #GstDiscoverer structure.
 264  **/
 265 struct _GstDiscoverer {
 266   GObject parent;
 267
 268   /*< private >*/
 269   GstDiscovererPrivate *priv;
 270
 271   gpointer _reserved[GST_PADDING];
 272 };
 273
 274 struct _GstDiscovererClass {
 275   GObjectClass parentclass;
 276
 277   /* signals */
 278   void        (*finished)        (GstDiscoverer *discoverer);
 279   void        (*starting)        (GstDiscoverer *discoverer);
 280   void        (*discovered)      (GstDiscoverer *discoverer,
 281                                   GstDiscovererInfo *info,
 282                                   const GError *err);
 283   void        (*source_setup)    (GstDiscoverer *discoverer,
 284                                   GstElement *source);
 285
 286   gpointer _reserved[GST_PADDING];
 287 };
 288
 289 GType          gst_discoverer_get_type (void);
 290 GstDiscoverer *gst_discoverer_new (GstClockTime timeout, GError **err);
 291
 292 /* Asynchronous API */
 293 void           gst_discoverer_start (GstDiscoverer *discoverer);
 294 void           gst_discoverer_stop (GstDiscoverer *discoverer);
 295 gboolean       gst_discoverer_discover_uri_async (GstDiscoverer *discoverer,
 296                                                   const gchar *uri);
 297
 298 /* Synchronous API */
 299 GstDiscovererInfo *
 300 gst_discoverer_discover_uri (GstDiscoverer * discoverer,
 301                              const gchar * uri,
 302                              GError ** err);
 303
 304 #ifdef G_DEFINE_AUTOPTR_CLEANUP_FUNC
 305 G_DEFINE_AUTOPTR_CLEANUP_FUNC(GstDiscoverer, gst_object_unref)
 306 #endif
 307
 308 #ifdef G_DEFINE_AUTOPTR_CLEANUP_FUNC
 309 G_DEFINE_AUTOPTR_CLEANUP_FUNC(GstDiscovererAudioInfo, gst_object_unref)
 310 #endif
 311
 312 #ifdef G_DEFINE_AUTOPTR_CLEANUP_FUNC
 313 G_DEFINE_AUTOPTR_CLEANUP_FUNC(GstDiscovererContainerInfo, gst_object_unref)
 314 #endif
 315
 316 #ifdef G_DEFINE_AUTOPTR_CLEANUP_FUNC
 317 G_DEFINE_AUTOPTR_CLEANUP_FUNC(GstDiscovererInfo, gst_object_unref)
 318 #endif
 319
 320 #ifdef G_DEFINE_AUTOPTR_CLEANUP_FUNC
 321 G_DEFINE_AUTOPTR_CLEANUP_FUNC(GstDiscovererStreamInfo, gst_object_unref)
 322 #endif
 323
 324 #ifdef G_DEFINE_AUTOPTR_CLEANUP_FUNC
 325 G_DEFINE_AUTOPTR_CLEANUP_FUNC(GstDiscovererSubtitleInfo, gst_object_unref)
 326 #endif
 327
 328 #ifdef G_DEFINE_AUTOPTR_CLEANUP_FUNC
 329 G_DEFINE_AUTOPTR_CLEANUP_FUNC(GstDiscovererVideoInfo, gst_object_unref)
 330 #endif
 331
 332 G_END_DECLS
 333
 334 #endif /* _GST_DISCOVERER_H */