Commit c81e177c authored by Thiago Sousa Santos's avatar Thiago Sousa Santos Committed by Sebastian Dröge

pbutils: add discoverer APIs

Fixes https://github.com/sdroege/gstreamer-rs/pull/84
parent e6265341
......@@ -11,6 +11,7 @@ members = [
"gstreamer-rtsp-server",
"gstreamer-sdp",
"gstreamer-video",
"gstreamer-pbutils",
"examples",
"tutorials",
]
[options]
girs_dir = "gir-files"
library = "GstPbutils"
version = "1.0"
min_cfg_version = "1.8"
target_path = "gstreamer-pbutils"
work_mode = "normal"
concurrency = "send+sync"
generate_safety_asserts = true
external_libraries = [
"GLib",
"GObject",
"Gst",
]
generate = [
"GstPbutils.DiscovererResult",
"GstPbutils.DiscovererSerializeFlags",
]
manual = [
"GLib.Error",
"GLib.Source",
"GLib.DateTime",
"GLib.Variant",
"GObject.Object",
"Gst.Object",
"Gst.Element",
]
[[object]]
name = "Gst.Toc"
status = "manual"
ref_mode = "ref"
[[object]]
name = "Gst.Caps"
status = "manual"
ref_mode = "ref"
[[object]]
name = "Gst.Message"
status = "manual"
ref_mode = "ref"
[[object]]
name = "Gst.Buffer"
status = "manual"
ref_mode = "ref"
[[object]]
name = "Gst.Event"
status = "manual"
ref_mode = "ref"
[[object]]
name = "Gst.TagList"
status = "manual"
ref_mode = "ref"
[[object]]
name = "Gst.Structure"
status = "manual"
ref_mode = "ref-mut"
[[object]]
name = "Gst.ClockTime"
status = "manual"
conversion_type = "scalar"
[[object]]
name = "GstPbutils.Discoverer"
status = "generate"
trait = false
[[object.function]]
name = "discover_uri_async"
[object.function.return]
bool_return_is_error = "Failed to add URI to list of discovers"
# Manually implemented to use ClockTime
[[object.property]]
name = "timeout"
ignore = true
[[object]]
name = "GstPbutils.DiscovererInfo"
status = "generate"
[[object.function]]
name = "copy"
[object.function.return]
nullable = false
[[object]]
name = "GstPbutils.DiscovererStreamInfo"
status = "generate"
# Not useful
[[object.function]]
name = "list_free"
ignore = true
[[object.function]]
name = "get_stream_type_nick"
[object.function.return]
nullable = false
[[object]]
name = "GstPbutils.DiscovererAudioInfo"
status = "generate"
trait = false
[[object]]
name = "GstPbutils.DiscovererVideoInfo"
status = "generate"
trait = false
# Implement manually to expose as gst::Fraction
[[object.function]]
name = "get_framerate_num"
ignore = true
[[object.function]]
name = "get_framerate_denom"
ignore = true
[[object.function]]
name = "get_par_num"
ignore = true
[[object.function]]
name = "get_par_denom"
ignore = true
[[object]]
name = "GstPbutils.DiscovererSubtitleInfo"
status = "generate"
trait = false
[[object]]
name = "GstPbutils.DiscovererContainerInfo"
status = "generate"
trait = false
<!-- file * -->
<!-- struct Discoverer -->
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 `DiscovererExt::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 `DiscovererExt::discover_uri_async`) and then
asks for the discovery to begin (through `DiscovererExt::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
[`DiscovererExt`](trait.DiscovererExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html)
<!-- trait DiscovererExt -->
Trait containing all `Discoverer` methods.
# Implementors
[`Discoverer`](struct.Discoverer.html)
<!-- impl Discoverer::fn new -->
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`.
<!-- trait DiscovererExt::fn discover_uri -->
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.
<!-- trait DiscovererExt::fn discover_uri_async -->
Appends the given `uri` to the list of URIs to discoverer. The actual
discovery of the `uri` will only take place if `DiscovererExt::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`
<!-- trait DiscovererExt::fn start -->
Allow asynchronous discovering of URIs to take place.
A `glib::MainLoop` must be available for `Discoverer` to properly work in
asynchronous mode.
<!-- trait DiscovererExt::fn stop -->
Stop the discovery of any pending URIs and clears the list of
pending URIS (if any).
<!-- trait DiscovererExt::fn connect_discovered -->
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.
<!-- trait DiscovererExt::fn connect_finished -->
Will be emitted in async mode when all pending URIs have been processed.
<!-- trait DiscovererExt::fn connect_source_setup -->
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
<!-- trait DiscovererExt::fn connect_starting -->
Will be emitted when the discover starts analyzing the pending URIs
<!-- trait DiscovererExt::fn get_property_timeout -->
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.
<!-- trait DiscovererExt::fn set_property_timeout -->
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.
<!-- struct DiscovererAudioInfo -->
`DiscovererStreamInfo` specific to audio streams.
# Implements
[`DiscovererStreamInfoExt`](trait.DiscovererStreamInfoExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html)
<!-- impl DiscovererAudioInfo::fn get_bitrate -->
# Returns
the average or nominal bitrate of the stream in bits/second.
<!-- impl DiscovererAudioInfo::fn get_channels -->
# Returns
the number of channels in the stream.
<!-- impl DiscovererAudioInfo::fn get_depth -->
# Returns
the number of bits used per sample in each channel.
<!-- impl DiscovererAudioInfo::fn get_language -->
# Returns
the language of the stream, or NULL if unknown.
<!-- impl DiscovererAudioInfo::fn get_max_bitrate -->
# Returns
the maximum bitrate of the stream in bits/second.
<!-- impl DiscovererAudioInfo::fn get_sample_rate -->
# Returns
the sample rate of the stream in Hertz.
<!-- struct DiscovererContainerInfo -->
`DiscovererStreamInfo` specific to container streams.
# Implements
[`DiscovererStreamInfoExt`](trait.DiscovererStreamInfoExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html)
<!-- impl DiscovererContainerInfo::fn get_streams -->
# Returns
the list of
`DiscovererStreamInfo` this container stream offers.
Free with `DiscovererStreamInfo::list_free` after usage.
<!-- struct DiscovererInfo -->
Structure containing the information of a URI analyzed by `Discoverer`.
# Implements
[`DiscovererInfoExt`](trait.DiscovererInfoExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html)
<!-- trait DiscovererInfoExt -->
Trait containing all `DiscovererInfo` methods.
# Implementors
[`DiscovererInfo`](struct.DiscovererInfo.html)
<!-- impl DiscovererInfo::fn from_variant -->
Parses a `glib::Variant` as produced by `DiscovererInfoExt::to_variant`
back to a `DiscovererInfo`.
## `variant`
A `glib::Variant` to deserialize into a `DiscovererInfo`.
# Returns
A newly-allocated `DiscovererInfo`.
<!-- trait DiscovererInfoExt::fn copy -->
# Returns
A copy of the `DiscovererInfo`
<!-- trait DiscovererInfoExt::fn get_audio_streams -->
Finds all the `DiscovererAudioInfo` contained in `self`
# Returns
A `glib::List` of
matching `DiscovererStreamInfo`. The caller should free it with
`DiscovererStreamInfo::list_free`.
<!-- trait DiscovererInfoExt::fn get_container_streams -->
Finds all the `DiscovererContainerInfo` contained in `self`
# Returns
A `glib::List` of
matching `DiscovererStreamInfo`. The caller should free it with
`DiscovererStreamInfo::list_free`.
<!-- trait DiscovererInfoExt::fn get_duration -->
# Returns
the duration of the URI in `gst::ClockTime` (nanoseconds).
<!-- trait DiscovererInfoExt::fn get_misc -->
# Deprecated
This functions is deprecated since version 1.4, use
`DiscovererInfoExt::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.
<!-- trait DiscovererInfoExt::fn get_missing_elements_installer_details -->
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.
<!-- trait DiscovererInfoExt::fn get_result -->
# Returns
the result of the discovery as a `DiscovererResult`.
<!-- trait DiscovererInfoExt::fn get_seekable -->
# Returns
the whether the URI is seekable.
<!-- trait DiscovererInfoExt::fn get_stream_info -->
# 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.
<!-- trait DiscovererInfoExt::fn get_stream_list -->
# Returns
the list of
all streams contained in the `info`. Free after usage
with `DiscovererStreamInfo::list_free`.
<!-- trait DiscovererInfoExt::fn get_streams -->
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`.
<!-- trait DiscovererInfoExt::fn get_subtitle_streams -->
Finds all the `DiscovererSubtitleInfo` contained in `self`
# Returns
A `glib::List` of
matching `DiscovererStreamInfo`. The caller should free it with
`DiscovererStreamInfo::list_free`.
<!-- trait DiscovererInfoExt::fn get_tags -->
# 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.
<!-- trait DiscovererInfoExt::fn get_toc -->
# 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.
<!-- trait DiscovererInfoExt::fn get_uri -->
# Returns
the URI to which this information corresponds to.
Copy it if you wish to use it after the life-time of `self`.
<!-- trait DiscovererInfoExt::fn get_video_streams -->
Finds all the `DiscovererVideoInfo` contained in `self`
# Returns
A `glib::List` of
matching `DiscovererStreamInfo`. The caller should free it with
`DiscovererStreamInfo::list_free`.
<!-- trait DiscovererInfoExt::fn to_variant -->
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`.
<!-- enum DiscovererResult -->
Result values for the discovery process.
<!-- enum DiscovererResult::variant Ok -->
The discovery was successful
<!-- enum DiscovererResult::variant UriInvalid -->
the URI is invalid
<!-- enum DiscovererResult::variant Error -->
an error happened and the GError is set
<!-- enum DiscovererResult::variant Timeout -->
the discovery timed-out
<!-- enum DiscovererResult::variant Busy -->
the discoverer was already discovering a file
<!-- enum DiscovererResult::variant MissingPlugins -->
Some plugins are missing for full discovery
<!-- struct DiscovererStreamInfo -->
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`](trait.DiscovererStreamInfoExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html)
<!-- trait DiscovererStreamInfoExt -->
Trait containing all `DiscovererStreamInfo` methods.
# Implementors
[`DiscovererAudioInfo`](struct.DiscovererAudioInfo.html), [`DiscovererContainerInfo`](struct.DiscovererContainerInfo.html), [`DiscovererStreamInfo`](struct.DiscovererStreamInfo.html), [`DiscovererSubtitleInfo`](struct.DiscovererSubtitleInfo.html), [`DiscovererVideoInfo`](struct.DiscovererVideoInfo.html)
<!-- impl DiscovererStreamInfo::fn list_free -->
Decrements the reference count of all contained `DiscovererStreamInfo`
and fress the `glib::List`.
## `infos`
a `glib::List` of `DiscovererStreamInfo`
<!-- trait DiscovererStreamInfoExt::fn get_caps -->
# Returns
the `gst::Caps` of the stream. Unref with
`gst_caps_unref` after usage.
<!-- trait DiscovererStreamInfoExt::fn get_misc -->
# Deprecated
This functions is deprecated since version 1.4, use
`DiscovererInfoExt::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.
<!-- trait DiscovererStreamInfoExt::fn get_next -->
# Returns
the next `DiscovererStreamInfo` in a chain. `None`
for final streams.
Unref with `gst_discoverer_stream_info_unref` after usage.
<!-- trait DiscovererStreamInfoExt::fn get_previous -->
# Returns
the previous `DiscovererStreamInfo` in a chain.
`None` for starting points. Unref with `gst_discoverer_stream_info_unref`
after usage.
<!-- trait DiscovererStreamInfoExt::fn get_stream_id -->
# 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.
<!-- trait DiscovererStreamInfoExt::fn get_stream_type_nick -->
# Returns
a human readable name for the stream type of the given `self` (ex : "audio",
"container",...).
<!-- trait DiscovererStreamInfoExt::fn get_tags -->
# 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.
<!-- trait DiscovererStreamInfoExt::fn get_toc -->
# 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.
<!-- struct DiscovererSubtitleInfo -->
`DiscovererStreamInfo` specific to subtitle streams (this includes text and
image based ones).
# Implements
[`DiscovererStreamInfoExt`](trait.DiscovererStreamInfoExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html)
<!-- impl DiscovererSubtitleInfo::fn get_language -->
# Returns
the language of the stream, or NULL if unknown.
<!-- struct DiscovererVideoInfo -->
`DiscovererStreamInfo` specific to video streams (this includes images).
# Implements
[`DiscovererStreamInfoExt`](trait.DiscovererStreamInfoExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html)
<!-- impl DiscovererVideoInfo::fn get_bitrate -->
# Returns
the average or nominal bitrate of the video stream in bits/second.
<!-- impl DiscovererVideoInfo::fn get_depth -->
# Returns
the depth in bits of the video stream.
<!-- impl DiscovererVideoInfo::fn get_framerate_denom -->
# Returns
the framerate of the video stream (denominator).
<!-- impl DiscovererVideoInfo::fn get_framerate_num -->
# Returns
the framerate of the video stream (numerator).
<!-- impl DiscovererVideoInfo::fn get_height -->
# Returns
the height of the video stream in pixels.
<!-- impl DiscovererVideoInfo::fn get_max_bitrate -->
# Returns
the maximum bitrate of the video stream in bits/second.
<!-- impl DiscovererVideoInfo::fn get_par_denom -->
# Returns
the Pixel Aspect Ratio (PAR) of the video stream (denominator).
<!-- impl DiscovererVideoInfo::fn get_par_num -->
# Returns
the Pixel Aspect Ratio (PAR) of the video stream (numerator).
<!-- impl DiscovererVideoInfo::fn get_width -->
# Returns
the width of the video stream in pixels.
<!-- impl DiscovererVideoInfo::fn is_image -->
# Returns
`true` if the video stream corresponds to an image (i.e. only contains
one frame).
<!-- impl DiscovererVideoInfo::fn is_interlaced -->
# Returns
`true` if the stream is interlaced, else `false`.