gstdiscoverer

gstdiscoverer — Utility for discovering information on URIs.

Functions

GstDiscoverer * gst_discoverer_new ()
void gst_discoverer_start ()
void gst_discoverer_stop ()
GstDiscovererInfo * gst_discoverer_discover_uri ()
gboolean gst_discoverer_discover_uri_async ()
GstClockTime gst_discoverer_info_get_duration ()
const GstStructure * gst_discoverer_info_get_misc ()
GstDiscovererResult gst_discoverer_info_get_result ()
GstDiscovererStreamInfo * gst_discoverer_info_get_stream_info ()
GList * gst_discoverer_info_get_stream_list ()
const GstTagList * gst_discoverer_info_get_tags ()
const GstToc * gst_discoverer_info_get_toc ()
const gchar * gst_discoverer_info_get_uri ()
gboolean gst_discoverer_info_get_seekable ()
#define gst_discoverer_info_ref()
#define gst_discoverer_info_unref()
GstCaps * gst_discoverer_stream_info_get_caps ()
const GstStructure * gst_discoverer_stream_info_get_misc ()
GstDiscovererStreamInfo * gst_discoverer_stream_info_get_next ()
GstDiscovererStreamInfo * gst_discoverer_stream_info_get_previous ()
const GstTagList * gst_discoverer_stream_info_get_tags ()
const GstToc * gst_discoverer_stream_info_get_toc ()
const gchar * gst_discoverer_stream_info_get_stream_id ()
#define gst_discoverer_stream_info_ref()
#define gst_discoverer_stream_info_unref()
void gst_discoverer_stream_info_list_free ()
const gchar * gst_discoverer_stream_info_get_stream_type_nick ()
const gchar ** gst_discoverer_info_get_missing_elements_installer_details ()
GList * gst_discoverer_info_get_audio_streams ()
GList * gst_discoverer_info_get_container_streams ()
GList * gst_discoverer_info_get_streams ()
GList * gst_discoverer_info_get_subtitle_streams ()
GList * gst_discoverer_info_get_video_streams ()
guint gst_discoverer_audio_info_get_bitrate ()
guint gst_discoverer_audio_info_get_channels ()
guint gst_discoverer_audio_info_get_depth ()
const gchar * gst_discoverer_audio_info_get_language ()
guint gst_discoverer_audio_info_get_max_bitrate ()
guint gst_discoverer_audio_info_get_sample_rate ()
GList * gst_discoverer_container_info_get_streams ()
const gchar * gst_discoverer_subtitle_info_get_language ()
guint gst_discoverer_video_info_get_bitrate ()
guint gst_discoverer_video_info_get_depth ()
guint gst_discoverer_video_info_get_framerate_denom ()
guint gst_discoverer_video_info_get_framerate_num ()
guint gst_discoverer_video_info_get_height ()
gboolean gst_discoverer_video_info_is_interlaced ()
gboolean gst_discoverer_video_info_is_image ()
guint gst_discoverer_video_info_get_max_bitrate ()
guint gst_discoverer_video_info_get_par_denom ()
guint gst_discoverer_video_info_get_par_num ()
guint gst_discoverer_video_info_get_width ()

Properties

guint64 timeout Read / Write / Construct

Signals

void discovered Run Last
void finished Run Last
void source-setup Run Last
void starting Run Last

Types and Values

Object Hierarchy

    GObject
    ├── GstDiscoverer
    ╰── GstDiscovererInfo

Includes

#include <gst/pbutils/pbutils.h>

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 iterating a 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()). By default this will use the GLib default main context unless you have set a custom context using g_main_context_push_thread_default().

All the information is returned in a GstDiscovererInfo structure.

Functions

gst_discoverer_new ()

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

Creates a new GstDiscoverer with the provided timeout.

Parameters

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

The new GstDiscoverer. If an error occurred when creating the discoverer, err will be set accordingly and NULL will be returned. If err is set, the caller must free it when no longer needed using g_error_free().

[transfer full]


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.

Parameters

discoverer

A GstDiscoverer

 

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).

Parameters

discoverer

A GstDiscoverer

 

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.

Parameters

discoverer

A GstDiscoverer

 

uri

The URI to run on.

 

err

If an error occurred, this field will be filled in.

[out][allow-none]

Returns

the result of the scanning. Can be NULL if an error occurred.

[transfer full]


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.

Parameters

discoverer

A GstDiscoverer

 

uri

the URI to add.

 

Returns

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


gst_discoverer_info_get_duration ()

GstClockTime
gst_discoverer_info_get_duration (const GstDiscovererInfo *info);

Parameters

info

a GstDiscovererInfo

 

Returns

the duration of the URI in GstClockTime (nanoseconds).


gst_discoverer_info_get_misc ()

const GstStructure *
gst_discoverer_info_get_misc (const GstDiscovererInfo *info);

gst_discoverer_info_get_misc is deprecated and should not be used in newly-written code.

This functions is deprecated since version 1.4, use gst_discoverer_info_get_missing_elements_installer_details

Parameters

info

a GstDiscovererInfo

 

Returns

Miscellaneous information stored as a GstStructure (for example: information about missing plugins). If you wish to use the GstStructure after the life-time of info , you will need to copy it.

[transfer none]


gst_discoverer_info_get_result ()

GstDiscovererResult
gst_discoverer_info_get_result (const GstDiscovererInfo *info);

Parameters

info

a GstDiscovererInfo

 

Returns

the result of the discovery as a GstDiscovererResult.


gst_discoverer_info_get_stream_info ()

GstDiscovererStreamInfo *
gst_discoverer_info_get_stream_info (GstDiscovererInfo *info);

Parameters

info

a GstDiscovererInfo

 

Returns

the structure (or topology) of the URI as a GstDiscovererStreamInfo. This structure can be traversed to see the original hierarchy. Unref with gst_discoverer_stream_info_unref() after usage.

[transfer full]


gst_discoverer_info_get_stream_list ()

GList *
gst_discoverer_info_get_stream_list (GstDiscovererInfo *info);

Parameters

info

a GstDiscovererInfo

 

Returns

the list of all streams contained in the info. Free after usage with gst_discoverer_stream_info_list_free().

[transfer full][element-type GstPbutils.DiscovererStreamInfo]


gst_discoverer_info_get_tags ()

const GstTagList *
gst_discoverer_info_get_tags (const GstDiscovererInfo *info);

Parameters

info

a GstDiscovererInfo

 

Returns

all tags contained in the URI. If you wish to use the tags after the life-time of info , you will need to copy them.

[transfer none]


gst_discoverer_info_get_toc ()

const GstToc *
gst_discoverer_info_get_toc (const GstDiscovererInfo *info);

Parameters

info

a GstDiscovererInfo

 

Returns

TOC contained in the URI. If you wish to use the TOC after the life-time of info , you will need to copy it.

[transfer none]


gst_discoverer_info_get_uri ()

const gchar *
gst_discoverer_info_get_uri (const GstDiscovererInfo *info);

Parameters

info

a GstDiscovererInfo

 

Returns

the URI to which this information corresponds to. Copy it if you wish to use it after the life-time of info .

[transfer none]


gst_discoverer_info_get_seekable ()

gboolean
gst_discoverer_info_get_seekable (const GstDiscovererInfo *info);

Parameters

info

a GstDiscovererInfo

 

Returns

the whether the URI is seekable.


gst_discoverer_info_ref()

#define gst_discoverer_info_ref(info) (g_object_ref((Gbject*)info))

Increments the reference count of info .

Parameters

info

a GstDiscovererInfo

 

Returns

the same GstDiscovererInfo object


gst_discoverer_info_unref()

#define gst_discoverer_info_unref(info) (g_object_unref((GObject*)info))

Decrements the reference count of info .

Parameters

info

a GstDiscovererInfo

 

gst_discoverer_stream_info_get_caps ()

GstCaps *
gst_discoverer_stream_info_get_caps (GstDiscovererStreamInfo *info);

Parameters

Returns

the GstCaps of the stream. Unref with gst_caps_unref after usage.

[transfer full]


gst_discoverer_stream_info_get_misc ()

const GstStructure *
gst_discoverer_stream_info_get_misc (GstDiscovererStreamInfo *info);

gst_discoverer_stream_info_get_misc is deprecated and should not be used in newly-written code.

This functions is deprecated since version 1.4, use gst_discoverer_stream_get_missing_elements_installer_details

Parameters

Returns

additional information regarding the stream (for example codec version, profile, etc..). If you wish to use the GstStructure after the life-time of info you will need to copy it.

[transfer none]


gst_discoverer_stream_info_get_next ()

GstDiscovererStreamInfo *
gst_discoverer_stream_info_get_next (GstDiscovererStreamInfo *info);

Parameters

Returns

the next GstDiscovererStreamInfo in a chain. NULL for final streams. Unref with gst_discoverer_stream_info_unref after usage.

[transfer full]


gst_discoverer_stream_info_get_previous ()

GstDiscovererStreamInfo *
gst_discoverer_stream_info_get_previous
                               (GstDiscovererStreamInfo *info);

Parameters

Returns

the previous GstDiscovererStreamInfo in a chain. NULL for starting points. Unref with gst_discoverer_stream_info_unref after usage.

[transfer full]


gst_discoverer_stream_info_get_tags ()

const GstTagList *
gst_discoverer_stream_info_get_tags (GstDiscovererStreamInfo *info);

Parameters

Returns

the tags contained in this stream. If you wish to use the tags after the life-time of info you will need to copy them.

[transfer none]


gst_discoverer_stream_info_get_toc ()

const GstToc *
gst_discoverer_stream_info_get_toc (GstDiscovererStreamInfo *info);

Parameters

Returns

the TOC contained in this stream. If you wish to use the TOC after the life-time of info you will need to copy it.

[transfer none]


gst_discoverer_stream_info_get_stream_id ()

const gchar *
gst_discoverer_stream_info_get_stream_id
                               (GstDiscovererStreamInfo *info);

Parameters

Returns

the stream ID of this stream. If you wish to use the stream ID after the life-time of info you will need to copy it.

[transfer none]


gst_discoverer_stream_info_ref()

#define gst_discoverer_stream_info_ref(info) ((GstDiscovererStreamInfo*) g_object_ref((GObject*) info))

Increments the reference count of info .

Parameters

Returns

the same GstDiscovererStreamInfo object


gst_discoverer_stream_info_unref()

#define gst_discoverer_stream_info_unref(info) (g_object_unref((GObject*) info))

Decrements the reference count of info .

Parameters


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.

Parameters

infos

a GList of GstDiscovererStreamInfo.

[element-type GstPbutils.DiscovererStreamInfo]

gst_discoverer_stream_info_get_stream_type_nick ()

const gchar *
gst_discoverer_stream_info_get_stream_type_nick
                               (GstDiscovererStreamInfo *info);

Parameters

Returns

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


gst_discoverer_info_get_missing_elements_installer_details ()

const gchar **
gst_discoverer_info_get_missing_elements_installer_details
                               (const GstDiscovererInfo *info);

Get the installer details for missing elements

Parameters

info

a GstDiscovererStreamInfo to retrieve installer detail for the missing element

 

Returns

An array of strings containing informations about how to install the various missing elements for info to be usable. Free with g_strfreev().

[transfer full][array zero-terminated=1]

Since 1.4


gst_discoverer_info_get_audio_streams ()

GList *
gst_discoverer_info_get_audio_streams (GstDiscovererInfo *info);

Finds all the GstDiscovererAudioInfo contained in info

Parameters

info

a GstDiscovererInfo

 

Returns

A GList of matching GstDiscovererStreamInfo. The caller should free it with gst_discoverer_stream_info_list_free().

[transfer full][element-type GstPbutils.DiscovererStreamInfo]


gst_discoverer_info_get_container_streams ()

GList *
gst_discoverer_info_get_container_streams
                               (GstDiscovererInfo *info);

Finds all the GstDiscovererContainerInfo contained in info

Parameters

info

a GstDiscovererInfo

 

Returns

A GList of matching GstDiscovererStreamInfo. The caller should free it with gst_discoverer_stream_info_list_free().

[transfer full][element-type GstPbutils.DiscovererStreamInfo]


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 .

Parameters

info

a GstDiscovererInfo

 

streamtype

a GType derived from GstDiscovererStreamInfo

 

Returns

A GList of matching GstDiscovererStreamInfo. The caller should free it with gst_discoverer_stream_info_list_free().

[transfer full][element-type GstPbutils.DiscovererStreamInfo]


gst_discoverer_info_get_subtitle_streams ()

GList *
gst_discoverer_info_get_subtitle_streams
                               (GstDiscovererInfo *info);

Finds all the GstDiscovererSubtitleInfo contained in info

Parameters

info

a GstDiscovererInfo

 

Returns

A GList of matching GstDiscovererStreamInfo. The caller should free it with gst_discoverer_stream_info_list_free().

[transfer full][element-type GstPbutils.DiscovererStreamInfo]


gst_discoverer_info_get_video_streams ()

GList *
gst_discoverer_info_get_video_streams (GstDiscovererInfo *info);

Finds all the GstDiscovererVideoInfo contained in info

Parameters

info

a GstDiscovererInfo

 

Returns

A GList of matching GstDiscovererStreamInfo. The caller should free it with gst_discoverer_stream_info_list_free().

[transfer full][element-type GstPbutils.DiscovererStreamInfo]


gst_discoverer_audio_info_get_bitrate ()

guint
gst_discoverer_audio_info_get_bitrate (const GstDiscovererAudioInfo *info);

Parameters

Returns

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


gst_discoverer_audio_info_get_channels ()

guint
gst_discoverer_audio_info_get_channels
                               (const GstDiscovererAudioInfo *info);

Parameters

Returns

the number of channels in the stream.


gst_discoverer_audio_info_get_depth ()

guint
gst_discoverer_audio_info_get_depth (const GstDiscovererAudioInfo *info);

Parameters

Returns

the number of bits used per sample in each channel.


gst_discoverer_audio_info_get_language ()

const gchar *
gst_discoverer_audio_info_get_language
                               (const GstDiscovererAudioInfo *info);

Parameters

Returns

the language of the stream, or NULL if unknown.


gst_discoverer_audio_info_get_max_bitrate ()

guint
gst_discoverer_audio_info_get_max_bitrate
                               (const GstDiscovererAudioInfo *info);

Parameters

Returns

the maximum bitrate of the stream in bits/second.


gst_discoverer_audio_info_get_sample_rate ()

guint
gst_discoverer_audio_info_get_sample_rate
                               (const GstDiscovererAudioInfo *info);

Parameters

Returns

the sample rate of the stream in Hertz.


gst_discoverer_container_info_get_streams ()

GList *
gst_discoverer_container_info_get_streams
                               (GstDiscovererContainerInfo *info);

Parameters

Returns

the list of GstDiscovererStreamInfo this container stream offers. Free with gst_discoverer_stream_info_list_free() after usage.

[transfer full][element-type GstPbutils.DiscovererStreamInfo]


gst_discoverer_subtitle_info_get_language ()

const gchar *
gst_discoverer_subtitle_info_get_language
                               (const GstDiscovererSubtitleInfo *info);

Parameters

Returns

the language of the stream, or NULL if unknown.


gst_discoverer_video_info_get_bitrate ()

guint
gst_discoverer_video_info_get_bitrate (const GstDiscovererVideoInfo *info);

Parameters

Returns

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


gst_discoverer_video_info_get_depth ()

guint
gst_discoverer_video_info_get_depth (const GstDiscovererVideoInfo *info);

Parameters

Returns

the depth in bits of the video stream.


gst_discoverer_video_info_get_framerate_denom ()

guint
gst_discoverer_video_info_get_framerate_denom
                               (const GstDiscovererVideoInfo *info);

Parameters

Returns

the framerate of the video stream (denominator).


gst_discoverer_video_info_get_framerate_num ()

guint
gst_discoverer_video_info_get_framerate_num
                               (const GstDiscovererVideoInfo *info);

Parameters

Returns

the framerate of the video stream (numerator).


gst_discoverer_video_info_get_height ()

guint
gst_discoverer_video_info_get_height (const GstDiscovererVideoInfo *info);

Parameters

Returns

the height of the video stream in pixels.


gst_discoverer_video_info_is_interlaced ()

gboolean
gst_discoverer_video_info_is_interlaced
                               (const GstDiscovererVideoInfo *info);

Parameters

Returns

TRUE if the stream is interlaced, else FALSE.


gst_discoverer_video_info_is_image ()

gboolean
gst_discoverer_video_info_is_image (const GstDiscovererVideoInfo *info);

Parameters

Returns

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


gst_discoverer_video_info_get_max_bitrate ()

guint
gst_discoverer_video_info_get_max_bitrate
                               (const GstDiscovererVideoInfo *info);

Parameters

Returns

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


gst_discoverer_video_info_get_par_denom ()

guint
gst_discoverer_video_info_get_par_denom
                               (const GstDiscovererVideoInfo *info);

Parameters

Returns

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


gst_discoverer_video_info_get_par_num ()

guint
gst_discoverer_video_info_get_par_num (const GstDiscovererVideoInfo *info);

Parameters

Returns

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


gst_discoverer_video_info_get_width ()

guint
gst_discoverer_video_info_get_width (const GstDiscovererVideoInfo *info);

Parameters

Returns

the width of the video stream in pixels.

Types and Values

struct GstDiscoverer

struct GstDiscoverer;

The GstDiscoverer structure.


GstDiscovererInfo

typedef struct _GstDiscovererInfo GstDiscovererInfo;

Structure containing the information of a URI analyzed by GstDiscoverer.


enum GstDiscovererResult

Result values for the discovery process.

Members

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

 

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.


GstDiscovererContainerInfo

typedef struct _GstDiscovererContainerInfo GstDiscovererContainerInfo;

GstDiscovererStreamInfo specific to container streams.


GstDiscovererAudioInfo

typedef struct _GstDiscovererAudioInfo GstDiscovererAudioInfo;

GstDiscovererStreamInfo specific to audio streams.


GstDiscovererVideoInfo

typedef struct _GstDiscovererVideoInfo GstDiscovererVideoInfo;

GstDiscovererStreamInfo specific to video streams (this includes images).


GstDiscovererSubtitleInfo

typedef struct _GstDiscovererSubtitleInfo GstDiscovererSubtitleInfo;

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

Property Details

The “timeout” property

  “timeout”                  guint64

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.

Flags: Read / Write / Construct

Allowed values: [1000000000,3600000000000]

Default value: 15000000000

Signal Details

The “discovered” signal

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

Will be emitted in async mode when all information on a URI could be discovered, or an error occurred.

When an error occurs, info might still contain some partial information, depending on the circumstances of the error.

Parameters

discoverer

the GstDiscoverer

 

info

the results GstDiscovererInfo

 

error

GError, which will be non-NULL if an error occurred during discovery. You must not free this GError, it will be freed by the discoverer.

[type GLib.Error]

user_data

user data set when the signal handler was connected.

 

Flags: Run Last


The “finished” signal

void
user_function (GstDiscoverer *discoverer,
               gpointer       user_data)

Will be emitted in async mode when all pending URIs have been processed.

Parameters

discoverer

the GstDiscoverer

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last


The “source-setup” signal

void
user_function (GstDiscoverer *discoverer,
               GstElement    *source,
               gpointer       user_data)

This signal is emitted after the source element has been created for, so the URI being discovered, so it can be configured by setting additional properties (e.g. set a proxy server for an http source, or set the device and read speed for an audio cd source).

This signal is usually emitted from the context of a GStreamer streaming thread.

Parameters

discoverer

the GstDiscoverer

 

source

source element

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last


The “starting” signal

void
user_function (GstDiscoverer *discoverer,
               gpointer       user_data)

Will be emitted when the discover starts analyzing the pending URIs

Parameters

discoverer

the GstDiscoverer

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last