| 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 'pads' of type GList contains list of GStreamer |
| pads related to the item. It can be used for example to link a TOC with |
| specific pad. 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_free() |
| to create/free it. GstTocEntry can be created using gst_toc_entry_new() and |
| gst_toc_entry_new_with_pad(). The latter method used to create GstTocEntry |
| linked to particular pad. 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 GstQuery |
| |
| GstQuery with GstToc can be created using gst_query_new_toc(). Use |
| gst_query_set_toc() to set TOC into the query and parse it with |
| gst_query_parse_toc(). The 'extend_uid' parameter (0 for root level) in two |
| last methods should be used for TOC extending: get GstTocEntry with |
| gst_toc_find_entry() by given UID and use it to add your own chapters/editions. |
| The common action on such query is to set TOC for it. |
| |
| 3. 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. |
| |
| 4. 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. |
| |