28 KiB
The Discoverer 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 Discoverer::discover_uri
with the URI one wishes to discover.
The non-blocking mode requires a running glib::MainLoop iterating a
glib::MainContext, where one connects to the various signals, appends the
URIs to be processed (through Discoverer::discover_uri_async) and then
asks for the discovery to begin (through Discoverer::start).
By default this will use the GLib default main context unless you have
set a custom context using glib::MainContext::push_thread_default.
All the information is returned in a DiscovererInfo structure.
Implements
Creates a new Discoverer with the provided timeout.
timeout
timeout per file, in nanoseconds. Allowed are values between
one second (GST_SECOND) and one hour (3600 * GST_SECOND)
Returns
The new Discoverer.
If an error occurred when creating the discoverer, err will be set
accordingly and None will be returned. If err is set, the caller must
free it when no longer needed using glib::Error::free.
Synchronously discovers the given uri.
A copy of uri will be made internally, so the caller can safely g_free
afterwards.
uri
The URI to run on.
Returns
the result of the scanning. Can be None if an
error occurred.
Appends the given uri to the list of URIs to discoverer. The actual
discovery of the uri will only take place if Discoverer::start has
been called.
A copy of uri will be made internally, so the caller can safely g_free
afterwards.
uri
the URI to add.
Returns
true if the uri was successfully appended to the list of pending
uris, else false
Allow asynchronous discovering of URIs to take place.
A glib::MainLoop must be available for Discoverer to properly work in
asynchronous mode.
Stop the discovery of any pending URIs and clears the list of pending URIS (if any).
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.
info
the results DiscovererInfo
error
glib::Error, which will be non-NULL
if an error occurred during
discovery. You must not free
this glib::Error, it will be freed by
the discoverer.
Will be emitted in async mode when all pending URIs have been processed.
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.
source
source element
Will be emitted when the discover starts analyzing the pending URIs
The duration (in nanoseconds) after which the discovery of an individual URI will timeout.
If the discovery of a URI times out, the DiscovererResult::Timeout will be
set on the result flags.
The duration (in nanoseconds) after which the discovery of an individual URI will timeout.
If the discovery of a URI times out, the DiscovererResult::Timeout will be
set on the result flags.
DiscovererStreamInfo specific to audio streams.
Implements
DiscovererStreamInfoExt, glib::object::ObjectExt
Returns
the average or nominal bitrate of the stream in bits/second.
Feature: v1_14
Returns
the channel-mask of the stream, refer to
gst_audio_channel_positions_from_mask for more
information.
Returns
the number of channels in the stream.
Returns
the number of bits used per sample in each channel.
Returns
the language of the stream, or NULL if unknown.
Returns
the maximum bitrate of the stream in bits/second.
Returns
the sample rate of the stream in Hertz.
DiscovererStreamInfo specific to container streams.
Implements
DiscovererStreamInfoExt, glib::object::ObjectExt
Returns
the list of
DiscovererStreamInfo this container stream offers.
Free with DiscovererStreamInfo::list_free after usage.
Structure containing the information of a URI analyzed by Discoverer.
Implements
Parses a glib::Variant as produced by DiscovererInfo::to_variant
back to a DiscovererInfo.
variant
A glib::Variant to deserialize into a DiscovererInfo.
Returns
A newly-allocated DiscovererInfo.
Returns
A copy of the DiscovererInfo
Finds all the DiscovererAudioInfo contained in self
Returns
A glib::List of
matching DiscovererStreamInfo. The caller should free it with
DiscovererStreamInfo::list_free.
Finds all the DiscovererContainerInfo contained in self
Returns
A glib::List of
matching DiscovererStreamInfo. The caller should free it with
DiscovererStreamInfo::list_free.
Returns
the duration of the URI in gst::ClockTime (nanoseconds).
Feature: v1_14
Returns
whether the URI is live.
Deprecated
This functions is deprecated since version 1.4, use
DiscovererInfo::get_missing_elements_installer_details
Returns
Miscellaneous information stored as a gst::Structure
(for example: information about missing plugins). If you wish to use the
gst::Structure after the life-time of self, you will need to copy it.
Get the installer details for missing elements
Returns
An array of strings
containing informations about how to install the various missing elements
for self to be usable. If you wish to use the strings after the life-time
of self, you will need to copy them.
Returns
the result of the discovery as a DiscovererResult.
Returns
the whether the URI is seekable.
Returns
the structure (or topology) of the URI as a
DiscovererStreamInfo.
This structure can be traversed to see the original hierarchy. Unref with
gst_discoverer_stream_info_unref after usage.
Returns
the list of
all streams contained in the info. Free after usage
with DiscovererStreamInfo::list_free.
Finds the DiscovererStreamInfo contained in self that match the
given streamtype.
streamtype
a glib::Type derived from DiscovererStreamInfo
Returns
A glib::List of
matching DiscovererStreamInfo. The caller should free it with
DiscovererStreamInfo::list_free.
Finds all the DiscovererSubtitleInfo contained in self
Returns
A glib::List of
matching DiscovererStreamInfo. The caller should free it with
DiscovererStreamInfo::list_free.
Returns
all tags contained in the URI. If you wish to use
the tags after the life-time of self, you will need to copy them.
Returns
TOC contained in the URI. If you wish to use
the TOC after the life-time of self, you will need to copy it.
Returns
the URI to which this information corresponds to.
Copy it if you wish to use it after the life-time of self.
Finds all the DiscovererVideoInfo contained in self
Returns
A glib::List of
matching DiscovererStreamInfo. The caller should free it with
DiscovererStreamInfo::list_free.
Serializes self to a glib::Variant that can be parsed again
through DiscovererInfo::from_variant.
Note that any gst::Toc (s) that might have been discovered will not be serialized
for now.
flags
A combination of DiscovererSerializeFlags to specify
what needs to be serialized.
Returns
A newly-allocated glib::Variant representing self.
Result values for the discovery process.
The discovery was successful
the URI is invalid
an error happened and the GError is set
the discovery timed-out
the discoverer was already discovering a file
Some plugins are missing for full discovery
Base structure for information concerning a media stream. Depending on the
stream type, one can find more media-specific information in
DiscovererAudioInfo, DiscovererVideoInfo, and
DiscovererContainerInfo.
The DiscovererStreamInfo represents the topology of the stream. Siblings
can be iterated over with DiscovererStreamInfoExt::get_next and
DiscovererStreamInfoExt::get_previous. Children (sub-streams) of a
stream can be accessed using the DiscovererContainerInfo API.
As a simple example, if you run Discoverer on an AVI file with one audio
and one video stream, you will get a DiscovererContainerInfo
corresponding to the AVI container, which in turn will have a
DiscovererAudioInfo sub-stream and a DiscovererVideoInfo sub-stream
for the audio and video streams respectively.
Implements
DiscovererStreamInfoExt, glib::object::ObjectExt
Trait containing all DiscovererStreamInfo methods.
Implementors
DiscovererAudioInfo, DiscovererContainerInfo, DiscovererStreamInfo, DiscovererSubtitleInfo, DiscovererVideoInfo
Decrements the reference count of all contained DiscovererStreamInfo
and fress the glib::List.
infos
a glib::List of DiscovererStreamInfo
Returns
the gst::Caps of the stream. Unref with
gst_caps_unref after usage.
Deprecated
This functions is deprecated since version 1.4, use
DiscovererInfo::get_missing_elements_installer_details
Returns
additional information regarding the stream (for
example codec version, profile, etc..). If you wish to use the gst::Structure
after the life-time of self you will need to copy it.
Returns
the next DiscovererStreamInfo in a chain. None
for final streams.
Unref with gst_discoverer_stream_info_unref after usage.
Returns
the previous DiscovererStreamInfo in a chain.
None for starting points. Unref with gst_discoverer_stream_info_unref
after usage.
Returns
the stream ID of this stream. If you wish to
use the stream ID after the life-time of self you will need to copy it.
Returns
a human readable name for the stream type of the given self (ex : "audio",
"container",...).
Returns
the tags contained in this stream. If you wish to
use the tags after the life-time of self you will need to copy them.
Returns
the TOC contained in this stream. If you wish to
use the TOC after the life-time of self you will need to copy it.
DiscovererStreamInfo specific to subtitle streams (this includes text and
image based ones).
Implements
DiscovererStreamInfoExt, glib::object::ObjectExt
Returns
the language of the stream, or NULL if unknown.
DiscovererStreamInfo specific to video streams (this includes images).
Implements
DiscovererStreamInfoExt, glib::object::ObjectExt
Returns
the average or nominal bitrate of the video stream in bits/second.
Returns
the depth in bits of the video stream.
Returns
the framerate of the video stream (denominator).
Returns
the framerate of the video stream (numerator).
Returns
the height of the video stream in pixels.
Returns
the maximum bitrate of the video stream in bits/second.
Returns
the Pixel Aspect Ratio (PAR) of the video stream (denominator).
Returns
the Pixel Aspect Ratio (PAR) of the video stream (numerator).
Returns
the width of the video stream in pixels.
Returns
true if the video stream corresponds to an image (i.e. only contains
one frame).
Returns
true if the stream is interlaced, else false.
Variant of EncodingProfile for audio streams.
Implements
EncodingProfileExt, glib::object::ObjectExt
Creates a new EncodingAudioProfile
All provided allocatable arguments will be internally copied, so can be safely freed/unreferenced after calling this method.
format
the gst::Caps
preset
the preset(s) to use on the encoder, can be None
restriction
the gst::Caps used to restrict the input to the encoder, can be
NULL. See EncodingProfileExt::get_restriction for more details.
presence
the number of time this stream must be used. 0 means any number of times (including never)
Returns
the newly created EncodingAudioProfile.
Encoding profiles for containers. Keeps track of a list of EncodingProfile
Implements
EncodingContainerProfileExt, EncodingProfileExt, glib::object::ObjectExt
Trait containing all EncodingContainerProfile methods.
Implementors
Creates a new EncodingContainerProfile.
name
The name of the container profile, can be None
description
The description of the container profile,
can be None
format
The format to use for this profile
preset
The preset to use for this profile.
Returns
The newly created EncodingContainerProfile.
Add a EncodingProfile to the list of profiles handled by self.
No copy of profile will be made, if you wish to use it elsewhere after this
method you should increment its reference count.
profile
the EncodingProfile to add.
Returns
true if the stream was properly added, else false.
Checks if self contains a EncodingProfile identical to
profile.
profile
a EncodingProfile
Returns
true if self contains a EncodingProfile identical
to profile, else false.
Returns
the list of contained EncodingProfile.
The opaque base class object for all encoding profiles. This contains generic information like name, description, format and preset.
Implements
EncodingProfileExt, glib::object::ObjectExt
Trait containing all EncodingProfile methods.
Implementors
EncodingAudioProfile, EncodingContainerProfile, EncodingProfile, EncodingVideoProfile
Find the EncodingProfile with the specified name and category.
targetname
The name of the target
profilename
The name of the profile, if None
provided, it will default to the encoding profile called default.
category
The target category. Can be None
Returns
The matching EncodingProfile or None.
Creates a EncodingProfile matching the formats from the given
DiscovererInfo. Streams other than audio or video (eg,
subtitles), are currently ignored.
info
The DiscovererInfo to read from
Returns
The new EncodingProfile or None.
Makes a deep copy of self
Returns
The copy of self
Since 1.12
Get whether the format that has been negotiated in at some point can be renegotiated later during the encoding.
Returns
the description of the profile, can be None.
Returns
a suitable file extension for self, or NULL.
Returns
the gst::Caps corresponding to the media format used
in the profile. Unref after usage.
Computes the full output caps that this self will be able to consume.
Returns
The full caps the given self can consume. Call
gst_caps_unref when you are done with the caps.
Returns
the name of the profile, can be None.
Returns
The number of times the profile is used in its parent container profile. If 0, it is not a mandatory stream.
Returns
the name of the gst::Preset to be used in the profile.
This is the name that has been set when saving the preset.
Returns
the name of the gst::Preset factory to be used in the profile.
Returns
The restriction gst::Caps to apply before the encoder
that will be used in the profile. The fields present in restriction caps are
properties of the raw stream (that is before encoding), such as height and
width for video and depth and sampling rate for audio. Does not apply to
EncodingContainerProfile (since there is no corresponding raw stream).
Can be None. Unref after usage.
Returns
the human-readable name of the type of self.
Checks whether the two EncodingProfile are equal
b
a EncodingProfile
Returns
true if self and b are equal, else false.
Sets whether the format that has been negotiated in at some point can be renegotiated later during the encoding.
allow_dynamic_output
Whether the format that has been negotiated first can be renegotiated during the encoding
Set description as the given description for the self. A copy of
description will be made internally.
description
the description to set on the profile
Set whether the profile should be used or not.
Since 1.6
enabled
false to disable profile, true to enable it
Sets the media format used in the profile.
format
the media format to use in the profile.
Set name as the given name for the self. A copy of name will be made
internally.
name
the name to set on the profile
Set the number of time the profile is used in its parent container profile. If 0, it is not a mandatory stream
presence
the number of time the profile can be used
Sets the name of the gst::Element that implements the gst::Preset interface
to use for the profile.
This is the name that has been set when saving the preset.
preset
the element preset to use
Sets the name of the gst::Preset's factory to be used in the profile.
preset_name
The name of the preset to use in this self.
Set the restriction gst::Caps to apply before the encoder
that will be used in the profile. See EncodingProfileExt::get_restriction
for more about restrictions. Does not apply to EncodingContainerProfile.
restriction
the restriction to apply
Collection of EncodingProfile for a specific target or use-case.
When being stored/loaded, targets come from a specific category, like
GST_ENCODING_CATEGORY_DEVICE.
Implements
Creates a new EncodingTarget.
The name and category can only consist of lowercase ASCII letters for the first character, followed by either lowercase ASCII letters, digits or hyphens ('-').
The category <emphasis>should</emphasis> be one of the existing
well-defined categories, like GST_ENCODING_CATEGORY_DEVICE, but it
<emphasis>can</emphasis> be a application or user specific category if
needed.
name
The name of the target.
category
The name of the category to which this target
belongs. For example: GST_ENCODING_CATEGORY_DEVICE.
description
A description of EncodingTarget in the
current locale.
profiles
A glib::List of
EncodingProfile.
Returns
The newly created EncodingTarget or None if
there was an error.
Searches for the EncodingTarget with the given name, loads it
and returns it.
If the category name is specified only targets from that category will be searched for.
name
the name of the EncodingTarget to load (automatically
converted to lower case internally as capital letters are not
valid for target names).
category
the name of the target category, like
GST_ENCODING_CATEGORY_DEVICE. Can be None
Returns
The EncodingTarget if available, else None.
Opens the provided file and returns the contained EncodingTarget.
filepath
The file location to load the EncodingTarget from
Returns
The EncodingTarget contained in the file, else
None
Adds the given profile to the self. Each added profile must have
a unique name within the profile.
The self will steal a reference to the profile. If you wish to use
the profile after calling this method, you should increase its reference
count.
profile
the EncodingProfile to add
Returns
true if the profile was added, else false.
Returns
The category of the self. For example:
GST_ENCODING_CATEGORY_DEVICE.
Returns
The description of the self.
Returns
The name of the self.
name
the name of the profile to retrieve
Returns
The matching EncodingProfile, or None.
Returns
A list of
EncodingProfile(s) this self handles.
Saves the self to a default user-local directory.
Returns
true if the target was correctly saved, else false.
Saves the self to the provided file location.
filepath
the location to store the self at.
Returns
true if the target was correctly saved, else false.
Variant of EncodingProfile for video streams, allows specifying the pass.
Implements
EncodingProfileExt, glib::object::ObjectExt
Creates a new EncodingVideoProfile
All provided allocatable arguments will be internally copied, so can be safely freed/unreferenced after calling this method.
If you wish to control the pass number (in case of multi-pass scenarios),
please refer to the EncodingVideoProfile::set_pass documentation.
If you wish to use/force a constant framerate please refer to the
EncodingVideoProfile::set_variableframerate documentation.
format
the gst::Caps
preset
the preset(s) to use on the encoder, can be None
restriction
the gst::Caps used to restrict the input to the encoder, can be
NULL. See EncodingProfileExt::get_restriction for more details.
presence
the number of time this stream must be used. 0 means any number of times (including never)
Returns
the newly created EncodingVideoProfile.
Get the pass number if this is part of a multi-pass profile.
Returns
The pass number. Starts at 1 for multi-pass. 0 if this is not a multi-pass profile
Returns
Whether non-constant video framerate is allowed for encoding.
Sets the pass number of this video profile. The first pass profile should have this value set to 1. If this video profile isn't part of a multi-pass profile, you may set it to 0 (the default value).
pass
the pass number for this profile
If set to true, then the incoming stream will be allowed to have non-constant
framerate. If set to false (default value), then the incoming stream will
be normalized by dropping/duplicating frames in order to produce a
constance framerate.
variableframerate
a boolean