gst-convenience/gst-libs/gst/discoverer/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 Lesser 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  * Lesser General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU Lesser General Public
  16  * License along with this library; if not, write to the
  17  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  18  * Boston, MA 02111-1307, USA.
  19  */
  20
  21 #ifndef _GST_DISCOVERER_H_
  22 #define _GST_DISCOVERER_H_
  23
  24 #ifndef GST_USE_UNSTABLE_API
  25 #warning "GstDiscovererInternal is unstable API and may change in future."
  26 #warning "You can define GST_USE_UNSTABLE_API to avoid this warning."
  27 #endif
  28
  29 #include <gst/gst.h>
  30 #include <gst/video/video.h>
  31 #include <gst/discoverer/gstdiscoverer-enumtypes.h>
  32
  33 G_BEGIN_DECLS
  34
  35 /**
  36  * GstStreamType:
  37  * @GST_STREAM_CONTAINER: Container media stream
  38  * @GST_STREAM_AUDIO: Audio media stream
  39  * @GST_STREAM_VIDEO: Video media stream
  40  * @GST_STREAM_IMAGE: Single-picture media stream
  41  * @GST_STREAM_UNKNOWN: Unknown media stream
  42  *
  43  * The various types of #GstStreamInformation.
  44  */
  45 typedef enum {
  46   GST_STREAM_CONTAINER,
  47   GST_STREAM_AUDIO,
  48   GST_STREAM_VIDEO,
  49   GST_STREAM_IMAGE,
  50   GST_STREAM_UNKNOWN,
  51 } GstStreamType;
  52
  53 typedef struct _GstStreamInformation GstStreamInformation;
  54
  55 /**
  56  * GstStreamInformation:
  57  * @streamtype: the type of stream, can be a container or a media type (audio/video/text)
  58  * @previous: previous #GstStreamInformation in a chain, NULL for starting points
  59  * @next: next #GstStreamInformation in a chain, NULL for containers
  60  * @caps: #GstCaps for the stream
  61  * @tags: #GstTagList containing tags for the stream
  62  * @misc: #GstStructure with additional information (for example, codec version, profile, etc.)
  63  *
  64  * Base structure for informations concerning a media stream. Depending on the @streamtype,
  65  * One can find more media-specific information in #GstStreamAudioInformation,
  66  * #GstStreamVideoInformation, #GstStreamContainerInformation.
  67  */
  68 struct _GstStreamInformation {
  69   GstStreamType         streamtype;
  70
  71   GstStreamInformation *previous;  /* NULL for starting points */
  72   GstStreamInformation *next; /* NULL for containers */
  73
  74   GstCaps               *caps;
  75   GstTagList            *tags;
  76   GstStructure          *misc;
  77 };
  78
  79 GstStreamInformation * gst_stream_information_new (void);
  80 GstStreamInformation *
  81 gst_stream_information_copy (GstStreamInformation * info);
  82 void gst_stream_information_free (GstStreamInformation *topology);
  83 GType gst_stream_information_get_type (void);
  84
  85 #define GST_TYPE_STREAM_INFORMATION (gst_stream_information_get_type ())
  86 #define GST_STREAM_INFORMATION(object) ((GstStreamInformation *)(object))
  87
  88
  89 /**
  90  * GstStreamContainerInformation:
  91  * @parent: See #GstStreamInformation for fields
  92  * @streams: List of #GstStreamInformation objects in this container
  93  *
  94  * #GstStreamInformation specific to streams of type #GST_STREAM_CONTAINER.
  95  */
  96 typedef struct _GstStreamContainerInformation GstStreamContainerInformation;
  97
  98 struct _GstStreamContainerInformation {
  99   GstStreamInformation parent;
 100
 101   GList               *streams;
 102 };
 103
 104 GstStreamContainerInformation * gst_stream_container_information_new (void);
 105 GstStreamContainerInformation *
 106 gst_stream_container_information_copy (GstStreamContainerInformation * ptr);
 107 void gst_stream_container_information_free (GstStreamContainerInformation *ptr);
 108 GType gst_stream_container_information_get_type (void);
 109
 110 #define GST_TYPE_STREAM_CONTAINER_INFORMATION       \
 111   (gst_stream_container_information_get_type ())
 112 #define GST_STREAM_CONTAINER_INFORMATION(object)    \
 113   ((GstStreamContainerInformation *)(object))
 114
 115
 116 /**
 117  * GstStreamAudioInformation:
 118  * @parent: See #GstStreamInformation for fields
 119  * @channels: Number of channels in the stream
 120  * @sample_rate: Sampling rate of the stream in Hz
 121  * @depth: Number of bits used per sample
 122  * @bitrate: Bitrate of the stream in bits/second
 123  * @is_vbr: True if the stream has a variable bitrate
 124  *
 125  * #GstStreamInformation specific to streams of type #GST_STREAM_AUDIO.
 126  */
 127 typedef struct _GstStreamAudioInformation GstStreamAudioInformation;
 128
 129 struct _GstStreamAudioInformation {
 130   GstStreamInformation parent;
 131
 132   guint channels;
 133   guint sample_rate;
 134   guint depth;
 135
 136   guint bitrate;
 137   guint max_bitrate;
 138   gboolean is_vbr;
 139 };
 140
 141 GstStreamAudioInformation * gst_stream_audio_information_new (void);
 142 GstStreamAudioInformation *
 143 gst_stream_audio_information_copy (GstStreamAudioInformation * ptr);
 144 void gst_stream_audio_information_free (GstStreamAudioInformation *ptr);
 145 GType gst_stream_audio_information_get_type (void);
 146
 147 #define GST_TYPE_STREAM_AUDIO_INFORMATION       \
 148   (gst_stream_audio_information_get_type ())
 149 #define GST_STREAM_AUDIO_INFORMATION(object)    \
 150   ((GstStreamAudioInformation *)(object))
 151
 152
 153 /**
 154  * GstStreamVideoInformation:
 155  * @parent: See #GstStreamInformation for fields
 156  * @width: Width of the video stream
 157  * @height: Height of the video stream
 158  * @depth: Depth in bits of the video stream (only relevant for RGB streams)
 159  * @frame_rate: Frame rte of the video stream as a fraction
 160  * @pixel_aspect_ratio: PAR of the video stream as a fraction
 161  * @format: Colorspace and depth of the stream as a #GstVideoFormat
 162  * @interlaced: True if the stream is interlaced, false otherwise
 163  *
 164  * #GstStreamInformation specific to streams of type #GST_STREAM_VIDEO.
 165  */
 166 typedef struct _GstStreamVideoInformation GstStreamVideoInformation;
 167
 168 struct _GstStreamVideoInformation {
 169   GstStreamInformation parent;
 170
 171   guint width;
 172   guint height;
 173   guint depth;
 174   GValue frame_rate;
 175   GValue pixel_aspect_ratio;
 176   GstVideoFormat format;
 177   gboolean interlaced;
 178 };
 179
 180 GstStreamVideoInformation * gst_stream_video_information_new (void);
 181 GstStreamVideoInformation *
 182 gst_stream_video_information_copy (GstStreamVideoInformation * ptr);
 183 void gst_stream_video_information_free (GstStreamVideoInformation *ptr);
 184 GType gst_stream_video_information_get_type (void);
 185
 186 #define GST_TYPE_STREAM_VIDEO_INFORMATION       \
 187   (gst_stream_video_information_get_type ())
 188 #define GST_STREAM_VIDEO_INFORMATION(object)    \
 189   ((GstStreamVideoInformation *)(object))
 190
 191
 192 /**
 193  * GstDiscovererResult:
 194  * @GST_DISCOVERER_OK: The discovery was successfull
 195  * @GST_DISCOVERER_URI_INVALID: the URI is invalid
 196  * @GST_DISCOVERER_ERROR: an error happend and the GError is set
 197  * @GST_DISCOVERER_TIMEOUT: the discovery timed-out
 198  * @GST_DISCOVERER_BUSY: the discoverer was already discovering a file
 199  * @GST_DISCOVERER_MISSING_PLUGINS: Some plugins are missing for full discovery
 200  *
 201  * Result values for the discovery process.
 202  */
 203 typedef enum
 204   {
 205     GST_DISCOVERER_OK               = 0,
 206     GST_DISCOVERER_URI_INVALID      = (1<<0),
 207     GST_DISCOVERER_ERROR            = (1<<1),
 208     GST_DISCOVERER_TIMEOUT          = (1<<2),
 209     GST_DISCOVERER_BUSY             = (1<<3),
 210     GST_DISCOVERER_MISSING_PLUGINS  = (1<<4)
 211   } GstDiscovererResult;
 212
 213
 214 /**
 215  * GstDiscovererInformation:
 216  * @uri: The URI for which the information was discovered
 217  * @result: Result of discovery as a #GstDiscovererResult
 218  * @stream_info: #GstStreamInformation struct with information about the stream and its substreams, preserving the original hierarchy
 219  * @stream_list: #GList of streams for easy iteration
 220  * @duration: Duration of the stream in nanoseconds
 221  * @misc: Miscellaneous information stored as a #GstStructure (for example, information about missing plugins)
 222  *
 223  * Structure containing the information of a URI analyzed by #GstDiscovererInternal.
 224  */
 225 typedef struct _GstDiscovererInformation GstDiscovererInformation;
 226
 227 struct _GstDiscovererInformation {
 228   gchar *uri;
 229   GstDiscovererResult result;
 230
 231   /* Sub-streams */
 232   GstStreamInformation *stream_info;
 233   GList *stream_list;
 234
 235   /* Stream global information */
 236   GstClockTime duration;
 237   GstStructure *misc;
 238   GstTagList *tags;
 239 };
 240
 241 GstDiscovererInformation * gst_discoverer_information_new (void);
 242 GstDiscovererInformation *
 243 gst_discoverer_information_copy (GstDiscovererInformation * ptr);
 244 void gst_discoverer_information_free (GstDiscovererInformation *ptr);
 245 GType gst_discoverer_information_get_type (void);
 246
 247 #define GST_TYPE_DISCOVERER_INFORMATION (gst_discoverer_information_get_type ())
 248 #define GST_DISCOVERER_INFORMATION(object) \
 249   ((GstDiscovererInformation *)(object))
 250
 251
 252 #define GST_TYPE_DISCOVERER_INTERNAL \
 253   (gst_discoverer_internal_get_type())
 254 #define GST_DISCOVERER_INTERNAL(obj) \
 255   (G_TYPE_CHECK_INSTANCE_CAST((obj),GST_TYPE_DISCOVERER_INTERNAL,GstDiscovererInternal))
 256 #define GST_DISCOVERER_INTERNAL_CLASS(klass) \
 257   (G_TYPE_CHECK_CLASS_CAST((klass),GST_TYPE_DISCOVERER_INTERNAL,GstDiscovererInternalClass))
 258 #define GST_IS_DISCOVERER_INTERNAL(obj) \
 259   (G_TYPE_CHECK_INSTANCE_TYPE((obj),GST_TYPE_DISCOVERER_INTERNAL))
 260 #define GST_IS_DISCOVERER_INTERNAL_CLASS(klass) \
 261   (G_TYPE_CHECK_CLASS_TYPE((klass),GST_TYPE_DISCOVERER_INTERNAL))
 262
 263 typedef struct _GstDiscovererInternal GstDiscovererInternal;
 264 typedef struct _GstDiscovererInternalClass GstDiscovererInternalClass;
 265
 266 /**
 267  * GstDiscovererInternal:
 268  *
 269  * The #GstDiscovererInternal structure.
 270  **/
 271 struct _GstDiscovererInternal {
 272   GObject parent;
 273
 274   /*< private >*/
 275   gboolean async;
 276
 277   /* allowed time to discover each uri in nanoseconds */
 278   GstClockTime timeout;
 279
 280   /* list of pending URI to process (current excluded) */
 281   GList *pending_uris;
 282
 283   GMutex *lock;
 284
 285   /* TRUE if processing a URI */
 286   gboolean running;
 287
 288   /* current items */
 289   /* FIXME : Protect all this with a lock */
 290   GstDiscovererInformation *current_info;
 291   GError *current_error;
 292   GstStructure *current_topology;
 293
 294   /* List of private streams */
 295   GList *streams;
 296
 297   /* Global elements */
 298   GstBin *pipeline;
 299   GstElement *uridecodebin;
 300   GstBus *bus;
 301
 302   GType decodebin2_type;
 303 };
 304
 305 struct _GstDiscovererInternalClass {
 306   GObjectClass parentclass;
 307
 308   /*< signals >*/
 309   void        (*ready)           (GstDiscovererInternal *discoverer);
 310   void        (*starting)        (GstDiscovererInternal *discoverer);
 311   void        (*discovered)      (GstDiscovererInternal *discoverer,
 312                                   GstDiscovererInformation *info,
 313                                   GError *err);
 314 };
 315
 316 GType gst_discoverer_internal_get_type (void);
 317 GstDiscovererInternal *gst_discoverer_internal_new (GstClockTime timeout);
 318
 319 /* Asynchronous API */
 320 void gst_discoverer_internal_start (GstDiscovererInternal *discoverer);
 321 void gst_discoverer_internal_stop (GstDiscovererInternal *discoverer);
 322 gboolean gst_discoverer_internal_append_uri (GstDiscovererInternal *discoverer, gchar *uri);
 323
 324
 325 /* Synchronous API */
 326 GstDiscovererInformation *
 327 gst_discoverer_internal_discover_uri (GstDiscovererInternal * discoverer, gchar * uri, GError ** err);
 328
 329 G_END_DECLS
 330
 331 #endif /* _GST_DISCOVERER_H */