Ogg Index

From XiphWiki

(Difference between revisions)
Jump to: navigation, search
 
(3 intermediate revisions not shown)
Line 1: Line 1:
{{draft}}
{{draft}}
-
= Ogg Skeleton 3.1 with Keyframe Index =
+
= Ogg Skeleton 3.3 with Keyframe Index =
-
'''DRAFT, last updated 11 January 2010'''
+
'''This specification is obsolete and has been superseded by [[Ogg Skeleton 4]]. Use that instead!'''
-
 
+
-
'''This specification is still a work in progress, and does not yet constitute an official Ogg track format.'''
+
== Overview ==
== Overview ==
Line 34: Line 32:
== Seeking with an index ==
== Seeking with an index ==
-
The Skeleton 3.1 bitstream attempts to alleviate this problem, by  
+
The Skeleton 3.3 bitstream attempts to alleviate this problem, by  
providing an index of periodic keyframes for every content stream in an  
providing an index of periodic keyframes for every content stream in an  
-
Ogg segment. Note that the Skeleton 3.1 track only holds data for the  
+
Ogg segment. Note that the Skeleton 3.3 track only holds data for the  
-
segment in which it resides. So if two Ogg files are concatenated together
+
segment or "link" in which it resides. So if two Ogg files are concatenated
-
("chained"), the Skeleton 3.1's keyframe indexes in the first Ogg segment
+
together ("chained"), the Skeleton 3.3's keyframe indexes in the first Ogg
-
(the first Ogg in the "chain") do not contain information about the
+
segment (the first "link" in the "chain") do not contain information
-
keyframes in the second Ogg segment (the second Ogg in the "chain").  
+
about the keyframes in the second Ogg segment (the second link in the chain).
Each content track has a separate index, which is stored in its own  
Each content track has a separate index, which is stored in its own  
-
packet in the Skeleton 3.1 track. The index for streams without the  
+
packet in the Skeleton 3.3 track. The index for streams without the  
concept of a keyframe, such as Vorbis streams, can instead record the  
concept of a keyframe, such as Vorbis streams, can instead record the  
time position at periodic intervals, which achieves the same result.  
time position at periodic intervals, which achieves the same result.  
Line 49: Line 47:
independent periodic samples from keyframe-less streams.  
independent periodic samples from keyframe-less streams.  
-
All the Skeleton 3.1 track's pages appear in the header pages of the Ogg  
+
All the Skeleton 3.3 track's pages appear in the header pages of the Ogg  
segment. This means the all the keyframe indexes are immediately  
segment. This means the all the keyframe indexes are immediately  
available once the header packets have been read when playing the media
available once the header packets have been read when playing the media
Line 56: Line 54:
For every content stream in an Ogg segment, the Ogg index bitstream  
For every content stream in an Ogg segment, the Ogg index bitstream  
provides seek algorithms with an ordered table of "key points". A key  
provides seek algorithms with an ordered table of "key points". A key  
-
point is intrinsically associated with exactly one stream, and refers to
+
point is intrinsically associated with exactly one stream, and stores the
-
a page in that stream. A key point k is defined as follows. Each key
+
offset of the page on which it starts, o, as well as the presentation time
-
point has an 8 byte offset o, a presentation time t as a fraction with an
+
of the keyframe t, as a fraction of seconds. This specifies that in order
-
8 byte numerator and an 8 byte denominator, and a 4 byte checksum c.  
+
to render the stream at presentation time t, the last page which lies before
-
This specifies that in order to render the stream at presentation time t,
+
all information required to render the keyframe at presentation time t begins
-
the last page which lies before all information required to render the  
+
exactly at byte offset o, as offset from the beginning of the Ogg segment.
-
keyframe at presentation time t begins at byte offset o, as offset from
+
The offset is exactly the first byte of the page, so if you seek to a
-
the beginning of the Ogg segment. The checksum c is the checksum of the
+
keypoint's offset and don't find the beginning of a page there, you can
-
page which begins at offset o. This enables you to verify that you're
+
assume that the Ogg segment has been modified since the index was constructed,
-
seeking to the intended page, and that the segment has not been modified
+
and that the index is now invalid and should not be used. The time t is the
-
since the index was constructed. The time t is the keyframe's presentation
+
keyframe's presentation time corresponding to the granulepos, and is
-
time corresponding to the granulepos, and is represented as a fraction in
+
represented as a fraction in seconds. Note that if a stream requires any
-
seconds. Note that if a stream requires any preroll, this will be  
+
preroll, this will be accounted for in the time stored in the keypoint.  
-
accounted for in the time stored in the keypoint.  
+
-
The Skeleton 3.1 track contains one index for each content stream in the  
+
The Skeleton 3.3 track contains one index for each content stream in the  
file. To seek in an Ogg file which contains keyframe indexes, first
file. To seek in an Ogg file which contains keyframe indexes, first
construct the set which contains every active streams' last keypoint which
construct the set which contains every active streams' last keypoint which
has time less than or equal to the seek target time. Then from that set
has time less than or equal to the seek target time. Then from that set
of key points, select the key point with the smallest byte offset. You then
of key points, select the key point with the smallest byte offset. You then
-
verify that the page found at the selected key point's byte offset has the
+
verify that there's a page found at exactly that offset, and if so, you can
-
same checksum as the selected keypoint's checksum, and if so, you can begin
+
begin decoding. If the first keyframe you encounter has a time equal to
-
decoding up to the seek target time. You are guaranteed to pass keyframes
+
that stored in the keypoint, you have made the optimal seek, and can safely
-
on all streams with time less than or equal to your seek target time while
+
continue to decode up to the seek target time. You are guaranteed to pass
-
decoding up to the seek target.  
+
keyframes on all streams with time less than or equal to your seek target
 +
time while decoding up to the seek target. However if the first keyframe
 +
you encounter after decoding does not have the same presentation time as
 +
is stored in the keypoint, you then the index is invalid (possibly the file
 +
has been changed without updating the index) and you must either fallback
 +
to a bisection search, or keep decoding if you've landed "close enough"
 +
to the seek target.
Be aware that you cannot assume that any or all Ogg files will contain  
Be aware that you cannot assume that any or all Ogg files will contain  
-
keyframe indexes, and so when implementing Ogg seeking, you must  
+
keyframe indexes, so when implementing Ogg seeking, you must gracefully
-
gracefully fall-back to a bisection search or other seek algorithm when  
+
fall-back to a bisection search or other seek algorithm when the index
-
the index is not present.  
+
is not present, or when it is invalid.
-
When using the index to seek, you must verify that the index is still
+
The Skeleton 3.3 BOS packet also stores meta data about the segment in  
-
correct - always check the key point's checksum matches the checksum of
+
-
the page found at excatly the checksum's offset. If it does not match,
+
-
the file has changed since it was indexed, and you cannot rely on the
+
-
index being reliable. You should then fallback to seek using a bisection
+
-
search. You should also always check the Skeleton version header field
+
-
to ensure your decoder correctly knows how to parse the Skeleton track.
+
-
 
+
-
The Skeleton 3.1 header packet also stores meta data about the segment in  
+
which it resides. It stores the timestamps of the first and last samples
which it resides. It stores the timestamps of the first and last samples
in the segment. This also allows you to determine the duration of the
in the segment. This also allows you to determine the duration of the
indexed Ogg media without having to decode the start and end of the
indexed Ogg media without having to decode the start and end of the
-
Ogg segment to calculate the difference (which is the duration). The index
+
Ogg segment to calculate the difference (which is the duration).
-
header also contains the length of the index segment in bytes. This is so
+
 
-
that if the seek target is outside of the indexed range, you can
+
The Skeleton 3.3 BOS packet also contains the length of the indexed segment
-
immediately move to the next/previous segment and either seek using that
+
in bytes. This is so that if the seek target is outside of the indexed range,
-
segment's index, or narrow the bisection window if that segment has no index.
+
you can immediately move to the next/previous segment and either seek using
 +
that segment's index, or narrow the bisection window if that segment has no
 +
index. You can also use the segement length to verify if the index is valid.
 +
If the contents of the segment have changed, it's highly likely that the
 +
length of the segment has changed as well. When you load the segment's
 +
header pages, you should check the length of the physical segment, and if it
 +
doesn't match that stored in the Skeleton header packet, you know the index
 +
is out of date and not safe to use.
 +
 
 +
The Skeleton 3.3 BOS packet also contains the offset of the first non header
 +
page in the Ogg segment. This means that if you wish to delay loading of an
 +
index for whatever reason, you can skip forward to that offset, and start
 +
decoding from that offset forwards.
 +
 
 +
When using the index to seek, you must verify that the index is still
 +
correct. You can consider the index invalid if any of the following are true:
 +
 
 +
# The segment length stored in the Skeleton BOS packet doesn't match the length of the physical segment, or
 +
# after a seek to a keypoint's offset, you don't land exactly on a page boundary, or
 +
# the first keyframe decoded after seeking to a keypoint's offset doesn't have the same presentation time as stored in the index.
 +
 
 +
You should also always check the Skeleton version header field
 +
to ensure your decoder correctly knows how to parse the Skeleton track.
 +
 
 +
Be aware that a keyframe index may not index all keyframes in the Ogg segment,
 +
it may only index periodic keyframes instead.
== Format Specification ==
== Format Specification ==
Line 112: Line 132:
significant byte first (i.e. little endian byte order).  
significant byte first (i.e. little endian byte order).  
-
The Skeleton 3.1 track is intended to be backwards compatible with the  
+
The Skeleton 3.3 track is intended to be backwards compatible with the  
Skeleton 3.0 specification, available at  
Skeleton 3.0 specification, available at  
http://www.xiph.org/ogg/doc/skeleton.html . Unless specified  
http://www.xiph.org/ogg/doc/skeleton.html . Unless specified  
differently here, it is safe to assume that anything specified for a  
differently here, it is safe to assume that anything specified for a  
-
Skeleton 3.0 track holds for a Skeleton 3.1 track.  
+
Skeleton 3.0 track holds for a Skeleton 3.3 track.  
-
As per the Skeleton 3.0 track, a segment containing a Skeleton 3.1 track  
+
As per the Skeleton 3.0 track, a segment containing a Skeleton 3.3 track  
-
must begin with a '''Skeleton 3.1 fishead BOS packet''' on a page by itself, with the  
+
must begin with a '''Skeleton 3.3 fishead BOS packet''' on a page by itself, with the  
following format:  
following format:  
Line 134: Line 154:
# '''[NEW]''' Last-sample-time numerator: 8 byte signed integer representing the end time of the last sample in the segment.
# '''[NEW]''' Last-sample-time numerator: 8 byte signed integer representing the end time of the last sample in the segment.
# '''[NEW]''' Last-sample-time denominator: 8 byte signed integer, with value 0 if the timestamp is unknown. Decoders should always ensure that the denominator is not 0 before using it as a divisor!
# '''[NEW]''' Last-sample-time denominator: 8 byte signed integer, with value 0 if the timestamp is unknown. Decoders should always ensure that the denominator is not 0 before using it as a divisor!
-
# '''[NEW]''' The length of the segment, in bytes: 8 byte signed integer, -1 if unknown.
+
# '''[NEW]''' The length of the segment, in bytes: 8 byte unsigned integer, 0 if unknown.
 +
# '''[NEW]''' The offset of the first non-header page, in bytes: 8 byte unsigned integer, 0 if unknown.
The first-sample-time and last-sample-time are rational numbers, in units
The first-sample-time and last-sample-time are rational numbers, in units
Line 142: Line 163:
subtracting the first-sample-time from the last-sample-time.
subtracting the first-sample-time from the last-sample-time.
-
In Skeleton 3.1 the "fisbone" packets remain unchanged from Skeleton  
+
In '''Skeleton 3.3 the "fisbone" packets remain unchanged from Skeleton  
-
3.0, and will still follow after the other streams' BOS pages and  
+
3.0''', and will still follow after the other streams' BOS pages and  
secondary header pages.  
secondary header pages.  
Before the Skeleton EOS page in the segment header pages come the  
Before the Skeleton EOS page in the segment header pages come the  
-
'''Skeleton 3.1 keyframe index packets'''. There is one index packet for each
+
Skeleton 3.3 keyframe index packets. There should be one index packet for
-
content stream in the Ogg segment. Each index packet contains the  
+
each content stream in the Ogg segment, but index packets are not required
-
following:  
+
for a Skeleton 3.3 track to be considered valid. Each keypoint in the index
 +
is stored in a "keypoint", which in turn stores an offset, checksum, and
 +
timestamp. In order to save space, the offsets and timestamps are stored as
 +
deltas, and then variable byte-encoded. The offset and timestamp deltas
 +
store the difference between the keypoint's offset and timestamp from the
 +
previous keypoint's offset and timestamp. So to calculate the page offset
 +
of a keypoint you must sum the offset deltas of up to and including the
 +
keypoint in the index.
 +
 
 +
The variable byte encoded integers are encoded using 7 bits per byte to
 +
store the integer's bits, and the high bit is set in the last byte used
 +
to encode the integer. The bits and bytes are in little endian byte order.
 +
For example, the integer 7843, or <tt>0001 1110 1010 0011</tt> in binary, would be
 +
stored as two bytes: <tt>0xBD 0x23</tt>, or <tt>1011 1101 0010 0011</tt> in binary.
 +
 
 +
Each '''Skeleton 3.3 keyframe index packet''' contains the following:  
# Identifier 6 bytes: "index\0"
# Identifier 6 bytes: "index\0"
# The serialno of the stream this index applies to, as a 4 byte field.
# The serialno of the stream this index applies to, as a 4 byte field.
-
# The number of keypoints in this index packet, 'n' as a 4 byte unsigned integer. This can be 0.
+
# The number of keypoints in this index packet, 'n' as a 8 byte unsigned integer. This can be 0.
# The keypoint presentation time denominator, as an 8 byte signed integer.
# The keypoint presentation time denominator, as an 8 byte signed integer.
# 'n' key points, each of which contain, in the following order:
# 'n' key points, each of which contain, in the following order:
-
## a page start's byte offset as an 8 byte unsigned integer, followed by
+
## the keyframe's page's byte offset delta, as a variable byte encoded integer. This is the number of bytes that this keypoint is after the preceeding keypoint's offset, or from the start of the segment if this is the first keypoint. The keypoint's page start is therefore the sum of the byte-offset-deltas of all the keypoints which come before it.
-
## the checksum of the page found at the offset, as a 4 byte field, followed by
+
## the presentation time numerator delta, of the first key frame which starts on the page at the keypoint's offset, as a variable byte encoded integer. This is the difference from the previous keypoint's timestamp numerator. The keypoint's timestamp numerator is therefore the sum of all the timestamp numerator deltas up to and including the keypoint's. Divide the timestamp numerator sum by the timestamp denominator stored earlier in the index packet to determine the presentation time of the keyframe in seconds.
-
## the presentation time numerator of the first key frame which starts on the page at the keypoint's offset, as an 8 byte integer. Divide this by the timestamp denominator to determine the presentation time of the keyframe in seconds.
+
Note that a keypoint always represents the first key frame on a page. If an
Note that a keypoint always represents the first key frame on a page. If an
Ogg page contains two or more keyframes, the index's key point *must* refer
Ogg page contains two or more keyframes, the index's key point *must* refer
-
to the first keyframe on that page, not the second.
+
to the first keyframe on that page, not any subsequent keyframes on that page.
The key points are stored in increasing order by offset (and thus by  
The key points are stored in increasing order by offset (and thus by  
-
presentation time as well). Note that an index packet may be larger than
+
presentation time as well).
-
(6 + 4 + 4 + 8 + (n * (8 + 4 + 8)) bytes, as it may have been
+
-
preallocated during encoding, but not completely filled. Do not make
+
-
assumptions about an index packet's size, always check an index packet's
+
-
'bytes' field to determine its size, and always use its 'n' field to
+
-
determine the number of keypoints contained in the index packet.  
+
The byte offsets stored in keypoints are relative to the start of the Ogg
The byte offsets stored in keypoints are relative to the start of the Ogg
Line 178: Line 208:
Also note that if a physical Ogg bitstream is made up of chained Oggs, the
Also note that if a physical Ogg bitstream is made up of chained Oggs, the
presence of an index in one segment does not imply that there will be an
presence of an index in one segment does not imply that there will be an
-
index in any other segment.
+
index in any other segment.
 +
 
 +
The exact number of keyframes used to construct key points in the index
 +
is up to the indexer, but to limit the index size, we recommend
 +
including at most one key point per every 64KB of data, or every 2000ms,
 +
whichever is least frequent.
 +
 
 +
As per the Skeleton 3.0 track, '''the last packet in the Skeleton 3.3 track
 +
is an empty EOS packet'''.
== Software Prototype ==
== Software Prototype ==
Line 185: Line 223:
Recent [http://firefogg.org/nightly/ ffmpeg2theora nightlies] will also include a keyframe index in the Skeleton
Recent [http://firefogg.org/nightly/ ffmpeg2theora nightlies] will also include a keyframe index in the Skeleton
-
3.1 track if you specify the command line option <tt>--seek-index</tt>.
+
3.3 track if you specify the command line option <tt>--seek-index</tt>.
To see how indexes improves network seeking performance, you can download a development
To see how indexes improves network seeking performance, you can download a development

Latest revision as of 23:22, 22 November 2010

Contents

The following is a draft. It is at best incomplete and at worst completely broken. In any case, it is not an "official" Xiph spec/codec, so use with care.


Ogg Skeleton 3.3 with Keyframe Index

This specification is obsolete and has been superseded by Ogg Skeleton 4. Use that instead!

Overview

Seeking in an Ogg file is typically implemented as a bisection search over the pages in the file. The Ogg physical bitstream is bisected and the next Ogg page's end-time is extracted. The bisection continues until it reaches an Ogg page with an end-time close enough to the seek target time. However in media containing streams which have keyframes and interframes, such as Theora streams, your bisection search won't necessarily terminate at a keyframe. Thus if you begin decoding after your first bisection terminates, you're likely to only get partial incomplete frames, with "visual artifacts", until you decode up to the next keyframe. So to eliminate these visual artifacts, after the first bisection terminates, you must extract the keyframe's timestamp from the last Theora page's granulepos, and seek again back to the start of the keyframe and decode forward until you reach the frame at the seek target.

This is further complicated by the fact that packets often span multiple Ogg pages, and that Ogg pages from different streams can be interleaved between spanning packets.

The bisection method above works fine for seeking in local files, but for seeking in files served over the Internet via HTTP, each bisection or non sequential read can trigger a new HTTP request, which can have very high latency, making seeking very slow.

Seeking with an index

The Skeleton 3.3 bitstream attempts to alleviate this problem, by providing an index of periodic keyframes for every content stream in an Ogg segment. Note that the Skeleton 3.3 track only holds data for the segment or "link" in which it resides. So if two Ogg files are concatenated together ("chained"), the Skeleton 3.3's keyframe indexes in the first Ogg segment (the first "link" in the "chain") do not contain information about the keyframes in the second Ogg segment (the second link in the chain).

Each content track has a separate index, which is stored in its own packet in the Skeleton 3.3 track. The index for streams without the concept of a keyframe, such as Vorbis streams, can instead record the time position at periodic intervals, which achieves the same result. When this document refers to keyframes, it also implicitly refers to these independent periodic samples from keyframe-less streams.

All the Skeleton 3.3 track's pages appear in the header pages of the Ogg segment. This means the all the keyframe indexes are immediately available once the header packets have been read when playing the media over a network connection.

For every content stream in an Ogg segment, the Ogg index bitstream provides seek algorithms with an ordered table of "key points". A key point is intrinsically associated with exactly one stream, and stores the offset of the page on which it starts, o, as well as the presentation time of the keyframe t, as a fraction of seconds. This specifies that in order to render the stream at presentation time t, the last page which lies before all information required to render the keyframe at presentation time t begins exactly at byte offset o, as offset from the beginning of the Ogg segment. The offset is exactly the first byte of the page, so if you seek to a keypoint's offset and don't find the beginning of a page there, you can assume that the Ogg segment has been modified since the index was constructed, and that the index is now invalid and should not be used. The time t is the keyframe's presentation time corresponding to the granulepos, and is represented as a fraction in seconds. Note that if a stream requires any preroll, this will be accounted for in the time stored in the keypoint.

The Skeleton 3.3 track contains one index for each content stream in the file. To seek in an Ogg file which contains keyframe indexes, first construct the set which contains every active streams' last keypoint which has time less than or equal to the seek target time. Then from that set of key points, select the key point with the smallest byte offset. You then verify that there's a page found at exactly that offset, and if so, you can begin decoding. If the first keyframe you encounter has a time equal to that stored in the keypoint, you have made the optimal seek, and can safely continue to decode up to the seek target time. You are guaranteed to pass keyframes on all streams with time less than or equal to your seek target time while decoding up to the seek target. However if the first keyframe you encounter after decoding does not have the same presentation time as is stored in the keypoint, you then the index is invalid (possibly the file has been changed without updating the index) and you must either fallback to a bisection search, or keep decoding if you've landed "close enough" to the seek target.

Be aware that you cannot assume that any or all Ogg files will contain keyframe indexes, so when implementing Ogg seeking, you must gracefully fall-back to a bisection search or other seek algorithm when the index is not present, or when it is invalid.

The Skeleton 3.3 BOS packet also stores meta data about the segment in which it resides. It stores the timestamps of the first and last samples in the segment. This also allows you to determine the duration of the indexed Ogg media without having to decode the start and end of the Ogg segment to calculate the difference (which is the duration).

The Skeleton 3.3 BOS packet also contains the length of the indexed segment in bytes. This is so that if the seek target is outside of the indexed range, you can immediately move to the next/previous segment and either seek using that segment's index, or narrow the bisection window if that segment has no index. You can also use the segement length to verify if the index is valid. If the contents of the segment have changed, it's highly likely that the length of the segment has changed as well. When you load the segment's header pages, you should check the length of the physical segment, and if it doesn't match that stored in the Skeleton header packet, you know the index is out of date and not safe to use.

The Skeleton 3.3 BOS packet also contains the offset of the first non header page in the Ogg segment. This means that if you wish to delay loading of an index for whatever reason, you can skip forward to that offset, and start decoding from that offset forwards.

When using the index to seek, you must verify that the index is still correct. You can consider the index invalid if any of the following are true:

  1. The segment length stored in the Skeleton BOS packet doesn't match the length of the physical segment, or
  2. after a seek to a keypoint's offset, you don't land exactly on a page boundary, or
  3. the first keyframe decoded after seeking to a keypoint's offset doesn't have the same presentation time as stored in the index.

You should also always check the Skeleton version header field to ensure your decoder correctly knows how to parse the Skeleton track.

Be aware that a keyframe index may not index all keyframes in the Ogg segment, it may only index periodic keyframes instead.

Format Specification

Unless otherwise specified, all integers and fields in the bitstream are encoded with the least significant bit coming first in each byte. Integers and fields comprising of more than one byte are encoded least significant byte first (i.e. little endian byte order).

The Skeleton 3.3 track is intended to be backwards compatible with the Skeleton 3.0 specification, available at http://www.xiph.org/ogg/doc/skeleton.html . Unless specified differently here, it is safe to assume that anything specified for a Skeleton 3.0 track holds for a Skeleton 3.3 track.

As per the Skeleton 3.0 track, a segment containing a Skeleton 3.3 track must begin with a Skeleton 3.3 fishead BOS packet on a page by itself, with the following format:

  1. Identifier: 8 bytes, "fishead\0".
  2. Version major: 2 Byte unsigned integer denoting the major version (3)
  3. Version minor: 2 Byte unsigned integer denoting the minor version (1)
  4. Presentationtime numerator: 8 Byte signed integer
  5. Presentationtime denominator: 8 Byte signed integer
  6. Basetime numerator: 8 Byte signed integer
  7. Basetime denominator: 8 Byte signed integer
  8. UTC [ISO8601]: a 20 Byte string containing a UTC time
  9. [NEW] First-sample-time numerator: 8 byte signed integer representing the numerator for the presentation time of the first sample in the media. Note that samples between the first-sample-time and the Presentationtime are supposed to be skipped during playback.
  10. [NEW] First-sample-time denominator: 8 byte signed integer, with value 0 if the timestamp is unknown. Decoders should always ensure that the denominator is not 0 before using it as a divisor!
  11. [NEW] Last-sample-time numerator: 8 byte signed integer representing the end time of the last sample in the segment.
  12. [NEW] Last-sample-time denominator: 8 byte signed integer, with value 0 if the timestamp is unknown. Decoders should always ensure that the denominator is not 0 before using it as a divisor!
  13. [NEW] The length of the segment, in bytes: 8 byte unsigned integer, 0 if unknown.
  14. [NEW] The offset of the first non-header page, in bytes: 8 byte unsigned integer, 0 if unknown.

The first-sample-time and last-sample-time are rational numbers, in units of seconds. If the denominator is 0 for the first-sample-time or the last-sample-time, then that value was unable to be determined at indexing time, and is unknown. The duration of the Ogg segment can be calculated by subtracting the first-sample-time from the last-sample-time.

In Skeleton 3.3 the "fisbone" packets remain unchanged from Skeleton 3.0, and will still follow after the other streams' BOS pages and secondary header pages.

Before the Skeleton EOS page in the segment header pages come the Skeleton 3.3 keyframe index packets. There should be one index packet for each content stream in the Ogg segment, but index packets are not required for a Skeleton 3.3 track to be considered valid. Each keypoint in the index is stored in a "keypoint", which in turn stores an offset, checksum, and timestamp. In order to save space, the offsets and timestamps are stored as deltas, and then variable byte-encoded. The offset and timestamp deltas store the difference between the keypoint's offset and timestamp from the previous keypoint's offset and timestamp. So to calculate the page offset of a keypoint you must sum the offset deltas of up to and including the keypoint in the index.

The variable byte encoded integers are encoded using 7 bits per byte to store the integer's bits, and the high bit is set in the last byte used to encode the integer. The bits and bytes are in little endian byte order. For example, the integer 7843, or 0001 1110 1010 0011 in binary, would be stored as two bytes: 0xBD 0x23, or 1011 1101 0010 0011 in binary.

Each Skeleton 3.3 keyframe index packet contains the following:

  1. Identifier 6 bytes: "index\0"
  2. The serialno of the stream this index applies to, as a 4 byte field.
  3. The number of keypoints in this index packet, 'n' as a 8 byte unsigned integer. This can be 0.
  4. The keypoint presentation time denominator, as an 8 byte signed integer.
  5. 'n' key points, each of which contain, in the following order:
    1. the keyframe's page's byte offset delta, as a variable byte encoded integer. This is the number of bytes that this keypoint is after the preceeding keypoint's offset, or from the start of the segment if this is the first keypoint. The keypoint's page start is therefore the sum of the byte-offset-deltas of all the keypoints which come before it.
    2. the presentation time numerator delta, of the first key frame which starts on the page at the keypoint's offset, as a variable byte encoded integer. This is the difference from the previous keypoint's timestamp numerator. The keypoint's timestamp numerator is therefore the sum of all the timestamp numerator deltas up to and including the keypoint's. Divide the timestamp numerator sum by the timestamp denominator stored earlier in the index packet to determine the presentation time of the keyframe in seconds.

Note that a keypoint always represents the first key frame on a page. If an Ogg page contains two or more keyframes, the index's key point *must* refer to the first keyframe on that page, not any subsequent keyframes on that page.

The key points are stored in increasing order by offset (and thus by presentation time as well).

The byte offsets stored in keypoints are relative to the start of the Ogg bitstream segment. So if you have a physical Ogg bitstream made up of two chained Oggs, the offsets in the second Ogg segment's bitstream's index are relative to the beginning of the second Ogg in the chain, not the first. Also note that if a physical Ogg bitstream is made up of chained Oggs, the presence of an index in one segment does not imply that there will be an index in any other segment.

The exact number of keyframes used to construct key points in the index is up to the indexer, but to limit the index size, we recommend including at most one key point per every 64KB of data, or every 2000ms, whichever is least frequent.

As per the Skeleton 3.0 track, the last packet in the Skeleton 3.3 track is an empty EOS packet.

Software Prototype

For a prototype indexer, see OggIndex. Also included there is a program OggIndexValid, which can verify that Theora and Vorbis indexes are valid. If you're implementing your own indexer, or going to be modifying existing indexes, always verify that your modified indexes are valid as per OggIndexValid!

Recent ffmpeg2theora nightlies will also include a keyframe index in the Skeleton 3.3 track if you specify the command line option --seek-index.

To see how indexes improves network seeking performance, you can download a development version of Firefox which can take advantage of indexes here:

http://pearce.org.nz/video/firefox-indexed-seek-linux.tar.bz2

http://pearce.org.nz/video/firefox-indexed-seek-macosx.dmg

http://pearce.org.nz/video/firefox-indexed-seek-win32.zip

If you already have a Firefox instance running, you'll need to either close your running Firefox instance before starting the index-capable Firefox, or start the index-capable Firefox with the --no-remote command line parameter.

To compare the network performance of indexed versus non-indexed seeking, point the index-capable Firefox here:

http://pearce.org.nz/video/indexed-seek-demo.html

Personal tools


Main Page

Xiph.Org Projects

Audio—

Video—

Text—

Container—

Streaming—