From 72c7b56b01595620b1199e88ef9ad38a21dfd619 Mon Sep 17 00:00:00 2001 From: Alexander Saprykin Date: Wed, 28 Mar 2012 23:15:41 +0400 Subject: [PATCH] docs: add overview of GstToc usage --- docs/design/Makefile.am | 1 + docs/design/part-toc.txt | 89 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 90 insertions(+) create mode 100644 docs/design/part-toc.txt diff --git a/docs/design/Makefile.am b/docs/design/Makefile.am index b313c9d366..087a3b03a6 100644 --- a/docs/design/Makefile.am +++ b/docs/design/Makefile.am @@ -44,6 +44,7 @@ EXTRA_DIST = \ part-stream-status.txt \ part-streams.txt \ part-synchronisation.txt \ + part-toc.txt \ part-TODO.txt \ part-trickmodes.txt diff --git a/docs/design/part-toc.txt b/docs/design/part-toc.txt new file mode 100644 index 0000000000..73231dacf2 --- /dev/null +++ b/docs/design/part-toc.txt @@ -0,0 +1,89 @@ +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. +