gstdiscoverer

gstdiscoverer — Utility for discovering information on URIs.

Synopsis


#include <gst/pbutils/pbutils.h>

                    GstDiscoverer;
GstDiscoverer *     gst_discoverer_new                  (GstClockTime timeout,
                                                         GError **err);
void                gst_discoverer_start                (GstDiscoverer *discoverer);
void                gst_discoverer_stop                 (GstDiscoverer *discoverer);
GstDiscovererInfo * gst_discoverer_discover_uri         (GstDiscoverer *discoverer,
                                                         const gchar *uri,
                                                         GError **err);
gboolean            gst_discoverer_discover_uri_async   (GstDiscoverer *discoverer,
                                                         const gchar *uri);

                    GstDiscovererInfo;
enum                GstDiscovererResult;
GstClockTime        gst_discoverer_info_get_duration    (const GstDiscovererInfo *info);
const GstStructure* gst_discoverer_info_get_misc        (const GstDiscovererInfo *info);
GstDiscovererResult  gst_discoverer_info_get_result     (const GstDiscovererInfo *info);
GstDiscovererStreamInfo* gst_discoverer_info_get_stream_info
                                                        (GstDiscovererInfo *info);
GList*              gst_discoverer_info_get_stream_list (GstDiscovererInfo *info);
const GstTagList*   gst_discoverer_info_get_tags        (const GstDiscovererInfo *info);
const gchar*        gst_discoverer_info_get_uri         (const GstDiscovererInfo *info);
gboolean            gst_discoverer_info_get_seekable    (const GstDiscovererInfo *info);
#define             gst_discoverer_info_ref             (info)
#define             gst_discoverer_info_unref           (info)

                    GstDiscovererStreamInfo;
                    GstDiscovererContainerInfo;
                    GstDiscovererAudioInfo;
                    GstDiscovererVideoInfo;
                    GstDiscovererSubtitleInfo;
GstCaps*            gst_discoverer_stream_info_get_caps (GstDiscovererStreamInfo *info);
const GstStructure* gst_discoverer_stream_info_get_misc (GstDiscovererStreamInfo *info);
GstDiscovererStreamInfo* gst_discoverer_stream_info_get_next
                                                        (GstDiscovererStreamInfo *info);
GstDiscovererStreamInfo* gst_discoverer_stream_info_get_previous
                                                        (GstDiscovererStreamInfo *info);
const GstTagList*   gst_discoverer_stream_info_get_tags (GstDiscovererStreamInfo *info);
#define             gst_discoverer_stream_info_ref      (info)
#define             gst_discoverer_stream_info_unref    (info)
void                gst_discoverer_stream_info_list_free
                                                        (GList *infos);
const gchar *       gst_discoverer_stream_info_get_stream_type_nick
                                                        (GstDiscovererStreamInfo *info);
GList *             gst_discoverer_info_get_audio_streams
                                                        (GstDiscovererInfo *info);
GList *             gst_discoverer_info_get_container_streams
                                                        (GstDiscovererInfo *info);
GList *             gst_discoverer_info_get_streams     (GstDiscovererInfo *info,
                                                         GType streamtype);
GList *             gst_discoverer_info_get_subtitle_streams
                                                        (GstDiscovererInfo *info);
GList *             gst_discoverer_info_get_video_streams
                                                        (GstDiscovererInfo *info);
guint               gst_discoverer_audio_info_get_bitrate
                                                        (const GstDiscovererAudioInfo *info);
guint               gst_discoverer_audio_info_get_channels
                                                        (const GstDiscovererAudioInfo *info);
guint               gst_discoverer_audio_info_get_depth (const GstDiscovererAudioInfo *info);
const gchar *       gst_discoverer_audio_info_get_language
                                                        (const GstDiscovererAudioInfo *info);
guint               gst_discoverer_audio_info_get_max_bitrate
                                                        (const GstDiscovererAudioInfo *info);
guint               gst_discoverer_audio_info_get_sample_rate
                                                        (const GstDiscovererAudioInfo *info);
GList *             gst_discoverer_container_info_get_streams
                                                        (GstDiscovererContainerInfo *info);
const gchar *       gst_discoverer_subtitle_info_get_language
                                                        (const GstDiscovererSubtitleInfo *info);
guint               gst_discoverer_video_info_get_bitrate
                                                        (const GstDiscovererVideoInfo *info);
guint               gst_discoverer_video_info_get_depth (const GstDiscovererVideoInfo *info);
guint               gst_discoverer_video_info_get_framerate_denom
                                                        (const GstDiscovererVideoInfo *info);
guint               gst_discoverer_video_info_get_framerate_num
                                                        (const GstDiscovererVideoInfo *info);
guint               gst_discoverer_video_info_get_height
                                                        (const GstDiscovererVideoInfo *info);
gboolean            gst_discoverer_video_info_is_interlaced
                                                        (const GstDiscovererVideoInfo *info);
gboolean            gst_discoverer_video_info_is_image  (const GstDiscovererVideoInfo *info);
guint               gst_discoverer_video_info_get_max_bitrate
                                                        (const GstDiscovererVideoInfo *info);
guint               gst_discoverer_video_info_get_par_denom
                                                        (const GstDiscovererVideoInfo *info);
guint               gst_discoverer_video_info_get_par_num
                                                        (const GstDiscovererVideoInfo *info);
guint               gst_discoverer_video_info_get_width (const GstDiscovererVideoInfo *info);

Object Hierarchy

  GObject
   +----GstDiscoverer

Properties

  "timeout"                  guint64               : Read / Write / Construct

Signals

  "discovered"                                     : Run Last
  "finished"                                       : Run Last
  "starting"                                       : Run Last

Description

The GstDiscoverer is a utility object which allows to get as much information as possible from one or many URIs.

It provides two APIs, allowing usage in blocking or non-blocking mode.

The blocking mode just requires calling gst_discoverer_discover_uri() with the URI one wishes to discover.

The non-blocking mode requires a running GMainLoop in the default GMainContext, where one connects to the various signals, appends the URIs to be processed (through gst_discoverer_discover_uri_async()) and then asks for the discovery to begin (through gst_discoverer_start()).

All the information is returned in a GstDiscovererInfo structure.

Details

GstDiscoverer

typedef struct _GstDiscoverer GstDiscoverer;

The GstDiscoverer structure.

Since 0.10.31


gst_discoverer_new ()

GstDiscoverer *     gst_discoverer_new                  (GstClockTime timeout,
                                                         GError **err);

Creates a new GstDiscoverer with the provided timeout.

timeout :

timeout per file, in nanoseconds. Allowed are values between one second (GST_SECOND) and one hour (3600 * GST_SECOND)

err :

a pointer to a GError. can be NULL

Returns :

transfer full. transfer full.

Since 0.10.31


gst_discoverer_start ()

void                gst_discoverer_start                (GstDiscoverer *discoverer);

Allow asynchronous discovering of URIs to take place. A GMainLoop must be available for GstDiscoverer to properly work in asynchronous mode.

discoverer :

A GstDiscoverer

Since 0.10.31


gst_discoverer_stop ()

void                gst_discoverer_stop                 (GstDiscoverer *discoverer);

Stop the discovery of any pending URIs and clears the list of pending URIS (if any).

discoverer :

A GstDiscoverer

Since 0.10.31


gst_discoverer_discover_uri ()

GstDiscovererInfo * gst_discoverer_discover_uri         (GstDiscoverer *discoverer,
                                                         const gchar *uri,
                                                         GError **err);

Synchronously discovers the given uri.

A copy of uri will be made internally, so the caller can safely g_free() afterwards.

discoverer :

A GstDiscoverer

uri :

The URI to run on.

err :

If an error occurred, this field will be filled in.. out. allow-none.

Returns :

transfer full. transfer full.

Since 0.10.31


gst_discoverer_discover_uri_async ()

gboolean            gst_discoverer_discover_uri_async   (GstDiscoverer *discoverer,
                                                         const gchar *uri);

Appends the given uri to the list of URIs to discoverer. The actual discovery of the uri will only take place if gst_discoverer_start() has been called.

A copy of uri will be made internally, so the caller can safely g_free() afterwards.

discoverer :

A GstDiscoverer

uri :

the URI to add.

Returns :

TRUE if the uri was successfully appended to the list of pending uris, else FALSE

Since 0.10.31


GstDiscovererInfo

typedef struct _GstDiscovererInfo GstDiscovererInfo;

Structure containing the information of a URI analyzed by GstDiscoverer.

Since 0.10.31


enum GstDiscovererResult

typedef enum {
  GST_DISCOVERER_OK               = 0,
  GST_DISCOVERER_URI_INVALID      = 1,
  GST_DISCOVERER_ERROR            = 2,
  GST_DISCOVERER_TIMEOUT          = 3,
  GST_DISCOVERER_BUSY             = 4,
  GST_DISCOVERER_MISSING_PLUGINS  = 5
} GstDiscovererResult;

Result values for the discovery process.

GST_DISCOVERER_OK

The discovery was successful

GST_DISCOVERER_URI_INVALID

the URI is invalid

GST_DISCOVERER_ERROR

an error happened and the GError is set

GST_DISCOVERER_TIMEOUT

the discovery timed-out

GST_DISCOVERER_BUSY

the discoverer was already discovering a file

GST_DISCOVERER_MISSING_PLUGINS

Some plugins are missing for full discovery

Since 0.10.31


gst_discoverer_info_get_duration ()

GstClockTime        gst_discoverer_info_get_duration    (const GstDiscovererInfo *info);

info :

a GstDiscovererInfo

Returns :

the duration of the URI in GstClockTime (nanoseconds).

Since 0.10.31


gst_discoverer_info_get_misc ()

const GstStructure* gst_discoverer_info_get_misc        (const GstDiscovererInfo *info);

info :

a GstDiscovererInfo

Returns :

transfer none. transfer none.

Since 0.10.31


gst_discoverer_info_get_result ()

GstDiscovererResult  gst_discoverer_info_get_result     (const GstDiscovererInfo *info);

info :

a GstDiscovererInfo

Returns :

the result of the discovery as a GstDiscovererResult.

Since 0.10.31


gst_discoverer_info_get_stream_info ()

GstDiscovererStreamInfo* gst_discoverer_info_get_stream_info
                                                        (GstDiscovererInfo *info);

info :

a GstDiscovererInfo

Returns :

transfer full. transfer full.

Since 0.10.31


gst_discoverer_info_get_stream_list ()

GList*              gst_discoverer_info_get_stream_list (GstDiscovererInfo *info);

info :

a GstDiscovererInfo

Returns :

transfer full) (element-type Gst.DiscovererStreamInfo. transfer full. element-type Gst.DiscovererStreamInfo.

Since 0.10.31


gst_discoverer_info_get_tags ()

const GstTagList*   gst_discoverer_info_get_tags        (const GstDiscovererInfo *info);

info :

a GstDiscovererInfo

Returns :

transfer none. transfer none.

Since 0.10.31


gst_discoverer_info_get_uri ()

const gchar*        gst_discoverer_info_get_uri         (const GstDiscovererInfo *info);

info :

a GstDiscovererInfo

Returns :

transfer none. transfer none.

Since 0.10.31


gst_discoverer_info_get_seekable ()

gboolean            gst_discoverer_info_get_seekable    (const GstDiscovererInfo *info);

info :

a GstDiscovererInfo

Returns :

the whether the URI is seekable.

Since 0.10.32


gst_discoverer_info_ref()

#define gst_discoverer_info_ref(info) (gst_mini_object_ref((GstMiniObject*)info))

Increments the reference count of info.

info :

a GstDiscovererInfo

Returns :

the same GstDiscovererInfo object

Since 0.10.31


gst_discoverer_info_unref()

#define gst_discoverer_info_unref(info) (gst_mini_object_unref((GstMiniObject*)info))

Decrements the reference count of info.

info :

a GstDiscovererInfo

Since 0.10.31


GstDiscovererStreamInfo

typedef struct _GstDiscovererStreamInfo GstDiscovererStreamInfo;

Base structure for information concerning a media stream. Depending on the stream type, one can find more media-specific information in GstDiscovererAudioInfo, GstDiscovererVideoInfo, and GstDiscovererContainerInfo.

The GstDiscovererStreamInfo represents the topology of the stream. Siblings can be iterated over with gst_discoverer_stream_info_get_next() and gst_discoverer_stream_info_get_previous(). Children (sub-streams) of a stream can be accessed using the GstDiscovererContainerInfo API.

As a simple example, if you run GstDiscoverer on an AVI file with one audio and one video stream, you will get a GstDiscovererContainerInfo corresponding to the AVI container, which in turn will have a GstDiscovererAudioInfo sub-stream and a GstDiscovererVideoInfo sub-stream for the audio and video streams respectively.

Since 0.10.31


GstDiscovererContainerInfo

typedef struct _GstDiscovererContainerInfo GstDiscovererContainerInfo;

GstDiscovererStreamInfo specific to container streams.

Since 0.10.31


GstDiscovererAudioInfo

typedef struct _GstDiscovererAudioInfo GstDiscovererAudioInfo;

GstDiscovererStreamInfo specific to audio streams.

Since 0.10.31


GstDiscovererVideoInfo

typedef struct _GstDiscovererVideoInfo GstDiscovererVideoInfo;

GstDiscovererStreamInfo specific to video streams (this includes images).

Since 0.10.31


GstDiscovererSubtitleInfo

typedef struct _GstDiscovererSubtitleInfo GstDiscovererSubtitleInfo;

GstDiscovererStreamInfo specific to subtitle streams (this includes text and image based ones).

Since 0.10.36


gst_discoverer_stream_info_get_caps ()

GstCaps*            gst_discoverer_stream_info_get_caps (GstDiscovererStreamInfo *info);

info :

a GstDiscovererStreamInfo

Returns :

transfer full. transfer full.

Since 0.10.31


gst_discoverer_stream_info_get_misc ()

const GstStructure* gst_discoverer_stream_info_get_misc (GstDiscovererStreamInfo *info);

info :

a GstDiscovererStreamInfo

Returns :

transfer none. transfer none.

Since 0.10.31


gst_discoverer_stream_info_get_next ()

GstDiscovererStreamInfo* gst_discoverer_stream_info_get_next
                                                        (GstDiscovererStreamInfo *info);

info :

a GstDiscovererStreamInfo

Returns :

transfer full. transfer full.

Since 0.10.31


gst_discoverer_stream_info_get_previous ()

GstDiscovererStreamInfo* gst_discoverer_stream_info_get_previous
                                                        (GstDiscovererStreamInfo *info);

info :

a GstDiscovererStreamInfo

Returns :

transfer full. transfer full.

Since 0.10.31


gst_discoverer_stream_info_get_tags ()

const GstTagList*   gst_discoverer_stream_info_get_tags (GstDiscovererStreamInfo *info);

info :

a GstDiscovererStreamInfo

Returns :

transfer none. transfer none.

Since 0.10.31


gst_discoverer_stream_info_ref()

#define gst_discoverer_stream_info_ref(info) ((GstDiscovererStreamInfo*) gst_mini_object_ref((GstMiniObject*) info))

Increments the reference count of info.

info :

a GstDiscovererStreamInfo

Returns :

the same GstDiscovererStreamInfo object

Since 0.10.31


gst_discoverer_stream_info_unref()

#define gst_discoverer_stream_info_unref(info) (gst_mini_object_unref((GstMiniObject*) info))

Decrements the reference count of info.

Since 0.10.31


gst_discoverer_stream_info_list_free ()

void                gst_discoverer_stream_info_list_free
                                                        (GList *infos);

Decrements the reference count of all contained GstDiscovererStreamInfo and fress the GList.


gst_discoverer_stream_info_get_stream_type_nick ()

const gchar *       gst_discoverer_stream_info_get_stream_type_nick
                                                        (GstDiscovererStreamInfo *info);

info :

a GstDiscovererStreamInfo

Returns :

a human readable name for the stream type of the given info (ex : "audio", "container",...).

Since 0.10.31


gst_discoverer_info_get_audio_streams ()

GList *             gst_discoverer_info_get_audio_streams
                                                        (GstDiscovererInfo *info);

Finds all the GstDiscovererAudioInfo contained in info

info :

a GstDiscovererInfo

Returns :

transfer full) (element-type Gst.DiscovererStreamInfo. transfer full. element-type Gst.DiscovererStreamInfo.

Since 0.10.31


gst_discoverer_info_get_container_streams ()

GList *             gst_discoverer_info_get_container_streams
                                                        (GstDiscovererInfo *info);

Finds all the GstDiscovererContainerInfo contained in info

info :

a GstDiscovererInfo

Returns :

transfer full) (element-type Gst.DiscovererStreamInfo. transfer full. element-type Gst.DiscovererStreamInfo.

Since 0.10.31


gst_discoverer_info_get_streams ()

GList *             gst_discoverer_info_get_streams     (GstDiscovererInfo *info,
                                                         GType streamtype);

Finds the GstDiscovererStreamInfo contained in info that match the given streamtype.

info :

a GstDiscovererInfo

streamtype :

a GType derived from GstDiscovererStreamInfo

Returns :

transfer full) (element-type Gst.DiscovererStreamInfo. transfer full. element-type Gst.DiscovererStreamInfo.

Since 0.10.31


gst_discoverer_info_get_subtitle_streams ()

GList *             gst_discoverer_info_get_subtitle_streams
                                                        (GstDiscovererInfo *info);

Finds all the GstDiscovererSubtitleInfo contained in info

info :

a GstDiscovererInfo

Returns :

transfer full) (element-type Gst.DiscovererStreamInfo. transfer full. element-type Gst.DiscovererStreamInfo.

Since 0.10.36


gst_discoverer_info_get_video_streams ()

GList *             gst_discoverer_info_get_video_streams
                                                        (GstDiscovererInfo *info);

Finds all the GstDiscovererVideoInfo contained in info

info :

a GstDiscovererInfo

Returns :

transfer full) (element-type Gst.DiscovererStreamInfo. transfer full. element-type Gst.DiscovererStreamInfo.

Since 0.10.31


gst_discoverer_audio_info_get_bitrate ()

guint               gst_discoverer_audio_info_get_bitrate
                                                        (const GstDiscovererAudioInfo *info);

info :

a GstDiscovererAudioInfo

Returns :

the average or nominal bitrate of the stream in bits/second.

Since 0.10.31


gst_discoverer_audio_info_get_channels ()

guint               gst_discoverer_audio_info_get_channels
                                                        (const GstDiscovererAudioInfo *info);

info :

a GstDiscovererAudioInfo

Returns :

the number of channels in the stream.

Since 0.10.31


gst_discoverer_audio_info_get_depth ()

guint               gst_discoverer_audio_info_get_depth (const GstDiscovererAudioInfo *info);

info :

a GstDiscovererAudioInfo

Returns :

the number of bits used per sample in each channel.

Since 0.10.31


gst_discoverer_audio_info_get_language ()

const gchar *       gst_discoverer_audio_info_get_language
                                                        (const GstDiscovererAudioInfo *info);

info :

a GstDiscovererAudioInfo

Returns :

the language of the stream, or NULL if unknown.

Since 0.10.36


gst_discoverer_audio_info_get_max_bitrate ()

guint               gst_discoverer_audio_info_get_max_bitrate
                                                        (const GstDiscovererAudioInfo *info);

info :

a GstDiscovererAudioInfo

Returns :

the maximum bitrate of the stream in bits/second.

Since 0.10.31


gst_discoverer_audio_info_get_sample_rate ()

guint               gst_discoverer_audio_info_get_sample_rate
                                                        (const GstDiscovererAudioInfo *info);

info :

a GstDiscovererAudioInfo

Returns :

the sample rate of the stream in Hertz.

Since 0.10.31


gst_discoverer_container_info_get_streams ()

GList *             gst_discoverer_container_info_get_streams
                                                        (GstDiscovererContainerInfo *info);

info :

a GstDiscovererStreamInfo

Returns :

transfer full) (element-type Gst.DiscovererStreamInfo. transfer full. element-type Gst.DiscovererStreamInfo.

Since 0.10.31


gst_discoverer_subtitle_info_get_language ()

const gchar *       gst_discoverer_subtitle_info_get_language
                                                        (const GstDiscovererSubtitleInfo *info);

info :

a GstDiscovererSubtitleInfo

Returns :

the language of the stream, or NULL if unknown.

Since 0.10.36


gst_discoverer_video_info_get_bitrate ()

guint               gst_discoverer_video_info_get_bitrate
                                                        (const GstDiscovererVideoInfo *info);

info :

a GstDiscovererVideoInfo

Returns :

the average or nominal bitrate of the video stream in bits/second.

Since 0.10.31


gst_discoverer_video_info_get_depth ()

guint               gst_discoverer_video_info_get_depth (const GstDiscovererVideoInfo *info);

info :

a GstDiscovererVideoInfo

Returns :

the depth in bits of the video stream.

Since 0.10.31


gst_discoverer_video_info_get_framerate_denom ()

guint               gst_discoverer_video_info_get_framerate_denom
                                                        (const GstDiscovererVideoInfo *info);

info :

a GstDiscovererVideoInfo

Returns :

the framerate of the video stream (denominator).

Since 0.10.31


gst_discoverer_video_info_get_framerate_num ()

guint               gst_discoverer_video_info_get_framerate_num
                                                        (const GstDiscovererVideoInfo *info);

info :

a GstDiscovererVideoInfo

Returns :

the framerate of the video stream (numerator).

Since 0.10.31


gst_discoverer_video_info_get_height ()

guint               gst_discoverer_video_info_get_height
                                                        (const GstDiscovererVideoInfo *info);

info :

a GstDiscovererVideoInfo

Returns :

the height of the video stream in pixels.

Since 0.10.31


gst_discoverer_video_info_is_interlaced ()

gboolean            gst_discoverer_video_info_is_interlaced
                                                        (const GstDiscovererVideoInfo *info);

info :

a GstDiscovererVideoInfo

Returns :

TRUE if the stream is interlaced, else FALSE.

Since 0.10.31


gst_discoverer_video_info_is_image ()

gboolean            gst_discoverer_video_info_is_image  (const GstDiscovererVideoInfo *info);

info :

a GstDiscovererVideoInfo

Returns :

TRUE if the video stream corresponds to an image (i.e. only contains one frame).

Since 0.10.31


gst_discoverer_video_info_get_max_bitrate ()

guint               gst_discoverer_video_info_get_max_bitrate
                                                        (const GstDiscovererVideoInfo *info);

info :

a GstDiscovererVideoInfo

Returns :

the maximum bitrate of the video stream in bits/second.

Since 0.10.31


gst_discoverer_video_info_get_par_denom ()

guint               gst_discoverer_video_info_get_par_denom
                                                        (const GstDiscovererVideoInfo *info);

info :

a GstDiscovererVideoInfo

Returns :

the Pixel Aspect Ratio (PAR) of the video stream (denominator).

Since 0.10.31


gst_discoverer_video_info_get_par_num ()

guint               gst_discoverer_video_info_get_par_num
                                                        (const GstDiscovererVideoInfo *info);

info :

a GstDiscovererVideoInfo

Returns :

the Pixel Aspect Ratio (PAR) of the video stream (numerator).

Since 0.10.31


gst_discoverer_video_info_get_width ()

guint               gst_discoverer_video_info_get_width (const GstDiscovererVideoInfo *info);

info :

a GstDiscovererVideoInfo

Returns :

the width of the video stream in pixels.

Since 0.10.31

Property Details

The "timeout" property

  "timeout"                  guint64               : Read / Write / Construct

The duration (in nanoseconds) after which the discovery of an individual URI will timeout.

If the discovery of a URI times out, the GST_DISCOVERER_TIMEOUT will be set on the result flags.

Allowed values: [1000000000,3600000000000]

Default value: 15000000000

Signal Details

The "discovered" signal

void                user_function                      (GstDiscoverer     *discoverer,
                                                        GstDiscovererInfo *info,
                                                        GError            *error,
                                                        gpointer           user_data)       : Run Last

Will be emitted when all information on a URI could be discovered.

discoverer :

the GstDiscoverer

info :

the results GstDiscovererInfo

error :

type GLib.Error. type GLib.Error.

user_data :

user data set when the signal handler was connected.

The "finished" signal

void                user_function                      (GstDiscoverer *discoverer,
                                                        gpointer       user_data)       : Run Last

Will be emitted when all pending URIs have been processed.

discoverer :

the GstDiscoverer

user_data :

user data set when the signal handler was connected.

The "starting" signal

void                user_function                      (GstDiscoverer *discoverer,
                                                        gpointer       user_data)       : Run Last

Will be emitted when the discover starts analyzing the pending URIs

discoverer :

the GstDiscoverer

user_data :

user data set when the signal handler was connected.