docs/design/part-toc.txt

   1 Implementing GstToc support in GStreamer elements
   2
   3 1. General info about GstToc structure
   4
   5 GstToc introduces a general way to handle chapters within multimedia
   6 formats. GstToc can be represented as tree structure with arbitrary
   7 hierarchy. Tree item can be either of two types: chapter or edition.
   8 Chapter acts like a part of the media data, for example audio track
   9 in CUE sheet, or part of the movie. Edition acts like some kind of
  10 alternative way to process media content, for example DVD angles.
  11 GstToc has one limitation on tree structure: on the same level of
  12 hierarchy there couldn't be items of different type, i.e. you shouldn't
  13 have editions and chapters mixed together. Here is an example of right TOC:
  14
  15   -------  TOC  -------
  16            /  \
  17    edition1    edition2
  18    |           |
  19    -chapter1   -chapter3
  20    -chapter2
  21
  22 Here are two editions, the first contains two chapters, and the second
  23 has only one chapter. And here is an example of invalid TOC:
  24
  25   -------  TOC  -------
  26            /  \
  27    edition1    chapter1
  28    |
  29    -chapter1
  30    -chapter2
  31
  32 Here you have edition1 and chapter1 mixed on the same level of hierarchy,
  33 and such TOC will be considered broken.
  34
  35 GstToc has 'entries' field of GList type which consists of children items.
  36 Each item is of type GstTocEntry. Also GstToc has list of tags and
  37 GstStructure called 'info'. Please, use GstToc.info and GstTocEntry.info
  38 fields this way: create a GstStructure, put all info related to your element
  39 there and put this structure into the 'info' field under the name of your
  40 element. Some fields in the 'info' structure can be used for internal
  41 purposes, so you should use it in the way described above to not to
  42 overwrite already existent fields.
  43
  44 Let's look at GstTocEntry a bit closer. One of the most important fields
  45 is 'uid', which must be unique for each item within the TOC. This is used
  46 to identify each item inside TOC, especially when element receives TOC
  47 select event with UID to seek on. Field 'subentries' of type GList contains
  48 children items of type GstTocEntry. Thus you can achieve arbitrary hierarchy
  49 level. Field 'type' can be either GST_TOC_ENTRY_TYPE_CHAPTER or
  50 GST_TOC_ENTRY_TYPE_EDITION which corresponds to chapter or edition type of
  51 item respectively. Field 'pads' of type GList contains list of GStreamer
  52 pads related to the item. It can be used for example to link a TOC with
  53 specific pad. Field 'tags' is a list of tags related to the item. And field
  54 'info' is similar to GstToc.info described above.
  55
  56 So, a little more about managing GstToc. Use gst_toc_new() and gst_toc_free()
  57 to create/free it. GstTocEntry can be created using gst_toc_entry_new() and
  58 gst_toc_entry_new_with_pad(). The latter method used to create GstTocEntry
  59 linked to particular pad. While building GstToc you can set start and stop
  60 timestamps for each item using gst_toc_entry_set_start_stop().
  61 The best way to process already created GstToc is to recursively go through
  62 the 'entries' and 'subentries' fields.
  63
  64 2. Working with GstQuery
  65
  66 GstQuery with GstToc can be created using gst_query_new_toc(). Use
  67 gst_query_set_toc() to set TOC into the query and parse it with
  68 gst_query_parse_toc(). The 'extend_uid' parameter (0 for root level) in two
  69 last methods should be used for TOC extending: get GstTocEntry with
  70 gst_toc_find_entry() by given UID and use it to add your own chapters/editions.
  71 The common action on such query is to set TOC for it.
  72
  73 3. Working with GstMessage
  74
  75 GstMessage with GstToc can be created using gst_message_new_toc() and parsed
  76 with gst_message_parse_toc(). The 'updated' parameter in these methods indicates
  77 whether the TOC was just discovered (set to false) or TOC was already found and
  78 have been updated (set to true). The common usage for such message is to post it
  79 to pipeline in case you have discovered TOC data within your element.
  80
  81 4. Working with GstEvent
  82
  83 GstToc supports select event through GstEvent infrastructure. The idea is the
  84 following: when you receive TOC select event, parse it with
  85 gst_event_parse_toc_select() and seek stream (if it is not streamable) for
  86 specified TOC UID (you can use gst_toc_find_entry() to find entry in TOC by UID).
  87 To create TOC select event use gst_event_new_toc_select(). The common action on
  88 such event is to seek to specified UID within your element.
  89