--- /dev/null
+1) intro
+--------
+
+For efficient and accurate seeking, a plugin typically needs
+an index of possible seek positions (in time, bytes, samples, ...).
+
+The purpose of GstTimecache is to provide an infrastructure for
+plugins to maintain such an index.
+
+By creating a generic interace to this functionality, it is also
+possible for the application to make use of the generated index.
+possible use cases are: saving/loading of indexes, obtain an
+overview of the indexed stream (where is sample N, where is
+the keyframe...)
+
+
+This document describes a proposed API for this functionality.
+
+
+2) Requirements
+---------------
+
+Bare minimum:
+
+- store mappings between format1 and format2 (bytes<->time,
+ samples<->tracks, ...)
+- update the mappings (add/remove/change entries)
+- query the index, locate entries.
+- store arbitrary extra metadata in the timecache (media file,
+ time, author, ...)
+- set/get cache on elements.
+
+Nice to have:
+
+- cache groups with varying certainty that are merged.
+- API to control the indexing process, what gets indexed, how much,
+ ...)
+- Get notification when a new entry is added, together with an
+ option to turn off in-memory caching, this could be used to
+ do direct-to-disk indexing (for large files) insteda of to-memory.
+
+3) use cases
+------------
+
+a) indexing an mpeg systems stream
+
+ - create an empty timecache object
+ - create filesrc ! mpegparse
+ - set timecache on mpegparse
+ - run the pipeline to EOS
+ - mpegparse will create a mapping from SCR to byte offset
+ and add it to the cache.
+ - read/save timecache
+
+b) running an mpeg with a previously created cache
+
+ - create timecache object from saved index
+ - create filesrc ! mpegparse
+ - set the timecache on mpegparse
+ - run the pipeline, seek, ...
+ - mpegparse uses the timecache to do accurate seek to
+ SCR timestamps.
+
+c) indexing an mpeg systems stream, SCR, video and audio elementary
+ streams.
+
+ - create an empty timecache object
+ - create filesrc ! mpegdemux
+ - set timecache on mpegdemux
+ - run the pipeline to EOS
+ - mpegparse will create a mappings for:
+ * SCR to byte offset
+ * PTS + streamid to byte offset
+ and add it to the cache.
+ - read/save timecache
+
+d) complete indexing of mpeg systems streams and audio/video
+ streams.
+
+ - create 3 empty timecaches
+ - create filesrc ! mpegdemux video_%02d! mpeg2dec
+ mpegdemux0 audio_%02d! mad
+ - set timecaches on mpegdemux, mpeg2dec, mad
+ - run pipeline to EOS
+ - mpegdemux creates timecache for SCR, PTS + streamid
+ - mpeg2dec creates timecache for frames + I/P/B id
+ - mad creates timecache for mpeg audio headers
+ - read/save timecaches
+
+ seeking in a fully indexed stream:
+ - seek on timestamp in mpeg2dec
+ - mpeg2dec locates previous I frame in cache, does
+ a timeseek on sinkpad
+ - mpegparse uses the cache to convert the timestamp
+ to an offset, then does a seek on offset
+ - filesrc seeks to offset
+
+4) Entry types
+--------------
+
+ - mapping between formats:
+
+ <padid> <flags> <format> <position>, <format> <position>, ...
+
+ - metadata, streaminfo, other objects:
+
+ <padid> <format> <position>, <keyword> gpointer
+
+
+5) implementation
+-----------------
+
+We define an abstract base class GstTimeCache with following
+abstract methods:
+
+
+6) cache format example
+-----------------------
+
+We define a binary format for the cache for space/speed reasons.
+It is entirely possible to create alternative implementations.
+
+
+
+
+
+
+
+
+
+
+
+