:right-sidebar: True

Toc
===================================================================

.. currentmodule:: gi.repository.Gst





.. class:: Toc(**kwargs)
   :no-contents-entry:






:obj:`~gi.repository.Gst.Toc` functions are used to create/free :obj:`~gi.repository.Gst.Toc` and :obj:`~gi.repository.Gst.TocEntry` structures.
Also they are used to convert :obj:`~gi.repository.Gst.Toc` into :obj:`~gi.repository.Gst.Structure` and vice versa.

:obj:`~gi.repository.Gst.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 :obj:`~gi.repository.Gst.Toc` structure which represents root
contents of the source. You can also attach TOC-specific tags to it. Then fill
it with :obj:`~gi.repository.Gst.TocEntry` entries by appending them to the :obj:`~gi.repository.Gst.Toc` using
:func:`~gi.repository.Gst.Toc.append_entry`, and appending subentries to a :obj:`~gi.repository.Gst.TocEntry` using
:func:`~gi.repository.Gst.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 :func:`~gi.repository.Gst.Event.new_toc` to create a new TOC :obj:`~gi.repository.Gst.Event`\, and :func:`~gi.repository.Gst.Event.parse_toc` to
parse received TOC event. Use :func:`~gi.repository.Gst.Event.new_toc_select` to create a new TOC select :obj:`~gi.repository.Gst.Event`\,
and :func:`~gi.repository.Gst.Event.parse_toc_select` to parse received TOC select event. The same rule for
the :obj:`~gi.repository.Gst.Message`\: :func:`~gi.repository.Gst.Message.new_toc` to create new TOC :obj:`~gi.repository.Gst.Message`\, and
:func:`~gi.repository.Gst.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).


Constructors
------------

.. rst-class:: interim-class

.. class:: Toc
   :no-index:


   .. classmethod:: new(scope: ~gi.repository.Gst.TocScope) -> ~gi.repository.Gst.Toc

      Create a new :obj:`~gi.repository.Gst.Toc` structure.






      :param scope: scope of this TOC








Methods
-------

.. rst-class:: interim-class

.. class:: Toc
   :no-index:


   .. method:: append_entry(entry: ~gi.repository.Gst.TocEntry) -> None

      Appends the :obj:`~gi.repository.Gst.TocEntry` ``entry`` to ``toc``\.






      :param entry: A :obj:`~gi.repository.Gst.TocEntry`




   .. method:: dump() -> None

      









   .. method:: find_entry(uid: str) -> ~gi.repository.Gst.TocEntry | None

      Find :obj:`~gi.repository.Gst.TocEntry` with given ``uid`` in the ``toc``\.






      :param uid: UID to find :obj:`~gi.repository.Gst.TocEntry` with.




   .. method:: get_entries() -> list[~gi.repository.Gst.TocEntry]

      Gets the list of :obj:`~gi.repository.Gst.TocEntry` of ``toc``\.









   .. method:: get_scope() -> ~gi.repository.Gst.TocScope

      









   .. method:: get_tags() -> ~gi.repository.Gst.TagList | None

      Gets the tags for ``toc``\.









   .. method:: merge_tags(tags: ~gi.repository.Gst.TagList | None, mode: ~gi.repository.Gst.TagMergeMode) -> None

      Merge ``tags`` into the existing tags of ``toc`` using ``mode``\.






      :param tags: A :obj:`~gi.repository.Gst.TagList` or :const:`None`

      :param mode: A :obj:`~gi.repository.Gst.TagMergeMode`




   .. method:: set_tags(tags: ~gi.repository.Gst.TagList | None = None) -> None

      Set a :obj:`~gi.repository.Gst.TagList` with tags for the complete ``toc``\.






      :param tags: A :obj:`~gi.repository.Gst.TagList` or :const:`None`