GstToc: GStreamer Core Reference Manual

## GstToc GstToc — Generic table of contents support |

## Functions

GstToc * | gst_toc_new ()
#define | gst_toc_ref()
#define | gst_toc_unref()
#define | gst_toc_copy()
#define | gst_toc_make_writable()
GstTocScope | gst_toc_get_scope ()
GList * | gst_toc_get_entries ()
void | gst_toc_append_entry ()
GstTagList * | gst_toc_get_tags ()
void | gst_toc_merge_tags ()
void | gst_toc_set_tags ()
void | gst_toc_dump ()
GstTocEntry * | gst_toc_entry_new ()
#define | gst_toc_entry_ref()
#define | gst_toc_entry_unref()
#define | gst_toc_entry_copy()
#define | gst_toc_entry_make_writable()
GstTocEntry * | gst_toc_find_entry ()
GstToc * | gst_toc_entry_get_toc ()
const gchar * | gst_toc_entry_get_uid ()
GstTocEntry * | gst_toc_entry_get_parent ()
GList * | gst_toc_entry_get_sub_entries ()
void | gst_toc_entry_append_sub_entry ()
gboolean | gst_toc_entry_get_loop ()
void | gst_toc_entry_set_loop ()
gboolean | gst_toc_entry_get_start_stop_times ()
void | gst_toc_entry_set_start_stop_times ()
GstTagList * | gst_toc_entry_get_tags ()
void | gst_toc_entry_merge_tags ()
void | gst_toc_entry_set_tags ()
const gchar * | gst_toc_entry_type_get_nick ()
GstTocEntryType | gst_toc_entry_get_entry_type ()
gboolean | gst_toc_entry_is_alternative ()
gboolean | gst_toc_entry_is_sequence ()
#define | GST_TOC_ENTRY_TYPE_IS_ALTERNATIVE()
#define | GST_TOC_ENTRY_TYPE_IS_SEQUENCE()

## Types and Values

| GstToc
enum | GstTocScope
| GstTocEntry
enum | GstTocEntryType
enum | GstTocLoopType
#define | GST_TOC_REPEAT_COUNT_INFINITE

## Object Hierarchy

        GBoxed
        ├── GstToc
        ╰── GstTocEntry

## Includes

    #include <gst/gst.h>

## Description

GstToc functions are used to create/free GstToc and GstTocEntry structures. Also they are used to convert GstToc into GstStructure and vice versa.

GstToc 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 GstToc structure which represents root contents of the source. You can also attach TOC-specific tags to it. Then fill it with GstTocEntry entries by appending them to the GstToc using `gst_toc_append_entry()`, and appending subentries to a GstTocEntry using `gst_toc_entry_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 `gst_event_new_toc()` to create a new TOC GstEvent, and `gst_event_parse_toc()` to parse received TOC event. Use `gst_event_new_toc_select()` to create a new TOC select GstEvent, and `gst_event_parse_toc_select()` to parse received TOC select event. The same rule for the GstMessage: `gst_message_new_toc()` to create new TOC GstMessage, and `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).

## Functions

### gst_toc_new ()

    GstToc *
    gst_toc_new (GstTocScope scope);

Create a new GstToc structure.

#### Parameters

scope | scope of this TOC |

#### Returns

newly allocated GstToc structure, free it with `gst_toc_unref()`.

[transfer full]

### gst_toc_ref()

    #define gst_toc_ref(toc)            (GstToc*)gst_mini_object_ref(GST_MINI_OBJECT_CAST(toc))

### gst_toc_unref()

    #define gst_toc_unref(toc)          gst_mini_object_unref(GST_MINI_OBJECT_CAST(toc))

### gst_toc_copy()

    #define gst_toc_copy(toc)           (GstToc*)gst_mini_object_copy(GST_MINI_OBJECT_CAST(toc))

Copy GstToc with all subentries (deep copy).

#### Parameters

toc | GstToc to copy. |

#### Returns

newly allocated GstToc in case of success, `NULL` otherwise; free it when done with `gst_toc_unref()`.

[nullable]

### gst_toc_make_writable()

    #define gst_toc_make_writable(toc)  (GstToc*)gst_mini_object_make_writable(GST_MINI_OBJECT_CAST(toc))

### gst_toc_get_scope ()

    GstTocScope
    gst_toc_get_scope (const GstToc *toc);

#### Parameters

toc | a GstToc instance |

#### Returns

scope of `toc`

### gst_toc_get_entries ()

    GList *
    gst_toc_get_entries (const GstToc *toc);

Gets the list of GstTocEntry of `toc` .

#### Parameters

toc | A GstToc instance |

#### Returns

A GList of GstTocEntry for `entry` .

[transfer none][element-type Gst.TocEntry]

### gst_toc_append_entry ()

    void
    gst_toc_append_entry (GstToc *toc,
                          GstTocEntry *entry);

Appends the GstTocEntry `entry` to `toc` .

#### Parameters

toc | A GstToc instance |
entry | A GstTocEntry. | [transfer full]

### gst_toc_get_tags ()

    GstTagList *
    gst_toc_get_tags (const GstToc *toc);

Gets the tags for `toc` .

#### Parameters

toc | A GstToc instance |

#### Returns

A GstTagList for `entry` .

[transfer none]

### gst_toc_merge_tags ()

    void
    gst_toc_merge_tags (GstToc *toc,
                        GstTagList *tags,
                        GstTagMergeMode mode);

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

#### Parameters

toc | A GstToc instance |
tags | A GstTagList or `NULL`. | [allow-none]
mode | A GstTagMergeMode |

### gst_toc_set_tags ()

    void
    gst_toc_set_tags (GstToc *toc,
                      GstTagList *tags);

Set a GstTagList with tags for the complete `toc` .

#### Parameters

toc | A GstToc instance |
tags | A GstTagList or `NULL`. | [allow-none][transfer full]

### gst_toc_dump ()

    void
    gst_toc_dump (GstToc *toc);

### gst_toc_entry_new ()

    GstTocEntry *
    gst_toc_entry_new (GstTocEntryType type,
                       const gchar *uid);

Create new GstTocEntry structure.

#### Parameters

type | entry type. |
uid | unique ID (UID) in the whole TOC. |

#### Returns

newly allocated GstTocEntry structure, free it with `gst_toc_entry_unref()`.

### gst_toc_entry_ref()

    #define gst_toc_entry_ref(entry)            (GstTocEntry*)gst_mini_object_ref(GST_MINI_OBJECT_CAST(entry))

### gst_toc_entry_unref()

    #define gst_toc_entry_unref(entry)          gst_mini_object_unref(GST_MINI_OBJECT_CAST(entry))

### gst_toc_entry_copy()

    #define gst_toc_entry_copy(entry)           (GstTocEntry*)gst_mini_object_copy(GST_MINI_OBJECT_CAST(entry))

Copy GstTocEntry with all subentries (deep copy).

#### Parameters

entry | GstTocEntry to copy. |

#### Returns

newly allocated GstTocEntry in case of success, `NULL` otherwise; free it when done with `gst_toc_entry_unref()`.

[nullable]

### gst_toc_entry_make_writable()

    #define gst_toc_entry_make_writable(entry)  (GstTocEntry*)gst_mini_object_make_writable(GST_MINI_OBJECT_CAST(entry))

### gst_toc_find_entry ()

    GstTocEntry *
    gst_toc_find_entry (const GstToc *toc,
                        const gchar *uid);

Find GstTocEntry with given `uid` in the `toc` .

#### Parameters

toc | GstToc to search in. |
uid | UID to find GstTocEntry with. |

#### Returns

GstTocEntry with specified `uid` from the `toc` , or `NULL` if not found.

[transfer none][nullable]

### gst_toc_entry_get_toc ()

    GstToc *
    gst_toc_entry_get_toc (GstTocEntry *entry);

Gets the parent GstToc of `entry` .

#### Parameters

entry | A GstTocEntry instance |

#### Returns

The parent GstToc of `entry` .

[transfer none]

### gst_toc_entry_get_uid ()

    const gchar *
    gst_toc_entry_get_uid (const GstTocEntry *entry);

Gets the UID of `entry` .

#### Parameters

entry | A GstTocEntry instance |

#### Returns

The UID of `entry` .

[transfer none]

### gst_toc_entry_get_parent ()

    GstTocEntry *
    gst_toc_entry_get_parent (GstTocEntry *entry);

Gets the parent GstTocEntry of `entry` .

#### Parameters

entry | A GstTocEntry instance |

#### Returns

The parent GstTocEntry of `entry` .

[transfer none][nullable]

### gst_toc_entry_get_sub_entries ()

    GList *
    gst_toc_entry_get_sub_entries (const GstTocEntry *entry);

Gets the sub-entries of `entry` .

#### Parameters

entry | A GstTocEntry instance |

#### Returns

A GList of GstTocEntry of `entry` .

[transfer none][element-type Gst.TocEntry]

### gst_toc_entry_append_sub_entry ()

    void
    gst_toc_entry_append_sub_entry (GstTocEntry *entry,
                                    GstTocEntry *subentry);

Appends the GstTocEntry `subentry` to `entry` .

#### Parameters

entry | A GstTocEntry instance |
subentry | A GstTocEntry. | [transfer full]

### gst_toc_entry_get_loop ()

    gboolean
    gst_toc_entry_get_loop (const GstTocEntry *entry,
                            GstTocLoopType *loop_type,
                            gint *repeat_count);

Get `loop_type` and `repeat_count` values from the `entry` and write them into appropriate storages. Loops are e.g. used by sampled instruments. GStreamer is not automatically applying the loop. The application can process this meta data and use it e.g. to send a seek-event to loop a section.

#### Parameters

entry | GstTocEntry to get values from. |
loop_type | the storage for the loop_type value, leave `NULL` if not need. | [out][allow-none]
repeat_count | the storage for the repeat_count value, leave `NULL` if not need. | [out][allow-none]

#### Returns

`TRUE` if all non-`NULL` storage pointers were filled with appropriate values, `FALSE` otherwise.

Since: 1.4

### gst_toc_entry_set_loop ()

    void
    gst_toc_entry_set_loop (GstTocEntry *entry,
                            GstTocLoopType loop_type,
                            gint repeat_count);

Set `loop_type` and `repeat_count` values for the `entry` .

#### Parameters

entry | GstTocEntry to set values. |
loop_type | loop_type value to set. |
repeat_count | repeat_count value to set. |

Since: 1.4

### gst_toc_entry_get_start_stop_times ()

    gboolean
    gst_toc_entry_get_start_stop_times (const GstTocEntry *entry,
                                        gint64 *start,
                                        gint64 *stop);

Get `start` and `stop` values from the `entry` and write them into appropriate storages.

#### Parameters

entry | GstTocEntry to get values from. |
start | the storage for the start value, leave `NULL` if not need. | [out][allow-none]
stop | the storage for the stop value, leave `NULL` if not need. | [out][allow-none]

#### Returns

`TRUE` if all non-`NULL` storage pointers were filled with appropriate values, `FALSE` otherwise.

### gst_toc_entry_set_start_stop_times ()

    void
    gst_toc_entry_set_start_stop_times (GstTocEntry *entry,
                                        gint64 start,
                                        gint64 stop);

Set `start` and `stop` values for the `entry` .

#### Parameters

entry | GstTocEntry to set values. |
start | start value to set. |
stop | stop value to set. |

### gst_toc_entry_get_tags ()

    GstTagList *
    gst_toc_entry_get_tags (const GstTocEntry *entry);

Gets the tags for `entry` .

#### Parameters

entry | A GstTocEntry instance |

#### Returns

A GstTagList for `entry` .

[transfer none]

### gst_toc_entry_merge_tags ()

    void
    gst_toc_entry_merge_tags (GstTocEntry *entry,
                              GstTagList *tags,
                              GstTagMergeMode mode);

Merge `tags` into the existing tags of `entry` using `mode` .

#### Parameters

entry | A GstTocEntry instance |
tags | A GstTagList or `NULL`. | [allow-none]
mode | A GstTagMergeMode |

### gst_toc_entry_set_tags ()

    void
    gst_toc_entry_set_tags (GstTocEntry *entry,
                            GstTagList *tags);

Set a GstTagList with tags for the complete `entry` .

#### Parameters

entry | A GstTocEntry instance |
tags | A GstTagList or `NULL`. | [allow-none][transfer full]

### gst_toc_entry_type_get_nick ()

    const gchar *
    gst_toc_entry_type_get_nick (GstTocEntryType type);

Converts `type` to a string representation.

#### Parameters

type | a GstTocEntryType. |

#### Returns

Returns a human-readable string for `type` . This string is only for debugging purpose and should not be displayed in a user interface.

### gst_toc_entry_get_entry_type ()

    GstTocEntryType
    gst_toc_entry_get_entry_type (const GstTocEntry *entry);

#### Parameters

entry | a GstTocEntry |

#### Returns

`entry` 's entry type

### gst_toc_entry_is_alternative ()

    gboolean
    gst_toc_entry_is_alternative (const GstTocEntry *entry);

#### Parameters

entry | a GstTocEntry |

#### Returns

`TRUE` if `entry` 's type is an alternative type, otherwise `FALSE`

### gst_toc_entry_is_sequence ()

    gboolean
    gst_toc_entry_is_sequence (const GstTocEntry *entry);

#### Parameters

entry | a GstTocEntry |

#### Returns

`TRUE` if `entry` 's type is a sequence type, otherwise `FALSE`

### GST_TOC_ENTRY_TYPE_IS_ALTERNATIVE()

    #define GST_TOC_ENTRY_TYPE_IS_ALTERNATIVE(entry_type)  (entry_type < 0)

Checks if `entry_type` indicates that its GstTocEntry is an alternative.

#### Parameters

entry_type | The GstTocEntryType from a GstTocEntry |

### GST_TOC_ENTRY_TYPE_IS_SEQUENCE()

    #define GST_TOC_ENTRY_TYPE_IS_SEQUENCE(entry_type)     (entry_type > 0)

Checks if `entry_type` indicates that its GstTocEntry is a sequence.

#### Parameters

entry_type | The GstTocEntryType from a GstTocEntry |

## Types and Values

### GstToc

    typedef struct _GstToc GstToc;

### enum GstTocScope

The scope of a TOC.

#### Members

GST_TOC_SCOPE_GLOBAL | global TOC representing all selectable options (this is what applications are usually interested in) |
GST_TOC_SCOPE_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) |

### GstTocEntry

    typedef struct _GstTocEntry GstTocEntry;

### enum GstTocEntryType

The different types of TOC entries (see GstTocEntry).

There are two types of TOC entries: alternatives or parts in a sequence.

#### Members

GST_TOC_ENTRY_TYPE_ANGLE | entry is an angle (i.e. an alternative) |
GST_TOC_ENTRY_TYPE_VERSION | entry is a version (i.e. alternative) |
GST_TOC_ENTRY_TYPE_EDITION | entry is an edition (i.e. alternative) |
GST_TOC_ENTRY_TYPE_INVALID | invalid entry type value |
GST_TOC_ENTRY_TYPE_TITLE | entry is a title (i.e. a part of a sequence) |
GST_TOC_ENTRY_TYPE_TRACK | entry is a track (i.e. a part of a sequence) |
GST_TOC_ENTRY_TYPE_CHAPTER | entry is a chapter (i.e. a part of a sequence) |

### enum GstTocLoopType

How a GstTocEntry should be repeated. By default, entries are played a single time.

#### Members

GST_TOC_LOOP_NONE | single forward playback |
GST_TOC_LOOP_FORWARD | repeat forward |
GST_TOC_LOOP_REVERSE | repeat backward |
GST_TOC_LOOP_PING_PONG | repeat forward and backward |

Since: 1.4

### GST_TOC_REPEAT_COUNT_INFINITE

    #define GST_TOC_REPEAT_COUNT_INFINITE (-1)

Special value for the repeat_count set in `gst_toc_entry_set_loop()` or returned by `gst_toc_entry_set_loop()` to indicate infinite looping.

Since: 1.4

## See Also

GstStructure, GstEvent, GstMessage, GstQuery