[xiph-commits] r12760 - trunk/theora/doc/spec

[giles at svn.xiph.org]

Author: giles
Date: 2007-03-14 12:01:44 -0700 (Wed, 14 Mar 2007)
New Revision: 12760

Modified:
   trunk/theora/doc/spec/spec.tex
Log:
Draft of the granulepos spec, not finished.


Modified: trunk/theora/doc/spec/spec.tex
===================================================================
--- trunk/theora/doc/spec/spec.tex	2007-03-14 14:30:21 UTC (rev 12759)
+++ trunk/theora/doc/spec/spec.tex	2007-03-14 19:01:44 UTC (rev 12760)
@@ -7710,24 +7710,44 @@
 These two page break requirements facilitate stream identification and
  simplify header acquisition for seeking and live streaming applications.
 
-All header pages MUST have their granule position field set to zero.
-%TODO: or -1?
-%TBT: What are we doing now?
-
 \subsection{Frame data}
 
 The first frame data packet in a logical bitstream MUST begin a fresh page.
-All other data packets are placed one at a time into Ogg pages
+All other data packets are placed in sequence into Ogg pages
  until the end of the stream.
 Packets can span pages and multiple packets can be placed within any
  one page.
 The last page in the logical bitstream MUST have its `end of stream'
  flag set.
 
+{\bf Note:} Care should be taken when packing many small packets into
+ the same Ogg page, especially with zero-length "duplicate frame"
+ packets. Readers and writers (usually) work at page granularity,
+ so this introduces additional latency in stream transmission. 
+
+\subsection{Granule position}
+
+Ogg stores a codec-defined timestamp in the header of each page
+ structure. In theora this timestamp is derived from the elapsed
+ count of decodable frames.
+
+However, to facilitate the location of keyframes when seeking, this
+ count is stored in two parts. The granulepos field is divided into
+ two parts based on the maximum keyframe spacing defined in the theora
+ info header. The more significant bits hold the frame count of
+ the most recent keyframe, and the less significant bits hold a
+ count of the frames elapsed since the first keyframe. The radix
+ dividing the two fields is $\ilog(maximum keyframe spacing - 1)$.
+ 
+All header pages SHOULD have their granule position field set to zero if
+ a packet terminates within that page. Since no frames are yet decodable,
+ and the keyframe radix is not yet known, the granulepos for the header
+ packets is conceptually zero.
+
 Frame data pages MUST be marked with a granule index corresponding to
- the display time of the last frame/packet that finishes in that page.
+ the elapsed count of frames as of the the last frame/packet that 
+ finishes in that page.
 
-%TODO: \subsection{Granule position}
 
 \section{Multiplexed stream mapping}