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]

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

Generated by GTK-Doc V1.25