[xiph-cvs] cvs commit: vorbis/doc/xml a1-encapsulation_ogg.xml a2-encapsulation_rtp.xml Vorbis_I_spec.xml footer.xml
Ralph Giles
giles at xiph.org
Wed Oct 16 15:46:44 PDT 2002
giles 02/10/16 18:46:44
Modified: doc/xml Vorbis_I_spec.xml footer.xml
Added: doc/xml a1-encapsulation_ogg.xml a2-encapsulation_rtp.xml
Log:
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.
Revision Changes Path
1.2 +3 -2 vorbis/doc/xml/Vorbis_I_spec.xml
Index: Vorbis_I_spec.xml
===================================================================
RCS file: /usr/local/cvsroot/vorbis/doc/xml/Vorbis_I_spec.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- Vorbis_I_spec.xml 12 Oct 2002 20:37:11 -0000 1.1
+++ Vorbis_I_spec.xml 16 Oct 2002 22:46:44 -0000 1.2
@@ -15,6 +15,7 @@
<!ENTITY oggvorbis SYSTEM "a1-encapsulation_ogg.xml">
<!ENTITY rtpvorbis SYSTEM "a2-encapsulation_rtp.xml">
<!ENTITY footer SYSTEM "footer.xml">
+<!ENTITY draft-rtp SYSTEM "../draft-moffitt-vorbis-rtp-00.txt" NDATA TXT>
]>
<article>
@@ -24,6 +25,7 @@
</articleinfo>
&intro;
+<!--
&bitpacking;
&codebook;
&codec;
@@ -33,10 +35,9 @@
&residue;
&helpers;
&tables;
-<!--
&oggvorbis;
-&rtpvorbis;
-->
+&rtpvorbis;
&footer;
</article>
<p><p>1.2 +14 -2 vorbis/doc/xml/footer.xml
Index: footer.xml
===================================================================
RCS file: /usr/local/cvsroot/vorbis/doc/xml/footer.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- footer.xml 12 Oct 2002 20:37:11 -0000 1.1
+++ footer.xml 16 Oct 2002 22:46:44 -0000 1.2
@@ -1,7 +1,15 @@
-<section id="footer">
+<!-- articles can't have an explicit colophon -->
+<appendix id="footer">
<title>Colophon</title>
<mediaobject>
+<!-- pdf is better but some tools don't handle it -->
+<imageobject>
+ <imagedata fileref="xifish.pdf" format="PDF"/>
+</imageobject>
+<imageobject>
+ <imagedata fileref="xifish.eps" format="EPS"/>
+</imageobject>
<imageobject>
<imagedata fileref="white-xifish.png" format="PNG"/>
</imageobject>
@@ -37,4 +45,8 @@
pages are copyright (C) 1994-2002 Xiph.org Foundation. All rights
reserved.</para>
-</section>
+<para>
+This document is set in DocBook XML.
+</para>
+
+</appendix>
<p><p>1.1 vorbis/doc/xml/a1-encapsulation_ogg.xml
Index: a1-encapsulation_ogg.xml
===================================================================
<?xml version="1.0" ?>
<appendix id="vorbis-over-ogg">
<appendixinfo>
<releaseinfo>
<emphasis>Last update to this document: July 14, 2002</emphasis>
$Id: a1-encapsulation_ogg.xml,v 1.1 2002/10/16 22:46:44 giles Exp $
</releaseinfo>
</appendixinfo>
<title>Embedding Vorbis into an Ogg stream</title>
<section>
<title>Overview</title>
<para>
This document describes using Ogg logical and physical transport
streams to encapsulate Vorbis compressed audio packet data into file
form.</para>
<para>
The <xref linkend="vorbis-spec-intro"/> provides an overview of the construction
of Vorbis audio packets.</para>
<para>
The <ulink url="oggstream.html">Ogg
bitstream overview</ulink> and <ulink url="framing.html">Ogg logical
bitstream and framing spec</ulink> 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.</para>
<section><title>Restrictions</title>
<para>
The Ogg/Vorbis I specification currently dictates that Ogg/Vorbis
streams use Ogg transport streams in degenerate, unmultiplexed
form only. That is:
<itemizedlist>
<listitem><simpara>
A meta-headerless Ogg file encapsulates the Vorbis I packets
</simpara></listitem>
<listitem><simpara>
The Ogg stream may be chained, i.e. contain multiple, contigous logical streams (links).
</simpara></listitem>
<listitem><simpara>
The Ogg stream must be unmultiplexed (only one stream, a Vorbis audio stream, per link)
</simpara></listitem>
</itemizedlist>
</para>
<para>
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).
</para>
</section>
<section><title>MIME type</title>
<para>
The correct MIME type of any Ogg file is <literal>application/x-ogg</literal>.
However, if a file is a Vorbis I audio file (which implies a
degenerate Ogg stream including only unmultiplexed Vorbis audio), the
mime type <literal>audio/x-vorbis</literal> is also allowed.</para>
</section>
</section>
<section>
<title>Encapsulation</title>
<para>
Ogg encapsulation of a Vorbis packet stream is straightforward.</para>
<itemizedlist>
<listitem><simpara>
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.
</simpara></listitem>
<listitem><simpara>
This first page is marked 'beginning of stream' in the page flags.
</simpara></listitem>
<listitem><simpara>
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.
</simpara></listitem>
<listitem><simpara>
The granule position of these first pages containing only headers is zero.
</simpara></listitem>
<listitem><simpara>
The first audio packet of the logical stream begins a fresh Ogg page.
</simpara></listitem>
<listitem><simpara>
Packets are placed into ogg pages in order until the end of stream.
</simpara></listitem>
<listitem><simpara>
The last page is marked 'end of stream' in the page flags.
</simpara></listitem>
<listitem><simpara>
Vorbis packets may span page boundaries.
</simpara></listitem>
<listitem><simpara>
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).
</simpara></listitem>
<listitem><simpara>
The granule position of a page represents the end PCM sample
position of the last packet <emphasis>completed</emphasis> 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'.
</simpara></listitem>
<listitem>
<simpara>
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.
</simpara>
<itemizedlist>
<listitem><simpara>
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.
</simpara></listitem>
<listitem><simpara>
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.
</simpara></listitem>
</itemizedlist>
<simpara>
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.
</simpara>
<note><simpara>
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.
</simpara></note>
</listitem>
<listitem><simpara>
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.
</simpara></listitem>
</itemizedlist>
</section>
</appendix>
<!-- end appendix on Vorbis encapsulation in Ogg -->
<p><p>1.1 vorbis/doc/xml/a2-encapsulation_rtp.xml
Index: a2-encapsulation_rtp.xml
===================================================================
<?xml version="1.0" ?>
<appendix id="vorbis-over-rtp">
<appendixinfo>
<releaseinfo>
<emphasis>$Id: a2-encapsulation_rtp.xml,v 1.1 2002/10/16 22:46:44 giles Exp $</emphasis>
</releaseinfo>
</appendixinfo>
<title>Vorbis encapsulation in RTP</title>
<screen>
<!-- the draft-rtp entity must be declared in the enclosing document.
currently it points to the internet draft text file -->
<![CDATA[
&draft-rtp;
]]>
</screen>
</appendix>
<!-- end rtp appendix -->
<p><p>--- >8 ----
List archives: http://www.xiph.org/archives/
Ogg project homepage: http://www.xiph.org/ogg/
To unsubscribe from this list, send a message to 'cvs-request at xiph.org'
containing only the word 'unsubscribe' in the body. No subject is needed.
Unsubscribe messages sent to the list will be ignored/filtered.
More information about the commits
mailing list