From: Ralph Giles Date: Wed, 16 Oct 2002 22:46:44 +0000 (+0000) Subject: Add the encapsulation sections as appendicies. I can't figure out how to X-Git-Tag: v1.3.3~649 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=b28daa2e476ac4b0a39fd91d8bd8c4dc71768e13;p=platform%2Fupstream%2Flibvorbis.git Add the encapsulation sections as appendicies. I can't figure out how to include parser-protected text into a docbook xml file, so the rtp version will have to wait for makefile support to generate a wrapper. Our colophon has become a third appendix, since articles aren't permitted to have explicit colophons. svn path=/trunk/vorbis/; revision=4016 --- diff --git a/doc/xml/Vorbis_I_spec.xml b/doc/xml/Vorbis_I_spec.xml index 3073d4f..8802a01 100644 --- a/doc/xml/Vorbis_I_spec.xml +++ b/doc/xml/Vorbis_I_spec.xml @@ -15,6 +15,7 @@ + ]>
@@ -24,6 +25,7 @@ &intro; + +&rtpvorbis; &footer;
diff --git a/doc/xml/a1-encapsulation_ogg.xml b/doc/xml/a1-encapsulation_ogg.xml new file mode 100644 index 0000000..ff6ea4d --- /dev/null +++ b/doc/xml/a1-encapsulation_ogg.xml @@ -0,0 +1,197 @@ + + + + + Last update to this document: July 14, 2002 + $Id: a1-encapsulation_ogg.xml,v 1.1 2002/10/16 22:46:44 giles Exp $ + + +Embedding Vorbis into an Ogg stream + +
+Overview + + +This document describes using Ogg logical and physical transport +streams to encapsulate Vorbis compressed audio packet data into file +form. + + +The provides an overview of the construction +of Vorbis audio packets. + + +The Ogg +bitstream overview and Ogg logical +bitstream and framing spec provide detailed descriptions of Ogg +transport streams. This specification document assumes a working +knowledge of the concepts covered in these named backround +documents. Please read them first. + +
Restrictions + + +The Ogg/Vorbis I specification currently dictates that Ogg/Vorbis +streams use Ogg transport streams in degenerate, unmultiplexed +form only. That is: + + + + A meta-headerless Ogg file encapsulates the Vorbis I packets + + + The Ogg stream may be chained, i.e. contain multiple, contigous logical streams (links). + + + The Ogg stream must be unmultiplexed (only one stream, a Vorbis audio stream, per link) + + + + + +This is not to say that it is not currently possible to multiplex +Vorbis with other media types into a multi-stream Ogg file. At the +time this document was written, Ogg was becoming a popular container +for low-bitrate movies consisting of DiVX video and Vorbis audio. +However, a 'Vorbis I audio file' is taken to imply Vorbis audio +existing alone within a degenerate Ogg stream. A compliant 'Vorbis +audio player' is not required to implement Ogg support beyond the +specific support of Vorbis within a degenrate ogg stream (naturally, +application authors are encouraged to support full multiplexed Ogg +handling). + + +
+ +
MIME type + + +The correct MIME type of any Ogg file is application/x-ogg. +However, if a file is a Vorbis I audio file (which implies a +degenerate Ogg stream including only unmultiplexed Vorbis audio), the +mime type audio/x-vorbis is also allowed. + +
+ +
+ +
+Encapsulation + + +Ogg encapsulation of a Vorbis packet stream is straightforward. + + + + + The first Vorbis packet (the indentification header), which + uniquely identifies a stream as Vorbis audio, is placed alone in the + first page of the logical Ogg stream. This results in a first Ogg + page of exactly 58 bytes at the very beginning of the logical stream. + + + + This first page is marked 'beginning of stream' in the page flags. + + + + The second and third vorbis packets (comment and setup + headers) may span one or more pages beginning on the second page of + the logical stream. However many pages they span, the third header + packet finishes the page on which it ends. The next (first audio) packet + must begin on a fresh page. + + + + The granule position of these first pages containing only headers is zero. + + + + The first audio packet of the logical stream begins a fresh Ogg page. + + + + Packets are placed into ogg pages in order until the end of stream. + + + + The last page is marked 'end of stream' in the page flags. + + + + Vorbis packets may span page boundaries. + + + + The granule position of pages containing Vorbis audio is in units + of PCM audio samples (per channel; a stereo stream's granule position + does not increment at twice the speed of a mono stream). + + + + The granule position of a page represents the end PCM sample + position of the last packet completed on that page. + A page that is entirely spanned by a single packet (that completes on a + subsequent page) has no granule position, and the granule position is + set to '-1'. + + + + + The granule (PCM) position of the first page need not indicate + that the stream started at position zero. Although the granule + position belongs to the last completed packet on the page and a + valid granule position must be positive, by + inference it may indicate that the PCM position of the beginning + of audio is positive or negative. + + + + + A positive starting value simply indicates that this stream begins at + some positive time offset, potentially within a larger + program. This is a common case when connecting to the middle + of broadcast stream. + + + A negative value indicates that + output samples preceeding time zero should be discarded during + decoding; this technique is used to allow sample-granularity + editing of the stream start time of already-encoded Vorbis + streams. The number of samples to be discarded must not exceed + the overlap-add span of the first two audio packets. + + + + + In both of these cases in which the initial audio PCM starting + offset is nonzero, the second finished audio packet must flush the + page on which it appears and the third packet begin a fresh page. + This allows the decoder to always be able to perform PCM position + adjustments before needing to return any PCM data from synthesis, + resulting in correct positioning information without any aditional + seeking logic. + + + + Failure to do so should, at worst, cause a + decoder implementation to return incorrect positioning information + for seeking operations at the very beginning of the stream. + + + + + A granule position on the final page in a stream that indicates + less audio data than the final packet would normally return is used to + end the stream on other than even frame boundaries. The difference + between the actual available data returned and the declared amount + indicates how many trailing samples to discard from the decoding + process. + + + +
+ + + + diff --git a/doc/xml/a2-encapsulation_rtp.xml b/doc/xml/a2-encapsulation_rtp.xml new file mode 100644 index 0000000..2bc27ef --- /dev/null +++ b/doc/xml/a2-encapsulation_rtp.xml @@ -0,0 +1,20 @@ + + + + + $Id: a2-encapsulation_rtp.xml,v 1.1 2002/10/16 22:46:44 giles Exp $ + + +Vorbis encapsulation in RTP + + + + + + + + + diff --git a/doc/xml/footer.xml b/doc/xml/footer.xml index 7e04f66..11ad308 100644 --- a/doc/xml/footer.xml +++ b/doc/xml/footer.xml @@ -1,7 +1,15 @@ - + +This document is set in DocBook XML. + + +