Commit 5e1fb903 authored by Monty's avatar Monty

Merge branch_beta3 onto the mainline.


svn path=/trunk/vorbis/; revision=990
parent 3241b245
......@@ -11,3 +11,4 @@ configure
......@@ -4,7 +4,10 @@ AUTOMAKE_OPTIONS = foreign dist-zip
SUBDIRS = lib include doc examples
EXTRA_DIST = README COPYING todo.txt libvorbis.spec
m4datadir = $(datadir)/aclocal
m4data_DATA = vorbis.m4
EXTRA_DIST = README COPYING todo.txt libvorbis.spec vorbis.m4
# acinclude.m4
# all .m4 files needed that might not be installed go here
# ogg.m4
# Configure paths for libogg
# Jack Moffitt <> 10-21-2000
# Shamelessly stolen from Owen Taylor and Manish Singh
dnl Test for libogg, and define OGG_CFLAGS and OGG_LIBS
dnl Get the cflags and libraries
AC_ARG_WITH(ogg-prefix,[ --with-ogg-prefix=PFX Prefix where libogg is installed (optional)], ogg_prefix="$withval", ogg_prefix="")
AC_ARG_ENABLE(oggtest, [ --disable-oggtest Do not try to compile and run a test Ogg program],, enable_oggtest=yes)
if test x$ogg_prefix != x ; then
ogg_args="$ogg_args --prefix=$ogg_prefix"
if test "x$enable_oggtest" = "xyes" ; then
dnl Now check if the installed Ogg is sufficiently new.
rm -f conf.oggtest
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <ogg/ogg.h>
int main ()
system("touch conf.oggtest");
return 0;
],, no_ogg=yes,[echo $ac_n "cross compiling; assumed OK... $ac_c"])
if test "x$no_ogg" = x ; then
ifelse([$1], , :, [$1])
if test -f conf.oggtest ; then
echo "*** Could not run Ogg test program, checking why..."
#include <stdio.h>
#include <ogg/ogg.h>
], [ return 0; ],
[ echo "*** The test program compiled, but did not run. This usually means"
echo "*** that the run-time linker is not finding Ogg or finding the wrong"
echo "*** version of Ogg. If it is not finding Ogg, you'll need to set your"
echo "*** LD_LIBRARY_PATH environment variable, or edit /etc/ to point"
echo "*** to the installed location Also, make sure you have run ldconfig if that"
echo "*** is required on your system"
echo "***"
echo "*** If you have an old version installed, it is best to remove it, although"
echo "*** you may also be able to get things to work by modifying LD_LIBRARY_PATH"],
[ echo "*** The test program failed to compile or link. See the file config.log for the"
echo "*** exact error that occured. This usually means Ogg was incorrectly installed"
echo "*** or that you have moved Ogg since it was installed. In the latter case, you"
echo "*** may want to edit the ogg-config script: $OGG_CONFIG" ])
ifelse([$2], , :, [$2])
rm -f conf.oggtest
......@@ -15,12 +15,18 @@ V_LIB_AGE=0
dnl --------------------------------------------------
dnl Check for programs
......@@ -34,12 +40,6 @@ CFLAGS="$cflags_save"
dnl --------------------------------------------------
dnl Additional arguments
dnl --------------------------------------------------
AC_ARG_WITH(ogg, [ --with-ogg=DIR Set where the Ogg library is located])
dnl --------------------------------------------------
dnl Set build flags based on environment
dnl --------------------------------------------------
......@@ -73,8 +73,8 @@ else
DEBUG="-g -Wall -D_REENTRANT -D__NO_MATH_INLINES -fsigned-char"
CFLAGS="-O20 -ffast-math -mno-ieee-fp -D_REENTRANT -fsigned-char"
# PROFILE="-Wall -W -pg -O20 -ffast-math -D_REENTRANT -fsigned-char -fno-inline -static"
PROFILE="-Wall -W -pg -O20 -ffast-math -mno-ieee-fp -D_REENTRANT -fsigned-char -fno-inline -static"
# PROFILE="-Wall -W -pg -g -O20 -ffast-math -D_REENTRANT -fsigned-char -fno-inline -static"
PROFILE="-Wall -W -pg -g -O20 -ffast-math -mno-ieee-fp -D_REENTRANT -fsigned-char -fno-inline -static"
# glibc < 2.1.3 has a serious FP bug in the math inline header
# that will cripple Vorbis. Look to see if the magic FP stack
......@@ -130,116 +130,6 @@ else
AC_CHECK_LIB(pthread, pthread_create, pthread_lib="-lpthread")
dnl This seems to be the only way to make autoconf only *sometimes* configure
dnl a subdirectory with AC_CONFIG_SUBDIRS. "__noconf" is assumed to not
dnl exist as a directory, so configure won't try to recursively enter it, unless
dnl the shell variable $dummy is reset to an existing directory inside the
dnl if clause.
# check macro modified from Jon Shiring's to compensate for autoconf's lagging
# behind the times on type madness
AC_MSG_CHECKING(for int16_t)
#ifdef __BEOS__
#include <inttypes.h>
#include <sys/types.h>
int16_t foo;
int main() {return 0;}
AC_MSG_CHECKING(for int32_t)
#ifdef __BEOS__
#include <inttypes.h>
#include <sys/types.h>
int32_t foo;
int main() {return 0;}
AC_MSG_CHECKING(for uint32_t)
#ifdef __BEOS__
#include <inttypes.h>
#include <sys/types.h>
uint32_t foo;
int main() {return 0;}
AC_MSG_CHECKING(for u_int32_t)
#ifdef __BEOS__
#include <inttypes.h>
#include <sys/types.h>
u_int32_t foo;
int main() {return 0;}
AC_MSG_CHECKING(for int64_t)
#ifdef __BEOS__
#include <inttypes.h>
#include <sys/types.h>
int64_t foo;
int main() {return 0;}
AC_CHECK_SIZEOF(long long)
if test x$has_int16_t = "xyes" ; then
case 2 in
$ac_cv_sizeof_short) SIZE16="short";;
$ac_cv_sizeof_int) SIZE16="int";;
dnl --------------------------------------------------
dnl Check for headers
dnl --------------------------------------------------
......@@ -259,11 +149,7 @@ dnl --------------------------------------------------
AC_CHECK_LIB(m, cos, LIBS="-lm", LIBS="")
AC_CHECK_LIB(pthread, pthread_create, pthread_lib="-lpthread", :)
dnl Check for libogg
if test -n $with_ogg; then
CFLAGS="$CFLAGS -I$with_ogg/include -L$with_ogg/lib"
AC_CHECK_LIB(ogg, oggpack_read, LIBS="$LIBS -logg", AC_MSG_ERROR([You must have libogg to compile vorbis!!!]))
AM_PATH_OGG(have_ogg=yes, have_ogg=no)
dnl --------------------------------------------------
dnl Check for library functions
......@@ -280,4 +166,4 @@ AC_SUBST(DEBUG)
AC_OUTPUT(Makefile lib/Makefile doc/Makefile include/Makefile include/vorbis/Makefile include/vorbis/book/Makefile examples/Makefile)
AC_OUTPUT(Makefile lib/Makefile lib/modes/Makefile lib/books/Makefile doc/Makefile doc/vorbisfile/Makefile include/Makefile include/vorbis/Makefile examples/Makefile)
......@@ -2,7 +2,9 @@
docdir = $(datadir)/$(PACKAGE)-$(VERSION)
SUBDIRS = vorbisfile
docdir = $(datadir)/doc/$(PACKAGE)-$(VERSION)
doc_DATA = v-comment.html vorbisword2.png white-ogg.png programming.html\
vorbis.html wait.png white-xifish.png
This diff is collapsed.
<HTML><HEAD><TITLE> Ogg Vorbis documentation</TITLE>
<BODY bgcolor="#ffffff" text="#202020" link="#006666" vlink="#000000">
<nobr><a href="vorbis.html"><img src="white-ogg.png" border=0><img
src="vorbisword2.png" border=0></a></nobr><p>
<h1><font color=#000070>
Ogg logical and physical bitstream overview
<em>Last update to this document: July 18, 1999</em><br>
<h2>Ogg bitstreams</h2>
Ogg codecs use octet vectors of raw, compressed data
(<em>packets</em>). These compressed packets do not have any
high-level structure or boundary information; strung together, they
appear to be streams of random bytes with no landmarks.<p>
Raw packets may be used directly by transport mechanisms that provide
their own framing and packet-seperation mechanisms (such as UDP
datagrams). For stream based storage (such as files) and transport
(such as TCP streams or pipes), Vorbis and other future Ogg codecs use
the Ogg bitstream format to provide framing/sync, sync recapture
after error, landmarks during seeking, and enough information to
properly seperate data back into packets at the original packet
boundaries without relying on decoding to find packet boundaries.<p>
<h2>Logical and physical bitstreams</h2>
Raw packets are grouped and encoded into contiguous pages of
structured bitstream data called <em>logical bitstreams</em>. A
logical bitstream consists of pages, in order, belonging to a single
codec instance. Each page is a self contained entity (although it is
possible that a packet may be split and encoded across one or more
pages); that is, the page decode mechanism is designed to recognize,
verify and handle single pages at a time from the overall bitstream.<p>
Multiple logical bitstreams can be combined (with restricctions) into
a single <em>physical bitstream</em>. A physical bitstream consists
of multiple logical bitstreams multiplexed at the page level. Whole
pages are taken in order from multiple logical bitstreams and combined
into a single physical stream of pages. The decoder reconstructs the
original logical bitstreams from the physical bitstream by taking the
pages in order fromt he physical bitstream and redirecting them into
the appropriate logical decoding entitiy. The simplest physical
bitstream is a single, unmultiplexed logical bitstream. <p>
<a href=framing.html>Ogg Logical Bitstream Framing</a> discusses
the page format of an Ogg bitstream, the packet coding process
and logical bitstreams in detail. The remainder of this document
specifies requirements for constructing finished, physical Ogg
<h2>Mapping Restrictions</h2>
Logical bitstreams may not be mapped/multiplexed into physical
bitstreams without restriction. Here we discuss design restrictions
on Ogg physical bitstreams in general, mostly to introduce
design rationale. Each 'media' format defines its own (generally more
restrictive) mapping. An '<a href="vorbis-stream.html">Ogg Vorbis
Audio Bitstream</a>', for example, has a <a
href="vorbis-stream.html">specific physical bitstream structure</a>.
An 'Ogg A/V' bitstream (not currently specified) will also mandate a
specific, restricted physical bitstream format.<p>
<h3>additional end-to-end structure</h3>
The <a href="framing.html">framing specification</a> defines
'beginning of stream' and 'end of stream' page markers via a header
flag (it is possible for a stream to consist of a single page). A
stream always consists of an integer number of pages, an easy
requirement given the variable size nature of pages.<p>
In addition to the header flag marking the first and last pages of a
logical bitstream, the first page of an Ogg bitstream obeys
additional restrictions. Each individual media mapping specifies its
own implementation details regarding these restrictions.<p>
The first page of a logical Ogg bitstream consists of a single,
small 'initial header' packet that includes sufficient information to
identify the exact CODEC type and media requirements of the logical
bitstream. The intent of this restriction is to simplify identifying
the bitstream type and content; for a given media type (or across all
Ogg media types) we can know that we only need a small, fixed
amount of data to uniquely identify the bitstream type.<p>
As an example, Ogg Vorbis places the name and revision of the Vorbis
CODEC, the audio rate and the audio quality into this initial header,
thus simplifying vastly the certain identification of an Ogg Vorbis
audio bitstream.<p>
<h3>sequential multiplexing (chaining)</h3>
The simplest form of logical bitstream multiplexing is concatenation
(<em>chaining</em>). Complete logical bitstreams are strung
one-after-another in order. The bitstreams do not overlap; the final
page of a given logical bitstream is immediately followed by the
initial page of the next. Chaining is the only logical->physical
mapping allowed by Ogg Vorbis.<p>
Each chained logical bitstream must have a unique serial number within
the scope of the physical bitstream.<p>
<h3>concurrent multiplexing (grouping)</h3>
Logical bitstreams may also be multiplexed 'in parallel'
(<em>grouped</em>). An example of grouping would be to allow
streaming of seperate audio and video streams, using differnt codecs
and different logical bitstreams, in the same physical bitstream.
Whole pages from multiple logical bitstreams are mixed together.<p>
The initial pages of each logical bitstream must appear first; the
media mapping specifies the order of the initial pages. For example,
Ogg A/V will eventually specify an Ogg video bitstream with
audio. The mapping may specify that the physical bitstream must begin
with the initial page of a logical video bitstream, followed by the
initial page of an audio stream. Unlike initial pages, terminal pages
for the logical bitstreams need not all occur contiguously (although a
specific media mapping may require this; it is not mandated by the
generic Ogg stream spec). Terminal pages may be 'nil' pages,
that is, pages containing no content but simply a page header with
position information and the 'last page of bitstream' flag set in the
page header.<p>
Each grouped bitstream must have a unique serial number within the
scope of the physical bitstream.<p>
<h3>sequential and concurrent multiplexing</h3>
Groups of concurrently multiplexed bitstreams may be chained
consecutively. Such a physical bitstream obeys all the rules of both
grouped and chained multiplexed streams; the groups, when unchained ,
must stand on their own as a valid concurrently multiplexed
<h3>multiplexing example</h3>
Below, we present an example of a grouped and chained bitstream:<p>
<img src=stream.png><p>
In this example, we see pages from five total logical bitstreams
multiplexed into a physical bitstream. Note the following
<ol><li>Grouped bitstreams begin together; all of the initial pages
must appear before any data pages. When concurrently multiplexed
groups are chained, the new group does not begin until all the
bitstreams in the previous group have terminated.<p>
<li>The pages of concurrently multiplexed bitstreams need not conform
to a regular order; the only requirement is that page <tt>n</tt> of a
logical bitstream follow page <tt>n-1</tt> in the physical bitstream.
There are no restrictions on intervening pages belonging to other
logical bitstreams. (Tying page appearence to bitrate demands is one
logical strategy, ie, the page appears at the chronological point
where decode requires more information).
<a href="">
<img src="white-xifish.png" align=left border=0>
<font size=-2 color=#505050>
Ogg is a <a href="">Xiphophorus</a> effort to
protect essential tenets of Internet multimedia from corporate
hostage-taking; Open Source is the net's greatest tool to keep
everyone honest. See <a href="">About
Xiphophorus</a> for details.
Ogg Vorbis is the first Ogg audio CODEC. Anyone may
freely use and distribute the Ogg and Vorbis specification,
whether in a private, public or corporate capacity. However,
Xiphophorus and the Ogg project ( reserve the right to set
the Ogg/Vorbis specification and certify specification compliance.<p>
Xiphophorus's Vorbis software CODEC implementation is distributed
under the Lesser/Library GNU Public License. This does not restrict
third parties from distributing independent implementations of Vorbis
software under other licenses.<p>
OggSquish, Vorbis, Xiphophorus and their logos are trademarks (tm) of
<a href="">Xiphophorus</a>. These pages are
copyright (C) 1994-2000 Xiphophorus. All rights reserved.<p>
Sample granularity editing of a Vorbis file; inferred arbitrary sample
length starting offsets / PCM stream lengths
Vorbis, like mp3, is a frame-based* audio compression where audio is
broken up into discrete short time segments. These segments are
'atomic' that is, one must recover the entire short time segment from
the frame packet; there's no way to recover only a part of the PCM time
segment from part of the coded packet without expanding the entire
packet and then discarding a portion of the resulting PCM audio.
* In mp3, the data segment representing a given time period is called
a 'frame'; the roughly equivalent Vorbis construct is a 'packet'.
Thus, when we edit a Vorbis stream, the finest physical editing
granularity is on these packet boundaries (the mp3 case is
actually somewhat more complex and mp3 editing is more complicated
than just snipping on a frame boundary because time data can be spread
backward or forward over frames. In Vorbis, packets are all
stand-alone). Thus, at the physical packet level, Vorbis is still
limited to streams that contain an integral number of packets.
However, Vorbis streams may still exactly represent and be edited to a
PCM stream of arbitrary length and starting offset without padding the
beginning or end of the decoded stream or requiring that the desired
edit points be packet aligned. Vorbis makes use of Ogg stream
framing, and this framing provides time-stamping data, called a
'granule position'; our starting offset and finished stream length may
be inferred from correct usage of the granule position data.
Time stamping mechanism:
Vorbis packets are bundled into into Ogg pages (note that pages do not
necessarily contain integral numbers of packets, but that isn't
inportant in this discussion. More about Ogg framing can be found in
ogg/doc/framing.html). Each page that contains a packet boundary is
stamped with the absolute sample-granularity offset of the data, that
is, 'complete samples-to-date' up to the last completed packet of that
page. (The same mechanism is used for eg, video, where the number
represents complete 2-D frames, and so on).
(It's possible but rare for a packet to span more than two pages such
that page[s] in the middle have no packet boundary; these packets have
a granule position of '-1'.)
This granule position mechaism in Ogg is used by Vorbis to indicate when the
PCM data intended to be represented in a Vorbis segment begins a
number of samples into the data represented by the first packet[s]
and/or ends before the physical PCM data represented in the last
File length a non-integral number of frames:
A file to be encoded in Vorbis will probably not encode into an
integral number of packets; such a file is encoded with the last
packet containing 'extra'* samples. These samples are not padding; they
will be discarded in decode.
*(For best results, the encoder should use extra samples that preserve
the character of the last frame. Simply setting them to zero will
introduce a 'cliff' that's hard to encode, resulting in spread-frame
noise. Libvorbis extrapolates the last frame past the end of data to
produce the extra samples. Even simply duplicating the last value is
better than clamping the signal to zero).
The encoder indicates to the decoder that the file is actually shorter
than all of the samples ('original' + 'extra') by setting the granule
position in the last page to a short value, that is, the last
timestamp is the original length of the file discarding extra samples.
The decoder will see that the number of samples it has decoded in the
last page is too many; it is 'original' + 'extra', where the
granulepos says that through the last packet we only have 'original'
number of samples. The decoder then ignores the 'extra' samples.
This behavior is to occur only when the end-of-stream bit is set in
the page (indicating last page of the logical stream).
Note that it not legal for the granule position of the last page to
indicate that there are more samples in the file than actually exist,
however, implementations should handle such an illegal file gracefully
in the interests of robust programming.
Beginning point not on integral packet boundary:
It is possible that we will the PCM data represented by a Vorbis
stream to begin at a position later than where the decoded PCM data
really begins after an integral packet boundary, a situation analagous
to the above description where the PCM data does not end at an
integral packet boundary. The easiest example is taking a clip out of
a larger Vorbis stream, and choosing a beginning point of the clip
that is not on a packet boundary; we need to ignore a few samples to
get the desired beginning point.
The process of marking the desired beginning point is similar to
marking an arbitrary ending point. If the encoder wishes sample zero
to be some location past the actual beginning of data, it associates a
'short' granule position value with the completion of the second*
audio packet. The granule position is associated with the second
packet simply by making sure the second packet completes its page.
*(We associate the short value with the second packet for two reasons.
a) The first packet only primes the overlap/add buffer. No data is
returned before decoding the second packet; this places the decision
information at the point of decision. b) Placing the short value on
the first packet would make the value negative (as the first packet
normally represents position zero); a negative value would break the
requirement that granule positions increase; the headers have
position values of zero)
The decoder sees that on the first page that will return
data from the overlap/add queue, we have more samples than the granule
position accounts for, and discards the 'surplus' from the beginning
of the queue.
Note that short granule values (indicating less than the actually
returned about of data) are not legal in the Vorbis spec outside of
indicating beginning and ending sample positions. However, decoders
should, at minimum, tolerate inadvertant short values elsewhere in the
stream (just as they should tolerate out-of-order/non-increasing
granulepos values, although this too is illegal).
Beginning point at arbitrary positive timestamp (no 'zero' sample):
It's also possible that the granule position of the first page of an
audio stream is a 'long value', that is, a value larger than the
amount of PCM audio decoded. This implies only that we are starting
playback at some point into the logical stream, a potentially common
occurence in streaming applications where the decoder may be
connecting into a live stream. The decoder should not treat the long
value specially.
A long value elsewhere in the stream would normally occur only when a
page is lost or out of sequence, as indicated by the page's sequence
number. A long value under any other situation is not legal, however
a decoder should tolerate both possibilities.
Error return codes possible from libvorbis and libvorbisfile:
All 'failure' style returns are <0; this either indicates a generic
'false' value (eg, ready? T or F) or an error condition. Code can
safely just test for < 0, or look at the specific return code for more
*** Return codes:
OV_FALSE The call returned a 'false' status (eg, ov_bitrate_instant
can return OV_FALSE if playback is not in progress, and thus
there is no instantaneous bitrate information to report.
OV_HOLE libvorbis/libvorbisfile is alerting the application that
there was an interruption in the data (one of: garbage
between pages, loss of sync followed by recapture, or a
corrupt page)
OV_EREAD A read from media returned an error.
OV_EFAULT Internal logic fault; indicates a bug or heap/stack
OV_EIMPL The bitstream makes use of a feature not implemented in this
library version.
OV_EINVAL Invalid argument value.
OV_ENOTVORBIS Bitstream/page/packet is not Vorbis data.
OV_EBADHEADER Invalid Vorbis bitstream header.
OV_EVERSION Vorbis version mismatch.
OV_ENOTAUDIO Packet data submitted to vorbis_synthesis is not audio data.
OV_EBADPACKET Invalid packet submitted to vorbis_synthesis.
OV_EBADLINK Invalid stream section supplied to libvorbis/libvorbisfile,
or the requested link is corrupt.
OV_ENOSEEK Bitstream is not seekable.