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