GstToc

GstToc — Generic table of contents support

Synopsis

#include <gst/gst.h>

                    GstToc;
enum                GstTocScope;
                    GstTocEntry;
enum                GstTocEntryType;
GstToc *            gst_toc_new                         (GstTocScope scope);
#define             gst_toc_ref                         (toc)
#define             gst_toc_unref                       (toc)
#define             gst_toc_copy                        (toc)
#define             gst_toc_make_writable               (toc)
GstTocScope         gst_toc_get_scope                   (const GstToc *toc);
GList *             gst_toc_get_entries                 (const GstToc *toc);
void                gst_toc_append_entry                (GstToc *toc,
                                                         GstTocEntry *entry);
GstTagList *        gst_toc_get_tags                    (const GstToc *toc);
void                gst_toc_merge_tags                  (GstToc *toc,
                                                         GstTagList *tags,
                                                         GstTagMergeMode mode);
void                gst_toc_set_tags                    (GstToc *toc,
                                                         GstTagList *tags);
void                gst_toc_dump                        (GstToc *toc);
GstTocEntry *       gst_toc_entry_new                   (GstTocEntryType type,
                                                         const gchar *uid);
#define             gst_toc_entry_ref                   (entry)
#define             gst_toc_entry_unref                 (entry)
#define             gst_toc_entry_copy                  (entry)
#define             gst_toc_entry_make_writable         (entry)
GstTocEntry *       gst_toc_find_entry                  (const GstToc *toc,
                                                         const gchar *uid);
GstToc *            gst_toc_entry_get_toc               (GstTocEntry *entry);
const gchar *       gst_toc_entry_get_uid               (const GstTocEntry *entry);
GstTocEntry *       gst_toc_entry_get_parent            (GstTocEntry *entry);
GList *             gst_toc_entry_get_sub_entries       (const GstTocEntry *entry);
void                gst_toc_entry_append_sub_entry      (GstTocEntry *entry,
                                                         GstTocEntry *subentry);
gboolean            gst_toc_entry_get_start_stop_times  (const GstTocEntry *entry,
                                                         gint64 *start,
                                                         gint64 *stop);
void                gst_toc_entry_set_start_stop_times  (GstTocEntry *entry,
                                                         gint64 start,
                                                         gint64 stop);
GstTagList *        gst_toc_entry_get_tags              (const GstTocEntry *entry);
void                gst_toc_entry_merge_tags            (GstTocEntry *entry,
                                                         GstTagList *tags,
                                                         GstTagMergeMode mode);
void                gst_toc_entry_set_tags              (GstTocEntry *entry,
                                                         GstTagList *tags);
const gchar *       gst_toc_entry_type_get_nick         (GstTocEntryType type);
GstTocEntryType     gst_toc_entry_get_entry_type        (const GstTocEntry *entry);
gboolean            gst_toc_entry_is_alternative        (const GstTocEntry *entry);
gboolean            gst_toc_entry_is_sequence           (const GstTocEntry *entry);
#define             GST_TOC_ENTRY_TYPE_IS_ALTERNATIVE   (entry_type)
#define             GST_TOC_ENTRY_TYPE_IS_SEQUENCE      (entry_type)

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).

Details

GstToc

typedef struct _GstToc GstToc;

enum GstTocScope

typedef enum {
  GST_TOC_SCOPE_GLOBAL = 1,
  GST_TOC_SCOPE_CURRENT = 2
} GstTocScope;

The scope of a TOC.

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

typedef enum {
  GST_TOC_ENTRY_TYPE_ANGLE       = -3,
  GST_TOC_ENTRY_TYPE_VERSION     = -2,
  GST_TOC_ENTRY_TYPE_EDITION     = -1,
  GST_TOC_ENTRY_TYPE_INVALID     = 0,
  GST_TOC_ENTRY_TYPE_TITLE       = 1,
  GST_TOC_ENTRY_TYPE_TRACK       = 2,
  GST_TOC_ENTRY_TYPE_CHAPTER     = 3,
} GstTocEntryType;

The different types of TOC entries (see GstTocEntry).

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

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)

gst_toc_new ()

GstToc *            gst_toc_new                         (GstTocScope scope);

Create a new GstToc structure.

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).

toc :

GstToc to copy.

Returns :

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

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);

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.

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.

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.

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.

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.

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.

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).

entry :

GstTocEntry to copy.

Returns :

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

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.

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]

gst_toc_entry_get_toc ()

GstToc *            gst_toc_entry_get_toc               (GstTocEntry *entry);

Gets the parent GstToc of entry.

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.

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.

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.

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.

entry :

A GstTocEntry instance

subentry :

A GstTocEntry. [transfer full]

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.

entry :

GstTocEntry to get values from.

start :

the storage for the start value, leave NULL if not need. [out]

stop :

the storage for the stop value, leave NULL if not need. [out]

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.

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.

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.

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.

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.

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);

entry :

a GstTocEntry

Returns :

entry's entry type

gst_toc_entry_is_alternative ()

gboolean            gst_toc_entry_is_alternative        (const GstTocEntry *entry);

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);

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)

GST_TOC_ENTRY_TYPE_IS_SEQUENCE()

#define GST_TOC_ENTRY_TYPE_IS_SEQUENCE(entry_type)     (entry_type > 0)

See Also

GstStructure, GstEvent, GstMessage, GstQuery