mirrors/gstreamer-rs
mirrors/gstreamer-rs
1
1
Fork 1
mirror of https://gitlab.freedesktop.org/gstreamer/gstreamer-rs.git synced 2024-12-23 00:26:31 +00:00
Code Issues Projects Releases Wiki Activity

Update docs

Browse source
This commit is contained in:
Sebastian Dröge 2017-08-17 13:10:30 +03:00
parent 165d85646f
commit 41e812d075
4 changed files with 382 additions and 78 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

110
docs/gstreamer-app/docs.md
View file

@ -8,10 +8,10 @@ appsink can be used by linking to the gstappsink.h header file to access the
methods or by using the appsink action signals and properties.
The normal way of retrieving samples from appsink is by using the
`AppSinkExt::pull_sample` and `AppSinkExt::pull_preroll` methods.
`AppSink::pull_sample` and `AppSink::pull_preroll` methods.
These methods block until a sample becomes available in the sink or when the
sink is shut down or reaches EOS. There are also timed variants of these
methods, `AppSinkExt::try_pull_sample` and `AppSinkExt::try_pull_preroll`,
methods, `AppSink::try_pull_sample` and `AppSink::try_pull_preroll`,
which accept a timeout parameter to limit the amount of time to wait.
Appsink will internally use a queue to collect buffers from the streaming
@ -32,21 +32,15 @@ the pulled samples can be obtained by getting the sample caps.
If one of the pull-preroll or pull-sample methods return `None`, the appsink
is stopped or in the EOS state. You can check for the EOS state with the
"eos" property or with the `AppSinkExt::is_eos` method.
"eos" property or with the `AppSink::is_eos` method.
The eos signal can also be used to be informed when the EOS state is reached
to avoid polling.
# Implements
[`AppSinkExt`](trait.AppSinkExt.html), [`ObjectExt`](trait.ObjectExt.html)
<!-- trait AppSinkExt -->
Trait containing all `AppSink` methods.
# Implementors
[`AppSink`](struct.AppSink.html)
<!-- trait AppSinkExt::fn get_buffer_list_support -->
[`ElementExt`](trait.ElementExt.html), [`ObjectExt`](trait.ObjectExt.html), [`ObjectExt`](trait.ObjectExt.html)
<!-- impl AppSink::fn get_buffer_list_support -->
Check if `self` supports buffer lists.
Feature: `v1_12`
@ -55,13 +49,13 @@ Feature: `v1_12`
# Returns
`true` if `self` supports buffer lists.
<!-- trait AppSinkExt::fn get_caps -->
<!-- impl AppSink::fn get_caps -->
Get the configured caps on `self`.
# Returns
the `gst::Caps` accepted by the sink. `gst_caps_unref` after usage.
<!-- trait AppSinkExt::fn get_drop -->
<!-- impl AppSink::fn get_drop -->
Check if `self` will drop old buffers when the maximum amount of queued
buffers is reached.
@ -69,20 +63,20 @@ buffers is reached.
`true` if `self` is dropping old buffers when the queue is
filled.
<!-- trait AppSinkExt::fn get_emit_signals -->
<!-- impl AppSink::fn get_emit_signals -->
Check if appsink will emit the "new-preroll" and "new-sample" signals.
# Returns
`true` if `self` is emiting the "new-preroll" and "new-sample"
signals.
<!-- trait AppSinkExt::fn get_max_buffers -->
<!-- impl AppSink::fn get_max_buffers -->
Get the maximum amount of buffers that can be queued in `self`.
# Returns
The maximum amount of buffers that can be queued.
<!-- trait AppSinkExt::fn get_wait_on_eos -->
<!-- impl AppSink::fn get_wait_on_eos -->
Check if `self` will wait for all buffers to be consumed when an EOS is
received.
@ -90,7 +84,7 @@ received.
`true` if `self` will wait for all buffers to be consumed when an
EOS is received.
<!-- trait AppSinkExt::fn is_eos -->
<!-- impl AppSink::fn is_eos -->
Check if `self` is EOS, which is when no more samples can be pulled because
an EOS event was received.
@ -100,7 +94,7 @@ PLAYING state.
# Returns
`true` if no more samples can be pulled and the appsink is EOS.
<!-- trait AppSinkExt::fn pull_preroll -->
<!-- impl AppSink::fn pull_preroll -->
Get the last preroll sample in `self`. This was the sample that caused the
appsink to preroll in the PAUSED state. This sample can be pulled many times
and remains available to the application even after EOS.
@ -110,7 +104,7 @@ state. Calling this function after doing a seek will give the sample right
after the seek position.
Note that the preroll sample will also be returned as the first sample
when calling `AppSinkExt::pull_sample`.
when calling `AppSink::pull_sample`.
If an EOS event was received before any buffers, this function returns
`None`. Use gst_app_sink_is_eos () to check for the EOS condition.
@ -122,7 +116,7 @@ element is set to the READY/NULL state.
a `gst::Sample` or NULL when the appsink is stopped or EOS.
Call `gst_sample_unref` after usage.
<!-- trait AppSinkExt::fn pull_sample -->
<!-- impl AppSink::fn pull_sample -->
This function blocks until a sample or EOS becomes available or the appsink
element is set to the READY/NULL state.
@ -139,7 +133,7 @@ If an EOS event was received before any buffers, this function returns
a `gst::Sample` or NULL when the appsink is stopped or EOS.
Call `gst_sample_unref` after usage.
<!-- trait AppSinkExt::fn set_buffer_list_support -->
<!-- impl AppSink::fn set_buffer_list_support -->
Instruct `self` to enable or disable buffer list support.
For backwards-compatibility reasons applications need to opt in
@ -149,7 +143,7 @@ Feature: `v1_12`
## `enable_lists`
enable or disable buffer list support
<!-- trait AppSinkExt::fn set_callbacks -->
<!-- impl AppSink::fn set_callbacks -->
Set callbacks which will be executed for each new preroll, new sample and eos.
This is an alternative to using the signals, it has lower overhead and is thus
less expensive, but also less flexible.
@ -162,35 +156,35 @@ the callbacks
a user_data argument for the callbacks
## `notify`
a destroy notify function
<!-- trait AppSinkExt::fn set_caps -->
<!-- impl AppSink::fn set_caps -->
Set the capabilities on the appsink element. This function takes
a copy of the caps structure. After calling this method, the sink will only
accept caps that match `caps`. If `caps` is non-fixed, or incomplete,
you must check the caps on the samples to get the actual used caps.
## `caps`
caps to set
<!-- trait AppSinkExt::fn set_drop -->
<!-- impl AppSink::fn set_drop -->
Instruct `self` to drop old buffers when the maximum amount of queued
buffers is reached.
## `drop`
the new state
<!-- trait AppSinkExt::fn set_emit_signals -->
<!-- impl AppSink::fn set_emit_signals -->
Make appsink emit the "new-preroll" and "new-sample" signals. This option is
by default disabled because signal emission is expensive and unneeded when
the application prefers to operate in pull mode.
## `emit`
the new state
<!-- trait AppSinkExt::fn set_max_buffers -->
<!-- impl AppSink::fn set_max_buffers -->
Set the maximum amount of buffers that can be queued in `self`. After this
amount of buffers are queued in appsink, any more buffers will block upstream
elements until a sample is pulled from `self`.
## `max`
the maximum number of buffers to queue
<!-- trait AppSinkExt::fn set_wait_on_eos -->
<!-- impl AppSink::fn set_wait_on_eos -->
Instruct `self` to wait for all buffers to be consumed when an EOS is received.
## `wait`
the new state
<!-- trait AppSinkExt::fn try_pull_preroll -->
<!-- impl AppSink::fn try_pull_preroll -->
Get the last preroll sample in `self`. This was the sample that caused the
appsink to preroll in the PAUSED state. This sample can be pulled many times
and remains available to the application even after EOS.
@ -200,7 +194,7 @@ state. Calling this function after doing a seek will give the sample right
after the seek position.
Note that the preroll sample will also be returned as the first sample
when calling `AppSinkExt::pull_sample`.
when calling `AppSink::pull_sample`.
If an EOS event was received before any buffers or the timeout expires,
this function returns `None`. Use gst_app_sink_is_eos () to check for the EOS
@ -218,7 +212,7 @@ the maximum amount of time to wait for the preroll sample
a `gst::Sample` or NULL when the appsink is stopped or EOS or the timeout expires.
Call `gst_sample_unref` after usage.
<!-- trait AppSinkExt::fn try_pull_sample -->
<!-- impl AppSink::fn try_pull_sample -->
This function blocks until a sample or EOS becomes available or the appsink
element is set to the READY/NULL state or the timeout expires.
@ -259,7 +253,7 @@ sample and sets them on the appsrc replacing any previously set caps (if
different from sample's caps).
The main way of handing data to the appsrc element is by calling the
`AppSrcExt::push_buffer` method or by emitting the push-buffer action signal.
`AppSrc::push_buffer` method or by emitting the push-buffer action signal.
This will put the buffer onto a queue from which appsrc will read from in its
streaming thread. It is important to note that data transport will not happen
from the thread that performed the push-buffer call.
@ -303,20 +297,14 @@ For the stream and seekable modes, setting this property is optional but
recommended.
When the application has finished pushing data into appsrc, it should call
`AppSrcExt::end_of_stream` or emit the end-of-stream action signal. After
`AppSrc::end_of_stream` or emit the end-of-stream action signal. After
this call, no more buffers can be pushed into appsrc until a flushing seek
occurs or the state of the appsrc has gone through READY.
# Implements
[`AppSrcExt`](trait.AppSrcExt.html), [`ObjectExt`](trait.ObjectExt.html)
<!-- trait AppSrcExt -->
Trait containing all `AppSrc` methods.
# Implementors
[`AppSrc`](struct.AppSrc.html)
<!-- trait AppSrcExt::fn end_of_stream -->
[`ElementExt`](trait.ElementExt.html), [`ObjectExt`](trait.ObjectExt.html), [`ObjectExt`](trait.ObjectExt.html)
<!-- impl AppSrc::fn end_of_stream -->
Indicates to the appsrc element that the last buffer queued in the
element is the last buffer of the stream.
@ -324,19 +312,19 @@ element is the last buffer of the stream.
`gst::FlowReturn::Ok` when the EOS was successfuly queued.
`gst::FlowReturn::Flushing` when `self` is not PAUSED or PLAYING.
<!-- trait AppSrcExt::fn get_caps -->
<!-- impl AppSrc::fn get_caps -->
Get the configured caps on `self`.
# Returns
the `gst::Caps` produced by the source. `gst_caps_unref` after usage.
<!-- trait AppSrcExt::fn get_current_level_bytes -->
<!-- impl AppSrc::fn get_current_level_bytes -->
Get the number of currently queued bytes inside `self`.
# Returns
The number of currently queued bytes.
<!-- trait AppSrcExt::fn get_duration -->
<!-- impl AppSrc::fn get_duration -->
Get the duration of the stream in nanoseconds. A value of GST_CLOCK_TIME_NONE means that the duration is
not known.
@ -345,41 +333,41 @@ Feature: `v1_10`
# Returns
the duration of the stream previously set with `AppSrcExt::set_duration`;
<!-- trait AppSrcExt::fn get_emit_signals -->
the duration of the stream previously set with `AppSrc::set_duration`;
<!-- impl AppSrc::fn get_emit_signals -->
Check if appsrc will emit the "new-preroll" and "new-buffer" signals.
# Returns
`true` if `self` is emitting the "new-preroll" and "new-buffer"
signals.
<!-- trait AppSrcExt::fn get_latency -->
<!-- impl AppSrc::fn get_latency -->
Retrieve the min and max latencies in `min` and `max` respectively.
## `min`
the min latency
## `max`
the min latency
<!-- trait AppSrcExt::fn get_max_bytes -->
<!-- impl AppSrc::fn get_max_bytes -->
Get the maximum amount of bytes that can be queued in `self`.
# Returns
The maximum amount of bytes that can be queued.
<!-- trait AppSrcExt::fn get_size -->
<!-- impl AppSrc::fn get_size -->
Get the size of the stream in bytes. A value of -1 means that the size is
not known.
# Returns
the size of the stream previously set with `AppSrcExt::set_size`;
<!-- trait AppSrcExt::fn get_stream_type -->
the size of the stream previously set with `AppSrc::set_size`;
<!-- impl AppSrc::fn get_stream_type -->
Get the stream type. Control the stream type of `self`
with `AppSrcExt::set_stream_type`.
with `AppSrc::set_stream_type`.
# Returns
the stream type.
<!-- trait AppSrcExt::fn push_buffer -->
<!-- impl AppSrc::fn push_buffer -->
Adds a buffer to the queue of buffers that the appsrc element will
push to its source pad. This function takes ownership of the buffer.
@ -393,7 +381,7 @@ a `gst::Buffer` to push
`gst::FlowReturn::Ok` when the buffer was successfuly queued.
`gst::FlowReturn::Flushing` when `self` is not PAUSED or PLAYING.
`gst::FlowReturn::Eos` when EOS occured.
<!-- trait AppSrcExt::fn push_sample -->
<!-- impl AppSrc::fn push_sample -->
Extract a buffer from the provided sample and adds it to the queue of
buffers that the appsrc element will push to its source pad. Any
previous caps that were set on appsrc will be replaced by the caps
@ -410,7 +398,7 @@ extracted
`gst::FlowReturn::Ok` when the buffer was successfuly queued.
`gst::FlowReturn::Flushing` when `self` is not PAUSED or PLAYING.
`gst::FlowReturn::Eos` when EOS occured.
<!-- trait AppSrcExt::fn set_callbacks -->
<!-- impl AppSrc::fn set_callbacks -->
Set callbacks which will be executed when data is needed, enough data has
been collected or when a seek should be performed.
This is an alternative to using the signals, it has lower overhead and is thus
@ -424,14 +412,14 @@ the callbacks
a user_data argument for the callbacks
## `notify`
a destroy notify function
<!-- trait AppSrcExt::fn set_caps -->
<!-- impl AppSrc::fn set_caps -->
Set the capabilities on the appsrc element. This function takes
a copy of the caps structure. After calling this method, the source will
only produce caps that match `caps`. `caps` must be fixed and the caps on the
buffers must match the caps or left NULL.
## `caps`
caps to set
<!-- trait AppSrcExt::fn set_duration -->
<!-- impl AppSrc::fn set_duration -->
Set the duration of the stream in nanoseconds. A value of GST_CLOCK_TIME_NONE means that the duration is
not known.
@ -439,31 +427,31 @@ Feature: `v1_10`
## `duration`
the duration to set
<!-- trait AppSrcExt::fn set_emit_signals -->
<!-- impl AppSrc::fn set_emit_signals -->
Make appsrc emit the "new-preroll" and "new-buffer" signals. This option is
by default disabled because signal emission is expensive and unneeded when
the application prefers to operate in pull mode.
## `emit`
the new state
<!-- trait AppSrcExt::fn set_latency -->
<!-- impl AppSrc::fn set_latency -->
Configure the `min` and `max` latency in `src`. If `min` is set to -1, the
default latency calculations for pseudo-live sources will be used.
## `min`
the min latency
## `max`
the min latency
<!-- trait AppSrcExt::fn set_max_bytes -->
<!-- impl AppSrc::fn set_max_bytes -->
Set the maximum amount of bytes that can be queued in `self`.
After the maximum amount of bytes are queued, `self` will emit the
"enough-data" signal.
## `max`
the maximum number of bytes to queue
<!-- trait AppSrcExt::fn set_size -->
<!-- impl AppSrc::fn set_size -->
Set the size of the stream in bytes. A value of -1 means that the size is
not known.
## `size`
the size to set
<!-- trait AppSrcExt::fn set_stream_type -->
<!-- impl AppSrc::fn set_stream_type -->
Set the stream type on `self`. For seekable streams, the "seek" signal must
be connected to.

70
docs/gstreamer-audio/docs.md
View file

@ -266,3 +266,73 @@ Layout of the audio samples for the different channels.
interleaved audio
<!-- enum AudioLayout::variant NonInterleaved -->
non-interleaved audio
<!-- struct StreamVolume -->
This interface is implemented by elements that provide a stream volume. Examples for
such elements are `volume` and `playbin`.
Applications can use this interface to get or set the current stream volume. For this
the "volume" `gobject::Object` property can be used or the helper functions `StreamVolume::set_volume`
and `StreamVolume::get_volume`. This volume is always a linear factor, i.e. 0.0 is muted
1.0 is 100%. For showing the volume in a GUI it might make sense to convert it to
a different format by using `StreamVolume::convert_volume`. Volume sliders should usually
use a cubic volume.
Separate from the volume the stream can also be muted by the "mute" `gobject::Object` property or
`StreamVolume::set_mute` and `StreamVolume::get_mute`.
Elements that provide some kind of stream volume should implement the "volume" and
"mute" `gobject::Object` properties and handle setting and getting of them properly.
The volume property is defined to be a linear volume factor.
# Implements
[`StreamVolumeExt`](trait.StreamVolumeExt.html)
<!-- trait StreamVolumeExt -->
Trait containing all `StreamVolume` methods.
# Implementors
[`StreamVolume`](struct.StreamVolume.html)
<!-- impl StreamVolume::fn convert_volume -->
## `from`
`StreamVolumeFormat` to convert from
## `to`
`StreamVolumeFormat` to convert to
## `val`
Volume in `from` format that should be converted
# Returns
the converted volume
<!-- trait StreamVolumeExt::fn get_mute -->
# Returns
Returns `true` if the stream is muted
<!-- trait StreamVolumeExt::fn get_volume -->
## `format`
`StreamVolumeFormat` which should be returned
# Returns
The current stream volume as linear factor
<!-- trait StreamVolumeExt::fn set_mute -->
## `mute`
Mute state that should be set
<!-- trait StreamVolumeExt::fn set_volume -->
## `format`
`StreamVolumeFormat` of `val`
## `val`
Linear volume factor that should be set
<!-- enum StreamVolumeFormat -->
Different representations of a stream volume. `StreamVolume::convert_volume`
allows to convert between the different representations.
Formulas to convert from a linear to a cubic or dB volume are
cbrt(val) and 20 * log10 (val).
<!-- enum StreamVolumeFormat::variant Linear -->
Linear scale factor, 1.0 = 100%
<!-- enum StreamVolumeFormat::variant Cubic -->
Cubic volume scale
<!-- enum StreamVolumeFormat::variant Db -->
Logarithmic volume scale (dB, amplitude not power)

15
docs/gstreamer-player/docs.md
View file

@ -113,9 +113,6 @@ If accurate seeking is disabled, elements will seek as close as the request
position without slowing down seeking too much.
Accurate seeking is disabled by default.
Feature: `v1_12`
## `accurate`
accurate seek or not
<!-- impl Player::fn get_audio_video_offset -->
@ -500,33 +497,21 @@ Application can use gst_sample_*`_` API's to get caps, buffer etc.
GstSample or NULL.
<!-- trait PlayerMediaInfoExt::fn get_number_of_audio_streams -->
Feature: `v1_12`
# Returns
number of audio streams.
<!-- trait PlayerMediaInfoExt::fn get_number_of_streams -->
Feature: `v1_12`
# Returns
number of total streams.
<!-- trait PlayerMediaInfoExt::fn get_number_of_subtitle_streams -->
Feature: `v1_12`
# Returns
number of subtitle streams.
<!-- trait PlayerMediaInfoExt::fn get_number_of_video_streams -->
Feature: `v1_12`
# Returns
number of video streams.

265
docs/gstreamer/docs.md
View file

@ -2163,7 +2163,7 @@ Trait containing all `Clock` methods.
# Implementors
[`Clock`](struct.Clock.html)
[`Clock`](struct.Clock.html), [`SystemClock`](struct.SystemClock.html)
<!-- impl Clock::fn id_compare_func -->
Compares the two `ClockID` instances. This function can be used
as a GCompareFunc when sorting ids.
@ -2605,6 +2605,33 @@ timeout for waiting or `GST_CLOCK_TIME_NONE`
# Returns
`true` if waiting was successful, or `false` on timeout
<!-- enum ClockReturn -->
The return value of a clock operation.
<!-- enum ClockReturn::variant Ok -->
The operation succeeded.
<!-- enum ClockReturn::variant Early -->
The operation was scheduled too late.
<!-- enum ClockReturn::variant Unscheduled -->
The clockID was unscheduled
<!-- enum ClockReturn::variant Busy -->
The ClockID is busy
<!-- enum ClockReturn::variant Badtime -->
A bad time was provided to a function.
<!-- enum ClockReturn::variant Error -->
An error occurred
<!-- enum ClockReturn::variant Unsupported -->
Operation is not supported
<!-- enum ClockReturn::variant Done -->
The ClockID is done waiting
<!-- enum ClockType -->
The different kind of clocks.
<!-- enum ClockType::variant Realtime -->
time since Epoch
<!-- enum ClockType::variant Monotonic -->
monotonic time since some unspecified starting
point
<!-- enum ClockType::variant Other -->
some other time source is used (Since 1.0.5)
<!-- struct Context -->
`Context` is a container object used to store contexts like a device
context, a display server connection and similar concepts that should
@ -3550,7 +3577,7 @@ Trait containing all `Element` methods.
# Implementors
[`Bin`](struct.Bin.html), [`Element`](struct.Element.html), [`TagSetter`](struct.TagSetter.html)
[`Bin`](struct.Bin.html), [`Element`](struct.Element.html), [`TagSetter`](struct.TagSetter.html), [`TocSetter`](struct.TocSetter.html)
<!-- impl Element::fn make_from_uri -->
Creates an element for handling the given URI.
## `type_`
@ -10637,6 +10664,22 @@ Get the structure of a query. This method should be called with a writable
the `Structure` of the query. The structure is
still owned by the query and will therefore be freed when the query
is unreffed.
<!-- enum Rank -->
Element priority ranks. Defines the order in which the autoplugger (or
similar rank-picking mechanisms, such as e.g. `Element::make_from_uri`)
will choose this element over an alternative one with the same function.
These constants serve as a rough guidance for defining the rank of a
`PluginFeature`. Any value is valid, including values bigger than
`Rank::Primary`.
<!-- enum Rank::variant None -->
will be chosen last or not at all
<!-- enum Rank::variant Marginal -->
unlikely to be chosen
<!-- enum Rank::variant Secondary -->
likely to be chosen
<!-- enum Rank::variant Primary -->
will be chosen first
<!-- enum ResourceError -->
Resource errors are for any resource used by an element:
memory, files, network connections, process space, ...
@ -12236,6 +12279,47 @@ The type of a `MessageType::StructureChange`.
Pad linking is starting or done.
<!-- enum StructureChangeType::variant Unlink -->
Pad unlinking is starting or done.
<!-- struct SystemClock -->
The GStreamer core provides a GstSystemClock based on the system time.
Asynchronous callbacks are scheduled from an internal thread.
Clock implementors are encouraged to subclass this systemclock as it
implements the async notification.
Subclasses can however override all of the important methods for sync and
async notifications to implement their own callback methods or blocking
wait operations.
# Implements
[`SystemClockExt`](trait.SystemClockExt.html), [`ClockExt`](trait.ClockExt.html), [`ObjectExt`](trait.ObjectExt.html), [`ObjectExt`](trait.ObjectExt.html)
<!-- trait SystemClockExt -->
Trait containing all `SystemClock` methods.
# Implementors
[`SystemClock`](struct.SystemClock.html)
<!-- impl SystemClock::fn obtain -->
Get a handle to the default system clock. The refcount of the
clock will be increased so you need to unref the clock after
usage.
# Returns
the default clock.
MT safe.
<!-- impl SystemClock::fn set_default -->
Sets the default system clock that can be obtained with
`SystemClock::obtain`.
This is mostly used for testing and debugging purposes when you
want to have control over the time reported by the default system
clock.
MT safe.
## `new_clock`
a `Clock`
<!-- struct TagList -->
List of tags and values used to describe media metadata.
@ -13007,6 +13091,183 @@ specified by this interface. The default is `TagMergeMode::Keep`, which keeps
the tags set with this interface and discards tags from events.
## `mode`
The mode with which tags are added
<!-- struct Toc -->
`Toc` functions are used to create/free `Toc` and `TocEntry` structures.
Also they are used to convert `Toc` into `Structure` and vice versa.
`Toc` lets you to inform other elements in pipeline or application that playing
source has some kind of table of contents (TOC). These may be chapters, editions,
angles or other types. For example: DVD chapters, Matroska chapters or cue sheet
TOC. Such TOC will be useful for applications to display instead of just a
playlist.
Using TOC is very easy. Firstly, create `Toc` structure which represents root
contents of the source. You can also attach TOC-specific tags to it. Then fill
it with `TocEntry` entries by appending them to the `Toc` using
`Toc::append_entry`, and appending subentries to a `TocEntry` using
`TocEntry::append_sub_entry`.
Note that root level of the TOC can contain only either editions or chapters. You
should not mix them together at the same level. Otherwise you will get serialization
/deserialization errors. Make sure that no one of the entries has negative start and
stop values.
Use `Event::new_toc` to create a new TOC `Event`, and `Event::parse_toc` to
parse received TOC event. Use `Event::new_toc_select` to create a new TOC select `Event`,
and `Event::parse_toc_select` to parse received TOC select event. The same rule for
the `Message`: `Message::new_toc` to create new TOC `Message`, and
`Message::parse_toc` to parse received TOC message.
TOCs can have global scope or current scope. Global scope TOCs contain
all entries that can possibly be selected using a toc select event, and
are what an application is usually interested in. TOCs with current scope
only contain the parts of the TOC relevant to the currently selected/playing
stream; the current scope TOC is used by downstream elements such as muxers
to write correct TOC entries when transcoding files, for example. When
playing a DVD, the global TOC would contain a hierarchy of all titles,
chapters and angles, for example, while the current TOC would only contain
the chapters for the currently playing title if playback of a specific
title was requested.
Applications and plugins should not rely on TOCs having a certain kind of
structure, but should allow for different alternatives. For example, a
simple CUE sheet embedded in a file may be presented as a flat list of
track entries, or could have a top-level edition node (or some other
alternative type entry) with track entries underneath that node; or even
multiple top-level edition nodes (or some other alternative type entries)
each with track entries underneath, in case the source file has extracted
a track listing from different sources).
<!-- impl Toc::fn new -->
Create a new `Toc` structure.
## `scope`
scope of this TOC
# Returns
newly allocated `Toc` structure, free it
with `gst_toc_unref`.
<!-- impl Toc::fn append_entry -->
Appends the `TocEntry` `entry` to `self`.
## `entry`
A `TocEntry`
<!-- impl Toc::fn find_entry -->
Find `TocEntry` with given `uid` in the `self`.
## `uid`
UID to find `TocEntry` with.
# Returns
`TocEntry` with specified
`uid` from the `self`, or `None` if not found.
<!-- impl Toc::fn get_entries -->
Gets the list of `TocEntry` of `self`.
# Returns
A `glib::List` of `TocEntry` for `entry`
<!-- impl Toc::fn get_scope -->
# Returns
scope of `self`
<!-- impl Toc::fn get_tags -->
Gets the tags for `self`.
# Returns
A `TagList` for `entry`
<!-- impl Toc::fn merge_tags -->
Merge `tags` into the existing tags of `self` using `mode`.
## `tags`
A `TagList` or `None`
## `mode`
A `TagMergeMode`
<!-- impl Toc::fn set_tags -->
Set a `TagList` with tags for the complete `self`.
## `tags`
A `TagList` or `None`
<!-- enum TocEntryType -->
The different types of TOC entries (see `TocEntry`).
There are two types of TOC entries: alternatives or parts in a sequence.
<!-- enum TocEntryType::variant Angle -->
entry is an angle (i.e. an alternative)
<!-- enum TocEntryType::variant Version -->
entry is a version (i.e. alternative)
<!-- enum TocEntryType::variant Edition -->
entry is an edition (i.e. alternative)
<!-- enum TocEntryType::variant Invalid -->
invalid entry type value
<!-- enum TocEntryType::variant Title -->
entry is a title (i.e. a part of a sequence)
<!-- enum TocEntryType::variant Track -->
entry is a track (i.e. a part of a sequence)
<!-- enum TocEntryType::variant Chapter -->
entry is a chapter (i.e. a part of a sequence)
<!-- enum TocLoopType -->
How a `TocEntry` should be repeated. By default, entries are played a
single time.
<!-- enum TocLoopType::variant None -->
single forward playback
<!-- enum TocLoopType::variant Forward -->
repeat forward
<!-- enum TocLoopType::variant Reverse -->
repeat backward
<!-- enum TocLoopType::variant PingPong -->
repeat forward and backward
<!-- enum TocScope -->
The scope of a TOC.
<!-- enum TocScope::variant Global -->
global TOC representing all selectable options
(this is what applications are usually interested in)
<!-- enum TocScope::variant Current -->
TOC for the currently active/selected stream
(this is a TOC representing the current stream from start to EOS,
and is what a TOC writer / muxer is usually interested in; it will
usually be a subset of the global TOC, e.g. just the chapters of
the current title, or the chapters selected for playback from the
current title)
<!-- struct TocSetter -->
Element interface that allows setting of the TOC.
Elements that support some kind of chapters or editions (or tracks like in
the FLAC cue sheet) will implement this interface.
If you just want to retrieve the TOC in your application then all you
need to do is watch for TOC messages on your pipeline's bus (or you can
perform TOC query). This interface is only for setting TOC data, not for
extracting it. To set TOC from the application, find proper tocsetter element
and set TOC using `TocSetter::set_toc`.
Elements implementing the `TocSetter` interface can extend existing TOC
by getting extend UID for that (you can use `Toc::find_entry` to retrieve it)
with any TOC entries received from downstream.
# Implements
[`TocSetterExt`](trait.TocSetterExt.html), [`ElementExt`](trait.ElementExt.html), [`ObjectExt`](trait.ObjectExt.html), [`ObjectExt`](trait.ObjectExt.html)
<!-- trait TocSetterExt -->
Trait containing all `TocSetter` methods.
# Implementors
[`TocSetter`](struct.TocSetter.html)
<!-- trait TocSetterExt::fn get_toc -->
Return current TOC the setter uses. The TOC should not be
modified without making it writable first.
# Returns
TOC set, or `None`. Unref with
`gst_toc_unref` when no longer needed
<!-- trait TocSetterExt::fn reset -->
Reset the internal TOC. Elements should call this from within the
state-change handler.
<!-- trait TocSetterExt::fn set_toc -->
Set the given TOC on the setter. Previously set TOC will be
unreffed before setting a new one.
## `toc`
a `Toc` to set.
<!-- enum URIError -->
Different URI-related errors that can occur.
<!-- enum URIError::variant UnsupportedProtocol -->