docs/random/wtay/timecache

   1 1) intro
   2 --------
   3
   4 For efficient and accurate seeking, a plugin typically needs
   5 an index of possible seek positions (in time, bytes, samples, ...).
   6
   7 The purpose of GstTimecache is to provide an infrastructure for
   8 plugins to maintain such an index.
   9
  10 By creating a generic interace to this functionality, it is also
  11 possible for the application to make use of the generated index.
  12 possible use cases are: saving/loading of indexes, obtain an
  13 overview of the indexed stream (where is sample N, where is
  14 the keyframe...)
  15
  16
  17 This document describes a proposed API for this functionality.
  18
  19
  20 2) Requirements
  21 ---------------
  22
  23 Bare minimum:
  24
  25 - store mappings between format1 and format2 (bytes<->time,
  26   samples<->tracks, ...)
  27 - update the mappings (add/remove/change entries)
  28 - query the index, locate entries.
  29 - store arbitrary extra metadata in the timecache (media file,
  30   time, author, ...)
  31 - set/get cache on elements.
  32
  33 Nice to have:
  34
  35 - cache groups with varying certainty that are merged.
  36 - API to control the indexing process, what gets indexed, how much,
  37   ...)
  38 - Get notification when a new entry is added, together with an
  39   option to turn off in-memory caching, this could be used to
  40   do direct-to-disk indexing (for large files) insteda of to-memory.
  41
  42 3) use cases
  43 ------------
  44
  45 a) indexing an mpeg systems stream
  46
  47   - create an empty timecache object
  48   - create filesrc ! mpegparse
  49   - set timecache on mpegparse
  50   - run the pipeline to EOS
  51     - mpegparse will create a mapping from SCR to byte offset
  52       and add it to the cache.
  53   - read/save timecache
  54
  55 b) running an mpeg with a previously created cache
  56
  57   - create timecache object from saved index
  58   - create filesrc ! mpegparse
  59   - set the timecache on mpegparse
  60   - run the pipeline, seek, ...
  61     - mpegparse uses the timecache to do accurate seek to
  62       SCR timestamps.
  63
  64 c) indexing an mpeg systems stream, SCR, video and audio elementary
  65    streams.
  66
  67   - create an empty timecache object
  68   - create filesrc ! mpegdemux
  69   - set timecache on mpegdemux
  70   - run the pipeline to EOS
  71     - mpegparse will create a mappings for:
  72        * SCR to byte offset
  73        * PTS + streamid to byte offset
  74       and add it to the cache.
  75   - read/save timecache
  76
  77 d) complete indexing of mpeg systems streams and audio/video
  78    streams.
  79
  80   - create 3 empty timecaches
  81   - create filesrc ! mpegdemux video_%02d! mpeg2dec
  82                      mpegdemux0 audio_%02d! mad
  83   - set timecaches on mpegdemux, mpeg2dec, mad
  84   - run pipeline to EOS
  85     - mpegdemux creates timecache for SCR, PTS + streamid
  86     - mpeg2dec creates timecache for frames + I/P/B id
  87     - mad creates timecache for mpeg audio headers
  88   - read/save timecaches
  89
  90   seeking in a fully indexed stream:
  91     - seek on timestamp in mpeg2dec
  92     - mpeg2dec locates previous I frame in cache, does
  93       a timeseek on sinkpad
  94     - mpegparse uses the cache to convert the timestamp
  95       to an offset, then does a seek on offset
  96     - filesrc seeks to offset
  97
  98 4) Entry types
  99 --------------
 100
 101  - mapping between formats:
 102
 103     <padid> <flags> <format> <position>, <format> <position>, ...
 104
 105  - metadata, streaminfo, other objects:
 106
 107     <padid> <format> <position>, <keyword> gpointer
 108
 109
 110 5) implementation
 111 -----------------
 112
 113 We define an abstract base class GstTimeCache with following
 114 abstract methods:
 115
 116
 117 6) cache format example
 118 -----------------------
 119
 120 We define a binary format for the cache for space/speed reasons.
 121 It is entirely possible to create alternative implementations.
 122
 123
 124
 125
 126
 127
 128
 129
 130
 131
 132
 133