mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2024-12-24 17:20:36 +00:00
77 lines
3.6 KiB
Text
77 lines
3.6 KiB
Text
Implementing GstToc support in GStreamer elements
|
|
|
|
1. General info about GstToc structure
|
|
|
|
GstToc introduces a general way to handle chapters within multimedia
|
|
formats. GstToc can be represented as tree structure with arbitrary
|
|
hierarchy. Tree item can be either of two types: chapter or edition.
|
|
Chapter acts like a part of the media data, for example audio track
|
|
in CUE sheet, or part of the movie. Edition acts like some kind of
|
|
alternative way to process media content, for example DVD angles.
|
|
GstToc has one limitation on tree structure: on the same level of
|
|
hierarchy there couldn't be items of different type, i.e. you shouldn't
|
|
have editions and chapters mixed together. Here is an example of right TOC:
|
|
|
|
------- TOC -------
|
|
/ \
|
|
edition1 edition2
|
|
| |
|
|
-chapter1 -chapter3
|
|
-chapter2
|
|
|
|
Here are two editions, the first contains two chapters, and the second
|
|
has only one chapter. And here is an example of invalid TOC:
|
|
|
|
------- TOC -------
|
|
/ \
|
|
edition1 chapter1
|
|
|
|
|
-chapter1
|
|
-chapter2
|
|
|
|
Here you have edition1 and chapter1 mixed on the same level of hierarchy,
|
|
and such TOC will be considered broken.
|
|
|
|
GstToc has 'entries' field of GList type which consists of children items.
|
|
Each item is of type GstTocEntry. Also GstToc has list of tags and
|
|
GstStructure called 'info'. Please, use GstToc.info and GstTocEntry.info
|
|
fields this way: create a GstStructure, put all info related to your element
|
|
there and put this structure into the 'info' field under the name of your
|
|
element. Some fields in the 'info' structure can be used for internal
|
|
purposes, so you should use it in the way described above to not to
|
|
overwrite already existent fields.
|
|
|
|
Let's look at GstTocEntry a bit closer. One of the most important fields
|
|
is 'uid', which must be unique for each item within the TOC. This is used
|
|
to identify each item inside TOC, especially when element receives TOC
|
|
select event with UID to seek on. Field 'subentries' of type GList contains
|
|
children items of type GstTocEntry. Thus you can achieve arbitrary hierarchy
|
|
level. Field 'type' can be either GST_TOC_ENTRY_TYPE_CHAPTER or
|
|
GST_TOC_ENTRY_TYPE_EDITION which corresponds to chapter or edition type of
|
|
item respectively. Field 'tags' is a list of tags related to the item. And field
|
|
'info' is similar to GstToc.info described above.
|
|
|
|
So, a little more about managing GstToc. Use gst_toc_new() and gst_toc_unref()
|
|
to create/free it. GstTocEntry can be created using gst_toc_entry_new().
|
|
While building GstToc you can set start and stop
|
|
timestamps for each item using gst_toc_entry_set_start_stop().
|
|
The best way to process already created GstToc is to recursively go through
|
|
the 'entries' and 'subentries' fields.
|
|
|
|
2. Working with GstMessage
|
|
|
|
GstMessage with GstToc can be created using gst_message_new_toc() and parsed
|
|
with gst_message_parse_toc(). The 'updated' parameter in these methods indicates
|
|
whether the TOC was just discovered (set to false) or TOC was already found and
|
|
have been updated (set to true). The common usage for such message is to post it
|
|
to pipeline in case you have discovered TOC data within your element.
|
|
|
|
3. Working with GstEvent
|
|
|
|
GstToc supports select event through GstEvent infrastructure. The idea is the
|
|
following: when you receive TOC select event, parse it with
|
|
gst_event_parse_toc_select() and seek stream (if it is not streamable) for
|
|
specified TOC UID (you can use gst_toc_find_entry() to find entry in TOC by UID).
|
|
To create TOC select event use gst_event_new_toc_select(). The common action on
|
|
such event is to seek to specified UID within your element.
|
|
|