gstreamer-rs/docs/gstreamer-pbutils/docs.md

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

glib::object::ObjectExt

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

glib::object::ObjectExt

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 information 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

You can use these flags to control what is serialized by DiscovererInfo::to_variant

Serialize only basic information, excluding caps, tags and miscellaneous information

Serialize the caps for each stream

Serialize the tags for each stream

Serialize miscellaneous information for each stream

Serialize all the available info, including caps, tags and miscellaneous information

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 EncodingProfile::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

EncodingProfileExt, glib::object::ObjectExt

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

Feature: v1_12

Returns

The copy of self

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.

Feature: v1_18

Returns

true if the stream represented by self should use a single segment before the encoder, false otherwise. This means that buffers will be retimestamped and segments will be eat so as to appear as one segment.

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.

enabled

false to disable self, 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 EncodingProfile::get_restriction for more about restrictions. Does not apply to EncodingContainerProfile.

restriction

the restriction to apply

If using a single segment, buffers will be retimestamped and segments will be eat so as to appear as one segment.

NOTE: Single segment is not property supported when using encodebin:avoid-reencoding

Feature: v1_18

single_segment

true if the stream represented by self should use a single segment before the encoder, false otherwise.

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

glib::object::ObjectExt

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 should be one of the existing well-defined categories, like GST_ENCODING_CATEGORY_DEVICE, but it can 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.

Feature: v1_18

Returns

The path to the self file.

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 EncodingProfile::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

NOTE: Fixed framerate won't be enforced when encodebin:avoid-reencoding is set.

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