markdown/additional/design/toc.md

   1 # Implementing GstToc support in GStreamer elements
   2
   3 ## 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: sequence or
   8 alternative. Sequence types acts like a part of the media data, for
   9 example audio track in CUE sheet, or part of the movie. Alternative
  10 types acts like some kind of selection to process a different version of
  11 the media content, for example DVD angles. `GstToc` has one constraint on
  12 the tree structure: it does not allow different entry types on the same
  13 level of the hierarchy, i.e. you shouldn’t have editions and chapters
  14 mixed together. Here is an example of right TOC:
  15
  16 ```
  17 -------  TOC  -------
  18          /  \
  19  edition1    edition2
  20  |           |
  21  -chapter1   -chapter3
  22  -chapter2
  23 ```
  24
  25 Here are two editions (alternatives), the first contains two chapters
  26 (sequence type), and the second has only one chapter. And here is an
  27 example of invalid TOC:
  28
  29 ```
  30 -------  TOC  -------
  31          /  \
  32  edition1    chapter1
  33  |
  34  -chapter1
  35  -chapter2
  36 ```
  37
  38 Here you have edition1 and chapter1 mixed on the same level of
  39 hierarchy, and such TOC will be considered broken.
  40
  41 `GstToc` has *entries* field of GList type which consists of children
  42 items. Each item is of type `GstTocEntry`. Also `GstToc` has list of tags
  43 and `GstStructure` called *info*. Please, use `GstToc.info` and
  44 `GstTocEntry.info` fields this way: create a `GstStructure`, put all info
  45 related to your element there and put this structure into the *info*
  46 field under the name of your element. Some fields in the *info*
  47 structure can be used for internal purposes, so you should use it in the
  48 way described above to not to overwrite already existent fields.
  49
  50 Let’s look at `GstTocEntry` a bit closer. One of the most important fields
  51 is *uid*, which must be unique for each item within the TOC. This is
  52 used to identify each item inside TOC, especially when element receives
  53 TOC select event with UID to seek on. Field *subentries* of type GList
  54 contains children items of type `GstTocEntry`. Thus you can achieve
  55 arbitrary hierarchy level. Field *type* can be either
  56 `GST_TOC_ENTRY_TYPE_CHAPTER` or `GST_TOC_ENTRY_TYPE_EDITION` which
  57 corresponds to chapter or edition type of item respectively. Field
  58 *tags* is a list of tags related to the item. And field *info* is
  59 similar to `GstToc.info` described above.
  60
  61 So, a little more about managing `GstToc`. Use `gst_toc_new()` and
  62 `gst_toc_unref()` to create/free it. `GstTocEntry` can be created using
  63 `gst_toc_entry_new()`. While building `GstToc` you can set start and stop
  64 timestamps for each item using `gst_toc_entry_set_start_stop()` and
  65 `loop_type` and `repeat_count` using `gst_toc_entry_set_loop()`. The
  66 best way to process already created `GstToc` is to recursively go through
  67 the *entries* and *subentries* fields.
  68
  69 Applications and plugins should not rely on TOCs having a certain kind
  70 of structure, but should allow for different alternatives. For example,
  71 a simple CUE sheet embedded in a file may be presented as a flat list of
  72 track entries, or could have a top-level edition node (or some other
  73 alternative type entry) with track entries underneath that node; or even
  74 multiple top-level edition nodes (or some other alternative type
  75 entries) each with track entries underneath, in case the source file has
  76 extracted a track listing from different sources).
  77
  78 ##  TOC scope: global and current
  79
  80 There are two main consumers for TOC information: applications and
  81 elements in the pipeline that are TOC writers (such as e.g.
  82 matroskamux).
  83
  84 Applications typically want to know the entire table of contents (TOC)
  85 with all entries that can possibly be selected.
  86
  87 TOC writers in the pipeline, however, would not want to write a TOC for
  88 all possible/available streams, but only for the current stream.
  89
  90 When transcoding a title from a DVD, for example, the application would
  91 still want to know the entire TOC, with all titles, the chapters for
  92 each title, and the available angles. When transcoding to a file, we
  93 only want the TOC information that is relevant to the transcoded stream
  94 to be written into the file structure, e.g. the chapters of the title
  95 being transcoded (or possibly only chapters 5-7 if only those have been
  96 selected for playback/ transcoding).
  97
  98 This is why we may need to create two different TOCs for those two types
  99 of consumers.
 100
 101 Elements that extract TOC information should send TOC events downstream.
 102
 103 Like with tags, sinks will post a TOC message on the bus for the
 104 application with the global TOC, once a global TOC event reaches the
 105 sink.
 106
 107 ##  Working with GstMessage
 108
 109 If a table of contents is available, applications will receive a TOC
 110 message on the pipeline’s `GstBus`.
 111
 112 A TOC message will be posted on the bus by sinks when the receive a TOC
 113 event containing a TOC with global scope. Elements extracting TOCs
 114 should not post a TOC message themselves, but send a TOC event
 115 downstream.
 116
 117 The reason for this is that there may be cascades of TOCs (e.g. a zip
 118 archive containing multiple matroska files, each with a TOC).
 119
 120 `GstMessage` with `GstToc` can be created using `gst_message_new_toc()` and
 121 parsed with `gst_message_parse_toc()`. The *updated* parameter in these
 122 methods indicates whether the TOC was just discovered (set to false) or
 123 TOC was already found and have been updated (set to true). This message
 124 will typically be posted by sinks to pipeline in case you have
 125 discovered TOC data within your element.
 126
 127 ##  Working with GstEvent
 128
 129 There are two types of TOC-related events:
 130
 131   - downstream TOC events that contain TOC information and travel
 132     downstream
 133
 134   - toc-select events that travel upstream and can be used to select a
 135     certain TOC entry for playback (similar to seek events)
 136
 137 `GstToc` supports select event through `GstEvent` infrastructure. The idea
 138 is the following: when you receive TOC select event, parse it with
 139 `gst_event_parse_toc_select()` and seek stream (if it is not
 140 streamable) for specified TOC UID (you can use `gst_toc_find_entry()`
 141 to find entry in TOC by UID). To create TOC select event use
 142 `gst_event_new_toc_select()`. The common action on such event is to
 143 seek to specified UID within your element.
 144
 145 ## Implementation coverage, Specifications, …
 146
 147 Below is a list of container formats, links to documentation and a
 148 summary of toc related features. Each section title also indicates
 149 whether reading/writing a toc is implemented. Below hollow bullet point
 150 *o* indicate no support and filled bullets *\*\* indicate that this
 151 feature is handled.
 152
 153 ### AIFC: -/-
 154 <http://www-mmsp.ece.mcgill.ca/Documents/AudioFormats/AIFF/Docs/AIFF-1.3.pdf>
 155 o *MARK* o *INST*
 156
 157 The *MARK* chunk defines a list of (cue-id, `position_in_samples`,
 158 label).
 159
 160 The *INST* chunk contains a sustainLoop and releaseLoop, each consisting
 161 of (loop-type, cue-begin, cue-end)
 162
 163 ### FLAC: read/write
 164
 165 <http://xiph.org/flac/format.html#metadata_block_cuesheet> \*
 166 METADATA\_BLOCK\_CUESHEET \* CUESHEET\_TRACK o CUESHEET\_TRACK\_INDEX
 167
 168 Both `CUESHEET_TRACK` and `CUESHEET_TRACK_INDEX` have a (relative) offset
 169 in samples. `CUESHEET_TRACK` has ISRC metadata.
 170
 171 ### MKV: read/write
 172
 173 <http://matroska.org/technical/specs/chapters/index.html> \* Chapters
 174 and Editions each having a uid \* Chapter have start/end time and
 175 metadata: ChapString, ChapLanguage, ChapCountry
 176
 177 ### MP4: \* elst
 178
 179 The *elst* atom contains a list of edits. Each edit consists of (length,
 180 start, play-back speed).
 181
 182 ### OGG: -/- <https://wiki.xiph.org/Chapter_Extension> o VorbisComment
 183
 184 fields called CHAPTERxxx and CHAPTERxxxNAME with xxx being a number
 185 between 000 and 999.
 186
 187 ### WAV: read/write <http://www.sonicspot.com/guide/wavefiles.html> \* *cue
 188 ' o 'plst* \* *adtl* \* *labl* \* *note* o *ltxt* o *smpl*
 189
 190 The `*cue` chunk defines a list of markers in the stream with `cue-id`s.
 191 The `smpl*` chunk defines a list of regions in the stream with `cue-id`s
 192 in the same namespace (?).
 193
 194 The various *adtl* chunks: *labl*, *note* and *ltxt* refer to the
 195 'cue-id’s.
 196
 197 A *plst* chunk defines a sequence of segments (`cue-id`, `length_samples`,
 198 repeats). The *smpl* chunk defines a list of loops (`cue-id`, `beg`, `end`,
 199 `loop-type`, `repeats`).
 200
 201 ## Conclusion/Ideas/Future work
 202
 203 Based on the data of chapter 5, a few thoughts and observations that can
 204 be used to extend and refine our API. These things below are not
 205 reflecting the current implementation.
 206
 207 All formats have table of `[cue-id, cue-start, (cue-end), (extra tags)]`
 208 - `cue-id` is commonly represented as and unsigned int 32bit - `cue-end` is
 209 optional. Extra tags could be represented as a structure/taglist
 210
 211 Many formats have metadata that references the cue-table. - loops in
 212 instruments in wav, aifc - edit lists in wav, mp4
 213
 214 For mp4.edtl, wav.plst we could expose two editions. 1) the edit list is
 215 flattened: default, for playback 2) the stream has the raw data and the
 216 edit list is there as chapter markers: useful for editing software
 217
 218 We might want to introduce a new `GST_TOC_ENTRY_TYPE_MARKER` or `_CUE`.
 219 This would be a sequence entry-type and it would not be used for
 220 navigational purposes, but to attach data to a point in time (envelopes,
 221 loops, …).
 222
 223 API wise there is some overlap between: - exposing multiple audio/video
 224 tracks as pads or as ToC editions. For ToC editions, we have the
 225 TocSelect event. - exposing subtitles as a sparse stream or as ToC
 226 sequence of markers with labels