LosaDev/ls-2019-source
1
0 Fork 1
Code Issues Pull Requests 2 Actions Packages Projects Releases Wiki Activity

LosaDev source snapshot 2019

Browse Source
This commit is contained in:
LosaDev committed 2026-11-07 13:30:45 +07:00
commit c198676e97
20588 files changed
+8812878
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

etc/Library/OggVobisSDK/doc/vorbis/Makefile.am
+54
View File
@@ -0,0 +1,54 @@
## Process this with automake to create Makefile.in
AUTOMAKE_OPTIONS = foreign
SUBDIRS = vorbisfile vorbisenc
docdir = $(datadir)/doc/$(PACKAGE)-$(VERSION)
doc_DATA = components.png \
draft-moffitt-vorbis-rtp-00.txt \
eightphase.png \
evenlsp.png \
floor1-1.png \
floor1-2.png \
floor1-3.png \
floor1-4.png \
floor1_inverse_dB_table.html \
floorval.png \
fourphase.png \
framing.html \
helper.html \
hufftree-under.png \
hufftree.png \
index.html \
lspmap.png \
oddlsp.png \
oggstream.html \
programming.html \
residue-pack.png \
residue2.png \
squarepolar.png \
stereo.html \
stream.png \
v-comment.html \
vorbis-clip.txt \
vorbis-errors.txt \
vorbis-fidelity.html \
vorbis-ogg.html \
vorbis-spec-bitpack.html \
vorbis-spec-codebook.html \
vorbis-spec-floor0.html \
vorbis-spec-floor1.html \
vorbis-spec-intro.html \
vorbis-spec-ref.html \
vorbis-spec-res.html \
vorbis.html \
vorbisword2.png \
wait.png \
white-ogg.png \
white-xifish.png \
window1.png \
window2.png
EXTRA_DIST = $(doc_DATA)
etc/Library/OggVobisSDK/doc/vorbis/components.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 11 KiB

etc/Library/OggVobisSDK/doc/vorbis/draft-moffitt-vorbis-rtp-00.txt
+230
View File
@@ -0,0 +1,230 @@
Network Working Group Jack Moffitt
Internet-Draft Xiph.org Foundation
Expire in six months February 2001
RTP Payload Format for Vorbis Encoded Audio
<draft-moffitt-vorbis-rtp-00.txt>
Status of this Memo
This document is an Internet-Draft and is in full conformance
with all provisions of Section 10 of RFC2026.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that
other groups may also distribute working documents as
Internet-Drafts.
Internet-Drafts are draft documents valid for a maximum of six
months and may be updated, replaced, or obsoleted by other
documents at any time. It is inappropriate to use Internet-
Drafts as reference material or to cite them other than as
"work in progress".
The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt
The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html.
Abstract
This document describes a RTP payload format for transporting Vorbis
encoded audio.
1 Introduction
This document describes how Vorbis encoded audio may be formatted for
use as an RTP payload type.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in RFC 2119 [1].
2 Background
The Xiph.org Foundation creates and defines codecs for use in
multimedia that are not encumbered by patents and thus may be freely
implemented by any individual or organization.
Vorbis is the general purpose multi-channel audio codec created by
the Xiph.org Foundation.
Vorbis encoded audio is generally found within an Ogg format
bitstream, which provides framing and synchronization. For the
purposes of RTP transport, this layer is unnecessary, and so raw
Vorbis packets are used in the payload.
Vorbis packets are unbounded in length currently. At some future
point there will likely be a practical limit placed on packet
length.
Typical Vorbis packet sizes are from very small (2-3 bytes) to
quite large (8-12 kilobytes). The reference implementation seems to
make every packet less than ~800 bytes, except for the codebooks
packet which is ~8-12 kilobytes.
3 Payload Format
The standard RTP header is followed by an 8 bit payload header, and
the payload data.
3.1 RTP Header
The following fields of the RTP header are used for Vorbis payloads:
Payload Type (PT): 7 bits
An RTP profile for a class of applications is expected to assign a
payload type for this format, or a dynamically allocated payload
type should be chosen which designates the payload as Vorbis.
Timestamp: 32 bits
A timestamp representing the sampling time of the first sample of
the first Vorbis packet in the RTP packet. The clock frequency
MUST be set to the sample rate of the encoded audio data and is
conveyed out-of-band.
Marker (M): 1 bit
Set to one if the payload contains complete packets or if it
contains the last fragment of a fragmented packet.
3.2 Payload Header
The first byte of the payload data is the payload header:
+---+---+---+---+---+---+---+---+
| C | R | R | # of packets |
+---+---+---+---+---+---+---+---+
C: 1 bit
Set to one if this is a continuation of a fragmented packet.
R: 1 bit x 2
Reserved, must be set to zero by senders, and ignored by
receivers.
The last 5 bits are the number of complete packets in this payload.
If C is set to one, this number should be 0.
3.3 Payload Data
If the payload contains a single Vorbis packet or a Vorbis packet
fragment, the Vorbis packet data follows the payload header.
For payloads which consist of multiple Vorbis packets, payload data
consists of one byte representing the packet length followed by the
packet data for each of the Vorbis packets in the payload.
The Vorbis packet length byte is the length minus one. A value of
0 means a length of 1.
3.4 Example RTP Packet
Here is an example RTP packet containing two Vorbis packets.
RTP Packet Header:
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 8 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|V=2|P|X| CC |M| PT | sequence number |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| timestamp (in sample rate units) |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| sychronization source (SSRC) identifier |
+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+
| contributing source (CSRC) identifiers |
| ... |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Payload Data:
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|0|0|0| # pks: 2| len | vorbis data ... |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| ...vorbis data... |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| ... | len | next vorbis packet data... |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
4 Frame Packetizing
Each RTP packet contains either one complete Vorbis packet, one
Vorbis packet fragment, or an integer number of complete Vorbis
packets (a max of 32 packets, since the number of packets is
defined by a 5 bit value).
Any Vorbis packet that is larger than 256 bytes and less than the
path-MTU should be placed in a RTP packet by itself.
Any Vorbis packet that is 256 bytes or less should be bundled in the
RTP packet with as many Vorbis packets as will fit, up to a maximum
of 32.
If a packet will not fit into the RTP packet, it must be fragmented.
A fragmented packet has a zero in the last five bits of the payload
header. Each fragment after the first will also set the Continued
(C) bit to one in the payload header. The RTP packet containing the
last fragment of the Vorbis packet will have the Marker (M) bit set
to one.
5 Open Issues
To decode a Vorbis stream, a set of codebooks is required. These
codebooks are allowed to change for each logical bitstream (for
example, for each song encoded in a radio stream).
The codebooks must be completely intact and a client can not decode
a stream with an incomplete or corrupted set.
A client connecting to a multicast RTP Vorbis session needs to get the
first set of codebooks in some manner. These codebooks are typically
between 4 kilobytes and 8 kilobytes in size.
A final solution to how best to deliver the codebooks has not yet been
realized. Here are the current proposals:
- Including the first set of codebooks in the SDP description
- Broadcasting a codebook only stream as a second multicast Vorbis
stream
- Create some method of requesting the codebooks via RTCP
- Periodically retransmit the headers inline
6 Security Considerations
RTP packets using this payload format are subject to the security
considerations discussed in the RTP specification [1]. This implies
that the confidentiality of the media stream is achieved by using
encryption. Becase the data compression used with this payload
format is applied end-to-end, encryption may be performed on the
compressed data.
7 Acknowledgements
Thanks to the rest of the Xiph.org team, especially Monty
<[email protected]>. Thanks also to Rob Lanphier <[email protected]> for
his guidance.
8 References
1. RTP: A Transport Protocol for Real-Time Applications (RFC 1889)
2. Xiph.org's Ogg Vorbis pages http://www.xiph.org/ogg/vorbis/
Vorbis documentation only currently exists as API documenation,
or as source code. The source can be obtained at
http://www.xiph.org/ogg/vorbis/download.html
9 Author's Address
Jack Moffitt
Executive Director
Xiph.org Foundation
email: [email protected]
WWW: http://www.xiph.org/
etc/Library/OggVobisSDK/doc/vorbis/eightphase.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 17 KiB

etc/Library/OggVobisSDK/doc/vorbis/evenlsp.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 2.9 KiB

etc/Library/OggVobisSDK/doc/vorbis/floor1-1.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 4.0 KiB

etc/Library/OggVobisSDK/doc/vorbis/floor1-2.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 4.4 KiB

etc/Library/OggVobisSDK/doc/vorbis/floor1-3.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 5.3 KiB

etc/Library/OggVobisSDK/doc/vorbis/floor1-4.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 4.8 KiB

etc/Library/OggVobisSDK/doc/vorbis/floor1_inverse_dB_table.html
+112
View File
@@ -0,0 +1,112 @@
<HTML><HEAD><TITLE>xiph.org: Ogg Vorbis documentation</TITLE>
<BODY bgcolor="#ffffff" text="#202020" link="#006666" vlink="#000000">
<nobr><img src="white-ogg.png"><img src="vorbisword2.png"></nobr><p>
<h1><font color=#000070>
Ogg Vorbis I format specification: floor1_inverse_dB_table
</font></h1>
<em>Last update to this document: July 18, 2002</em><p>
The vector <tt>[floor1_inverse_dB_table]</tt> is a 256 element static
lookup table consiting of the following values (read left to right
then top to bottom):
<pre>
1.0649863e-07, 1.1341951e-07, 1.2079015e-07, 1.2863978e-07,
1.3699951e-07, 1.4590251e-07, 1.5538408e-07, 1.6548181e-07,
1.7623575e-07, 1.8768855e-07, 1.9988561e-07, 2.1287530e-07,
2.2670913e-07, 2.4144197e-07, 2.5713223e-07, 2.7384213e-07,
2.9163793e-07, 3.1059021e-07, 3.3077411e-07, 3.5226968e-07,
3.7516214e-07, 3.9954229e-07, 4.2550680e-07, 4.5315863e-07,
4.8260743e-07, 5.1396998e-07, 5.4737065e-07, 5.8294187e-07,
6.2082472e-07, 6.6116941e-07, 7.0413592e-07, 7.4989464e-07,
7.9862701e-07, 8.5052630e-07, 9.0579828e-07, 9.6466216e-07,
1.0273513e-06, 1.0941144e-06, 1.1652161e-06, 1.2409384e-06,
1.3215816e-06, 1.4074654e-06, 1.4989305e-06, 1.5963394e-06,
1.7000785e-06, 1.8105592e-06, 1.9282195e-06, 2.0535261e-06,
2.1869758e-06, 2.3290978e-06, 2.4804557e-06, 2.6416497e-06,
2.8133190e-06, 2.9961443e-06, 3.1908506e-06, 3.3982101e-06,
3.6190449e-06, 3.8542308e-06, 4.1047004e-06, 4.3714470e-06,
4.6555282e-06, 4.9580707e-06, 5.2802740e-06, 5.6234160e-06,
5.9888572e-06, 6.3780469e-06, 6.7925283e-06, 7.2339451e-06,
7.7040476e-06, 8.2047000e-06, 8.7378876e-06, 9.3057248e-06,
9.9104632e-06, 1.0554501e-05, 1.1240392e-05, 1.1970856e-05,
1.2748789e-05, 1.3577278e-05, 1.4459606e-05, 1.5399272e-05,
1.6400004e-05, 1.7465768e-05, 1.8600792e-05, 1.9809576e-05,
2.1096914e-05, 2.2467911e-05, 2.3928002e-05, 2.5482978e-05,
2.7139006e-05, 2.8902651e-05, 3.0780908e-05, 3.2781225e-05,
3.4911534e-05, 3.7180282e-05, 3.9596466e-05, 4.2169667e-05,
4.4910090e-05, 4.7828601e-05, 5.0936773e-05, 5.4246931e-05,
5.7772202e-05, 6.1526565e-05, 6.5524908e-05, 6.9783085e-05,
7.4317983e-05, 7.9147585e-05, 8.4291040e-05, 8.9768747e-05,
9.5602426e-05, 0.00010181521, 0.00010843174, 0.00011547824,
0.00012298267, 0.00013097477, 0.00013948625, 0.00014855085,
0.00015820453, 0.00016848555, 0.00017943469, 0.00019109536,
0.00020351382, 0.00021673929, 0.00023082423, 0.00024582449,
0.00026179955, 0.00027881276, 0.00029693158, 0.00031622787,
0.00033677814, 0.00035866388, 0.00038197188, 0.00040679456,
0.00043323036, 0.00046138411, 0.00049136745, 0.00052329927,
0.00055730621, 0.00059352311, 0.00063209358, 0.00067317058,
0.00071691700, 0.00076350630, 0.00081312324, 0.00086596457,
0.00092223983, 0.00098217216, 0.0010459992, 0.0011139742,
0.0011863665, 0.0012634633, 0.0013455702, 0.0014330129,
0.0015261382, 0.0016253153, 0.0017309374, 0.0018434235,
0.0019632195, 0.0020908006, 0.0022266726, 0.0023713743,
0.0025254795, 0.0026895994, 0.0028643847, 0.0030505286,
0.0032487691, 0.0034598925, 0.0036847358, 0.0039241906,
0.0041792066, 0.0044507950, 0.0047400328, 0.0050480668,
0.0053761186, 0.0057254891, 0.0060975636, 0.0064938176,
0.0069158225, 0.0073652516, 0.0078438871, 0.0083536271,
0.0088964928, 0.009474637, 0.010090352, 0.010746080,
0.011444421, 0.012188144, 0.012980198, 0.013823725,
0.014722068, 0.015678791, 0.016697687, 0.017782797,
0.018938423, 0.020169149, 0.021479854, 0.022875735,
0.024362330, 0.025945531, 0.027631618, 0.029427276,
0.031339626, 0.033376252, 0.035545228, 0.037855157,
0.040315199, 0.042935108, 0.045725273, 0.048696758,
0.051861348, 0.055231591, 0.058820850, 0.062643361,
0.066714279, 0.071049749, 0.075666962, 0.080584227,
0.085821044, 0.091398179, 0.097337747, 0.10366330,
0.11039993, 0.11757434, 0.12521498, 0.13335215,
0.14201813, 0.15124727, 0.16107617, 0.17154380,
0.18269168, 0.19456402, 0.20720788, 0.22067342,
0.23501402, 0.25028656, 0.26655159, 0.28387361,
0.30232132, 0.32196786, 0.34289114, 0.36517414,
0.38890521, 0.41417847, 0.44109412, 0.46975890,
0.50028648, 0.53279791, 0.56742212, 0.60429640,
0.64356699, 0.68538959, 0.72993007, 0.77736504,
0.82788260, 0.88168307, 0.9389798, 1.
<pre>
<hr>
<a href="http://www.xiph.org/">
<img src="white-xifish.png" align=left border=0>
</a>
<font size=-2 color=#505050>
Ogg is a <a href="http://www.xiph.org">Xiph.org Foundation</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="http://www.xiph.org/about.html">About
the Xiph.org Foundation</a> for details.
<p>
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, the Xiph.org Foundation and
the Ogg project (xiph.org) reserve the right to set the Ogg Vorbis
specification and certify specification compliance.<p>
Xiph.org's Vorbis software CODEC implementation is distributed under a
BSD-like license. This does not restrict third parties from
distributing independent implementations of Vorbis software under
other licenses.<p>
Ogg, Vorbis, Xiph.org Foundation and their logos are trademarks (tm)
of the <a href="http://www.xiph.org/">Xiph.org Foundation</a>. These
pages are copyright (C) 1994-2002 Xiph.org Foundation. All rights
reserved.<p>
</body>
etc/Library/OggVobisSDK/doc/vorbis/floorval.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 2.9 KiB

etc/Library/OggVobisSDK/doc/vorbis/fourphase.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 15 KiB

etc/Library/OggVobisSDK/doc/vorbis/framing.html
+395
View File
@@ -0,0 +1,395 @@
<HTML><HEAD><TITLE>xiph.org: Ogg Vorbis documentation</TITLE>
<BODY bgcolor="#ffffff" text="#202020" link="#006666" vlink="#000000">
<nobr><a href="http://www.xiph.org/ogg/index.html"><img src="white-ogg.png" border=0><img
src="vorbisword2.png" border=0></a></nobr><p>
<h1><font color=#000070>
Ogg logical bitstream framing
</font></h1>
<em>Last update to this document: July 14, 2002</em><br>
<h2>Ogg bitstreams</h2>
The Ogg transport bitstream is designed to provide framing, error
protection and seeking structure for higher-level codec streams that
consist of raw, unencapsulated data packets, such as the Vorbis audio
codec or Tarkin video codec.
<h2>Application example: Vorbis</h2>
Vorbis encodes short-time blocks of PCM data into raw packets of
bit-packed data. These raw packets may be used directly by transport
mechanisms that provide their own framing and packet-separation
mechanisms (such as UDP datagrams). For stream based storage (such as
files) and transport (such as TCP streams or pipes), Vorbis uses the
Ogg bitstream format to provide framing/sync, sync recapture
after error, landmarks during seeking, and enough information to
properly separate data back into packets at the original packet
boundaries without relying on decoding to find packet boundaries.<p>
<h2>Design constraints for Ogg bitstreams</h2>
<ol><li>True streaming; we must not need to seek to build a 100%
complete bitstream.
<li> Use no more than approximately 1-2% of bitstream bandwidth for
packet boundary marking, high-level framing, sync and seeking.
<li> Specification of absolute position within the original sample
stream.
<li> Simple mechanism to ease limited editing, such as a simplified
concatenation mechanism.
<li> Detection of corruption, recapture after error and direct, random
access to data at arbitrary positions in the bitstream.
</ol>
<h2>Logical and Physical Bitstreams</h2>
A <em>logical</em> Ogg bitstream is a contiguous stream of
sequential pages belonging only to the logical bitstream. A
<em>physical</em> Ogg bitstream is constructed from one or more
than one logical Ogg bitstream (the simplest physical bitstream
is simply a single logical bitstream). We describe below the exact
formatting of an Ogg logical bitstream. Combining logical
bitstreams into more complex physical bitstreams is described in the
<a href="oggstream.html">Ogg bitstream overview</a>. The exact
mapping of raw Vorbis packets into a valid Ogg Vorbis physical
bitstream is described in <a href="vorbis-stream.html">Vorbis
bitstream mapping</a>.
<h2>Bitstream structure</h2>
An Ogg stream is structured by dividing incoming packets into
segments of up to 255 bytes and then wrapping a group of contiguous
packet segments into a variable length page preceded by a page
header. Both the header size and page size are variable; the page
header contains sizing information and checksum data to determine
header/page size and data integrity.<p>
The bitstream is captured (or recaptured) by looking for the beginning
of a page, specifically the capture pattern. Once the capture pattern
is found, the decoder verifies page sync and integrity by computing
and comparing the checksum. At that point, the decoder can extract the
packets themselves.<p>
<h3>Packet segmentation</h3>
Packets are logically divided into multiple segments before encoding
into a page. Note that the segmentation and fragmentation process is a
logical one; it's used to compute page header values and the original
page data need not be disturbed, even when a packet spans page
boundaries.<p>
The raw packet is logically divided into [n] 255 byte segments and a
last fractional segment of < 255 bytes. A packet size may well
consist only of the trailing fractional segment, and a fractional
segment may be zero length. These values, called "lacing values" are
then saved and placed into the header segment table.<p>
An example should make the basic concept clear:<p>
<pre>
<tt>
raw packet:
___________________________________________
|______________packet data__________________| 753 bytes
lacing values for page header segment table: 255,255,243
</tt>
</pre>
We simply add the lacing values for the total size; the last lacing
value for a packet is always the value that is less than 255. Note
that this encoding both avoids imposing a maximum packet size as well
as imposing minimum overhead on small packets (as opposed to, eg,
simply using two bytes at the head of every packet and having a max
packet size of 32k. Small packets (<255, the typical case) are
penalized with twice the segmentation overhead). Using the lacing
values as suggested, small packets see the minimum possible
byte-aligned overheade (1 byte) and large packets, over 512 bytes or
so, see a fairly constant ~.5% overhead on encoding space.<p>
Note that a lacing value of 255 implies that a second lacing value
follows in the packet, and a value of < 255 marks the end of the
packet after that many additional bytes. A packet of 255 bytes (or a
multiple of 255 bytes) is terminated by a lacing value of 0:<p>
<pre><tt>
raw packet:
_______________________________
|________packet data____________| 255 bytes
lacing values: 255, 0
</tt></pre>
Note also that a 'nil' (zero length) packet is not an error; it
consists of nothing more than a lacing value of zero in the header.<p>
<h3>Packets spanning pages</h3>
Packets are not restricted to beginning and ending within a page,
although individual segments are, by definition, required to do so.
Packets are not restricted to a maximum size, although excessively
large packets in the data stream are discouraged; the Ogg
bitstream specification strongly recommends nominal page size of
approximately 4-8kB (large packets are foreseen as being useful for
initialization data at the beginning of a logical bitstream).<p>
After segmenting a packet, the encoder may decide not to place all the
resulting segments into the current page; to do so, the encoder places
the lacing values of the segments it wishes to belong to the current
page into the current segment table, then finishes the page. The next
page is begun with the first value in the segment table belonging to
the next packet segment, thus continuing the packet (data in the
packet body must also correspond properly to the lacing values in the
spanned pages. The segment data in the first packet corresponding to
the lacing values of the first page belong in that page; packet
segments listed in the segment table of the following page must begin
the page body of the subsequent page).<p>
The last mechanic to spanning a page boundary is to set the header
flag in the new page to indicate that the first lacing value in the
segment table continues rather than begins a packet; a header flag of
0x01 is set to indicate a continued packet. Although mandatory, it
is not actually algorithmically necessary; one could inspect the
preceding segment table to determine if the packet is new or
continued. Adding the information to the packet_header flag allows a
simpler design (with no overhead) that needs only inspect the current
page header after frame capture. This also allows faster error
recovery in the event that the packet originates in a corrupt
preceding page, implying that the previous page's segment table
cannot be trusted.<p>
Note that a packet can span an arbitrary number of pages; the above
spanning process is repeated for each spanned page boundary. Also a
'zero termination' on a packet size that is an even multiple of 255
must appear even if the lacing value appears in the next page as a
zero-length continuation of the current packet. The header flag
should be set to 0x01 to indicate that the packet spanned, even though
the span is a nil case as far as data is concerned.<p>
The encoding looks odd, but is properly optimized for speed and the
expected case of the majority of packets being between 50 and 200
bytes (note that it is designed such that packets of wildly different
sizes can be handled within the model; placing packet size
restrictions on the encoder would have only slightly simplified design
in page generation and increased overall encoder complexity).<p>
The main point behind tracking individual packets (and packet
segments) is to allow more flexible encoding tricks that requiring
explicit knowledge of packet size. An example is simple bandwidth
limiting, implemented by simply truncating packets in the nominal case
if the packet is arranged so that the least sensitive portion of the
data comes last.<p>
<h3>Page header</h3>
The headering mechanism is designed to avoid copying and re-assembly
of the packet data (ie, making the packet segmentation process a
logical one); the header can be generated directly from incoming
packet data. The encoder buffers packet data until it finishes a
complete page at which point it writes the header followed by the
buffered packet segments.<p>
<h4>capture_pattern</h4>
A header begins with a capture pattern that simplifies identifying
pages; once the decoder has found the capture pattern it can do a more
intensive job of verifying that it has in fact found a page boundary
(as opposed to an inadvertent coincidence in the byte stream).<p>
<pre><tt>
byte value
0 0x4f 'O'
1 0x67 'g'
2 0x67 'g'
3 0x53 'S'
</tt></pre>
<h4>stream_structure_version</h4>
The capture pattern is followed by the stream structure revision:
<pre><tt>
byte value
4 0x00
</tt></pre>
<h4>header_type_flag</h4>
The header type flag identifies this page's context in the bitstream:
<pre><tt>
byte value
5 bitflags: 0x01: unset = fresh packet
set = continued packet
0x02: unset = not first page of logical bitstream
set = first page of logical bitstream (bos)
0x04: unset = not last page of logical bitstream
set = last page of logical bitstream (eos)
</tt></pre>
<h4>absolute granule position</h4>
(This is packed in the same way the rest of Ogg data is packed; LSb
of LSB first. Note that the 'position' data specifies a 'sample'
number (eg, in a CD quality sample is four octets, 16 bits for left
and 16 bits for right; in video it would likely be the frame number.
It is up to the specific codec in use to define the semantic meaning
of the granule position value). The position specified is the total
samples encoded after including all packets finished on this page
(packets begun on this page but continuing on to the next page do not
count). The rationale here is that the position specified in the
frame header of the last page tells how long the data coded by the
bitstream is. A truncated stream will still return the proper number
of samples that can be decoded fully.
<p>
A special value of '-1' (in two's complement) indicates that no packets
finish on this page.
<pre><tt>
byte value
6 0xXX LSB
7 0xXX
8 0xXX
9 0xXX
10 0xXX
11 0xXX
12 0xXX
13 0xXX MSB
</tt></pre>
<h4>stream serial number</h4>
Ogg allows for separate logical bitstreams to be mixed at page
granularity in a physical bitstream. The most common case would be
sequential arrangement, but it is possible to interleave pages for
two separate bitstreams to be decoded concurrently. The serial
number is the means by which pages physical pages are associated with
a particular logical stream. Each logical stream must have a unique
serial number within a physical stream:
<pre><tt>
byte value
14 0xXX LSB
15 0xXX
16 0xXX
17 0xXX MSB
</tt></pre>
<h4>page sequence no</h4>
Page counter; lets us know if a page is lost (useful where packets
span page boundaries).
<pre><tt>
byte value
18 0xXX LSB
19 0xXX
20 0xXX
21 0xXX MSB
</tt></pre>
<h4>page checksum</h4>
32 bit CRC value (direct algorithm, initial val and final XOR = 0,
generator polynomial=0x04c11db7). The value is computed over the
entire header (with the CRC field in the header set to zero) and then
continued over the page. The CRC field is then filled with the
computed value.<p>
(A thorough discussion of CRC algorithms can be found in <a
href="ftp://ftp.rocksoft.com/clients/rocksoft/papers/crc_v3.txt">"A
Painless Guide to CRC Error Detection Algorithms"</a> by Ross
Williams <a
href="mailto:[email protected]">[email protected]</a>.)
<pre><tt>
byte value
22 0xXX LSB
23 0xXX
24 0xXX
25 0xXX MSB
</tt></pre>
<h4>page_segments</h4>
The number of segment entries to appear in the segment table. The
maximum number of 255 segments (255 bytes each) sets the maximum
possible physical page size at 65307 bytes or just under 64kB (thus
we know that a header corrupted so as destroy sizing/alignment
information will not cause a runaway bitstream. We'll read in the
page according to the corrupted size information that's guaranteed to
be a reasonable size regardless, notice the checksum mismatch, drop
sync and then look for recapture).<p>
<pre><tt>
byte value
26 0x00-0xff (0-255)
</tt></pre>
<h4>segment_table (containing packet lacing values)</h4>
The lacing values for each packet segment physically appearing in
this page are listed in contiguous order.
<pre><tt>
byte value
27 0x00-0xff (0-255)
[...]
n 0x00-0xff (0-255, n=page_segments+26)
</tt></pre>
Total page size is calculated directly from the known header size and
lacing values in the segment table. Packet data segments follow
immediately after the header.<p>
Page headers typically impose a flat .25-.5% space overhead assuming
nominal ~8k page sizes. The segmentation table needed for exact
packet recovery in the streaming layer adds approximately .5-1%
nominal assuming expected encoder behavior in the 44.1kHz, 128kbps
stereo encodings.<p>
<hr>
<a href="http://www.xiph.org/">
<img src="white-xifish.png" align=left border=0>
</a>
<font size=-2 color=#505050>
Ogg is a <a href="http://www.xiph.org">Xiph.org Foundation</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="http://www.xiph.org/about.html">About
the Xiph.org Foundation</a> for details.
<p>
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, the Xiph.org Foundation and
the Ogg project (xiph.org) reserve the right to set the Ogg Vorbis
specification and certify specification compliance.<p>
Xiph.org's Vorbis software CODEC implementation is distributed under a
BSD-like license. This does not restrict third parties from
distributing independent implementations of Vorbis software under
other licenses.<p>
Ogg, Vorbis, Xiph.org Foundation and their logos are trademarks (tm)
of the <a href="http://www.xiph.org/">Xiph.org Foundation</a>. These
pages are copyright (C) 1994-2002 Xiph.org Foundation. All rights
reserved.<p>
</body>
etc/Library/OggVobisSDK/doc/vorbis/helper.html
+196
View File
@@ -0,0 +1,196 @@
<HTML><HEAD><TITLE>xiph.org: Ogg Vorbis documentation</TITLE>
<BODY bgcolor="#ffffff" text="#202020" link="#006666" vlink="#000000">
<nobr><img src="white-ogg.png"><img src="vorbisword2.png"></nobr><p>
<h1><font color=#000070>
Ogg Vorbis I format specification: helper equations
</font></h1>
<em>Last update to this document: July 18, 2002</em><p>
<h1>Overview</h1>
The equations below are used in multiple places by the Vorbis codec
specification. Rather than cluttering up the main specification
documents, they are defined here and linked int he main documents
where appropriate.<p>
<a name=log><h2>ilog</h2></a>
The "ilog(x)" function returns the highest set bit in the two's complement integer value
<tt>[x]</tt>. Values of <tt>[x]</tt> less than zero are defined to return zero.
<pre>
1) [return_value] = 0;
2) if ( [x] is greater than nonzero ){
3) increment [return_value];
4) logical shift [x] one bit to the right, padding the MSb with zero
5) repeat at step 2)
}
6) done
</pre>
Examples:
<ul><li> ilog(0) = 0;
<li> ilog(1) = 1;
<li> ilog(2) = 2;
<li> ilog(3) = 2;
<li> ilog(4) = 3;
<li> ilog(7) = 3;
<li> ilog(negative number) = 0;
</uL>
<a name=float32_unpack><h2>float32_unpack</h2></a>
"float32_unpack(x)" is intended to translate the packed binary
representation of a Vorbis codebook float value into the
representation used by the decoder for floating point numbers. For
purposes of this example, we will unpack a Vorbis float32 into a
host-native floating point number.<p>
<pre>
1) [mantissa] = [x] bitwise AND 0x1fffff (unsigned result)
2) [sign] = [x] bitwise AND 0x80000000 (unsigned result)
3) [exponent] = ( [x] bitwise AND 0x7fe00000) shifted left 21 bits (unsigned result)
4) if ( [mantissa] is nonzero ) then negate [mantissa]
5) return [mantissa] * ( 2 ^ ( [exponent] - 788 ) )
</pre>
<a name=lookup1_values><h2>lookup1_values</h2></a>
"lookup1_values(codebook_entries,codebook_dimensions)" is used to
compute the correct length of the value index for a codebook VQ lookup
table of lookup type 1. The values on this list are permuted to
construct the VQ vector lookup table of size
<tt>[codebook_entries]</tt>.<p>
The return value for this function is defined to be 'the greatest
integer value for which <tt>[return_value] to the power of
[codebook_dimensions] is less than or equal to
[codebook_entries]</tt>'.
<a name=low_neighbor><h2>low_neighbor</h2></a>
"low_neighbor(v,x)" finds the position <i>n</i> in vector [v] of
the greatest value scalar element for which <i>n</i> is less than
<tt>[x]</tt> and <tt>vector [v] element <i>n</i> is less
than vector [v] element [x]</tt>.
<a name=high_neighbor><h2>high_neighbor</h2></a>
"high_neighbor(v,x)" finds the position <i>n</i> in vector [v] of
the lowest value scalar element for which <i>n</i> is less than
<tt>[x]</tt> and <tt>vector [v] element <i>n</i> is greater
than vector [v] element [x]</tt>.
<a name=render_point><h2>render_point</h2></a>
"render_point(x0,x1,y0,y1,X)" is used to find the Y value at point X
along the line specified by x0, x1, y0 and y1. This function uses an
integer algorithm to solve for the point directly without calculating
intervening values along the line.<p>
<pre>
1) [dy] = [y1] - [y0]
2) [adx] = [x1] - [x0]
3) [ady] = absolute value of [dy]
4) [err] = [ady] * ([X] - [x0])
5) [off] = [err] / [adx] using integer division
6) if ( [dy] is less than zero ) {
7) [Y] = [y0] - [off]
} else {
8) [Y] = [y0] + [off]
}
9) done
</pre>
<a name=render_line><h2>render_line</h2></a>
Floor decode type one uses the integer line drawing algorithm of
"render_line(x0, y0, x1, y1, v)" to construct an integer floor
curve for contiguous piecewise line segments. Note that it has not
been relevant elsewhere, but here we must define integer division as
rounding division of both positive and negative numbers toward zero.
<pre>
1) [dy] = [y1] - [y0]
2) [adx] = [x1] - [x0]
3) [ady] = absolute value of [dy]
4) [base] = [dy] / [adx] using integer division
5) [x] = [x0]
6) [y] = [y0]
7) [err] = 0
8) if ( [dy] is less than 0 ) {
9) [sy] = [base] - 1
} else {
10) [sy] = [base] + 1
}
11) [ady] = [ady] - [base] * [adx]
12) vector [v] element [x] = [y]
13) iterate [x] over the range [x0]+1 ... [x1]-1 {
14) [err] = [err] + [ady];
15) if ( [err] >= [adx] ) {
15) [err] = [err] - [adx]
16) [y] = [y] + [sy]
} else {
17) [y] = [y] + [base]
}
18) vector [v] element [x] = [y]
}
</pre>
<hr>
<a href="http://www.xiph.org/">
<img src="white-xifish.png" align=left border=0>
</a>
<font size=-2 color=#505050>
Ogg is a <a href="http://www.xiph.org">Xiph.org Foundation</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="http://www.xiph.org/about.html">About
the Xiph.org Foundation</a> for details.
<p>
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, the Xiph.org Foundation and
the Ogg project (xiph.org) reserve the right to set the Ogg Vorbis
specification and certify specification compliance.<p>
Xiph.org's Vorbis software CODEC implementation is distributed under a
BSD-like license. This does not restrict third parties from
distributing independent implementations of Vorbis software under
other licenses.<p>
Ogg, Vorbis, Xiph.org Foundation and their logos are trademarks (tm)
of the <a href="http://www.xiph.org/">Xiph.org Foundation</a>. These
pages are copyright (C) 1994-2002 Xiph.org Foundation. All rights
reserved.<p>
</body>
etc/Library/OggVobisSDK/doc/vorbis/hufftree-under.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 1.4 KiB

etc/Library/OggVobisSDK/doc/vorbis/hufftree.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 1.4 KiB

etc/Library/OggVobisSDK/doc/vorbis/index.html
+79
View File
@@ -0,0 +1,79 @@
<title> xiph.org: Ogg Vorbis documentation </title>
<HTML><HEAD><TITLE>xiph.org: Ogg Vorbis documentation</TITLE>
<BODY bgcolor="#ffffff" text="#202020" link="#006666" vlink="#000000">
<nobr><img src="white-ogg.png"><img src="vorbisword2.png"></nobr><p>
<h1><font color=#000070>
Ogg Vorbis Documentation
</font></h1>
<em>Last documentation revision: July 16, 2002</em><p>
<h2>Vorbis technical discussion documents</h2>
<ul>
<li><a href="vorbis-fidelity.html">Fidelity measurement terminology</a>
<li><a href="stereo.html">Vorbis channel coupling and stereo-specific application</a>
</ul>
<h2>Ogg Vorbis I specification documents</h2>
<ul>
<li><a href="vorbis-spec-intro.html">Vorbis specification introduction and description</a>
<li><a href="vorbis-spec-bitpack.html">Vorbis bitpacking convention</a>
<li><a href="vorbis-spec-codebook.html">Vorbis probability model and codebooks</a>
<li><a href="vorbis-spec-ref.html">Vorbis codec setup and packet decode</a>
<li><a href="v-comment.html">Vorbis comment header specification</a>
<li><a href="vorbis-spec-floor0.html">Vorbis floor type 0 setup and decode</a>
<li><a href="vorbis-spec-floor1.html">Vorbis floor type 1 setup and decode</a>
<li><a href="vorbis-spec-res.html">Vorbis residue types 0, 1 and 2 setup and decode</a>
<li><a href="vorbis-ogg.html">Embedding Vorbis encoded audio in an Ogg bitstream</a>
<li><a href="draft-moffitt-vorbis-rtp-00.txt">Embedding Vorbis encoded audio in an RTP payload format</a>
</ul>
<h2>Ogg Vorbis programming documents</h2>
<ul>
<li>Programming with libvorbis
<li><a href="vorbisfile/index.html">Programming with vorbisfile</a>
<li><a href="vorbisenc/index.html">Programming with vorbisenc</a><P>
</ul>
<h2>Ogg bitstream documentation</h2>
<ul>
<li><a href="oggstream.html">Ogg bitstream overview</a>
<li><a href="framing.html">Ogg logical bitstream and framing spec</a>
</ul>
<hr>
<a href="http://www.xiph.org/">
<img src="white-xifish.png" align=left border=0>
</a>
<font size=-2 color=#505050>
Ogg is a <a href="http://www.xiph.org">Xiph.org Foundation</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="http://www.xiph.org/about.html">About
the Xiph.org Foundation</a> for details.
<p>
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, the Xiph.org Foundation and
the Ogg project (xiph.org) reserve the right to set the Ogg Vorbis
specification and certify specification compliance.<p>
Xiph.org's Vorbis software CODEC implementation is distributed under a
BSD-like license. This does not restrict third parties from
distributing independent implementations of Vorbis software under
other licenses.<p>
Ogg, Vorbis, Xiph.org Foundation and their logos are trademarks (tm)
of the <a href="http://www.xiph.org/">Xiph.org Foundation</a>. These
pages are copyright (C) 1994-2002 Xiph.org Foundation. All rights
reserved.<p>
</body>
etc/Library/OggVobisSDK/doc/vorbis/lspmap.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 4.4 KiB

etc/Library/OggVobisSDK/doc/vorbis/oddlsp.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 2.2 KiB

etc/Library/OggVobisSDK/doc/vorbis/oggstream.html
+196
View File
@@ -0,0 +1,196 @@
<HTML><HEAD><TITLE>xiph.org: Ogg Vorbis documentation</TITLE>
<BODY bgcolor="#ffffff" text="#202020" link="#006666" vlink="#000000">
<nobr><a href="http://www.xiph.org/ogg/index.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
</font></h1>
<em>Last update to this document: July 14, 2002</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-separation 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 separate 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 restrictions) into a
single <em>physical bitstream</em>. A physical bitstream consists of
multiple logical bitstreams multiplexed at the page level and may
include a 'meta-header' at the beginning of the multiplexed logical
stream that serves as identification magic. 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 from the physical bitstream and redirecting them into the
appropriate logical decoding entity. The simplest physical bitstream
is a single, unmultiplexed logical bitstream with no meta-header; this
is referred to as a 'degenerate stream'. <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
bitstreams.<p>
<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-ogg.html">Ogg Vorbis
Audio Bitstream</a>', for example, has a <a
href="vorbis-ogg.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 separate audio and video streams, using different 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
bitstream.<p>
<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
characteristics:
<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 appearance to bitrate demands is one
logical strategy, ie, the page appears at the chronological point
where decode requires more information).
</ol>
<hr>
<a href="http://www.xiph.org/">
<img src="white-xifish.png" align=left border=0>
</a>
<font size=-2 color=#505050>
Ogg is a <a href="http://www.xiph.org">Xiph.org Foundation</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="http://www.xiph.org/about.html">About
the Xiph.org Foundation</a> for details.
<p>
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, the Xiph.org Foundation and
the Ogg project (xiph.org) reserve the right to set the Ogg Vorbis
specification and certify specification compliance.<p>
Xiph.org's Vorbis software CODEC implementation is distributed under a
BSD-like license. This does not restrict third parties from
distributing independent implementations of Vorbis software under
other licenses.<p>
Ogg, Vorbis, Xiph.org Foundation and their logos are trademarks (tm)
of the <a href="http://www.xiph.org/">Xiph.org Foundation</a>. These
pages are copyright (C) 1994-2002 Xiph.org Foundation. All rights
reserved.<p>
</body>
etc/Library/OggVobisSDK/doc/vorbis/programming.html
+502
View File
@@ -0,0 +1,502 @@
<HTML><HEAD><TITLE>xiph.org: Ogg Vorbis documentation</TITLE>
<BODY bgcolor="#ffffff" text="#202020" link="#006666" vlink="#000000">
<nobr><img src="white-ogg.png"><img src="vorbisword2.png"></nobr><p>
<h1><font color=#000070>
Programming with Xiph.org <tt>libvorbis</tt>
</font></h1>
<em>Last update to this document: July 22, 1999</em><br>
<h2>Description</h2>
Libvorbis is the Xiph.org Foundation's portable Ogg Vorbis CODEC
implemented as a programmatic library. Libvorbis provides primitives
to handle framing and manipulation of Ogg bitstreams (used by the
Vorbis for streaming), a full analysis (encoding) interface as well as
packet decoding and synthesis for playback. <p>
The libvorbis library does not provide any system interface; a
full-featured demonstration player included with the library
distribtion provides example code for a variety of system interfaces
as well as a working example of using libvorbis in production code.
<h2>Encoding Overview</h2>
<h2>Decoding Overview</h2>
Decoding a bitstream with libvorbis follows roughly the following
steps:
<ol>
<li>Frame the incoming bitstream into pages
<li>Sort the pages by logical bitstream and buffer then into logical streams
<li>Decompose the logical streams into raw packets
<li>Reconstruct segments of the original data from each packet
<li>Glue the reconstructed segments back into a decoded stream
</ol>
<h3>Framing</h3>
An Ogg bitstream is logically arranged into pages, but to decode
the pages, we have to find them first. The raw bitstream is first fed
into an <tt>ogg_sync_state</tt> buffer using <tt>ogg_sync_buffer()</tt>
and <tt>ogg_sync_wrote()</tt>. After each block we submit to the sync
buffer, we should check to see if we can frame and extract a complete
page or pages using <tt>ogg_sync_pageout()</tt>. Extra pages are
buffered; allowing them to build up in the <tt>ogg_sync_state</tt>
buffer will eventually exhaust memory.<p>
The Ogg pages returned from <tt>ogg_sync_pageout</tt> need not be
decoded further to be used as landmarks in seeking; seeking can be
either a rough process of simply jumping to approximately intuited
portions of the bitstream, or it can be a precise bisection process
that captures pages and inspects data position. When seeking,
however, sequential multiplexing (chaining) must be accounted for;
beginning play in a new logical bitstream requires initializing a
synthesis engine with the headers from that bitstream. Vorbis
bitstreams do not make use of concurent multiplexing (grouping).<p>
<h3>Sorting</h3>
The pages produced by <tt>ogg_sync_pageout</tt> are then sorted by
serial number to seperate logical bitstreams. Initialize logical
bitstream buffers (<tt>og_stream_state</tt>) using
<tt>ogg_stream_init()</tt>. Pages are submitted to the matching
logical bitstream buffer using <tt>ogg_stream_pagein</tt>; the serial
number of the page and the stream buffer must match, or the page will
be rejected. A page submitted out of sequence will simply be noted,
and in the course of outputting packets, the hole will be flagged
(<tt>ogg_sync_pageout</tt> and <tt>ogg_stream_packetout</tt> will
return a negative value at positions where they had to recapture the
stream).
<h3>Extracting packets</h3>
After submitting page[s] to a logical stream, read available packets
using <tt>ogg_stream_packetout</tt>.
<h3>Decoding packets</h3>
<h3>Reassembling data segments</h3>
<h2>Ogg Bitstream Manipulation Structures</h3>
Two of the Ogg bitstream data structures are intended to be
transparent to the developer; the fields should be used directly.<p>
<h3>ogg_packet</h3>
<pre>
typedef struct {
unsigned char *packet;
long bytes;
long b_o_s;
long e_o_s;
size64 granulepos;
} ogg_packet;
</pre>
<dl>
<dt>packet: <dd>a pointer to the byte data of the raw packet
<dt>bytes: <dd>the size of the packet' raw data
<dt>b_o_s: <dd>beginning of stream; nonzero if this is the first packet of
the logical bitstream
<dt>e_o_s: <dd>end of stream; nonzero if this is the last packet of the
logical bitstream
<dt>granulepos: <dd>the absolute position of this packet in the original
uncompressed data stream.
</dl>
<h4>encoding notes</h4> The encoder is responsible for setting all of
the fields of the packet to appropriate values before submission to
<tt>ogg_stream_packetin()</tt>; however, it is noted that the value in
<tt>b_o_s</tt> is ignored; the first page produced from a given
<tt>ogg_stream_state</tt> structure will be stamped as the initial
page. <tt>e_o_s</tt>, however, must be set; this is the means by
which the stream encoding primitives handle end of stream and cleanup.
<h4>decoding notes</h4><tt>ogg_stream_packetout()</tt> sets the fields
to appropriate values. Note that granulepos will be >= 0 only in the
case that the given packet actually represents that position (ie, only
the last packet completed on any page will have a meaningful
<tt>granulepos</tt>). Intervening frames will see <tt>granulepos</tt> set
to -1.
<h3>ogg_page</h3>
<pre>
typedef struct {
unsigned char *header;
long header_len;
unsigned char *body;
long body_len;
} ogg_page;
</pre>
<dl>
<dt>header: <dd>pointer to the page header data
<dt>header_len: <dd>length of the page header in bytes
<dt>body: <dd>pointer to the page body
<dt>body_len: <dd>length of the page body
</dl>
Note that although the <tt>header</tt> and <tt>body</tt> pointers do
not necessarily point into a single contiguous page vector, the page
body must immediately follow the header in the bitstream.<p>
<h2>Ogg Bitstream Manipulation Functions</h3>
<h3>
int ogg_page_bos(ogg_page *og);
</h3>
Returns the 'beginning of stream' flag for the given Ogg page. The
beginning of stream flag is set on the initial page of a logical
bitstream.<P>
Zero indicates the flag is cleared (this is not the initial page of a
logical bitstream). Nonzero indicates the flag is set (this is the
initial page of a logical bitstream).<p>
<h3>
int ogg_page_continued(ogg_page *og);
</h3>
Returns the 'packet continued' flag for the given Ogg page. The packet
continued flag indicates whether or not the body data of this page
begins with packet continued from a preceeding page.<p>
Zero (unset) indicates that the body data begins with a new packet.
Nonzero (set) indicates that the first packet data on the page is a
continuation from the preceeding page.
<h3>
int ogg_page_eos(ogg_page *og);
</h3>
Returns the 'end of stream' flag for a give Ogg page. The end of page
flag is set on the last (terminal) page of a logical bitstream.<p>
Zero (unset) indicates that this is not the last page of a logical
bitstream. Nonzero (set) indicates that this is the last page of a
logical bitstream and that no addiitonal pages belonging to this
bitstream may follow.<p>
<h3>
size64 ogg_page_granulepos(ogg_page *og);
</h3>
Returns the position of this page as an absolute position within the
original uncompressed data. The position, as returned, is 'frames
encoded to date up to and including the last whole packet on this
page'. Partial packets begun on this page but continued to the
following page are not included. If no packet ends on this page, the
frame position value will be equal to the frame position value of the
preceeding page. If none of the original uncompressed data is yet
represented in the logical bitstream (for example, the first page of a
bitstream consists only of a header packet; this packet encodes only
metadata), the value shall be zero.<p>
The units of the framenumber are determined by media mapping. A
vorbis audio bitstream, for example, defines one frame to be the
channel values from a single sampling period (eg, a 16 bit stereo
bitstream consists of two samples of two bytes for a total of four
bytes, thus a frame would be four bytes). A video stream defines one
frame to be a single frame of video.<p>
<h3>
int ogg_page_pageno(ogg_page *og);
</h3>
Returns the sequential page number of the given Ogg page. The first
page in a logical bitstream is numbered zero; following pages are
numbered in increasing monotonic order.<p>
<h3>
int ogg_page_serialno(ogg_page *og);
</h3>
Returns the serial number of the given Ogg page. The serial number is
used as a handle to distinguish various logical bitstreams in a
physical Ogg bitstresm. Every logical bitstream within a
physical bitstream must use a unique (within the scope of the physical
bitstream) serial number, which is stamped on all bitstream pages.<p>
<h3>
int ogg_page_version(ogg_page *og);
</h3>
Returns the revision of the Ogg bitstream structure of the given page.
Currently, the only permitted number is zero. Later revisions of the
bitstream spec will increment this version should any changes be
incompatable.</p>
<h3>
int ogg_stream_clear(ogg_stream_state *os);
</h3>
Clears and deallocates the internal storage of the given Ogg stream.
After clearing, the stream structure is not initialized for use;
<tt>ogg_stream_init</tt> must be called to reinitialize for use.
Use <tt>ogg_stream_reset</tt> to reset the stream state
to a fresh, intiialized state.<p>
<tt>ogg_stream_clear</tt> does not call <tt>free()</tt> on the pointer
<tt>os</tt>, allowing use of this call on stream structures in static
or automatic storage. <tt>ogg_stream_destroy</tt>is a complimentary
function that frees the pointer as well.<p>
Returns zero on success and non-zero on failure. This function always
succeeds.<p>
<h3>
int ogg_stream_destroy(ogg_stream_state *os);
</h3>
Clears and deallocates the internal storage of the given Ogg stream,
then frees the storage associated with the pointer <tt>os</tt>.<p>
<tt>ogg_stream_clear</tt> does not call <tt>free()</tt> on the pointer
<tt>os</tt>, allowing use of that call on stream structures in static
or automatic storage.<p>
Returns zero on success and non-zero on failure. This function always
succeeds.<p>
<h3>
int ogg_stream_init(ogg_stream_state *os,int serialno);
</h3>
Initialize the storage associated with <tt>os</tt> for use as an Ogg
stream. This call is used to initialize a stream for both encode and
decode. The given serial number is the serial number that will be
stamped on pages of the produced bitstream (during encode), or used as
a check that pages match (during decode).<p>
Returns zero on success, nonzero on failure.<p>
<h3>
int ogg_stream_packetin(ogg_stream_state *os, ogg_packet *op);
</h3>
Used during encoding to add the given raw packet to the given Ogg
bitstream. The contents of <tt>op</tt> are copied;
<tt>ogg_stream_packetin</tt> does not retain any pointers into
<tt>op</tt>'s storage. The encoding proccess buffers incoming packets
until enough packets have been assembled to form an entire page;
<tt>ogg_stream_pageout</tt> is used to read complete pages.<p>
Returns zero on success, nonzero on failure.<p>
<h3>
int ogg_stream_packetout(ogg_stream_state *os,ogg_packet *op);
</h3>
Used during decoding to read raw packets from the given logical
bitstream. <tt>ogg_stream_packetout</tt> will only return complete
packets for which checksumming indicates no corruption. The size and
contents of the packet exactly match those given in the encoding
process. <p>
Returns zero if the next packet is not ready to be read (not buffered
or incomplete), positive if it returned a complete packet in
<tt>op</tt> and negative if there is a gap, extra bytes or corruption
at this position in the bitstream (essentially that the bitstream had
to be recaptured). A negative value is not necessarily an error. It
would be a common occurence when seeking, for example, which requires
recapture of the bitstream at the position decoding continued.<p>
Iff the return value is positive, <tt>ogg_stream_packetout</tt> placed
a packet in <tt>op</tt>. The data in <t>op</tt> points to static
storage that is valid until the next call to
<tt>ogg_stream_pagein</tt>, <tt>ogg_stream_clear</tt>,
<tt>ogg_stream_reset</tt>, or <tt>ogg_stream_destroy</tt>. The
pointers are not invalidated by more calls to
<tt>ogg_stream_packetout</tt>.<p>
<h3>
int ogg_stream_pagein(ogg_stream_state *os, ogg_page *og);
</h3>
Used during decoding to buffer the given complete, pre-verified page
for decoding into raw Ogg packets. The given page must be framed,
normally produced by <tt>ogg_sync_pageout</tt>, and from the logical
bitstream associated with <tt>os</tt> (the serial numbers must match).
The contents of the given page are copied; <tt>ogg_stream_pagein</tt>
retains no pointers into <tt>og</tt> storage.<p>
Returns zero on success and non-zero on failure.<p>
<h3>
int ogg_stream_pageout(ogg_stream_state *os, ogg_page *og);
</h3>
Used during encode to read complete pages from the stream buffer. The
returned page is ready for sending out to the real world.<p>
Returns zero if there is no complete page ready for reading. Returns
nonzero when it has placed data for a complete page into
<tt>og</tt>. Note that the storage returned in og points into internal
storage; the pointers in <tt>og</tt> are valid until the next call to
<tt>ogg_stream_pageout</tt>, <tt>ogg_stream_packetin</tt>,
<tt>ogg_stream_reset</tt>, <tt>ogg_stream_clear</tt> or
<tt>ogg_stream_destroy</tt>.
<h3>
int ogg_stream_reset(ogg_stream_state *os);
</h3>
Resets the given stream's state to that of a blank, unused stream;
this may be used during encode or decode. <p>
Note that if used during encode, it does not alter the stream's serial
number. In addition, the next page produced during encoding will be
marked as the 'initial' page of the logical bitstream.<p>
When used during decode, this simply clears the data buffer of any
pending pages. Beginning and end of stream cues are read from the
bitstream and are unaffected by reset.<p>
Returns zero on success and non-zero on failure. This function always
succeeds.<p>
<h3>
char *ogg_sync_buffer(ogg_sync_state *oy, long size);
</h3>
This call is used to buffer a raw bitstream for framing and
verification. <tt>ogg_sync_buffer</tt> handles stream capture and
recapture, checksumming, and division into Ogg pages (as required by
<tt>ogg_stream_pagein</tt>).<p>
<tt>ogg_sync_buffer</tt> exposes a buffer area into which the decoder
copies the next (up to) <tt>size</tt> bytes. We expose the buffer
(rather than taking a buffer) in order to avoid an extra copy many
uses; this way, for example, <tt>read()</tt> can transfer data
directly into the stream buffer without first needing to place it in
temporary storage.<p>
Returns a pointer into <tt>oy</tt>'s internal bitstream sync buffer;
the remaining space in the sync buffer is at least <tt>size</tt>
bytes. The decoder need not write all of <tt>size</tt> bytes;
<tt>ogg_sync_wrote</tt> is used to inform the engine how many bytes
were actually written. Use of <tt>ogg_sync_wrote</tt> after writing
into the exposed buffer is mandantory.<p>
<h3>
int ogg_sync_clear(ogg_sync_state *oy);
</h3>
<tt>ogg_sync_clear</tt>
Clears and deallocates the internal storage of the given Ogg sync
buffer. After clearing, the sync structure is not initialized for
use; <tt>ogg_sync_init</tt> must be called to reinitialize for use.
Use <tt>ogg_sync_reset</tt> to reset the sync state and buffer to a
fresh, intiialized state.<p>
<tt>ogg_sync_clear</tt> does not call <tt>free()</tt> on the pointer
<tt>oy</tt>, allowing use of this call on sync structures in static
or automatic storage. <tt>ogg_sync_destroy</tt>is a complimentary
function that frees the pointer as well.<p>
Returns zero on success and non-zero on failure. This function always
succeeds.<p>
<h3>
int ogg_sync_destroy(ogg_sync_state *oy);
</h3>
Clears and deallocates the internal storage of the given Ogg sync
buffer, then frees the storage associated with the pointer
<tt>oy</tt>.<p>
<tt>ogg_sync_clear</tt> does not call <tt>free()</tt> on the pointer
<tt>oy</tt>, allowing use of that call on stream structures in static
or automatic storage.<p>
Returns zero on success and non-zero on failure. This function always
succeeds.<p>
<h3>
int ogg_sync_init(ogg_sync_state *oy);
</h3>
Initializes the sync buffer <tt>oy</tt> for use.<p>
Returns zero on success and non-zero on failure. This function always
succeeds.<p>
<h3>
int ogg_sync_pageout(ogg_sync_state *oy, ogg_page *og);
</h3>
Reads complete, framed, verified Ogg pages from the sync buffer,
placing the page data in <tt>og</tt>.<p>
Returns zero when there's no complete pages buffered for
retrieval. Returns negative when a loss of sync or recapture occurred
(this is not necessarily an error; recapture would be required after
seeking, for example). Returns positive when a page is returned in
<tt>og</tt>. Note that the data in <tt>og</tt> points into the sync
buffer storage; the pointers are valid until the next call to
<tt>ogg_sync_buffer</tt>, <tt>ogg_sync_clear</tt>,
<tt>ogg_sync_destroy</tt> or <tt>ogg_sync_reset</tt>.
<h3>
int ogg_sync_reset(ogg_sync_state *oy);
</h3>
<tt>ogg_sync_reset</tt> resets the sync state in <tt>oy</tt> to a
clean, empty state. This is useful, for example, when seeking to a
new location in a bitstream.<p>
Returns zero on success, nonzero on failure.<p>
<h3>
int ogg_sync_wrote(ogg_sync_state *oy, long bytes);
</h3>
Used to inform the sync state as to how many bytes were actually
written into the exposed sync buffer. It must be equal to or less
than the size of the buffer requested.<p>
Returns zero on success and non-zero on failure; failure occurs only
when the number of bytes written were larger than the buffer.<p>
<hr>
<a href="http://www.xiph.org/">
<img src="white-xifish.png" align=left border=0>
</a>
<font size=-2 color=#505050>
Ogg is a <a href="http://www.xiph.org"></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="http://www.xiph.org/about.html">About
</a> for details.
<p>
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, the Xiph.org Foundation and
the Ogg project (xiph.org) reserve the right to set the Ogg Vorbis
specification and certify specification compliance.<p>
Xiph.org's Vorbis software CODEC implementation is distributed under a
BSD-like license. This does not restrict third parties from
distributing independent implementations of Vorbis software under
other licenses.<p>
Ogg, Vorbis, Xiph.org Foundation and their logos are trademarks (tm)
of the <a href="http://www.xiph.org/">Xiph.org Foundation</a>. These
pages are copyright (C) 1994-2002 Xiph.org Foundation. All rights
reserved.<p>
</body>
etc/Library/OggVobisSDK/doc/vorbis/residue-pack.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 35 KiB

etc/Library/OggVobisSDK/doc/vorbis/residue2.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 22 KiB

etc/Library/OggVobisSDK/doc/vorbis/squarepolar.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 12 KiB

etc/Library/OggVobisSDK/doc/vorbis/stereo.html
+371
View File
@@ -0,0 +1,371 @@
<HTML><HEAD><TITLE>xiph.org: Ogg Vorbis documentation</TITLE>
<BODY bgcolor="#ffffff" text="#202020" link="#006666" vlink="#000000">
<nobr><img src="white-ogg.png"><img src="vorbisword2.png"></nobr><p>
<h1><font color=#000070>
Ogg Vorbis stereo-specific channel coupling discussion
</font></h1>
<em>Last update to this document: July 16, 2002</em><br>
<h2>Abstract</h2> The Vorbis audio CODEC provides a channel coupling
mechanisms designed to reduce effective bitrate by both eliminating
interchannel redundancy and eliminating stereo image information
labeled inaudible or undesirable according to spatial psychoacoustic
models. This document describes both the mechanical coupling
mechanisms available within the Vorbis specification, as well as the
specific stereo coupling models used by the reference
<tt>libvorbis</tt> codec provided by xiph.org.
<h2>Mechanisms</h2>
In encoder release beta 4 and earlier, Vorbis supported multiple
channel encoding, but the channels were encoded entirely separately
with no cross-analysis or redundancy elimination between channels.
This multichannel strategy is very similar to the mp3's <em>dual
stereo</em> mode and Vorbis uses the same name for its analogous
uncoupled multichannel modes.<p>
However, the Vorbis spec provides for, and Vorbis release 1.0 rc1 and
later implement a coupled channel strategy. Vorbis has two specific
mechanisms that may be used alone or in conjunction to implement
channel coupling. The first is <em>channel interleaving</em> via
residue backend type 2, and the second is <em>square polar
mapping</em>. These two general mechanisms are particularly well
suited to coupling due to the structure of Vorbis encoding, as we'll
explore below, and using both we can implement both totally
<em>lossless stereo image coupling</em> [bit-for-bit decode-identical
to uncoupled modes], as well as various lossy models that seek to
eliminate inaudible or unimportant aspects of the stereo image in
order to enhance bitrate. The exact coupling implementation is
generalized to allow the encoder a great deal of flexibility in
implementation of a stereo or surround model without requiring any
significant complexity increase over the combinatorially simpler
mid/side joint stereo of mp3 and other current audio codecs.<p>
A particular Vorbis bitstream may apply channel coupling directly to
more than a pair of channels; polar mapping is hierarchical such that
polar coupling may be extrapolated to an arbitrary number of channels
and is not restricted to only stereo, quadraphonics, ambisonics or 5.1
surround. However, the scope of this document restricts itself to the
stereo coupling case.<p>
<h3>Square Polar Mapping</h3>
<h4>maximal correlation</h4>
Recall that the basic structure of a a Vorbis I stream first generates
from input audio a spectral 'floor' function that serves as an
MDCT-domain whitening filter. This floor is meant to represent the
rough envelope of the frequency spectrum, using whatever metric the
encoder cares to define. This floor is subtracted from the log
frequency spectrum, effectively normalizing the spectrum by frequency.
Each input channel is associated with a unique floor function.<p>
The basic idea behind any stereo coupling is that the left and right
channels usually correlate. This correlation is even stronger if one
first accounts for energy differences in any given frequency band
across left and right; think for example of individual instruments
mixed into different portions of the stereo image, or a stereo
recording with a dominant feature not perfectly in the center. The
floor functions, each specific to a channel, provide the perfect means
of normalizing left and right energies across the spectrum to maximize
correlation before coupling. This feature of the Vorbis format is not
a convenient accident.<p>
Because we strive to maximally correlate the left and right channels
and generally succeed in doing so, left and right residue is typically
nearly identical. We could use channel interleaving (discussed below)
alone to efficiently remove the redundancy between the left and right
channels as a side effect of entropy encoding, but a polar
representation gives benefits when left/right correlation is
strong. <p>
<h4>point and diffuse imaging</h4>
The first advantage of a polar representation is that it effectively
separates the spatial audio information into a 'point image'
(magnitude) at a given frequency and located somewhere in the sound
field, and a 'diffuse image' (angle) that fills a large amount of
space simultaneously. Even if we preserve only the magnitude (point)
data, a detailed and carefully chosen floor function in each channel
provides us with a free, fine-grained, frequency relative intensity
stereo*. Angle information represents diffuse sound fields, such as
reverberation that fills the entire space simultaneously.<p>
*<em>Because the Vorbis model supports a number of different possible
stereo models and these models may be mixed, we do not use the term
'intensity stereo' talking about Vorbis; instead we use the terms
'point stereo', 'phase stereo' and subcategories of each.</em><p>
The majority of a stereo image is representable by polar magnitude
alone, as strong sounds tend to be produced at near-point sources;
even non-diffuse, fast, sharp echoes track very accurately using
magnitude representation almost alone (for those experimenting with
Vorbis tuning, this strategy works much better with the precise,
piecewise control of floor 1; the continuous approximation of floor 0
results in unstable imaging). Reverberation and diffuse sounds tend
to contain less energy and be psychoacoustically dominated by the
point sources embedded in them. Thus, we again tend to concentrate
more represented energy into a predictably smaller number of numbers.
Separating representation of point and diffuse imaging also allows us
to model and manipulate point and diffuse qualities separately.<p>
<h4>controlling bit leakage and symbol crosstalk</h4> Because polar
representation concentrates represented energy into fewer large
values, we reduce bit 'leakage' during cascading (multistage VQ
encoding) as a secondary benefit. A single large, monolithic VQ
codebook is more efficient than a cascaded book due to entropy
'crosstalk' among symbols between different stages of a multistage cascade.
Polar representation is a way of further concentrating entropy into
predictable locations so that codebook design can take steps to
improve multistage codebook efficiency. It also allows us to cascade
various elements of the stereo image independently.<p>
<h4>eliminating trigonometry and rounding</h4>
Rounding and computational complexity are potential problems with a
polar representation. As our encoding process involves quantization,
mixing a polar representation and quantization makes it potentially
impossible, depending on implementation, to construct a coupled stereo
mechanism that results in bit-identical decompressed output compared
to an uncoupled encoding should the encoder desire it.<p>
Vorbis uses a mapping that preserves the most useful qualities of
polar representation, relies only on addition/subtraction (during
decode; high quality encoding still requires some trig), and makes it
trivial before or after quantization to represent an angle/magnitude
through a one-to-one mapping from possible left/right value
permutations. We do this by basing our polar representation on the
unit square rather than the unit-circle.<p>
Given a magnitude and angle, we recover left and right using the
following function (note that A/B may be left/right or right/left
depending on the coupling definition used by the encoder):<p>
<pre>
if(magnitude>0)
if(angle>0){
A=magnitude;
B=magnitude-angle;
}else{
B=magnitude;
A=magnitude+angle;
}
else
if(angle>0){
A=magnitude;
B=magnitude+angle;
}else{
B=magnitude;
A=magnitude-angle;
}
}
</pre>
The function is antisymmetric for positive and negative magnitudes in
order to eliminate a redundant value when quantizing. For example, if
we're quantizing to integer values, we can visualize a magnitude of 5
and an angle of -2 as follows:<p>
<img src="squarepolar.png">
<p>
This representation loses or replicates no values; if the range of A
and B are integral -5 through 5, the number of possible Cartesian
permutations is 121. Represented in square polar notation, the
possible values are:
<pre>
0, 0
-1,-2 -1,-1 -1, 0 -1, 1
1,-2 1,-1 1, 0 1, 1
-2,-4 -2,-3 -2,-2 -2,-1 -2, 0 -2, 1 -2, 2 -2, 3
2,-4 2,-3 ... following the pattern ...
... 5, 1 5, 2 5, 3 5, 4 5, 5 5, 6 5, 7 5, 8 5, 9
</pre>
...for a grand total of 121 possible values, the same number as in
Cartesian representation (note that, for example, <tt>5,-10</tt> is
the same as <tt>-5,10</tt>, so there's no reason to represent
both. 2,10 cannot happen, and there's no reason to account for it.)
It's also obvious that this mapping is exactly reversible.<p>
<h3>Channel interleaving</h3>
We can remap and A/B vector using polar mapping into a magnitude/angle
vector, and it's clear that, in general, this concentrates energy in
the magnitude vector and reduces the amount of information to encode
in the angle vector. Encoding these vectors independently with
residue backend #0 or residue backend #1 will result in bitrate
savings. However, there are still implicit correlations between the
magnitude and angle vectors. The most obvious is that the amplitude
of the angle is bounded by its corresponding magnitude value.<p>
Entropy coding the results, then, further benefits from the entropy
model being able to compress magnitude and angle simultaneously. For
this reason, Vorbis implements residue backend #2 which pre-interleaves
a number of input vectors (in the stereo case, two, A and B) into a
single output vector (with the elements in the order of
A_0, B_0, A_1, B_1, A_2 ... A_n-1, B_n-1) before entropy encoding. Thus
each vector to be coded by the vector quantization backend consists of
matching magnitude and angle values.<p>
The astute reader, at this point, will notice that in the theoretical
case in which we can use monolithic codebooks of arbitrarily large
size, we can directly interleave and encode left and right without
polar mapping; in fact, the polar mapping does not appear to lend any
benefit whatsoever to the efficiency of the entropy coding. In fact,
it is perfectly possible and reasonable to build a Vorbis encoder that
dispenses with polar mapping entirely and merely interleaves the
channel. Libvorbis based encoders may configure such an encoding and
it will work as intended.<p>
However, when we leave the ideal/theoretical domain, we notice that
polar mapping does give additional practical benefits, as discussed in
the above section on polar mapping and summarized again here:<p>
<ul>
<li>Polar mapping aids in controlling entropy 'leakage' between stages
of a cascaded codebook. <li>Polar mapping separates the stereo image
into point and diffuse components which may be analyzed and handled
differently.
</ul>
<h2>Stereo Models</h2>
<h3>Dual Stereo</h3>
Dual stereo refers to stereo encoding where the channels are entirely
separate; they are analyzed and encoded as entirely distinct entities.
This terminology is familiar from mp3.<p>
<h3>Lossless Stereo</h3>
Using polar mapping and/or channel interleaving, it's possible to
couple Vorbis channels losslessly, that is, construct a stereo
coupling encoding that both saves space but also decodes
bit-identically to dual stereo. OggEnc 1.0 and later uses this
mode in all high-bitrate encoding.<p>
Overall, this stereo mode is overkill; however, it offers a safe
alternative to users concerned about the slightest possible
degradation to the stereo image or archival quality audio.<p>
<h3>Phase Stereo</h3>
Phase stereo is the least aggressive means of gracefully dropping
resolution from the stereo image; it affects only diffuse imaging.<p>
It's often quoted that the human ear is deaf to signal phase above
about 4kHz; this is nearly true and a passable rule of thumb, but it
can be demonstrated that even an average user can tell the difference
between high frequency in-phase and out-of-phase noise. Obviously
then, the statement is not entirely true. However, it's also the case
that one must resort to nearly such an extreme demonstration before
finding the counterexample.<p>
'Phase stereo' is simply a more aggressive quantization of the polar
angle vector; above 4kHz it's generally quite safe to quantize noise
and noisy elements to only a handful of allowed phases, or to thin the
phase with respect to the magnitude. The phases of high amplitude
pure tones may or may not be preserved more carefully (they are
relatively rare and L/R tend to be in phase, so there is generally
little reason not to spend a few more bits on them) <p>
<h4>example: eight phase stereo</h4>
Vorbis may implement phase stereo coupling by preserving the entirety
of the magnitude vector (essential to fine amplitude and energy
resolution overall) and quantizing the angle vector to one of only
four possible values. Given that the magnitude vector may be positive
or negative, this results in left and right phase having eight
possible permutation, thus 'eight phase stereo':<p>
<img src="eightphase.png"><p>
Left and right may be in phase (positive or negative), the most common
case by far, or out of phase by 90 or 180 degrees.<p>
<h4>example: four phase stereo</h4>
Similarly, four phase stereo takes the quantization one step further;
it allows only in-phase and 180 degree out-out-phase signals:<p>
<img src="fourphase.png"><p>
<h3>example: point stereo</h3>
Point stereo eliminates the possibility of out-of-phase signal
entirely. Any diffuse quality to a sound source tends to collapse
inward to a point somewhere within the stereo image. A practical
example would be balanced reverberations within a large, live space;
normally the sound is diffuse and soft, giving a sonic impression of
volume. In point-stereo, the reverberations would still exist, but
sound fairly firmly centered within the image (assuming the
reverberation was centered overall; if the reverberation is stronger
to the left, then the point of localization in point stereo would be
to the left). This effect is most noticeable at low and mid
frequencies and using headphones (which grant perfect stereo
separation). Point stereo is is a graceful but generally easy to
detect degradation to the sound quality and is thus used in frequency
ranges where it is least noticeable.<p>
<h3>Mixed Stereo</h3>
Mixed stereo is the simultaneous use of more than one of the above
stereo encoding models, generally using more aggressive modes in
higher frequencies, lower amplitudes or 'nearly' in-phase sound.<p>
It is also the case that near-DC frequencies should be encoded using
lossless coupling to avoid frame blocking artifacts.<p>
<h3>Vorbis Stereo Modes</h3>
Vorbis, as of 1.0, uses lossless stereo and a number of mixed modes
constructed out of lossless and point stereo. Phase stereo was used
in the rc2 encoder, but is not currently used for simplicity's sake. It
will likely be re-added to the stereo model in the future.
<p>
<hr>
<a href="http://www.xiph.org/">
<img src="white-xifish.png" align=left border=0>
</a>
<font size=-2 color=#505050>
Ogg is a <a href="http://www.xiph.org">Xiph.org Foundation</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="http://www.xiph.org/about.html">About
the Xiph.org Foundation</a> for details.
<p>
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, the Xiph.org Foundation and
the Ogg project (xiph.org) reserve the right to set the Ogg Vorbis
specification and certify specification compliance.<p>
Xiph.org's Vorbis software CODEC implementation is distributed under a
BSD-like license. This does not restrict third parties from
distributing independent implementations of Vorbis software under
other licenses.<p>
Ogg, Vorbis, Xiph.org Foundation and their logos are trademarks (tm)
of the <a href="http://www.xiph.org/">Xiph.org Foundation</a>. These
pages are copyright (C) 1994-2002 Xiph.org Foundation. All rights
reserved.<p>
</body>
etc/Library/OggVobisSDK/doc/vorbis/stream.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 2.3 KiB

etc/Library/OggVobisSDK/doc/vorbis/v-comment.html
+231
View File
@@ -0,0 +1,231 @@
<HTML><HEAD><TITLE>xiph.org: Ogg Vorbis documentation</TITLE>
<BODY bgcolor="#ffffff" text="#202020" link="#006666" vlink="#000000">
<nobr><img src="white-ogg.png"><img src="vorbisword2.png"></nobr><p>
<h1><font color=#000070>
Ogg Vorbis I format specification: comment field and header specification
</font></h1>
<em>Last update to this document: July 16, 2002</em><p>
<h1>Overview</h1>
<p>The Vorbis text comment header is the second (of three) header
packets that begin a Vorbis bitstream. It is meant for short, text
comments, not arbitrary metadata; arbitrary metadata belongs in a
separate logical bitstream (usually an XML stream type) that provides
greater structure and machine parseability.
<p>The comment field is meant to be used much like someone jotting a
quick note on the bottom of a CDR. It should be a little information to
remember the disc by and explain it to others; a short, to-the-point
text note that need not only be a couple words, but isn't going to be
more than a short paragraph. The essentials, in other words, whatever
they turn out to be, eg:
<blockquote>
"Honest Bob and the Factory-to-Dealer-Incentives, _I'm Still Around_,
opening for Moxy Fruvous, 1997"
</blockquote>
<h1>Comment encoding</h1>
<h2>Structure</h2>
The comment header logically is a list of eight-bit-clean vectors; the
number of vectors is bounded to 2^32-1 and the length of each vector
is limited to 2^32-1 bytes. The vector length is encoded; the vector
contents themselves are not null terminated. In addition to the vector
list, there is a single vector for vendor name (also 8 bit clean,
length encoded in 32 bits). Libvorbis currently sets the vendor string
to "Xiph.Org libVorbis I 20020717".<p>
The comment header is decoded as follows:<p>
<pre>
1) [vendor_length] = read an unsigned integer of 32 bits
2) [vendor_string] = read a UTF-8 vector as [vendor_length] octets
3) [user_comment_list_length] = read an unsigned integer of 32 bits
4) iterate [user_comment_list_length] times {
5) [length] = read an unsigned integer of 32 bits
6) this iteration's user comment = read a UTF-8 vector as [length] octets
}
7) [framing_bit] = read a single bit as boolean
8) if ( [framing_bit] unset or end of packet ) then ERROR
9) done.
</pre>
<h2>Content vector format</h2>
The comment vectors are structured similarly to a UNIX environment variable.
That is, comment fields consist of a field name and a field value and
look like:
<pre>
comment[0]="ARTIST=me";
comment[1]="TITLE=the sound of Vorbis";
</pre>
<ul>
<li>A case-insensitive field name that may consist of ASCII 0x20 through
0x7D, 0x3D ('=') excluded. ASCII 0x41 through 0x5A inclusive (A-Z) is
to be considered equivalent to ASCII 0x61 through 0x7A inclusive
(a-z).
<li>The field name is immediately followed by ASCII 0x3D ('='); this
equals sign is used to terminate the field name.
<li>0x3D is followed by 8 bit clean UTF-8 encoded field contents
to the end of the field.
</ul>
<h3>Field names</h3>
Below is a proposed, minimal list of standard filed names with a
description of intended use. No single or group of field names is
mandatory; a comment header may contain one, all or none of the names
in this list.<p>
<dl>
<dt>TITLE<dd>Track/Work name
<dt>VERSION<dd>The version field may be used to differentiate multiple
versions of the same track title in a single collection. (e.g. remix info)
<dt>ALBUM<dd>The collection name to which this track belongs
<dt>TRACKNUMBER<dd>The track number of this piece if part of a specific larger collection or album
<dt>ARTIST<dd>The artist generally considered responsible for the work. In popular music this is usually the performing band or singer. For classical music it would be the composer. For an audio book it would be the author of the original text.
<dt>PERFORMER<dd>The artist(s) who performed the work. In classical music this would be the conductor, orchestra, soloists. In an audio book it would be the actor who did the reading. In popular music this is typically the same as the ARTIST and is omitted.
<dt>COPYRIGHT<dd>Copyright attribution, e.g., '2001 Nobody's Band' or '1999 Jack Moffitt'
<dt>LICENSE<dd>License information, eg, 'All Rights Reserved', 'Any
Use Permitted', a URL to a license such as a Creative Commons license
("www.creativecommons.org/blahblah/license.html") or the EFF Open
Audio License ('distributed under the terms of the Open Audio
License. see http://www.eff.org/IP/Open_licenses/eff_oal.html for
details'), etc.
<dt>ORGANIZATION<dd>Name of the organization producing the track (i.e.
the 'record label')
<dt>DESCRIPTION<dd>A short text description of the contents
<dt>GENRE<dd>A short text indication of music genre
<dt>DATE<dd>Date the track was recorded
<dt>LOCATION<dd>Location where track was recorded
<dt>CONTACT<dd>Contact information for the creators or distributors of the track. This could be a URL, an email address, the physical address of the producing label.
<dt>ISRC<dd>ISRC number for the track; see <a href="http://www.ifpi.org/site-content/online/isrc_intro.html">the ISRC intro page</a> for more information on ISRC numbers.
</dl>
<h3>Implications</h3>
<ul>
<li>
Field names should not be 'internationalized'; this is a
concession to simplicity not an attempt to exclude the majority of
the world that doesn't speak English. Field *contents*, however,
are represented in UTF-8 to allow easy representation of any language.
<li>
We have the length of the entirety of the field and restrictions on
the field name so that the field name is bounded in a known way. Thus
we also have the length of the field contents.
<li>
Individual 'vendors' may use non-standard field names within
reason. The proper use of comment fields should be clear through
context at this point. Abuse will be discouraged.
<li>
There is no vendor-specific prefix to 'nonstandard' field names.
Vendors should make some effort to avoid arbitrarily polluting the
common namespace. We will generally collect the more useful tags
here to help with standardization.
<li>
Field names are not required to be unique (occur once) within a
comment header. As an example, assume a track was recorded by three
well know artists; the following is permissible, and encouraged:
<pre>
ARTIST=Dizzy Gillespie
ARTIST=Sonny Rollins
ARTIST=Sonny Stitt
</pre>
</ul>
<h2>Encoding</h2>
The comment header comprises the entirety of the second bitstream
header packet. Unlike the first bitstream header packet, it is not
generally the only packet on the second page and may not be restricted
to within the second bitstream page. The length of the comment header
packet is [practically] unbounded. The comment header packet is not
optional; it must be present in the bitstream even if it is
effectively empty.<p>
The comment header is encoded as follows (as per Ogg's standard
bitstream mapping which renders least-significant-bit of the word to be
coded into the least significant available bit of the current
bitstream octet first):
<ol>
<li>
Vendor string length (32 bit unsigned quantity specifying number of octets)
<li>
Vendor string ([vendor string length] octets coded from beginning of string to end of string, not null terminated)
<li>Number of comment fields (32 bit unsigned quantity specifying number of fields)
<li>Comment field 0 length (if [Number of comment fields]>0; 32 bit unsigned quantity specifying number of octets)
<li>
Comment field 0 ([Comment field 0 length] octets coded from beginning of string to end of string, not null terminated)
<li>Comment field 1 length (if [Number of comment fields]>1...)...
</ol>
This is actually somewhat easier to describe in code; implementation of the above can be found in vorbis/lib/info.c:_vorbis_pack_comment(),_vorbis_unpack_comment()
<hr>
<a href="http://www.xiph.org/">
<img src="white-xifish.png" align=left border=0>
</a>
<font size=-2 color=#505050>
Ogg is a <a href="http://www.xiph.org">Xiph.org Foundation</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="http://www.xiph.org/about.html">About
the Xiph.org Foundation</a> for details.
<p>
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, the Xiph.org Foundation and
the Ogg project (xiph.org) reserve the right to set the Ogg Vorbis
specification and certify specification compliance.<p>
Xiph.org's Vorbis software CODEC implementation is distributed under a
BSD-like license. This does not restrict third parties from
distributing independent implementations of Vorbis software under
other licenses.<p>
Ogg, Vorbis, Xiph.org Foundation and their logos are trademarks (tm)
of the <a href="http://www.xiph.org/">Xiph.org Foundation</a>. These
pages are copyright (C) 1994-2002 Xiph.org Foundation. All rights
reserved.<p>
</body>
etc/Library/OggVobisSDK/doc/vorbis/vorbis-clip.txt
+139
View File
@@ -0,0 +1,139 @@
Topic:
Sample granularity editing of a Vorbis file; inferred arbitrary sample
length starting offsets / PCM stream lengths
Overview:
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
packet[s].
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.
etc/Library/OggVobisSDK/doc/vorbis/vorbis-errors.txt
+103
View File
@@ -0,0 +1,103 @@
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
detail.
*** 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
corruption.
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.
****************************************************************
*** Libvorbis functions that can return failure/error codes:
int vorbis_analysis_headerout()
OV_EIMPL
int vorbis_analysis_wrote()
OV_EINVAL
int vorbis_synthesis_headerin()
OV_ENOTVORBIS, OV_EVERSION, OV_EBADHEADER
int vorbis_synthesis()
OV_ENOTAUDIO, OV_EBADPACKET
int vorbis_synthesis_read()
OV_EINVAL
****************************************************************
*** Libvorbisfile functions that can return failure/error codes:
int ov_open_callbacks()
OV_EREAD, OV_ENOTVORBIS, OV_EVERSION, OV_EBADHEADER, OV_FAULT
int ov_open()
OV_EREAD, OV_ENOTVORBIS, OV_EVERSION, OV_EBADHEADER, OV_FAULT
long ov_bitrate()
OV_EINVAL, OV_FALSE
long ov_bitrate_instant()
OV_FALSE
ogg_int64_t ov_raw_total()
OV_EINVAL
ogg_int64_t ov_pcm_total()
OV_EINVAL
double ov_time_total()
OV_EINVAL
int ov_raw_seek()
OV_ENOSEEK, OV_EINVAL, OV_BADLINK
int ov_pcm_seek_page()
OV_ENOSEEK, OV_EINVAL, OV_EREAD, OV_BADLINK, OV_FAULT
int ov_pcm_seek()
OV_ENOSEEK, OV_EINVAL, OV_EREAD, OV_BADLINK, OV_FAULT
int ov_time_seek()
OV_ENOSEEK, OV_EINVAL, OV_EREAD, OV_BADLINK, OV_FAULT
int ov_time_seek_page()
OV_ENOSEEK, OV_EINVAL, OV_EREAD, OV_BADLINK, OV_FAULT
long ov_read()
OV_HOLE, OV_EBADLINK
etc/Library/OggVobisSDK/doc/vorbis/vorbis-fidelity.html
+142
View File
@@ -0,0 +1,142 @@
<HTML><HEAD><TITLE>xiph.org: Ogg Vorbis documentation</TITLE>
<BODY bgcolor="#ffffff" text="#202020" link="#006666" vlink="#000000">
<nobr><img src="white-ogg.png"><img src="vorbisword2.png"></nobr><p>
<h1><font color=#000070>
Ogg Vorbis: Fidelity measurement and terminology discussion
</font></h1>
<em>Last update to this document: July 16, 2002</em><p>
Terminology discussed in this document is based on common terminology
associated with contemporary codecs such as MPEG I audio layer 3
(mp3). However, some differences in terminology are useful in the
context of Vorbis as Vorbis functions somewhat differently than most
current formats. For clarity, then, we describe a common terminology
for discussion of Vorbis's and other formats' audio quality.<p>
<h2>Subjective and Objective</h2>
<em>Objective</em> fidelity is a measure, based on a computable,
mechanical metric, of how carefully an output matches an input. For
example, a stereo amplifier may claim to introduce less that .01%
total harmonic distortion when amplifying an input signal; this claim
is easy to verify given proper equipment, and any number of testers are
likely to arrive at the same, exact results. One need not listen to
the equipment to make this measurement.<p>
However, given two amplifiers with identical, verifiable objective
specifications, listeners may strongly prefer the sound quality of one
over the other. This is actually the case in the decades old debate
[some would say jihad] among audiophiles involving vacuum tube versus
solid state amplifiers. There are people who can tell the difference,
and strongly prefer one over the other despite seemingly identical,
measurable quality. This preference is <em>subjective</em> and
difficult to measure but nonetheless real.
Individual elements of subjective differences often can be qualified,
but overall subjective quality generally is not measurable. Different
observers are likely to disagree on the exact results of a subjective
test as each observer's perspective differs. When measuring
subjective qualities, the best one can hope for is average, empirical
results that show statistical significance across a group.<p>
Perceptual codecs are most concerned with subjective, not objective,
quality. This is why evaluating a perceptual codec via distortion
measures and sonograms alone is useless; these objective measures may
provide insight into the quality or functioning of a codec, but cannot
answer the much squishier subjective question, "Does it sound
good?". The tube amplifier example is perhaps not the best as very few
people can hear, or care to hear, the minute differences between tubes
and transistors, whereas the subjective differences in perceptual
codecs tend to be quite large even when objective differences are
not.<p>
<h2>Fidelity, Artifacts and Differences</h2> Audio <em>artifacts</em>
and loss of fidelity or more simply put, audio <em>differences</em>
are not the same thing.<p>
A loss of fidelity implies differences between the perceived input and
output signal; it does not necessarily imply that the differences in
output are displeasing or that the output sounds poor (although this
is often the case). Tube amplifiers are <em>not</em> higher fidelity
than modern solid state and digital systems. They simply produce a
form of distortion and coloring that is either unnoticeable or actually
pleasing to many ears.<p>
As compared to an original signal using hard metrics, all perceptual
codecs [ASPEC, ATRAC, MP3, WMA, AAC, TwinVQ, AC3 and Vorbis included]
lose objective fidelity in order to reduce bitrate. This is fact. The
idea is to lose fidelity in ways that cannot be perceived. However,
most current streaming applications demand bitrates lower than what
can be achieved by sacrificing only objective fidelity; this is also
fact, despite whatever various company press releases might claim.
Subjective fidelity eventually must suffer in one way or another.<p>
The goal is to choose the best possible tradeoff such that the
fidelity loss is graceful and not obviously noticeable. Most listeners
of FM radio do not realize how much lower fidelity that medium is as
compared to compact discs or DAT. However, when compared directly to
source material, the difference is obvious. A cassette tape is lower
fidelity still, and yet the degradation, relatively speaking, is
graceful and generally easy not to notice. Compare this graceful loss
of quality to an average 44.1kHz stereo mp3 encoded at 80 or 96kbps.
The mp3 might actually be higher objective fidelity but subjectively
sounds much worse.<p>
Thus, when a CODEC <em>must</em> sacrifice subjective quality in order
to satisfy a user's requirements, the result should be a
<em>difference</em> that is generally either difficult to notice
without comparison, or easy to ignore. An <em>artifact</em>, on the
other hand, is an element introduced into the output that is
immediately noticeable, obviously foreign, and undesired. The famous
'underwater' or 'twinkling' effect synonymous with low bitrate (or
poorly encoded) mp3 is an example of an <em>artifact</em>. This
working definition differs slightly from common usage, but the coined
distinction between differences and artifacts is useful for our
discussion.<p>
The goal, when it is absolutely necessary to sacrifice subjective
fidelity, is obviously to strive for differences and not artifacts.
The vast majority of codecs today fail at this task miserably,
predictably, and regularly in one way or another. Avoiding such
failures when it is necessary to sacrifice subjective quality is a
fundamental design objective of Vorbis and that objective is reflected
in Vorbis's design and tuning.<p>
<hr>
<a href="http://www.xiph.org/">
<img src="white-xifish.png" align=left border=0>
</a>
<font size=-2 color=#505050>
Ogg is a <a href="http://www.xiph.org">Xiph.org Foundation</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="http://www.xiph.org/about.html">About
the Xiph.org Foundation</a> for details.
<p>
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, the Xiph.org Foundation and
the Ogg project (xiph.org) reserve the right to set the Ogg Vorbis
specification and certify specification compliance.<p>
Xiph.org's Vorbis software CODEC implementation is distributed under a
BSD-like license. This does not restrict third parties from
distributing independent implementations of Vorbis software under
other licenses.<p>
Ogg, Vorbis, Xiph.org Foundation and their logos are trademarks (tm)
of the <a href="http://www.xiph.org/">Xiph.org Foundation</a>. These
pages are copyright (C) 1994-2002 Xiph.org Foundation. All rights
reserved.<p>
</body>
etc/Library/OggVobisSDK/doc/vorbis/vorbis-ogg.html
+164
View File
@@ -0,0 +1,164 @@
<HTML><HEAD><TITLE>xiph.org: Ogg Vorbis documentation</TITLE>
<BODY bgcolor="#ffffff" text="#202020" link="#006666" vlink="#000000">
<nobr><img src="white-ogg.png"><img src="vorbisword2.png"></nobr><p>
<h1><font color=#000070>
Ogg Vorbis I format specification: embedding Vorbis into an Ogg stream
</font></h1>
<em>Last update to this document: July 14, 2002</em><br>
<h1>Overview</h1>
This document describes using Ogg logical and physical transport
streams to encapsulate Vorbis compressed audio packet data into file
form.<p>
_<a href="vorbis-spec-intro.html">Ogg Vorbis I format specification:
high-level description</a>_ provides an overview of the construction
of Vorbis audio packets.<p> The _<a href="oggstream.html">Ogg
bitstream overview</a>_ and <a href="framing.html">Ogg logical
bitstream and framing spec</a>_ 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.<p>
<h2>Restrictions</h2>
The Ogg/Vorbis I specification currently dictates that Ogg/Vorbis
streams use Ogg transport streams in degenerate, unmultiplexed
form only. That is:
<ul>
<li>A meta-headerless Ogg file encapsulates the Vorbis I packets
<li>The Ogg stream may be chained, i.e. contain multiple, contigous logical streams (links).
<li>The Ogg stream must be unmultiplexed (only one stream, a Vorbis audio stream, per link)
</ul>
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).
<p>
<h2>MIME type</h2>
The correct MIME type of any Ogg file is <tt>application/x-ogg</tt>.
However, if a file is a Vorbis I audio file (which implies a
degenerate Ogg stream including only unmultiplexed Vorbis audio), the
mime type <tt>audio/x-vorbis</tt> is also allowed.
<h1>Encapsulation</h1>
Ogg encapsulation of a Vorbis packet stream is straightforward.<p>
<ul>
<li>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.<p>
<li>This first page is marked 'beginning of stream' in the page flags.<p>
<li>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.<p>
<li>The granule position of these first pages containing only headers is
zero.<p>
<li>The first audio packet of the logical stream begins a fresh Ogg page.<p>
<li>Packets are placed into ogg pages in order until the end of stream.<p>
<li>The last page is marked 'end of stream' in the page flags.<p>
<li>Vorbis packets may span page boundaries. <p>
<li>The granule position of pages contining Vorbis audio is in units
of PCM audio samples (per channel; a stereo stream's granule position
does no increment at twice the speed of a mono stream).<p>
<li>The granule position of a page represents the end PCM sample
position of the last packet <em>completed</em> 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'.<p>
<li>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.<p>
<ul>
<li>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.<p> <li>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.<p>
</uL>
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.<p>
(Note however that 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.)<p>
<li> 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.<p>
</ul>
<hr>
<a href="http://www.xiph.org/">
<img src="white-xifish.png" align=left border=0>
</a>
<font size=-2 color=#505050>
Ogg is a <a href="http://www.xiph.org">Xiph.org Foundation</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="http://www.xiph.org/about.html">About
the Xiph.org Foundation</a> for details.
<p>
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, the Xiph.org Foundation and
the Ogg project (xiph.org) reserve the right to set the Ogg Vorbis
specification and certify specification compliance.<p>
Xiph.org's Vorbis software CODEC implementation is distributed under a
BSD-like license. This does not restrict third parties from
distributing independent implementations of Vorbis software under
other licenses.<p>
Ogg, Vorbis, Xiph.org Foundation and their logos are trademarks (tm)
of the <a href="http://www.xiph.org/">Xiph.org Foundation</a>. These
pages are copyright (C) 1994-2002 Xiph.org Foundation. All rights
reserved.<p>
</body>
etc/Library/OggVobisSDK/doc/vorbis/vorbis-spec-bitpack.html
+257
View File
@@ -0,0 +1,257 @@
<HTML><HEAD><TITLE>xiph.org: Ogg Vorbis documentation</TITLE>
<BODY bgcolor="#ffffff" text="#202020" link="#006666" vlink="#000000">
<nobr><img src="white-ogg.png"><img src="vorbisword2.png"></nobr><p>
<h1><font color=#000070>
Ogg Vorbis I format specification: bitpacking convention
</font></h1>
<em>Last update to this document: July 14, 2002</em><br>
<h1>Overview</h1>
The Vorbis codec uses relatively unstructured raw packets containing
arbitrary-width binary integer fields. Logically, these packets are a
bitstream in which bits are coded one-by-one by the encoder and then
read one-by-one in the same monotonically increasing order by the
decoder. Most current binary storage arrangements group bits into a
native word size of eight bits (octets), sixteen bits, thirty-two bits
or, less commonly other fixed word sizes. The Vorbis bitpacking
convention specifies the correct mapping of the logical packet
bitstream into an actual representation in fixed-width words.
<h2>octets, bytes and words</h2>
In most contemporary architectures, a 'byte' is synonymous with an
'octet', that is, eight bits. This has not always been the case;
seven, ten, eleven and sixteen bit 'bytes' have been used. For
purposes of the bitpacking convention, a byte implies the native,
smallest integer storage representation offered by a platform. On
modern platforms, this is generally assumed to be eight bits (not
necessarily because of the processor but because of the
filesystem/memory architecture. Modern filesystems invariably offer
bytes as the fundamental atom of storage). A 'word' is an integer
size that is a grouped multiple of this smallest size.<p>
The most ubiquitous architectures today consider a 'byte' to be an
octet (eight bits) and a word to be a group of two, four or eight
bytes (16,32 or 64 bits). Note however that the Vorbis bitpacking
convention is still well defined for any native byte size; Vorbis uses
the native bit-width of a given storage system. This document assumes
that a byte is one octet for purposes of example.<p>
<h2>bit order</h2>
A byte has a well-defined 'least significant' bit [LSb], which is the
only bit set when the byte is storing the two's complement integer
value +1. A byte's 'most significant' bit [MSb] is at the opposite
end of the byte. Bits in a byte are numbered from zero at the LSb to
<i>n</i> (<i>n</i>=7 in an octet) for the MSb.<n>
<h2>byte order</h2>
Words are native groupings of multiple bytes. Several byte orderings
are possible in a word; the common ones are 3-2-1-0 ('big endian' or
'most significant byte first' in which the highest-valued byte comes
first), 0-1-2-3 ('little endian' or 'least significant byte first' in
which the lowest value byte comes first) and less commonly 3-1-2-0 and
0-2-1-3 ('mixed endian').<p>
The Vorbis bitpacking convention specifies storage and bitstream
manipulation at the byte, not word, level, thus host word ordering is
of a concern only during optimization when writing high performance
code that operates on a word of storage at a time rather than by byte.
Logically, bytes are always coded and decoded in order from byte zero
through byte <em>n</em>.<p>
<h2>coding bits into byte sequences</h2>
The Vorbis codec has need to code arbitrary bit-width integers, from
zero to 32 bits wide, into packets. These integer fields are not
aligned to the boundaries of the byte representation; the next field
is written at the bit position that the previous field ends.<p>
The encoder logically packs integers by writing the LSb of an binary
integer to the logical bitstream first, followed by next least
significant bit, etc, until the requested number of bits have been
coded. When packing the bits into bytes, the encoder begins by
placing the LSb of the integer to be written into the least
significant unused bit position of the destination byte, followed by
the next-least significant bit of the source integer and so on up to
the requested number of bits. When all bits of the destination byte
have been filled, encoding continues by zeroing all bits of the next
byte and writing the next bit into the bit position 0 of that byte.
Decoding follows the same process as encoding, but by reading bits
from the byte stream and reassembling them into integers.<p>
<h2>signedness</h2>
The signedness of a specific number resulting from decode is to be
interpreted by the decoder given decode context. That is, the three
bit binary pattern 'b111' can be taken to represent either 'seven' as
an unsigned integer, or '-1' as a signed, two's complement integer.
The encoder and decoder are responsible for knowing if fields are to
be treated as signed or unsigned.
<h2>coding example</h2>
Code the 4 bit integer value '12' [b1100] into an empty bytestream.
Bytestream result:
<pre>
|
V
7 6 5 4 3 2 1 0
byte 0 [0 0 0 0 1 1 0 0] <-
byte 1 [ ]
byte 2 [ ]
byte 3 [ ]
...
byte n [ ] bytestream length == 1 byte
</pre>
Continue by coding the 3 bit integer value '-1' [b111]:
<pre>
|
V
7 6 5 4 3 2 1 0
byte 0 [0 1 1 1 1 1 0 0] <-
byte 1 [ ]
byte 2 [ ]
byte 3 [ ]
...
byte n [ ] bytestream length == 1 byte
</pre>
Continue by coding the 7 bit integer value '17' [b0010001]:
<pre>
|
V
7 6 5 4 3 2 1 0
byte 0 [1 1 1 1 1 1 0 0]
byte 1 [0 0 0 0 1 0 0 0] <-
byte 2 [ ]
byte 3 [ ]
...
byte n [ ] bytestream length == 2 bytes
bit cursor == 6
</pre>
Continue by coding the 13 bit integer value '6969' [b110 11001110 01]:
<pre>
|
V
7 6 5 4 3 2 1 0
byte 0 [1 1 1 1 1 1 0 0]
byte 1 [0 1 0 0 1 0 0 0]
byte 2 [1 1 0 0 1 1 1 0]
byte 3 [0 0 0 0 0 1 1 0] <-
...
byte n [ ] bytestream length == 4 bytes
</pre>
<h2>decoding example</h2>
Reading from the beginning of the bytestream encoded in the above example:
<pre>
|
V
7 6 5 4 3 2 1 0
byte 0 [1 1 1 1 1 1 0 0] <-
byte 1 [0 1 0 0 1 0 0 0]
byte 2 [1 1 0 0 1 1 1 0]
byte 3 [0 0 0 0 0 1 1 0] bytestream length == 4 bytes
</pre>
We read two, two-bit integer fields, resulting in the returned numbers
'b00' and 'b11'. Two things are worth noting here:
<ul>
<li>Although these four bits were originally written as a single four-bit
integer, reading some other combination of bit-widths from the
bitstream is well defined. There are no artificial alignment
boundaries maintained in the bitstream. <li>The second value is the
two-bit-wide integer 'b11'. This value may be interpreted either as
the unsigned value '3', or the signed value '-1'. Signedness is
dependent on decode context.
</uL>
<h2>end-of-packet alignment</h2>
The typical use of bitpacking is to produce many independent
byte-aligned packets which are embedded into a larger byte-aligned
container structure, such as an Ogg transport bitstream. Externally,
each bytestream (encoded bitstream) must begin and end on a byte
boundary. Often, the encoded bitstream is not an integer number of
bytes, and so there is unused (uncoded) space in the last byte of a
packet.<p>
Unused space in the last byte of a bytestream is always zeroed during
the coding process. Thus, should this unused space be read, it will
return binary zeroes.<p>
Attempting to read past the end of an encoded packet results in an
'end-of-packet' condition. End-of-packet is not to be considered an
error; it is merely a state indicating that there is insufficient
remaining data to fulfill the desired read size. Vorbis uses truncated
packets as a normal mode of operation, and as such, decoders must
handle reading past the end of a packet as a typical mode of
operation. Any further read operations after an 'end-of-packet'
condition shall also return 'end-of-packet'.<p>
<h2> reading zero bits</h2>
Reading a zero-bit-wide integer returns the value '0' and does not
increment the stream cursor. Reading to the end of the packet (but
not past, such that an 'end-of-packet' condition has not triggered)
and then reading a zero bit integer shall succeed, returning 0, and
not trigger an end-of-packet condition. Reading a zero-bit-wide
integer after a previous read sets 'end-of-packet' shall also fail
with 'end-of-packet'<p>
<hr>
<a href="http://www.xiph.org/">
<img src="white-xifish.png" align=left border=0>
</a>
<font size=-2 color=#505050>
Ogg is a <a href="http://www.xiph.org">Xiph.org Foundation</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="http://www.xiph.org/about.html">About
the Xiph.org Foundation</a> for details.
<p>
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, the Xiph.org Foundation and
the Ogg project (xiph.org) reserve the right to set the Ogg Vorbis
specification and certify specification compliance.<p>
Xiph.org's Vorbis software CODEC implementation is distributed under a
BSD-like license. This does not restrict third parties from
distributing independent implementations of Vorbis software under
other licenses.<p>
Ogg, Vorbis, Xiph.org Foundation and their logos are trademarks (tm)
of the <a href="http://www.xiph.org/">Xiph.org Foundation</a>. These
pages are copyright (C) 1994-2002 Xiph.org Foundation. All rights
reserved.<p>
</body>
etc/Library/OggVobisSDK/doc/vorbis/vorbis-spec-codebook.html
+399
View File
@@ -0,0 +1,399 @@
<HTML><HEAD><TITLE>xiph.org: Ogg Vorbis documentation</TITLE>
<BODY bgcolor="#ffffff" text="#202020" link="#006666" vlink="#000000">
<nobr><img src="white-ogg.png"><img src="vorbisword2.png"></nobr><p>
<h1><font color=#000070>
Ogg Vorbis I format specification: probability model and codebooks
</font></h1>
<em>Last update to this document: July 16, 2002</em><br>
<h1>Overview</h1>
Unlike practically every other mainstream audio codec, Vorbis has no
statically configured probability model, instead packing all entropy
decoding configuration, VQ and Huffman, into the bitstream itself in
the third header, the codec setup header. This packed configuration
consists of multiple 'codebooks', each containing a specific
Huffman-equivalent representation for decoding compressed codewords as
well as an optional lookup table of output vector values to which a
decoded Huffman value is applied as an offset, generating the final
decoded output corresponding to a given compressed codeword.
<h2>bitwise operation</h2>
The codebook mechanism is built on top of the <a
href="vorbis-spec-bitpack.html">Vorbis bitpacker</a>; both the
codebooks themselves and the codewords they decode are unrolled from a
packet as a series of arbitrary-width values read from the stream
according to the <a href="vorbis-spec-bitpack.html">Vorbis bitpacking
convention</a>.
<h1>Packed Codebook Format</h1>
For purposes of the below examples, we assume that the storage
system's native byte width is eight bits. This is not universally
true; see <a href="vorbis-spec-bitpack.html">the Vorbis bitpacking
convention</a> document for discussion relating to non-eight-bit
bytes.<p>
<h2>codebook decode</h2>
A codebook begins with a 24 bit sync pattern, 0x564342:
<pre>
byte 0: [ 0 1 0 0 0 0 1 0 ] (0x42)
byte 1: [ 0 1 0 0 0 0 1 1 ] (0x43)
byte 2: [ 0 1 0 1 0 1 1 0 ] (0x56)
</pre>
16 bit <tt>[codebook_dimensions]</tt> and 24 bit <tt>[codebook_entries]</tt> fields:
<pre>
byte 3: [ X X X X X X X X ]
byte 4: [ X X X X X X X X ] [codebook_dimensions] (16 bit unsigned)
byte 5: [ X X X X X X X X ]
byte 6: [ X X X X X X X X ]
byte 7: [ X X X X X X X X ] [codebook_entries] (24 bit unsigned)
</pre>
Next is the <tt>[ordered]</tt> bit flag:
<pre>
byte 8: [ X ] [ordered] (1 bit)
</pre>
We now read the list of codeword lengths; each entry (numbering a
total of <tt>[codebook_entries]</tt>) is assigned a codeword length. However,
decode of lengths is according to whether the <tt>[ordered]</tt> flag is
set or unset.
<ul>
<li>If the <tt>[ordered]</tt> flag is unset, the codeword list is not
length ordered and the decoder needs to read each codeword length
one-by-one.<p> The decoder first reads one additional bit flag, the
<tt>[sparse]</tt> flag. This flag determines whether or not the
codebook contains unused entries that are not to be included in the
codeword decode tree:<p>
<pre>
byte 8: [ X 1 ] [sparse] flag (1 bit)
</pre>
The decoder now performs for each of the <tt>[codebook_entries]</tt> code book entries:
<pre>
1) if([sparse] is set){
2) [flag] = read one bit;
3) if([flag] is set){
4) [length] = read a five bit unsigned integer;
5) codeword length for this entry is [length]+1;
} else {
6) this entry is unused. mark it as such.
}
} else the sparse flag is not set {
7) [length] = read a five bit unsigned integer;
8) the codeword length for this entry is [length]+1;
}
</pre>
<li>If the <tt>[ordered]</tt> flag is set, the codeword list for this
codebook is encoded in ascending length order. Rather than reading
a length for every codeword, the encoder reads the number of
codewords per length. That is, beginning at entry zero:
<pre>
1) [current_entry] = 0;
2) [current_length] = read a five bit unsigned integer and add one;
3) [number] = read <a
href="helper.html#ilog">ilog</a>([codebook_entries] - [current_entry]) bits as an unsigned integer
4) set the entries [current_entry] through [current_entry]+[n]-1
inclusive of the [codebook_codeword_lengths] array to [current_length]
5) set [current_entry] to [number] + [current_entry]
6) increment [current_length]
7) if [current_entry] is greater than [codebook_entries] ERROR CONDITION; the decoder will
not be able to read this stream.
8) if [current_entry] is less than [codebook_entries], repeat process starting at 3)
9) done.
</pre>
</ul>
After all codeword lengths have been decoded, the decoder reads the
vector lookup table. Vorbis I supports three lookup types:
<ol><li>No lookup
<li>Implicitly populated value mapping (lattice VQ)
<li>Explicitly populated value mapping (tessellated or 'foam' VQ)
</ol>
The lookup table type is read as a four bit unsigned integer:
<pre>
1) [codebook_lookup_type] = read four bits as an unsigned integer
</pre>
Codebook decode precedes according to <tt>[codebook_lookup_type]</tt>:
<ul>
<li> Lookup type zero indicates no lookup to be read. Proceed past
lookup decode.
<li> Lookup types one and two are similar, differing only in the
number of lookup values to be read. Lookup type one reads a list of
values that are permuted in a set pattern to build a list of vectors,
each vector of order <tt>[codebook_dimensions]</tt> scalars. Lookup
type two builds the same vector list, but reads each scalar for each
vector explicitly, rather than building vectors from a smaller list of
possible scalar values. Lookup decode proceeds as follows:
<pre>
1) [codebook_minimum_value] = <a href="helper.html#float32_unpack">float32_unpack</a>( read 32 bits as an unsigned integer)
2) [codebook_delta_value] = <a href="helper.html#float32_unpack">float32_unpack</a>( read 32 bits as an unsigned integer)
3) [codebook_value_bits] = read 4 bits as an unsigned integer and add one
4) [codebook_sequence_p] = read 1 bit as a boolean flag
if ( [codebook_lookup_type] is 1 ) {
5) [codebook_lookup_values] = <a href="helper.html#lookup1_values">lookup1_values</a>( <tt>[codebook_entries]</tt>, <tt>[codebook_dimensions]</tt> )
} else {
6) [codebook_lookup_values] = <tt>[codebook_entries]</tt> * <tt>[codebook_dimensions]</tt>
}
7) read a total of [codebook_lookup_values] unsigned integers of [codebook_value_bits] each;
store these in order in the array [codebook_multiplicands]
</pre>
<li>A <tt>[codebook_lookup_type]</tt> of greater than two is reserved and indicates
a stream that's not decodable by the specification in this document.
</ul>
An 'end of packet' during any read operation in the above steps is
considered an error condition rendering the stream undecodable.<p>
<h2>Huffman decision tree representation</h2>
The <tt>[codebook_codeword_lengths]</tt> array and
<tt>[codebook_entries]</tt> value uniquely define the Huffman decision
tree used for entropy decoding.<p>
Briefly, each used codebook entry (recall that length-unordered
codebooks support unused codeword entries) is assigned, in order, the
lowest valued unused binary Huffman codeword possible. Assume the
following codeword length list:<p>
<pre>
entry 0: length 2
entry 1: length 4
entry 2: length 4
entry 3: length 4
entry 4: length 4
entry 5: length 2
entry 6: length 3
entry 7: length 3
</pre>
Assigning codewords in order (lowest possible value of the appropriate
length to highest) results in the following codeword list:<p>
<pre>
entry 0: length 2 codeword 00
entry 1: length 4 codeword 0100
entry 2: length 4 codeword 0101
entry 3: length 4 codeword 0110
entry 4: length 4 codeword 0111
entry 5: length 2 codeword 10
entry 6: length 3 codeword 110
entry 7: length 3 codeword 111
</pre>
<em>note that unlike most binary numerical values in this document, we
intend the above codewords to be read and used bit by bit from left to
right, thus the codeword '001' is the bit string 'zero, zero, one'.
When determining 'lowest possible value' in the assignment definition
above, the leftmost bit is the MSb.</em><p>
It is clear that the codeword length list represents a Huffman
decision tree with the entry numbers equivalent to the leaves numbered
left-to-right:<p>
<img src="hufftree.png"><p>
As we assign codewords in order, we see that each choice constructs a
new leaf in the leftmost possible position.<p>
Note that it's possible to underspecify or overspecify a Huffman tree
via the length list. In the above example, if codeword seven were
eliminated, it's clear that the tree is unfinished:<p>
<img src="hufftree-under.png"><p>
Similarly, in the original codebook, it's clear that the tree is fully
populated and a ninth codeword is impossible. Both underspecified and
overspecified trees are an error condition rendering the stream
undecodable.<p>
Codebook entries marked 'unused' are simply skipped in the assigning
process. They have no codeword and do not appear in the decision
tree, thus it's impossible for any bit pattern read from the stream to
decode to that entry number.<p>
<h2>VQ lookup table vector representation</h2>
Decoding the VQ lookup table vectors relies on the following values:
<ul>
<li> the <tt>[codebook_multiplicands]</tt> array
<li> <tt>[codebook_minimum_value]</tt>
<li> <tt>[codebook_delta_value]</tt>
<li> <tt>[codebook_sequence_p]</tt>
<li> <tt>[codebook_lookup_type]</tt>
<li> <tt>[codebook_entries]</tt>
<li> <tt>[codebook_dimensions]</tt>
<li> <tt>[codebook_lookup_values]</tt>
</tt>
</ul>
Decoding a specific vector in the vector lookup table proceeds
according to <tt>[codebook_lookup_type]</tt>.<p>
<h3>Vector value decode: Lookup type 1</h3>
Lookup type one specifies a lattice VQ lookup table built
algorithmically from a list of scalar values. The scalar values of a
specific vector entry are calculated as follows, assuming
<tt>[lookup_offset]</tt> specifies the vector to be
calculated:<p>
<pre>
1) [last] = zero;
2) [index_divisor] = one;
3) iterate [codebook_dimensions] times, once for each scalar value in the vector {
4) [multiplicand_offset] = ( [lookup_offset] divided by [index_divisor] using integer
division ) integer modulo [codebook_lookup_values]
5) set this iteration's scalar value =
( [codebook_multiplicands] array element number [multiplicand_offset] ) *
[codebook_delta_value] + [codebook_minimum_value] + [last];
6) if ( [codebook_sequence_p] is set ) then set [last] = this iteration's scalar value
7) [index_divisor] = [index_divisor] * [codebook_lookup_values]
}
8) vector calculation completed.
</pre>
<h3>Vector value decode: Lookup type 2</h3>
Lookup type two specifies a VQ lookup table in which each scalar in
each vector is explicitly set by the <tt>[codebook_multiplicands]</tt>
array in a one-to-one mapping. The scalar values of a specific vector
entry in the lookup table are calculated as follows, assuming
<tt>[lookup_offset]</tt> specifies the vector to be calculated:<p>
<pre>
1) [last] = zero;
2) [multiplicand_offset] = [lookup_offset] * [codebook_dimensions]
3) iterate [codebook_dimensions] times, once for each scalar value in the vector {
4) set this iteration's scalar value =
( [codebook_multiplicands] array element number [multiplicand_offset] ) *
[codebook_delta_value] + [codebook_minimum_value] + [last];
5) if ( [codebook_sequence_p] is set ) then set [last] = this iteration's scalar value
6) increment [multiplicand_offset]
}
7) vector calculation completed.
</pre>
<h1>Use of the codebook abstraction</h1>
The decoder uses the codebook abstraction much as it does the
bit-unpacking convention; a specific codebook reads a
codeword from the bitstream, decoding it into an entry number, and then
returns that entry number to the decoder (when used in a scalar
entropy coding context), or uses that entry number as an offset into
the VQ lookup table, returning a vector of values (when used in a context
desiring a VQ value). Scalar or VQ context is always explicit; any call
to the codebook mechanism requests either a scalar entry number or a
lookup vector.<p>
Note that VQ lookup type zero indicates that there is no lookup table;
requesting decode using a codebook of lookup type 0 in any context
expecting a vector return value (even in a case where a vector of
dimension one) is forbidden. If decoder setup or decode requests such
an action, that is an error condition rendering the packet
undecodable.<p>
Using a codebook to read from the packet bitstream consists first of
reading and decoding the next codeword in the bitstream. The decoder
reads bits until the accumulated bits match a codeword in the
codebook. This process can be though of as logically walking the
Huffman decode tree by reading one bit at a time from the bitstream,
and using the bit as a decision boolean to take the 0 branch (left in
the above examples) or the 1 branch (right in the above examples).
Walking the tree finishes when the decode process hits a leaf in the
decision tree; the result is the entry number corresponding to that
leaf. Reading past the end of a packet propagates the 'end-of-stream'
condition to the decoder.<p>
When used in a scalar context, the resulting codeword entry is the
desired return value.<p>
When used in a VQ context, the codeword entry number is used as an
offset into the VQ lookup table. The value returned to the decoder is
the vector of scalars corresponding to this offset.<p>
<hr>
<a href="http://www.xiph.org/">
<img src="white-xifish.png" align=left border=0>
</a>
<font size=-2 color=#505050>
Ogg is a <a href="http://www.xiph.org">Xiph.org Foundation</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="http://www.xiph.org/about.html">About
the Xiph.org Foundation</a> for details.
<p>
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, the Xiph.org Foundation and
the Ogg project (xiph.org) reserve the right to set the Ogg Vorbis
specification and certify specification compliance.<p>
Xiph.org's Vorbis software CODEC implementation is distributed under a
BSD-like license. This does not restrict third parties from
distributing independent implementations of Vorbis software under
other licenses.<p>
Ogg, Vorbis, Xiph.org Foundation and their logos are trademarks (tm)
of the <a href="http://www.xiph.org/">Xiph.org Foundation</a>. These
pages are copyright (C) 1994-2002 Xiph.org Foundation. All rights
reserved.<p>
</body>
etc/Library/OggVobisSDK/doc/vorbis/vorbis-spec-floor0.html
+185
View File
@@ -0,0 +1,185 @@
<HTML><HEAD><TITLE>xiph.org: Ogg Vorbis documentation</TITLE>
<BODY bgcolor="#ffffff" text="#202020" link="#006666" vlink="#000000">
<nobr><img src="white-ogg.png"><img src="vorbisword2.png"></nobr><p>
<h1><font color=#000070>
Ogg Vorbis I format specification: floor type 0 setup and decode
</font></h1>
<em>Last update to this document: July 19, 2002</em><br>
<h1>Overview</h1>
Vorbis floor type zero uses Line Spectral Pair [LSP, also alternately
known as Line Spectral Frequency or LSF] representation to encode a
smooth spectral envelope curve as the frequency response of the LSP
filter. This representation is equivalent to a traditional all-pole
infinite impulse response filter as would be used in linear predictive
coding; LSP representation may be converted to LPC representation and
vice-versa.<p>
<h1>Floor 0 format</h1>
Floor zero configuration consists of six integer fields and a list of
VQ codebooks for use in coding/decoding the LSP filter coefficient
values used by each frame. <p>
<h2>header decode</h2>
Configuration information for instances of floor zero decodes from the
codec setup header (third packet). configuration decode proceeds as
follows:<p>
<pre>
1) [floor0_order] = read an unsigned integer of 8 bits
2) [floor0_rate] = read an unsigned integer of 16 bits
3) [floor0_bark_map_size] = read an unsigned integer of 16 bits
4) [floor0_amplitude_bits] = read an unsigned integer of six bits
5) [floor0_amplitude_offset] = read an unsigned integer of eight bits
6) [floor0_number_of_books] = read an unsigned integer of four bits and add 1
7) if any of [floor0_order], [floor0_rate], [floor0_bark_map_size], [floor0_amplitude_bits],
[floor0_amplitude_offset] or [floor0_number_of_books] are less than zero, the stream is not decodable
8) array [floor0_book_list] = read a list of [floor0_number_of_books] unsigned integers of eight bits each;
</pre>
An end-of-packet condition during any of these bitstream reads renders
this stream undecodable. In addition, any element of the array
<tt>[floor0_book_list]</tt> that is greater than the maximum codebook
number for this bitstream is an error condition that also renders the
stream undecodable.
<a name=decode>
<h2>packet decode</h2></a>
Extracting a floor0 curve from an audio packet consists of first
decoding the curve amplitude and <tt>[floor0_order]</tt> LSP
coefficient values from the bitstream, and then computing the floor
curve, which is defined as the frequency response of the decoded LSP
filter.<p>
Packet decode proceeds as follows:<p>
<pre>
1) [amplitude] = read an unsigned integer of [floor0_amplitude_bits] bits
2) if ( [amplitude] is greater than zero ) {
3) [coefficients] is an empty, zero length vector
4) [booknumber] = read an unsigned integer of <a href="helper.html#ilog">ilog</a>( [floor0_number_of_books] ) bits
5) if ( [booknumber] is greater than the highest number decode codebook ) then packet is undecodable
6) [lastval] = zero;
7) vector [temp_vector] = read vector from bitstream using codebook number [booknumber] in VQ context.
8) add the scalar value [last] to each scalar in vector [temp_vector]
9) [last] = the value of the last scalar in vector [temp_vector]
10) concatenate [temp_vector] onto the end of the [coefficients] vector
11) if (length of vector [coefficients] is less than [floor0_order], continue at step 6
}
12) done.
</pre>
Take note of the following properties of decode:
<ul>
<li>An <tt>[amplitude]</tt> value of zero must result in a return code that indicates this channel is unused in this frame (the output of the channel will be all-zeroes in synthesis). Several later stages of decode don't occur for an unused channel.<p>
<li>An end-of-packet condition during decode should be considered a
nominal occruence; if end-of-packet is reached during any read
operation above, floor decode is to return 'unused' status as if the
<tt>[amplitude]</tt> value had read zero at the beginning of decode.
<li>The book number used for decode
can, in fact, be stored in the bitstream in <a
href="helper.html#ilog">ilog</a>( <tt>[floor0_number_of_books]</tt> -
1 ) bits. Nevertheless, the above specification is correct and values
greater than the maximum possible book value are reserved. <p>
<li>The number of scalars read into the vector <tt>[coefficients]</tt>
may be greater than <tt>[floor0_order]</tt>, the number actually
required for curve computation. For example, if the VQ codebook used
for the floor currently being decoded has a
<tt>[codebook_dimensions]</tt> value of three and
<tt>[floor0_order]</tt> is ten, the only way to fill all the needed
scalars in <tt>[coefficients]</tt> is to to read a total of twelve
scalars as four vectors of three scalars each. This is not an error
condition, and care must be taken not to allow a buffer overflow in
decode. The extra values are not used and may be ignored or discarded.
</ul>
<a name=synth>
<h2>curve computation</h2></a>
Given an <tt>[amplitude]</tt> integer and <tt>[coefficients]</tt>
vector from packet decode as well as the [floor0_order],
[floor0_rate], [floor0_bark_map_size], [floor0_amplitude_bits] and
[floor0_amplitude_offset] values from floor setup, and an output
vector size <tt>[n]</tt> specified by the decode process, we compute a
floor output vector.<p>
If the value <tt>[amplitude]</tt> is zero, the return value is a
length <tt>[n]</tt> vector with all-zero scalars. Otherwise, begin by
assuming the following definitions for the given vector to be
synthesized:<p>
<img src="lspmap.png"><p>
The above is used to synthesize the LSP curve on a Bark-scale frequency
axis, then map the result to a linear-scale frequency axis.
Similarly, the below calculation synthesizes the output LSP curve [output] on a log
(dB) amplitude scale, mapping it to linear amplitude in the last step:<p>
<pre>
1) [i] = 0
2) if ( [floor0_order] is odd ) {
3) calculate [p] and [q] according to: <br>
<img src="oddlsp.png">
} else [floor0_order] is even {
4) calculate [p] and [q] according to: <br>
<img src="evenlsp.png">
}
5) calculate [linear_floor_value] according to:<br>
<img src="floorval.png">
6) [iteration_condition] = map element [i]
7) [output] element [i] = [linear_floor_value]
8) increment [i]
9) if ( map element [i] is equal to [iteration_condition] ) continue at step 7
10) if ( [i] is less than [n] ) continue at step 2
11) done
</pre>
<hr>
<a href="http://www.xiph.org/">
<img src="white-xifish.png" align=left border=0>
</a>
<font size=-2 color=#505050>
Ogg is a <a href="http://www.xiph.org">Xiph.org Foundation</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="http://www.xiph.org/about.html">About
the Xiph.org Foundation</a> for details.
<p>
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, the Xiph.org Foundation and
the Ogg project (xiph.org) reserve the right to set the Ogg Vorbis
specification and certify specification compliance.<p>
Xiph.org's Vorbis software CODEC implementation is distributed under a
BSD-like license. This does not restrict third parties from
distributing independent implementations of Vorbis software under
other licenses.<p>
Ogg, Vorbis, Xiph.org Foundation and their logos are trademarks (tm)
of the <a href="http://www.xiph.org/">Xiph.org Foundation</a>. These
pages are copyright (C) 1994-2002 Xiph.org Foundation. All rights
reserved.<p>
</body>
etc/Library/OggVobisSDK/doc/vorbis/vorbis-spec-floor1.html
+398
View File
@@ -0,0 +1,398 @@
<HTML><HEAD><TITLE>xiph.org: Ogg Vorbis documentation</TITLE>
<BODY bgcolor="#ffffff" text="#202020" link="#006666" vlink="#000000">
<nobr><img src="white-ogg.png"><img src="vorbisword2.png"></nobr><p>
<h1><font color=#000070>
Ogg Vorbis I format specification: floor type 1 setup and decode
</font></h1>
<em>Last update to this document: July 19, 2002</em><br>
<h1>Overview</h1>
Vorbis floor type one uses a piecewise straight-line representation to
encode a spectral envelope curve. The representation plots this curve
mechanically on a linear frequency axis and a logarithmic (dB)
amplitude axis. The integer plotting algorithm used is similar to
Bresenham's algorithm.<p>
<h1>Floor 1 format</h1>
<h2>model</h2> Floor type one represents a spectral curve as a series of
line segments. Synthesis constructs a floor curve using iterative
prediction in a process roughly equivalent to the following simplified
description:<p>
<ul><li> the first line segment (base case) is a logical line spanning
from x_0,y_0 to x_1,y_1 where in the base case x_0=0 and x_1=[n], the
full range of the spectral floor to be computed.<p>
<li>the induction step chooses a point x_new within an existing
logical line segment and produces a y_new value at that point computed
from the existing line's y value at x_new (as plotted by the line) and
a difference value decoded from the bitstream packet.<p>
<li>floor computation produces two new line segments, one running from
x_0,y_0 to x_new,y_new and from x_new,y_new to x_1,y_1. This step is
performed logically even if y_new represents no change to the
amplitude value at x_new so that later refinement is additionally
bounded at x_new.<p>
<li>the induction step repeats, using a list of x values specified in
the codec setup header at floor 1 initialization time. Computation
is completed at the end of the x value list.
</ul>
Consider the following example, with values chosen for ease of
understanding rather than representing typical configuration:<p>
For the below example, we assume a floor setup with an [n] of 128.
The list of selected X values in increasing order is
0,16,32,48,64,80,96,112 and 128. In list order, the values interleave
as 0, 128, 64, 32, 96, 16, 48, 80 and 112. The corresponding
list-order Y values as decoded from an example packet are 110, 20, -5,
-45, 0, -25, -10, 30 and -10. We compute the floor in the following
way, beginning with the first line:<p>
<img src="floor1-1.png"><p>
We now draw new logical lines to reflect the correction to new_Y, and
iterate for X positions 32 and 96:<p>
<img src="floor1-2.png"><p>
Although the new Y value at X position 96 is unchanged, it is still
used later as an endpoint for further refinement. From here on, the
pattern should be clear; we complete the floor computation as follows:<p>
<img src="floor1-3.png"><p>
<img src="floor1-4.png"><p>
A more efficient algorithm with carefully defined integer rounding
behavior is used for actual decode, as described later. The actual
algorithm splits Y value computation and line plotting into two steps
with modifications to the above algorithm to eliminate noise
accumulation through integer roundoff/truncation. <p>
<h2>header decode</h2>
A list of floor X values is stored in the packet header in interleaved
format (used in list order during packet decode and synthesis). This
list is split into partitions, and each partition is assigned to a
partition class. X positions 0 and [n] are implicit and do not belong
to an explicit partition or partition class.<p>
A partition class consists of a representation vector width (the
number of Y values which the partition class encodes at once), a
'subclass' value representing the number of alternate entropy books
the partition class may use in representing Y values, the list of
[subclass] books and a master book used to encode which alternate
books were chosen for representation in a given packet. The
master/subclass mechanism is meant to be used as a flexible
representation cascade while still using codebooks only in a scalar
context.<p>
<pre>
1) [floor1_partitions] = read 5 bits as unsigned integer
2) [maximum_class] = 0
3) iterate [i] over the range 0 ... [floor1_partitions]-1 {
4) vector [floor1_partition_class_list] element [i] = read 4 bits as unsigned integer
}
5) [maximum_class] = largest integer scalar value in vector [floor1_partition_class_list]
6) iterate [i] over the range 0 ... [maximum_class] {
7) vector [floor1_class_dimensions] element [i] = read 3 bits as unsigned integer and add 1
8) vector [floor1_class_subclasses] element [i] = read 2 bits as unsigned integer
9) if ( vector [floor1_class_subclasses] element [i] is nonzero ) {
10) vector [floor1_class_masterbooks] element [i] = read 8 bits as unsigned integer
}
11) iterate [j] over the range 0 ... (2 exponent [floor1_class_subclasses] element [i]) - 1 {
12) array [floor1_subclass_books] element [i],[j] =
read 8 bits as unsigned integer and subtract one
}
}
13) [floor1_multiplier] = read 2 bits as unsigned integer and add one
14) [rangebits] = read 4 bits as unsigned integer
15) vector [floor1_X_list] element [0] = 0
16) vector [floor1_X_list] element [1] = 2 exponent [rangebits];
17) [floor1_values] = 1
18) iterate [i] over the range 0 ... [floor1_partitions]-1 {
19) iterate [j] over the range 0 ... ([floor1_class_dimensions] element [i])-1 {
20) vector [floor1_X_list] element ([j] + [floor1_values]) =
read [rangebits] bits as unsigned integer
}
21) [floor1_values] = [floor1_values] + [floor1_class_dimensions] element [i]
}
19) done
</pre>
An end-of-packet condition while reading any aspect of a floor 1
configuration during setup renders a stream undecodable. In
addition, a <tt>[floor1_class_masterbooks]</tt> or
<tt>[floor1_subclass_books]</tt> scalar element greater than the
highest numbered codebook configured in this stream is an error
condition that renders the stream undecodable.<p>
<a name=decode>
<h2>packet decode</h2></a>
Packet decode begins by checking the <tt>[nonzero]</tt> flag:<p>
<pre>
1) [nonzero] = read 1 bit as boolean
</pre>
If <tt>[nonzero]</tt> is unset, that indicates this channel contained
no audio energy in this frame. Decode immediately returns a status
indicating this floor curve (and thus this channel) is unused this
frame. (A return status of 'unused' is different from decoding a
floor that has all points set to minimum representation amplitude,
which happens to be approximately -140dB).
Assuming <tt>[nonzero]</tt> is set, decode proceeds as follows:<p>
<pre>
1) [range] = vector { 256, 128, 86, 64 } element ([floor1_multiplier]-1)
2) vector [floor1_Y] element [0] = read <a href="helper.html#ilog">ilog</a>([range]-1) bits as unsigned integer
3) vector [floor1_Y] element [1] = read <a href="helper.html#ilog">ilog</a>([range]-1) bits as unsigned integer
4) [offset] = 2;
5) iterate [i] over the range 0 ... [floor1_partitions]-1 {
6) [class] = vector [floor1_partition_class] element [i]
7) [cdim] = vector [floor1_class_dimensions] element [class]
8) [cbits] = vector [floor1_class_subclasses] element [class]
9) [csub] = (2 exponent [cbits])-1
10) [cval] = 0
11) if ( [cbits] is greater than zero ) {
12) [cval] = read from packet using codebook number
(vector [floor1_class_masterbooks] element [class]) in scalar context
}
13) iterate [j] over the range 0 ... [cdim]-1 {
14) [book] = array [floor1_subclass_books] element [class],([cval] bitwise AND [csub])
15) if ( [book] is not less than zero ) {
16) vector [floor1_Y] element ([j]+[offset]) = read from packet using codebook
[book] in scalar context
} else [book] is less than zero {
17) vector [floor1_Y] element ([j]+[offset]) = 0
}
}
18) [offset] = [offset] + [cdim]
}
19) done
</pre>
An end-of-packet condition during curve decode should be considered a
nominal occurrence; if end-of-packet is reached during any read
operation above, floor decode is to return 'unused' status as if the
<tt>[nonzero]</tt> flag had been unset at the beginning of decode.
Vector <tt>[floor1_Y]</tt> contains the values from packet decode
needed for floor 1 synthesis.<p>
<a name=synth>
<h2>curve computation</h2></a>
Curve computation is split into two logical steps; the first step
derives final Y amplitude values from the encoded, wrapped difference
values taken from the bitstream. The second step plots the curve
lines. Also, although zero-difference values are used in the
iterative prediction to find final Y values, these points are
conditionally skipped during final line computation in step two.
Skipping zero-difference values allows a smoother line fit. <p>
Although some aspects of the below algorithm look like inconsequential
optimizations, implementors are warned to follow the details closely.
Deviation from implementing a strictly equivalent algorithm can result
in serious decoding errors.<p>
<h3>step 1: amplitude value synthesis</h3>
Unwrap the always-positive-or-zero values read from the packet into
+/- difference values, then apply to line prediction.<p>
<pre>
1) [range] = vector { 256, 128, 86, 64 } element ([floor1_multiplier]-1)
2) iterate [i] over the range 2 ... [floor1_values]-1 {
3) [low_neighbor_offset] = <a href="helper.html#low_neighbor">low_neighbor</a>([floor1_X_list],[i])
4) [high_neighbor_offset] = <a href="helper.html#high_neighbor">high_neighbor</a>([floor1_X_list],[i])
5) [predicted] = <a href="helper.html#render_point">render_point</a>( vector [floor1_X_list] element [low_neighbor_offset],
vector [floor1_X_list] element [high_neighbor_offset],
vector [floor1_Y] element [low_neighbor_offset],
vector [floor1_Y] element [high_neighbor_offset],
vector [floor1_X_list] element [i] )
6) [val] = vector [floor1_Y] element [i]
7) [highroom] = [range] - [predicted]
8) [lowroom] = [predicted]
9) if ( [highroom] is less than [lowroom] ) {
10) [room] = [highroom] * 2
} else [highroom] is not less than [lowroom] {
11) [root] = [lowroom] * 2
}
12) if ( [val] is nonzero ) {
13) vector [floor1_step2_flag] element [low_neighbor_offset] = set
14) vector [floor1_step2_flag] element [high_neighbor_offset] = set
15) vector [floor1_step2_flag] element [i] = set
16) if ( [val] is greater than or equal to [room] ) {
17) if ( [hiroom] is greater than [lowroom] ) {
18) vector [floor1_final_Y] element [i] = [val] - [lowroom] + [predicted]
} else [hiroom] is not greater than [lowroom] {
19) vector [floor1_final_Y] element [i] = [predicted] - ([val] - [lowroom]) - 1
}
} else [val] is less than [room] {
20) if ([val] is odd) {
21) vector [floor1_final_Y] element [i] =
[predicted] - (([val] - 1) divided by 2 using integer division)
} else [val] is even {
22) vector [floor1_final_Y] element [i] =
[predicted] + ([val] / 2 using integer division)
}
}
} else [val] is zero {
23) vector [floor1_step2_flag] element [i] = unset
24) vector [floor1_final_Y] element [i] = [predicted]
}
}
25) vector [floor1_step2_flag] element [0] = set
26) vector [floor1_step2_flag] element [1] = set
27) vector [floor1_final_Y] element [0] = vector [floor1_Y] element [0]
28) vector [floor1_final_Y] element [1] = vector [floor1_Y] element [1]
29) done
</pre>
<h3>step 2: curve synthesis</h3>
Curve synthesis generates a return vector <tt>[floor]</tt> of length
<tt>[n]</tt> (where <tt>[n]</tt> is provided by the decode process
calling to floor decode). Floor 1 curve synthesis makes use of the
<tt>[floor1_X_list]</tt>, <tt>[floor1_final_Y]</tt> and
<tt>[floor1_step2_flag]</tt> vectors, as well as [floor1_multiplier]
and [floor1_values] values.<p>
Decode begins by sorting the scalars from vectors
<tt>[floor1_X_list]</tt>, <tt>[floor1_final_Y]</tt> and
<tt>[floor1_step2_flag]</tt> together into new vectors
<tt>[floor1_X_list]'</tt>, <tt>[floor1_final_Y]'</tt> and
<tt>[floor1_step2_flag]'</tt> according to ascending sort order of the
values in <tt>[floor1_X_list]</tt>. That is, sort the values of
<tt>[floor1_X_list]</tt> and then apply the same permutation to
elements of the other two vectors so that the X, Y and step2_flag
values still match.<p>
Then compute the final curve in one pass:<p>
<pre>
1) [hx] = 0
2) [lx] = 0
3) [ly] = vector [floor1_final_Y]' element [0] * [floor1_multiplier]
4) iterate [i] over the range 1 ... [floor1_values]-1 {
5) if ( [floor1_step2_flag]' is set ) {
6) [hy] = [floor1_final_Y]' element [i] * [floor1_multiplier]
7) [hx] = [floor1_X_list]' element [i]
8) <a href="helper.html#render_line">render_line</a>( [lx], [hx], [ly], [hy], [floor] )
9) [lx] = [hx]
10) [ly] = [hy]
}
11) if ( [hx] is less than [n] ) {
12) <a href="helper.html#render_line">render_line</a>( [hx], [hy], [n], [hy], [floor] )
}
13) if ( [hx] is greater than [n] ) {
14) truncate vector [floor] to [n] elements
}
}
15) for each scalar in vector [floor], perform a lookup substitution using
the scalar value from [floor] as an offset into the vector <a href="floor1_inverse_dB_table.html">[floor1_inverse_dB_static_table]</a>
16) done
</pre>
<hr>
<a href="http://www.xiph.org/">
<img src="white-xifish.png" align=left border=0>
</a>
<font size=-2 color=#505050>
Ogg is a <a href="http://www.xiph.org">Xiph.org Foundation</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="http://www.xiph.org/about.html">About
the Xiph.org Foundation</a> for details.
<p>
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, the Xiph.org Foundation and
the Ogg project (xiph.org) reserve the right to set the Ogg Vorbis
specification and certify specification compliance.<p>
Xiph.org's Vorbis software CODEC implementation is distributed under a
BSD-like license. This does not restrict third parties from
distributing independent implementations of Vorbis software under
other licenses.<p>
Ogg, Vorbis, Xiph.org Foundation and their logos are trademarks (tm)
of the <a href="http://www.xiph.org/">Xiph.org Foundation</a>. These
pages are copyright (C) 1994-2002 Xiph.org Foundation. All rights
reserved.<p>
</body>
etc/Library/OggVobisSDK/doc/vorbis/vorbis-spec-intro.html
+534
View File
@@ -0,0 +1,534 @@
<HTML><HEAD><TITLE>xiph.org: Ogg Vorbis documentation</TITLE>
<BODY bgcolor="#ffffff" text="#202020" link="#006666" vlink="#000000">
<nobr><img src="white-ogg.png"><img src="vorbisword2.png"></nobr><p>
<h1><font color=#000070>
Ogg Vorbis I format specification: introduction and description
</font></h1>
<em>Last update to this document: July 18, 2002</em><br>
<h1>Overview</h1>
This document provides a high level description of the Vorbis codec's
construction. A bit-by-bit specification appears beginning in the <a
href="vorbis-spec-ref.html">packet specification and reference</a>
document. The other reference documents assumes a high-level
understanding of the Vorbis decode process, which is provided in this
document.<p>
<h2>Application</h2>
Vorbis is a general purpose perceptual audio CODEC intended to allow
maximum encoder flexibility, thus allowing it to scale competitively
over an exceptionally wide range of bitrates. At the high
quality/bitrate end of the scale (CD or DAT rate stereo, 16/24 bits),
it is in the same league as MPEG-2 and MPC. Similarly, the 1.0
encoder can encode high-quality CD and DAT rate stereo at below 48kpbs
without resampling to a lower rate. Vorbis is also intended for
lower and higher sample rates (from 8kHz telephony to 192kHz digital
masters) and a range of channel representations (monaural,
polyphonic, stereo, quadraphonic, 5.1, ambisonic, or up to 255
discrete channels).<p>
<h2>Classification</h2>
Vorbis I is a forward-adaptive monolithic transform CODEC based on the
Modified Discrete Cosine Transform. The codec is structured to allow
addition of a hybrid wavelet filterbank in Vorbis II to offer better
transient response and reproduction using a transform better suited to
localized time events.
<h2>Assumptions</h2>
The Vorbis CODEC design assumes a complex, psychoacoustically-aware
encoder and simple, low-complexity decoder. Vorbis decode is
computationally simpler than mp3, although it does require more
working memory as Vorbis has no static probability model; the vector
codebooks used in the first stage of decoding from the bitstream are
packed, in their entirety, into the Vorbis bitstream headers. In
packed form, these codebooks occupy only a few kilobytes; the extent
to which they are pre-decoded into a cache is the dominant factor in
decoder memory usage.<p>
Vorbis provides none of its own framing, synchronization or protection
against errors; it is solely a method of accepting input audio,
dividing it into individual frames and compressing these frames into
raw, unformatted 'packets'. The decoder then accepts these raw
packets in sequence, decodes them, synthesizes audio frames from
them, and reassembles the frames into a facsimile of the original
audio stream. Vorbis is a free-form VBR codec and packets have no
minimum size, maximum size, or fixed/expected size. Packets
are designed that they may be truncated (or padded) and remain
decodable; this is not to be considered an error condition and is used
extensively in bitrate management in peeling. Both the transport
mechanism and decoder must allow that a packet may be any size, or
end before or after packet decode expects.<p>
Vorbis packets are thus intended to be used with a transport mechanism
that provides free-form framing, sync, positioning and error correction
in accordance with these design assumptions, such as Ogg (for file
transport) or RTP (for network multicast). For purposes of a few
examples in this document, we will assume that Vorbis is to be
embedded in an Ogg stream specifically, although this is by no means a
requirement or fundamental assumption in the Vorbis design.<p>
<a href="vorbis-ogg.html">The specifications for embedding Vorbis into
an Ogg transport stream is in a separate document.</a><p>
<h2>Codec Setup and Probability Model</h2>
Vorbis's heritage is as a research CODEC and its current design
reflects a desire to allow multiple decades of continuous encoder
improvement before running out of room within the codec specification.
For these reasons, configurable aspects codec setup intentionally
lean toward the extreme of forward adaptive.<p>
The single most controversial design decision in Vorbis [and the most
unusual for a Vorbis developer to keep in mind] is that the entire
probability model of the codec, the Huffman and VQ codebooks, is
packed into the bitstream header along with extensive CODEC setup
parameters (often several hundred fields). This makes it impossible,
as it would be with MPEG audio layers, to embed a simple frame type
flag in each audio packet, or begin decode at any frame in the stream
without having previously fetched the codec setup header. [Note:
Vorbis *can* initiate decode at any arbitrary packet within a
bitstream so long as the codec has been initialized/setup with the
setup headers].<p>
Thus, Vorbis headers are both required for decode to begin and
relatively large as bitstream headers go. The header size is
unbounded, although for streaming a rule-of-thumb of 4kB or less is
recommended (and Xiph.Org's Vorbis encoder follows this suggestion).<p>
Our own design work indicates the the primary liability of the
required header is in mindshare; it is an unusual design and thus
causes some amount of complaint among engineers as this runs against
current design trends (and also points out limitations in some
existing software/interface designs, such as Windows' ACM codec
framework). However, we find that it does not fundamentally limit
Vorbis's suitable application space.<p>
<h2>Format Specification</h2>
The Vorbis format is well-defined by its decode specification; any
encoder that produces packets that are correctly decoded by the
reference Vorbis decoder described below may be considered a proper
Vorbis encoder. A decoder must faithfully and completely implement
the specification defined below [except where noted] to be considered
a proper Vorbis decoder.<p>
<h2>Hardware Profile</h2>
Although Vorbis decode is computationally simple, it may still run
into specific limitations of an embedded design. For this reason,
embedded designs are allowed to deviate in limited ways from the
'full' decode specification yet still be certified compliant. These
optional omissions are labelled in the spec where relevant.<p>
<h1>Decoder Configuration</h1>
Decoder setup consists of configuration of multiple, self-contained
component abstractions that perform specific functions in the decode
pipeline. Each different component instance of a specific type is
semantically interchangeable; decoder configuration consists both of
internal component configuration, as well as arrangement of specific
instances into a decode pipeline. Componentry arrangement is roughly
as follows:<p>
<img src="components.png"><p>
<h2> Global Config </h2>
Global codec configuration consists of a few audio related fields
(sample rate, channels), Vorbis version (always '0' in Vorbis I),
bitrate hints, and the lists of component instances. All other
configuration is in the context of specific components.<p>
<h2> Mode </h2>
Each Vorbis frame is coded according to a master 'mode'. A bitstream
may use one or many modes.<p>
The mode mechanism is used to encode a frame according to one of
multiple possible methods with the intention of choosing a method best
suited to that frame. Different modes are, e.g. how frame size
is changed from frame to frame. The mode number of a frame serves as a
top level configuration switch for all other specific aspects of frame
decode.<p>
A 'mode' configuration consists of a frame size setting, window type
(always 0, the Vorbis window, in Vorbis I), transform type (always
type 0, the MDCT, in Vorbis I) and a mapping number. The mapping
number specifies which mapping configuration instance to use for
low-level packet decode and synthesis.<p>
<h2> Mapping </h2>
A mapping contains a channel coupling description and a list of
'submaps' that bundle sets of channel vectors together for grouped
encoding and decoding. These submaps are not references to external
components; the submap list is internal and specific to a mapping.<p>
A 'submap' is a configuration/grouping that applies to a subset of
floor and residue vectors within a mapping. The submap functions as a
last layer of indirection such that specific special floor or residue
settings can be applied not only to all the vectors in a given mode,
but also specific vectors in a specific mode. Each submap specifies
the proper floor and residue instance number to use for decoding that
submap's spectral floor and spectral residue vectors.<p>
As an example:<p>
Assume a Vorbis stream that contains six channels in the standard 5.1
format. The sixth channel, as is normal in 5.1, is bass only.
Therefore it would be wasteful to encode a full-spectrum version of it
as with the other channels. The submapping mechanism can be used to
apply a full range floor and residue encoding to channels 0 through 4,
and a bass-only representation to the bass channel, thus saving space.
In this example, channels 0-4 belong to submap 0 (which indicates use
of a full-range floor) and channel 5 belongs to submap 1, which uses a
bass-only representation.<p>
<h2> Floor </h2>
Vorbis encodes a spectral 'floor' vector for each PCM channel. This
vector is a low-resolution representation of the audio spectrum for
the given channel in the current frame, generally used akin to a
whitening filter. It is named a 'floor' because the Xiph.Org
reference encoder has historically used it as a unit-baseline for
spectral resolution.<p>
A floor encoding may be of two types. Floor 0 uses a packed LSP
representation on a dB amplitude scale and Bark frequency scale.
Floor 1 represents the curve as a piecewise linear interpolated
representation on a dB amplitude scale and linear frequency scale.
The two floors are semantically interchangeable in
encoding/decoding. However, floor type 1 provides more stable
inter-frame behavior, and so is the preferred choice in all
coupled-stereo and high bitrate modes. Floor 1 is also considerably
less expensive to decode than floor 0.<p>
Floor 0 is not to be considered deprecated, but it is of limited
modern use. No known Vorbis encoder past Xiph.org's own beta 4 makes
use of floor 0.<p>
The values coded/decoded by a floor are both compactly formatted and
make use of entropy coding to save space. For this reason, a floor
configuration generally refers to multiple codebooks in the codebook
component list. Entropy coding is thus provided as an abstraction,
and each floor instance may choose from any and all available
codebooks when coding/decoding.<p>
<h2> Residue </h2>
The spectral residue is the fine structure of the audio spectrum
once the floor curve has been subtracted out. In simplest terms, it
is coded in the bitstream using cascaded (multi-pass) vector
quantization according to one of three specific packing/coding
algorithms numbered 0 through 2. The packing algorithm details are
configured by residue instance. As with the floor components, the
final VQ/entropy encoding is provided by external codebook instances
and each residue instance may choose from any and all available
codebooks.<p>
<h2> Codebooks </h2>
Codebooks are a self-contained abstraction that perform entropy
decoding and, optionally, use the entropy-decoded integer value as an
offset into an index of output value vectors, returning the indicated
vector of values.<p>
The entropy coding in a Vorbis I codebook is provided by a standard
Huffman binary tree representation. This tree is tightly packed using
one of several methods, depending on whether codeword lengths are
ordered or unordered, or the tree is sparse.<p>
The codebook vector index is similarly packed according to index
characteristic. Most commonly, the vector index is encoded as a
single list of values of possible values that are then permuted into
a list of n-dimensional rows (lattice VQ).<p>
<h1>High-level Decode Process</h1>
<h2>Decode setup</h2>
Before decoding can begin, a decoder must initialize using the
bitstream headers matching the stream to be decoded. Vorbis uses
three header packets; all are required, in-order, by this
specification. Once set up, decode may begin at any audio packet
belonging to the Vorbis stream. In Vorbis I, all packets after the
three initial headers are audio packets. <p>
The header packets are, in order, the identification
header, the comments header, and the setup header.<p>
<h3>Identification Header</h3>
The identification header identifies the bitstream as Vorbis, Vorbis
version, and the simple audio characteristics of the stream such as
sample rate and number of channels.<p>
<h3>Comment Header</h3>
The comment header includes user text comments ["tags"] and a vendor
string for the application/library that produced the bitstream. The
encoding of the comment header is described within this document; the
proper use of the comment fields is described in <a href="v-comment.html">the Ogg Vorbis comment field specification</a>.<p>
<h3>Setup Header</h3>
The setup header includes extensive CODEC setup information as well as
the complete VQ and Huffman codebooks needed for decode.<p>
<h2>Decode Procedure</h2>
The decoding and synthesis procedure for all audio packets is
fundamentally the same.
<ol>
<li>decode packet type flag
<li>decode mode number
<li>decode window shape [long windows only]
<li>decode floor
<li>decode residue into residue vectors
<li>inverse channel coupling of residue vectors
<li>generate floor curve from decoded floor data
<li>compute dot product of floor and residue, producing audio spectrum vector
<li>inverse monolithic transform of audio spectrum vector, always an MDCT in Vorbis I
<li>overlap/add left-hand output of transform with right-hand output of previous frame
<li>store right hand-data from transform of current frame for future lapping.
<li>if not first frame, return results of overlap/add as audio result of current frame
</ol>
Note that clever rearrangement of the synthesis arithmetic is
possible; as an example, one can take advantage of symmetries in the
MDCT to store the right-hand transform data of a partial MDCT for a
50% inter-frame buffer space savings, and then complete the transform
later before overlap/add with the next frame. This optimization
produces entirely equivalent output and is naturally perfectly legal.
The decoder must be <em>entirely mathematically equivalent</em> to the
specification, it need not be a literal semantic implementation.
<h3>Packet type decode</h3>
Vorbis I uses four packet types. The first three packet types mark each
of the three Vorbis headers described above. The fourth packet type
marks an audio packet. All others packet types are reserved; packets
marked with a reserved flag type should be ignored.<p>
Following the three header packets, all packets in a Vorbis I stream
are audio. The first step of audio packet decode is to read and
verify the packet type; <em>a non-audio packet when audio is expected
indicates stream corruption or a non-compliant stream. The decoder
must ignore the packet and not attempt decoding it to audio</em>.
<h3>Mode decode</h3>
Vorbis allows an encoder to set up multiple, numbered packet 'modes',
as described earlier, all of which may be used in a given Vorbis
stream. The mode is encoded as an integer used as a direct offset into
the mode instance index. <p>
<a name=window>
<h3>Window shape decode [long windows only]</h3></a>
Vorbis frames may be one of two PCM sample sizes specified during
codec setup. In Vorbis I, legal frame sizes are powers of two from 64
to 8192 samples. Aside from coupling, Vorbis handles channels as
independent vectors and these frame sizes are in samples per channel.<p>
Vorbis uses an overlapping transform, namely the MDCT, to blend one
frame into the next, avoiding most inter-frame block boundary
artifacts. The MDCT output of one frame is windowed according to MDCT
requirements, overlapped 50% with the output of the previous frame and
added. The window shape assures seamless reconstruction. <p>
This is easy to visualize in the case of equal sized-windows:<p>
<img src="window1.png"><p>
And slightly more complex in the case of overlapping unequal sized
windows:<p>
<img src="window2.png"><p>
In the unequal-sized window case, the window shape of the long window
must be modified for seamless lapping as above. It is possible to
correctly infer window shape to be applied to the current window from
knowing the sizes of the current, previous and next window. It is
legal for a decoder to use this method; However, in the case of a long
window (short windows require no modification), Vorbis also codes two
flag bits to specify pre- and post- window shape. Although not
strictly necessary for function, this minor redundancy allows a packet
to be fully decoded to the point of lapping entirely independently of
any other packet, allowing easier abstraction of decode layers as well
as allowing a greater level of easy parallelism in encode and
decode.<p>
A description of valid window functions for use with an inverse MDCT
can be found in the paper <a
href="http://www.iocon.com/resource/docs/ps/eusipco_corrected.ps">_The
use of multirate filter banks for coding of high quality digital
audio_</a>, by T. Sporer, K. Brandenburg and B. Edler. Vorbis windows
all use the slope function y=sin(2PI*sin^2(x/n)).<p>
<h3>floor decode</h3>
Each floor is encoded/decoded in channel order, however each floor
belongs to a 'submap' that specifies which floor configuration to
use. All floors are decoded before residue decode begins.<p>
<h3>residue decode</h3>
Although the number of residue vectors equals the number of channels,
channel coupling may mean that the raw residue vectors extracted
during decode do not map directly to specific channels. When channel
coupling is in use, some vectors will correspond to coupled magnitude
or angle. The coupling relationships are described in the codec setup
and may differ from frame to frame, due to different mode numbers.<p>
Vorbis codes residue vectors in groups by submap; the coding is done
in submap order from submap 0 through n-1. This differs from floors
which are coded using a configuration provided by submap number, but
are coded individually in channel order.<p>
<h3>inverse channel coupling</h3>
A detailed discussion of stereo in the Vorbis codec can be found in
the document <a href="stereo.html">_Stereo Channel Coupling in the
Vorbis CODEC_</a>. Vorbis is not limited to only stereo coupling, but
the stereo document also gives a good overview of the generic coupling
mechanism.<p>
Vorbis coupling applies to pairs of reside vectors at a time;
decoupling is done in-place a pair at a time in the order and using
the vectors specified in the current mapping configuration. The
decoupling operation is the same for all pairs, converting square
polar representation (where one vector is magnitude and the second
angle) back to Cartesian representation. <p>
After decoupling, in order, each pair of vectors on the coupling list
in, the resulting residue vector represents the fine spectral detail
of each output channel.<p>
<h3>generate floor curve</h3>
The decoder may choose to generate the floor curve at any appropriate
time. It is reasonable to generate the output curve when the floor
data is decoded from the raw packet, or it can be generated after
inverse coupling and applied to the spectral residue directly,
combining generation and the dot product into one step and eliminating
some working space.<p>
Both floor 0 and floor 1 generate a linear-range, linear-domain output
vector to be multiplied (dot product) by the linear-range,
linear-domain spectral residue.<p>
<h3>compute floor/residue dot product</h3>
This step is straightforward; for each output channel, the decoder
multiplies the floor curve and residue vectors element by element,
producing the finished audio spectrum of each channel.<p>
One point is worth mentioning about this dot product; a common mistake
in a fixed point implementation might be to assume that a 32 bit
fixed-point representation for floor and residue and direct
multiplication of the vectors is sufficient for acceptable spectral
depth in all cases because it happens to mostly work with the current
Xiph.Org reference encoder. <p>
However, floor vector values can span ~140dB (~24 bits unsigned), and
the audio spectrum vector should represent a minimum of 120dB (~21
bits with sign), even when output is to a 16 bit PCM device. For the
residue vector to represent full scale if the floor is nailed to
-140dB, it must be able to span 0 to +140dB. For the residue vector
to reach full scale if the floor is nailed at 0dB, it must be able to
represent -140dB to +0dB. Thus, in order to handle full range
dynamics, a residue vector may span -140dB to +140dB entirely within
spec. A 280dB range is approximately 48 bits with sign; thus the
residue vector must be able to represent a 48 bit range and the dot
product must be able to handle an effective 48 bit times 24 bit
multiplication. This range may be achieved using large (64 bit or
larger) integers, or implementing a movable binary point
representation.<p>
<h3>inverse monolithic transform (MDCT)</h3>
The audio spectrum is converted back into time domain PCM audio via an
inverse Modified Discrete Cosine Transform (MDCT). A detailed
description of the MDCT is available in the paper <a
href="http://www.iocon.com/resource/docs/ps/eusipco_corrected.ps">_The
use of multirate filter banks for coding of high quality digital
audio_</a>, by T. Sporer, K. Brandenburg and B. Edler.<p>
Note that the PCM produced directly from the MDCT is not yet finished
audio; it must be lapped with surrounding frames using an appropriate
window (such as the Vorbis window) before the MDCT can be considered
orthogonal.<p>
<h3>overlap/add data</h3>
Windowed MDCT output is overlapped and added with the right hand data
of the previous window such that the 3/4 point of the previous window
is aligned with the 1/4 point of the current window (as illustrated in
the window overlap diagram). At this point, the audio data between the
center of the previous frame and the center of the current frame is
now finished and ready to be returned. <p>
<h3>cache right hand data</h3>
The decoder must cache the right hand portion of the current frame to
be lapped with the left hand portion of the next frame.
<h3>return finished audio data</h3>
The overlapped portion produced from overlapping the previous and
current frame data is finished data to be returned by the decoder.
This data spans from the center of the previous window to the center
of the current window. In the case of same-sized windows, the amount
of data to return is one-half block consisting of and only of the
overlapped portions. When overlapping a short and long window, much of
the returned range is not actually overlap. This does not damage
transform orthogonality. Pay attention however to returning the
correct data range; the amount of data to be returned is:<p>
<tt>window_blocksize(previous_window)/4+window_blocksize(current_window)/4</tt>
from the center of the previous window to the center of the current
window.<p>
Data is not returned from the first frame; it must be used to 'prime'
the decode engine. The encoder accounts for this priming when
calculating PCM offsets; after the first frame, the proper PCM output
offset is '0' (as no data has been returned yet).<p>
<hr>
<a href="http://www.xiph.org/">
<img src="white-xifish.png" align=left border=0>
</a>
<font size=-2 color=#505050>
Ogg is a <a href="http://www.xiph.org">Xiph.org Foundation</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="http://www.xiph.org/about.html">About
the Xiph.org Foundation</a> for details.
<p>
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, the Xiph.org Foundation and
the Ogg project (xiph.org) reserve the right to set the Ogg Vorbis
specification and certify specification compliance.<p>
Xiph.org's Vorbis software CODEC implementation is distributed under a
BSD-like license. This does not restrict third parties from
distributing independent implementations of Vorbis software under
other licenses.<p>
Ogg, Vorbis, Xiph.org Foundation and their logos are trademarks (tm)
of the <a href="http://www.xiph.org/">Xiph.org Foundation</a>. These
pages are copyright (C) 1994-2002 Xiph.org Foundation. All rights
reserved.<p>
</body>
etc/Library/OggVobisSDK/doc/vorbis/vorbis-spec-ref.html
+547
View File
@@ -0,0 +1,547 @@
<HTML><HEAD><TITLE>xiph.org: Ogg Vorbis documentation</TITLE>
<BODY bgcolor="#ffffff" text="#202020" link="#006666" vlink="#000000">
<nobr><img src="white-ogg.png"><img src="vorbisword2.png"></nobr><p>
<h1><font color=#000070>
Ogg Vorbis I format specification: codec setup and packet decode
</font></h1>
<em>Last update to this document: July 18, 2002</em><br>
<h1>Overview</h1>
This document serves as the top-level reference document for the
bit-by-bit decode specification of Vorbis I. This document assumes a
high-level understanding of the Vorbis decode process, which is
provided in the document <a href="vorbis-spec-intro.html">Ogg Vorbis I
format specification: introduction and description</a>. <a
href="vorbis-spec-bitpack.html">Ogg Vorbis I format specification:
bitpacking convention</a> covers reading and writing bit fields from
and to bitstream packets.<p>
<h1>Header decode and decode setup</h1>
A Vorbis bitstream begins with three header packets. The header
packets are, in order, the identification header, the comments header,
and the setup header. All are required for decode compliance. An
end-of-packet condition during decoding the first or third header
packet renders the stream undecodable. End-of-packet decoding the
comment header is a non-fatal error condition.<p>
<h2>Common header decode</h2>
Each header packet begins with the same header fields
<pre>
1) [packet_type] : 8 bit value
2) 0x76, 0x6f, 0x72, 0x62, 0x69, 0x73: the characters 'v','o','r','b','i','s' as six octets
</pre>
Decode continues according to packet type; the identification header
is type 1, the comment header type 3 and the setup header type 5
(these types are all odd as a packet with a leading single bit of '0'
is an audio packet). The packets must occur in the order of
identification, comment, setup.
<h2>Identification Header</h2>
The identification header is a short header of only a few fields used
to declare the stream definitively as Vorbis, and provide a few externally
relevant pieces of information about the audio stream. The
identification header is coded as follows:<p>
<pre>
1) [vorbis_version] = read 32 bits as unsigned integer
2) [audio_channels] = read 8 bit integer as unsigned
3) [audio_sample_rate] = read 32 bits as unsigned integer
4) [bitrate_maximum] = read 32 bits as signed integer
5) [bitrate_nominal] = read 32 bits as signed integer
6) [bitrate_lower] = read 32 bits as signed integer
7) [blocksize_0] = 2 exponent (read 4 bits as unsigned integer)
8) [blocksize_1] = 2 exponent (read 4 bits as unsigned integer)
9) [framing_flag] = read one bit
</pre>
<tt>[vorbis_version]</tt> is to read '0' in order to be compatible
with this document. Both <tt>[audio_channels]</tt> and
<tt>[audio_rate]</tt> must read greater than zero. Allowed final
blocksize values are 64, 128, 256, 512, 1024, 2048, 4096 and 8192 in
Vorbis I. <tt>[blocksize_0]</tt> must be less than or equal to
<tt>[blocksize_1]</tt>. The framing bit must be nonzero. Failure to
meet any of these conditions renders a stream undecodable.<p>
The bitrate fields above are used only as hints. The nominal bitrate
field especially may be considerably off in purely VBR streams. The
fields are meaningful only when greater than zero.<p>
<ul><li>All three fields set to the same value implies a fixed rate, or tightly bounded, nearly fixed-rate bitstream
<li>Only nominal set implies a VBR or ABR stream that averages the nominal bitrate
<li>Upper and or lower set implies a VBR bitstream that obeys the bitrate limits
<li>None set indicates the encoder does not care to speculate.
</ul>
<h2>Comment Header</h2>
Comment header decode and data specification is covered in <a
href="v-comment.html">Ogg Vorbis I format specification: comment field
and header specification</a>.
<h2>Setup Header</h2>
Vorbis codec setup is configurable to an extreme degree:<p>
<img src="components.png"><p>
The setup header contains the bulk of the codec setup information
needed for decode. The setup header contains, in order, the lists of
codebook configurations, time-domain transform configurations
(placeholders in Vorbis I), floor configurations, residue
configurations, channel mapping configurations and mode
configurations. It finishes with a framing bit of '1'. Header decode
proceeds in the following order:<p>
<h3>codebooks</h3>
<ol>
<li><tt>[vorbis_codebook_count]</tt> = read eight bits as unsigned integer and add one
<li>Decode <tt>[vorbis_codebook_count]</tt> codebooks in order as defined
in <a href="vorbis-spec-codebook.html">the codebook specification
document</a>. Save each configuration, in order, in an array of
codebook configurations <tt>[vorbis_codebook_configurations]</tt>.
</ol>
<h3>time domain transforms</h3>
These hooks are placeholders in Vorbis I. Nevertheless, the
configuration placeholder values must be read to maintain bitstream
sync.<p>
<ol>
<li><tt>[vorbis_time_count]</tt> = read 6 bits as unsigned integer and add one
<li>read <tt>[vorbis_time_count]</tt> 16 bit values; each value should be zero. If any other values is nonzero, this is an error condition and the stream is undecodable.
</ol>
<h3>floors</h3>
Vorbis uses two floor types; header decode is handed to the decode
abstraction of the appropriate type.
<ol>
<li><tt>[vorbis_floor_count]</tt> = read 6 bits as unsigned integer and add one
<li>For each of <tt>[vorbis_floor_count]</tt> floor numbers:
<ol>
<li>read the floor type; vector <tt>[vorbis_floor_types]</tt> element <tt>[i]</tt> = read 16 bits as unsigned integer
<li>If the floor type is zero, decode the floor configuration as defined in <a href="vorbis-spec-floor0.html">the floor type 0 specification document</a>; save this configuration in slot <tt>[i]</tt> of the floor configuration array <tt>[vorbis_floor_configurations]</tt>.
<li>If the floor type is one, decode the floor configuration as defined in <a href="vorbis-spec-floor1.html">the floor type 1 specification document</a>; save this configuration in slot <tt>[i]</tt> of the floor configuration array <tt>[vorbis_floor_configurations]</tt>.
<li>If the the floor type is greater than one, this stream is undecodable; ERROR CONDITION
</ol>
</ol>
<h3>residues</h3>
Vorbis uses three residue types; header decode of each type is identical.
<ol>
<li><tt>[vorbis_residue_count]</tt> = read 6 bits as unsigned integer and add one
<li>For each of <tt>[vorbis_residue_count]</tt> residue numbers:
<ol>
<li>read the residue type; vector <tt>[vorbis_residue_types]</tt> element <tt>[i]</tt> = read 16 bits as unsigned integer
<li>If the residue type is zero, one or two, decode the residue configuration as defined in <a href="vorbis-spec-res.html">the residue specification document</a>; save this configuration in slot <tt>[i]</tt> of the residue configuration array <tt>[vorbis_residue_configurations]</tt>.
<li>If the the residue type is greater than two, this stream is undecodable; ERROR CONDITION
</ol>
</ol>
<h3>mappings</h3>
Mappings are used to set up specific pipelines for encoding
multichannel audio with varying channel mapping applications. Vorbis I
uses a single mapping type (0), with implicit PCM channel mappings.<p>
<ol>
<li><tt>[vorbis_mapping_count]</tt> = read 6 bits as unsigned integer and add one<p>
<li>For each <tt>[i]</tt> of <tt>[vorbis_mapping_count]</tt> mapping numbers:<p>
<ol>
<li>read the mapping type: 16 bits as unsigned integer. There's no reason to save the mapping type in Vorbis I.<p>
<li>If the mapping type is nonzero, the stream is undecodable<p>
<li>If the mapping type is zero:<p>
<ol> <li>read 1 bit as a boolean flag<p>
<ol><li>if set, <tt>[vorbis_mapping_submaps]</tt> = read 4 bits as unsigned integer and add one<p>
<li>if unset, <tt>[vorbis_mapping_submaps]</tt> = 1<p>
</ol>
<li>read 1 bit as a boolean flag; if set, square polar channel mapping is in use:<p>
<ol><li><tt>[vorbis_mapping_coupling_steps]</tt>= read 8 bits as unsigned integer and add one<p>
<li>for <tt>[j]</tt> each of <tt>[vorbis_mapping_coupling_steps]</tt> steps:<p>
<ol>
<li>vector <tt>[vorbis_mapping_magnitude]</tt> element <tt>[j]</tt>= read <a href="helper.html#ilog">ilog</a>([audio_channels]) bits as unsigned integer<p>
<li>vector <tt>[vorbis_mapping_angle]</tt> element <tt>[j]</tt>= read <a href="helper.html#ilog">ilog</a>([audio_channels]) bits as unsigned integer<p>
<li>the numbers read in the above two steps are channel numbers representing the channel to treat as magnitude and the channel to treat as angle, respectively. If any of angle channel equals magnitude channel, magnitude channel is greater than <tt>[audio_channels]</tt>-1, or angle channel is greater than <tt>[audio_channels]</tt>-1, the stream is undecodable.<p>
</ol>
</ol>
<li>read 2 bits (reserved field); if the value is nonzero, the stream is undecodable<p>
<li>if <tt>[vorbis_mapping_submaps]</tt> is greater than one, we read channel multiplex settings. For each <tt>[j]</tt> of <tt>[audio_channels]</tt> channels:<p>
<ol><li>vector <tt>[vorbis_mapping_mux]</tt> element <tt>[j]</tt> = read 4 bits as unsigned integer<p>
<li>if the value is greater than the highest numbered submap, this in an error condition rendering the stream undecodable<p>
</ol>
<li>for each submap <tt>[j]</tt> of <tt>[vorbis_mapping_submaps]</tt> submaps, read the floor and residue numbers for use in decoding that submap:
<ol><li>read and discard 8 bits (the unused time configuration placeholder)<p>
<li>read 8 bits as unsigned integer for the floor number; save in vector <tt>[vorbis_mapping_submap_floor]</tt> element <tt>[j]</tt><p>
<li>verify the floor number is not greater than the highest number floor configured for the bitstream. If it is, the bitstream is undecodable<p>
<li>read 8 bits as unsigned integer for the residue number; save in vector <tt>[vorbis_mapping_submap_residue]</tt> element <tt>[j]</tt><p>
<li>verify the residue number is not greater than the highest number residue configured for the bitstream. If it is, the bitstream is undecodable<p>
</ol>
<li>save this mapping configuration in slot <tt>[i]</tt> of the mapping configuration array <tt>[vorbis_mapping_configurations]</tt>.
</ol>
</ol>
</ol>
<h3>modes</h3>
<ol>
<li><tt>[vorbis_mode_count]</tt> = read 6 bits as unsigned integer and add one<p.
<li>For each of <tt>[vorbis_mode_count]</tt> mode numbers:<p>
<ol>
<li><tt>[vorbis_mode_blockflag]</tt> = read 1 bit<p>
<li><tt>[vorbis_mode_windowtype]</tt> = read 16 bits as unsigned integer<p>
<li><tt>[vorbis_mode_transformtype]</tt> = read 16 bits as unsigned integer<p>
<li><tt>[vorbis_mode_mapping]</tt> = read 8 bits as unsigned integer<p>
<li>verify ranges; zero is the only legal value in Vorbis I for <tt>[vorbis_mode_windowtype]</tt> and <tt>[vorbis_mode_transformtype]</tt>. <tt>[vorbis_mode_mapping]</tt> must not be greater than the highest number mapping in use. Any illegal values render the stream undecodable.<p>
<li>save this mode configuration in slot <tt>[i]</tt> of the mode configuration array <tt>[vorbis_mode_configurations]</tt>.<p>
</ol>
<li>read 1 bit as a framing flag. If unset, a framing error occurred and the stream is not decodable.
</ol><p>
After reading mode descriptions, setup header decode is complete.<p>
<h1>Audio packet decode and synthesis</h1>
Following the three header packets, all packets in a Vorbis I stream
are audio. The first step of audio packet decode is to read and
verify the packet type; <em>a non-audio packet when audio is expected
indicates stream corruption or a non-compliant stream. The decoder
must ignore the packet and not attempt decoding it to audio</em>.
<h2>packet type, mode and window decode</h2>
<ol>
<li>read 1 bit <tt>[packet_type]</tt>; check that packet type is 0 (audio)<p>
<li>read <a href="helper.html#ilog">ilog</a>([vorbis_mode_count]-1) bits <tt>[mode_number]</tt><p>
<li>decode blocksize <tt>[n]</tt> is equal to <tt>[blocksize_0]</tt> if <tt>[vorbis_mode_blockflag]</tt> is 0, else <tt>[n]</tt> is equal to <tt>[blocksize_1]</tt><p.
<li>perform window selection and setup; this window is used later by the inverse MDCT:<p>
<ol><li>if this is a long window (the <tt>[vorbis_mode_blockflag]</tt> flag of this mode is set):<p>
<ol>
<li>read 1 bit for <tt>[previous_window_flag]</tt><p>
<li>read 1 bit for <tt>[next_window_flag]</tt><p>
<li>if <tt>[previous_window_flag]</tt> is not set, the left half
of the window will be a hybrid window for lapping with a
short block. See <a href="vorbis-spec-intro.html#window">the
'Window' subheading of the specification introduction
document</a> for an illustration of overlapping dissimilar
windows. Else, the left half window will have normal long
shape.<p>
<li>if <tt>[next_window_flag]</tt> is not set, the right half of
the window will be a hybrid window for lapping with a short
block. See <a href="vorbis-spec-intro.html#window">the
'Window' subheading of the specification introduction
document</a> for an illustration of overlapping dissimilar
windows. Else, the left right window will have normal long
shape.<p>
</ol>
<li> if this is a short window, the window is always the same
short-window shape.<p>
</ol>
</ol>
Vorbis windows all use the slope function y=sin(2*PI*sin^2(x/n)),
but dissimilar lapping requirements can affect overall shape. Window
generation proceeds as follows:<p>
<ol>
<li> <tt>[window_center]</tt> = <tt>[n]</tt> / 2
<li> <tt>[left_window_start]</tt>
<li> if (<tt>[vorbis_mode_blockflag]</tt> is set and <tt>[previous_window_flag]</tt> is not set) then
<ol><li><tt>[left_window_start]</tt> = <tt>[n]</tt>/4 - <tt>[blocksize_0]</tt>/4
<li><tt>[left_window_end]</tt> = <tt>[n]</tt>/4 + <tt>[blocksize_0]</tt>/4
<li><tt>[left_n]</tt> = <tt>[blocksize_0]</tt>/2
</ol>
else
<ol><li><tt>[left_window_start]</tt> = 0
<li><tt>[left_window_end]</tt> = <tt>[window_center]</tt>
<li><tt>[left_n]</tt> = <tt>[n]</tt>/2
</ol>
<li> if (<tt>[vorbis_mode_blockflag]</tt> is set and <tt>[next_window_flag]</tt> is not set) then
<ol><li><tt>[right_window_start]</tt> = <tt>[n]*3</tt>/4 - <tt>[blocksize_0]</tt>/4
<li><tt>[right_window_end]</tt> = <tt>[n]*3</tt>/4 + <tt>[blocksize_0]</tt>/4
<li><tt>[right_n]</tt> = <tt>[blocksize_0]</tt>/2
</ol>
else
<ol><li><tt>[right_window_start]</tt> = <tt>[window_center]</tt>
<li><tt>[right_window_end]</tt> = <tt>[n]</tt>
<li><tt>[right_n]</tt> = <tt>[n]</tt>/2
</ol>
<li> window from range 0 ... <tt>[left_window_start]</tt>-1 inclusive is zero
<li> for <tt>[i]</tt> in range <tt>[left_window_start]</tt> ... <tt>[left_window_end]</tt>-1, window(<tt>[i]</tt>) = sin(2*PI*sin^2((<tt>[i]</tt>-<tt>[left_window_start]</tt>+.5)/<tt>[left_n]</tt>*PI/2))
<li> window from range <tt>[left_window_end]</tt> ... <tt>[right_window_start]</tt>-1 inclusive is one
<li> for <tt>[i]</tt> in range <tt>[right_window_start]</tt> ... <tt>[right_window_end]</tt>-1, window(<tt>[i]</tt>) = sin(2*PI*sin^2((<tt>[i]</tt>-<tt>[right_window_start]</tt>+.5)/<tt>[right_n]</tt>*PI/2.+PI/2.))
<li> window from range <tt>[rigth_window_start]</tt> ... <tt>[n]</tt>-1 is zero
</ol><p>
An end-of-packet condition up to this point should be considered an
error that discards this packet from the stream. An end of packet
condition past this point is to be considered a possible nominal
occurrence.<p>
<h2>floor curve decode</h2>
From this point on, we assume out decode context is using mode number
<tt>[mode_number]</tt> from configuration array
<tt>[vorbis_mode_configurations]</tt> and the map number
<tt>[vorbis_mode_mapping]</tt> (specified by the current mode) taken
from the mapping configuration array
<tt>[vorbis_mapping_configurations]</tt>.<p>
Floor curves are decoded one-by-one in channel order.<p>
For each floor <tt>[i]</tt> of <tt>[audio_channels]</tt>
<ol><li><tt>[submap_number]</tt> = element <tt>[i]</tt> of vector [vorbis_mapping_mux] <p>
<li><tt>[floor_number]</tt> = element <tt>[submap_number]</tt> of vector [vorbis_submap_floor]<p>
<li>if the floor type of this floor (vector <tt>[vorbis_floor_types]</tt> element <tt>[floor_number]</tt>) is zero then decode the floor for channel <tt>[i]</tt> according to the <a href="vorbis-spec-floor0.html#decode">floor 0 decode algorithm</a><p>
<li>if the type of this floor is one then decode the floor for channel <tt>[i]</tt> according to the <a href="vorbis-spec-floor1.html#decode">floor 1 decode algorithm</a><p>
<li>save the needed decoded floor information for channel for later synthesis<p>
<li>if the decoded floor returned 'unused', set vector <tt>[no_residue]</tt> element <tt>[i]</tt> to true, else set vector <tt>[no_residue]</tt> element <tt>[i]</tt> to false<p>
</ol>
An end-of-packet condition during floor decode shall result in packet
decode zeroing all channel output vectors and skipping to the
add/overlap output stage.<p>
<h2>nonzero vector propagate</h2>
A possible result of floor decode is that a specific vector is marked
'unused' which indicates that that final output vector is all-zero
values (and the floor is zero). The residue for that vector is not
coded in the stream, save for one complication. If some vectors are
used and some are not, channel coupling could result in mixing a
zeroed and nonzeroed vector to produce two nonzeroed vectors.<p>
for each <tt>[i]</tt> from 0 ... <tt>[vorbis_mapping_coupling_steps]</tt>-1
<ol><li>if either <tt>[no_residue]</tt> entry for channel
(<tt>[vorbis_mapping_magnitude]</tt> element <tt>[i]</tt>) or (channel
<tt>[vorbis_mapping_angle]</tt> element <tt>[i]</tt>) are set to false, then both
must be set to false. Note that an 'unused' floor has no decoded floor
information; it is important that this is remembered at floor curve
synthesis time.
</ol>
<h2>residue decode</h2>
Unlike floors, which are decoded in channel order, the residue vectors
are decoded in submap order.<p>
for each submap <tt>[i]</tt> in order from 0 ... <tt>[vorbis_mapping_submaps]</tt>-1<p>
<ol><li><tt>[ch]</tt> = 0<p>
<li>for each channel <tt>[j]</tt> in order from 0 ... <tt>[audio_channels]</tt><p>
<ol><li>if channel <tt>[j]</tt> is in submap <tt>[i]</tt> (vector <tt>[vorbis_mapping_mux]</tt> element <tt>[j]</tt> is equal to <tt>[i]</tt>)<p>
<ol><li>if vector <tt>[no_residue]</tt> element <tt>[j]</tt> is true<p>
<ol><li>vector <tt>[do_not_decode_flag]</tt> element <tt>[channels_in_bundle]</tt> is set<p>
</ol>else<ol><li>vector <tt>[do_not_decode_flag]</tt> element <tt>[channels_in_bundle]</tt> is unset<p>
</ol>
<li>increment <tt>[ch]</tt><p>
</ol>
</ol>
<li><tt>[residue_number]</tt> = vector <tt>[vorbis_mapping_submap_residue]</tt> element <tt>[i]</tt><p>
<li><tt>[residue_type]</tt> = vector <tt>[vorbis_residue_types]</tt> element <tt>[residue_number]</tt><p>
<li>decode <tt>[ch]</tt> vectors using residue <tt>[residue_number]</tt>, according to type <tt>[residue_type]</tt>, also passing vector <tt>[do_not_decode_flag]</tt> to indicate which vectors in the bundle should not be decoded. Correct per-vector decode length is <tt>[n]</tt>/2.<p>
<li><tt>[ch]</tt> = 0<p>
<li>for each channel <tt>[j]</tt> in order from 0 ... <tt>[audio_channels]</tt><p>
<ol><li>if channel <tt>[j]</tt> is in submap <tt>[i]</tt> (vector <tt>[vorbis_mapping_mux]</tt> element <tt>[j]</tt> is equal to <tt>[i]</tt>)<p>
<ol><li>residue vector for channel <tt>[j]</tt> is set to decoded residue vector <tt>[ch]</tt><p>
<li>increment <tt>[ch]</tt>
</ol>
</ol>
</ol>
<h2>inverse coupling</h2>
for each <tt>[i]</tt> from <tt>[vorbis_mapping_coupling_steps]</tt>-1 descending to 0
<ol>
<li><tt>[magnitude_vector]</tt> = the residue vector for channel
(vector <tt>[vorbis_mapping_magnitude]</tt> element <tt>[i]</tt>)
<li><tt>[angle_vector]</tt> = the residue vector for channel (vector
<tt>[vorbis_mapping_angle]</tt> element <tt>[i]</tt>)
<li>for each scalar value <tt>[M]</tt> in vector <tt>[magnitude_vector]</tt> and the corresponding scalar value <tt>[A]</tt> in vector <tt>[angle_vector]</tt>:
<ol><li>if (<tt>[M]</tt> is greater than zero)
<ol><li>if (<tt>[A]</tt> is greater than zero)
<ol>
<li><tt>[new_M]</tt> = <tt>[M]</tt>
<li><tt>[new_A]</tt> = <tt>[M]</tt>-<tt>[A]</tt>
</ol>
else
<ol>
<li><tt>[new_A]</tt> = <tt>[M]</tt>
<li><tt>[new_M]</tt> = <tt>[M]</tt>+<tt>[A]</tt>
</ol>
</ol>
else
<ol><li>if (<tt>[A]</tt> is greater than zero)
<ol>
<li><tt>[new_M]</tt> = <tt>[M]</tt>
<li><tt>[new_A]</tt> = <tt>[M]</tt>+<tt>[A]</tt>
</ol>
else
<ol>
<li><tt>[new_A]</tt> = <tt>[M]</tt>
<li><tt>[new_M]</tt> = <tt>[M]</tt>-<tt>[A]</tt>
</ol>
</ol><p>
<li>set scalar value <tt>[M]</tt> in vector <tt>[magnitude_vector]</tt> to <tt>[new_M]</tt>
<li>set scalar value <tt>[A]</tt> in vector <tt>[angle_vector]</tt> to <tt>[new_A]</tt>
</ol>
</ol>
<h2>dot product</h2>
For each channel, synthesize the floor curve from the decoded floor
information, according to packet type. Note that the vector synthesis
length for floor computation is <tt>[n]</tt>/2.<p>
For each channel, multiply each element of the floor curve by each
element of that channel's residue vector. The result is the dot
product the floor and residue vectors for each channel; the produced
vectors are the length <tt>[n]</tt>/2 audio spectrum for each
channel.<p>
One point is worth mentioning about this dot product; a common mistake
in a fixed point implementation might be to assume that a 32 bit
fixed-point representation for floor and residue and direct
multiplication of the vectors is sufficient for acceptable spectral
depth in all cases because it happens to mostly work with the current
Xiph.Org reference encoder. <p>
However, floor vector values can span ~140dB (~24 bits unsigned), and
the audio spectrum vector should represent a minimum of 120dB (~21
bits with sign), even when output is to a 16 bit PCM device. For the
residue vector to represent full scale if the floor is nailed to
-140dB, it must be able to span 0 to +140dB. For the residue vector
to reach full scale if the floor is nailed at 0dB, it must be able to
represent -140dB to +0dB. Thus, in order to handle full range
dynamics, a residue vector may span -140dB to +140dB entirely within
spec. A 280dB range is approximately 48 bits with sign; thus the
residue vector must be able to represent a 48 bit range and the dot
product must be able to handle an effective 48 bit times 24 bit
multiplication. This range may be achieved using large (64 bit or
larger) integers, or implementing a movable binary point
representation.<p>
<h2>inverse MDCT</h2>
Convert the audio spectrum vector of each channel back into time
domain PCM audio via an inverse Modified Discrete Cosine Transform
(MDCT). A detailed description of the MDCT is available in the paper
<a
href="http://www.iocon.com/resource/docs/ps/eusipco_corrected.ps">_The
use of multirate filter banks for coding of high quality digital
audio_</a>, by T. Sporer, K. Brandenburg and B. Edler. The window
function used for the MDCT is the window determined earlier.<p>
<h2>overlap_add</h2>
Windowed MDCT output is overlapped and added with the right hand data
of the previous window such that the 3/4 point of the previous window
is aligned with the 1/4 point of the current window (as illustrated in
<a href="vorbis-spec-intro.html#window">the 'Window' portion of the
specification introduction document</a>. The overlapped portion
produced from overlapping the previous and current frame data is
finished data to be returned by the decoder. This data spans from the
center of the previous window to the center of the current window. In
the case of same-sized windows, the amount of data to return is
one-half block consisting of and only of the overlapped portions. When
overlapping a short and long window, much of the returned range is not
actually overlap. This does not damage transform orthogonality. Pay
attention however to returning the correct data range; the amount of
data to be returned is:<p>
<tt>window_blocksize(previous_window)/4+window_blocksize(current_window)/4</tt>
from the center (element windowsize/2) of the previous window to the
center (element windowsize/2-1, inclusive) of the current window.<p>
Data is not returned from the first frame; it must be used to 'prime'
the decode engine. The encoder accounts for this priming when
calculating PCM offsets; after the first frame, the proper PCM output
offset is '0' (as no data has been returned yet).<p>
<h2>output channel order</h2>
Vorbis I specifies only a channel mapping type 0. In mapping type 0,
channel mapping is implicitly defined as follows for standard audio
applications:<p>
<dl>
<dt>one channel:<dd> the stream is monophonic
<dt>two channels:<dd> the stream is stereo. channel order: left, right
<dt>three channels:<dd> the stream is a 1d-surround encoding. channel order: left, center, right
<dt>four channels:<dd> the stream is quadraphonic surround. channel order: front left, front right, rear left, rear right
<dt>five channels:<dd> the stream is five-channel surround. channel order: front left, front center, front right, rear left, rear right
<dt>six channels:<dd> the stream is 5,1 surround. channel order: front left, front center, front right, rear left, rear right, LFE
<dt>greater than six channels:<dd> channel use and order is defined by the application
</dl>
Applications using Vorbis for dedicated purposes may define channel
mapping as seen fit. Future channel mappings (such as three and four
channel <a href="http://www.ambisonic.net">Ambisonics</a>) will make
use of channel mappings other than mapping 0.<p>
<hr>
<a href="http://www.xiph.org/">
<img src="white-xifish.png" align=left border=0>
</a>
<font size=-2 color=#505050>
Ogg is a <a href="http://www.xiph.org">Xiph.org Foundation</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="http://www.xiph.org/about.html">About
the Xiph.org Foundation</a> for details.
<p>
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, the Xiph.org Foundation and
the Ogg project (xiph.org) reserve the right to set the Ogg Vorbis
specification and certify specification compliance.<p>
Xiph.org's Vorbis software CODEC implementation is distributed under a
BSD-like license. This does not restrict third parties from
distributing independent implementations of Vorbis software under
other licenses.<p>
Ogg, Vorbis, Xiph.org Foundation and their logos are trademarks (tm)
of the <a href="http://www.xiph.org/">Xiph.org Foundation</a>. These
pages are copyright (C) 1994-2002 Xiph.org Foundation. All rights
reserved.<p>
</body>
etc/Library/OggVobisSDK/doc/vorbis/vorbis-spec-res.html
+422
View File
@@ -0,0 +1,422 @@
<HTML><HEAD><TITLE>xiph.org: Ogg Vorbis documentation</TITLE>
<BODY bgcolor="#ffffff" text="#202020" link="#006666" vlink="#000000">
<nobr><img src="white-ogg.png"><img src="vorbisword2.png"></nobr><p>
<h1><font color=#000070>
Ogg Vorbis I format specification: residue setup and decode
</font></h1>
<em>Last update to this document: July 19, 2002</em><br>
<h1>Overview</h1>
A residue vector represents the fine detail of the audio spectrum of
one channel in an audio frame after the encoder subtracts the floor
curve and performs any channel coupling. A residue vector may
represent spectral lines, spectral magnitude, spectral phase or
hybrids as mixed by channel coupling. The exact semantic content of
the vector does not matter to the residue abstraction.<p>
Whatever the exact qualities, the Vorbis residue abstraction codes the
residue vectors into the bitstream packet, and then reconstructs the
vectors during decode. Vorbis makes use of three different encoding
variants (numbered 0, 1 and 2) of the same basic vector encoding
abstraction.<p>
<h1>Residue format</h1>
Reside format partitions each vector in the vector bundle into chunks,
classifies each chunk, encodes the chunk classifications and finally
encodes the chunks themselves using the the specific VQ arrangement
defined for each selected selected classification. The exact
interleaving and partitioning vary by residue encoding number, however
the high-level process used to classify and encode the residue vector
is the same in all three variants.<p>
A set of coded residue vectors are all of the same length. High level
coding structure, ignoring for the moment exactly how a partition is
encoded and simply trusting that it is, is as follows:<p>
<ul>
<li>Each vector is partitioned into multiple equal sized chunks
according to configuration specified. If we have a vector size of
<i>n</i>, a partition size <i>residue_partition_size</i>, and a total
of <i>ch</i> residue vectors, the total number of partitioned chunks
coded is <i>n</i>/<i>residue_partition_size</i>*<i>ch</i>. It is
important to note that the integer division truncates. In the below
example, we assume an example <i>residue_partition_size</i> of 8.<p>
<li>Each partition in each vector has a classification number that
specifies which of multiple configured VQ codebook setups are used to
decode that partition. The classification numbers of each partition
can be thought of as forming a vector in their own right, as in the
illustration below. Just as the residue vectors are coded in grouped
partitions to increase encoding efficiency, the classification vector
is also partitioned into chunks. The integer elements of each scalar
in a classification chunk are built into a single scalar that
represents the classification numbers in that chunk. In the below
example, the classification codeword encodes two classification
numbers.<p>
<li>The values in a residue vector may be encoded monolithically in a
single pass through the residue vector, but more often efficient
codebook design dictates that each vector is encoded as the additive
sum of several passes through the residue vector using more than one
VQ codebook. Thus, each residue value potentially accumulates values
from multiple decode passes. The classification value associated with
a partition is the same in each pass, thus the classification codeword
is coded only in the first pass.<p>
</ul>
<img src="residue-pack.png"><p>
<h2>residue 0</h2>
Residue 0 and 1 differ only in the way the values within a residue
partition are interleaved during partition encoding (visually treated
as a black box- or cyan box or brown box- in the above figure).<p>
Residue encoding 0 interleaves VQ encoding according to the
dimension of the codebook used to encode a partition in a specific
pass. The dimension of the codebook need not be the same in multiple
passes, however the partition size must be an even multiple of the
codebook dimension.<p>
As an example, assume a partition vector of size eight, to be encoded
by residue 0 using codebook sizes of 8, 4, 2 and 1:<p>
<pre>
original residue vector: [ 0 1 2 3 4 5 6 7 ]
codebook dimensions = 8 encoded as: [ 0 1 2 3 4 5 6 7 ]
codebook dimensions = 4 encoded as: [ 0 2 4 6 ], [ 1 3 5 7 ]
codebook dimensions = 2 encoded as: [ 0 4 ], [ 1 5 ], [ 2 6 ], [ 3 7 ]
codebook dimensions = 1 encoded as: [ 0 ], [ 1 ], [ 2 ], [ 3 ], [ 4 ], [ 5 ], [ 6 ], [ 7 ]
</pre>
It is worth mentioning at this point that no configurable value in the
residue coding setup is restricted to a power of two.<p>
<h2> residue 1 </h2>
Residue 1 does not interleave VQ encoding. It represents partition
vector scalars in order. As with residue 0, however, partition length
must be an integer multiple of the codebook dimension, although
dimension may vary from pass to pass.
As an example, assume a partition vector of size eight, to be encoded
by residue 0 using codebook sizes of 8, 4, 2 and 1:<p>
<pre>
original residue vector: [ 0 1 2 3 4 5 6 7 ]
codebook dimensions = 8 encoded as: [ 0 1 2 3 4 5 6 7 ]
codebook dimensions = 4 encoded as: [ 0 1 2 3 ], [ 4 5 6 7 ]
codebook dimensions = 2 encoded as: [ 0 1 ], [ 2 3 ], [ 4 5 ], [ 6 7 ]
codebook dimensions = 1 encoded as: [ 0 ], [ 1 ], [ 2 ], [ 3 ], [ 4 ], [ 5 ], [ 6 ], [ 7 ]
</pre>
<h2> residue 2 </h2>
Residue type two can be thought of as a variant of residue type 1.
Rather than encoding multiple passed-in vectors as in residue type 1,
the <i>ch</i> passed in vectors of length <i>n</i> are first
interleaved and flattened into a single vector of length
<i>ch</i>*<i>n</i>. Encoding then proceeds as in type 1. Decoding is
as in type 1 with decode interleave reversed. If operating on a single
vector to begin with, residue type 1 and type 2 are equivalent.<p>
<img src="residue2.png"><p>
<h1>Residue decode</h1>
<h2>header decode</h2>
Header decode for all three residue types is identical.<p>
<pre>
1) [residue_begin] = read 24 bits as unsigned integer
2) [residue_end] = read 24 bits as unsigned integer
3) [residue_partition_size] = read 24 bits as unsigned integer and add one
4) [residue_classifications] = read 6 bits as unsigned integer and add one
5) [residue_classbook] = read 8 bits as unsigned integer
</pre>
<tt>[residue_begin]</tt> and <tt>[residue_end]</tt> select the specific
sub-portion of each vector that is actually coded; it implements akin
to a bandpass where, for coding purposes, the vector effectively
begins at element <tt>[residue_begin]</tt> and ends at
<tt>[residue_end]</tt>. Preceding and following values in the unpacked
vectors are zeroed. Note that for residue type 2, these values as
well as <tt>[residue_partition_size]</tt>apply to the interleaved
vector, not the individual vectors before interleave.
<tt>[residue_partition_size]</tt> is as explained above,
<tt>[residue_classifications]</tt> is the number of possible
classification to which a partition can belong and
<tt>[residue_classbook]</tt> is the codebook number used to code
classification codewords. The number of dimensions in book
<tt>[residue_classbook]</tt> determines how many classification values
are grouped into a single classification codeword.<p>
Next we read a bitmap pattern that specifies which partition classes
code values in which passes.<p>
<pre>
1) iterate [i] over the range 0 ... [residue_classifications]-1 {
2) [high_bits] = 0
3) [low_bits] = read 3 bits as unsigned integer
4) [bitflag] = read one bit as boolean
5) if ( [bitflag] is set ) then [high_bits] = read five bits as unsigned integer
6) vector [residue_cascade] element [i] = [high_bits] * 8 + [low_bits]
}
7) done
</pre>
Finally, we read in a list of book numbers, each corresponding to
specific bit set in the cascade bitmap. We loop over the possible
codebook classifications and the maximum possible number of encoding
stages (8 in Vorbis I, as constrained by the elements of the cascade
bitmap being eight bits):<p>
<pre>
1) iterate [i] over the range 0 ... [residue_classifications]-1 {
2) iterate [j] over the range 0 ... 7 {
3) if ( vector [residue_cascade] element [i] bit [j] is set ) {
4) array [residue_books] element [i][j] = read 8 bits as unsigned integer
} else {
5) array [residue_books] element [i][j] = unused
}
}
}
6) done
</pre>
An end-of-packet condition at any point in header decode renders the
stream undecodable. In addition, any codebook number greater than the
maximum numbered codebook set up in this stream also renders the
stream undecodable.<p>
<h2>packet decode</h2>
Format 0 and 1 packet decode is identical except for specific
partition interleave. Format 2 packet decode can be built out of the
format 1 decode process. Thus we describe first the decode
infrastructure identical to all three formats.<p>
In addition to configuration information, the residue decode process
is passed the number of vectors in the submap bundle and a vector of
flags indicating if any of the vectors are not to be decoded. If the
passed in number of vectors is 3 and vector number 1 is marked 'do not
decode', decode skips vector 1 during the decode loop. However, even
'do not decode' vectors are allocated and zeroed.<p>
The following convenience values are conceptually useful to clarifying
the decode process:<p>
<pre>
1) [classvals_per_codeword] = [codebook_dimensions] value of codebook [residue_classbook]
2) [n_to_read] = [residue_end] - [residue-begin]
3) [partitions_to_read] = [n_to_read] / [residue_partition_size]
</pre>
Packet decode proceeds as follows, matching the description offered earlier in the document. We assume that the number of vectors being encoded, <tt>[ch]</tt> is provided by the higher level decoding process.<p>
<pre>
1) allocate and zero all vectors that will be returned.
2) iterate [pass] over the range 0 ... 7 {
3) [partition_count] = 0
4) if ([pass] is zero) {
5) iterate [j] over the range 0 .. [ch]-1 {
6) if vector [j] is not marked 'do not decode' {
7) [temp] = read from packet using codebook [residue_classbook] in scalar context
8) iterate [k] descending over the range [classvals_per_codeword]-1 ... 0 {
9) array [classifications] element [j],([partition_count]+[k]) =
[temp] integer modulo [residue_classifications]
10) [temp] = [temp] / [residue_classifications] using integer division
}
}
}
}
11) [classword_count] = 0
12) iterate [j] over the range 0 .. [ch]-1 {
13) if vector [j] is not marked 'do not decode' {
14) [vqclass] = array [classifications] element [j],([partition_count]+[classword_count])
15) [vqbook] = array [residue_books] element [vqclass],[pass]
16) if ([vqbook] is not 'unused') {
17) decode partition into output vector number [j], starting at scalar
offset [residue_begin]+[partition_count]*[residue_partition_size] using
codebook number [vqbook] in VQ context
}
}
}
18) increment [classword_count]
19) increment [partition_count]
20) if ([classword_count] is less than [classvals_per_codeword]) AND
([partition_count] is less than [partitions_to_read) then continue at step 11
21) if ([partition_count] is less than [partitions_to_read) then continue at step 4
}
22) done
</pre>
An end-of-packet condition during packet decode is to be considered a
nominal occurrence. Decode returns the result of vector decode up to
that point.<p>
<h2>format 0 specifics</h2>
Format zero decodes partitions exactly as described earlier in the
'Residue Format: residue 0' section. The following pseudocode
presents the same algorithm. Assume:<p>
<ul>
<li> <tt>[n]</tt> is the value in
<tt>[residue_partition_size]</tt>
<li><tt>[v]</tt> is the residue vector
<li><tt>[offset]</tt> is the beginning read offset in [v]
</ul>
<pre>
1) [step] = [n] / [codebook_dimensions]
2) iterate [i] over the range 0 ... [step]-1 {
3) vector [entry_temp] = read vector from packet using current codebook in VQ context
4) iterate [j] over the range 0 ... [codebook_dimensions]-1 {
5) vector [v] element ([offset]+[i]+[j]*[step]) =
vector [v] element ([offset]+[i]+[j]*[step]) +
vector [entry_temp] element [j]
}
}
6) done
</pre>
<p>
<h2>format 1 specifics</h2>
Format 1 decodes partitions exactly as described earlier in the
'Residue Format: residue 1' section. The following pseudocode
presents the same algorithm. Assume:<p>
<ul>
<li> <tt>[n]</tt> is the value in
<tt>[residue_partition_size]</tt>
<li><tt>[v]</tt> is the residue vector
<li><tt>[offset]</tt> is the beginning read offset in [v]
</ul>
<pre>
1) [i] = 0
2) vector [entry_temp] = read vector from packet using current codebook in VQ context
3) iterate [j] over the range 0 ... [codebook_dimensions]-1 {
5) vector [v] element ([offset]+[i]) =
vector [v] element ([offset]+[i]) +
vector [entry_temp] element [j]
6) increment [i]
}
4) if ( [i] is less than [n] ) continue at step 2
5) done
</pre>
<p>
<h2>format 2 specifics</h2>
Format 2 is reducible to format 1 through the following steps, performed in order: <p>
<ol>
<li>Assume format 2 is to decode <i>ch</i> vectors of length <i>n</i>.
<li>Decode, using format 1, a single vector <tt>[v]</tt>of length <i>ch</i>*<i>n</i>.
<li>Deinterleave this single vector <tt>[v]</tt> into <i>ch</i> independent vectors according to:<p>
<pre>
1) iterate [i] over the range 0 ... [n]-1 {
2) iterate [j] over the range 0 ... [ch]-1 {
3) output vector number [j] element [i] = vector [t] element ([i] * [ch] +[j])
}
}
4) done
</pre>
</ol>
<p>
Format 2 handles 'do not decode' vectors differently that residue 0 or
1; if all vectors are marked 'do not decode', no decode occurrs.
However, if at least one vector is to be decoded, all the vectors are
decoded.<p>
<hr>
<a href="http://www.xiph.org/">
<img src="white-xifish.png" align=left border=0>
</a>
<font size=-2 color=#505050>
Ogg is a <a href="http://www.xiph.org">Xiph.org Foundation</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="http://www.xiph.org/about.html">About
the Xiph.org Foundation</a> for details.
<p>
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, the Xiph.org Foundation and
the Ogg project (xiph.org) reserve the right to set the Ogg Vorbis
specification and certify specification compliance.<p>
Xiph.org's Vorbis software CODEC implementation is distributed under a
BSD-like license. This does not restrict third parties from
distributing independent implementations of Vorbis software under
other licenses.<p>
Ogg, Vorbis, Xiph.org Foundation and their logos are trademarks (tm)
of the <a href="http://www.xiph.org/">Xiph.org Foundation</a>. These
pages are copyright (C) 1994-2002 Xiph.org Foundation. All rights
reserved.<p>
</body>
etc/Library/OggVobisSDK/doc/vorbis/vorbis.html
+197
View File
@@ -0,0 +1,197 @@
<HTML><HEAD><TITLE>xiph.org: Ogg Vorbis documentation</TITLE>
<BODY bgcolor="#ffffff" text="#202020" link="#006666" vlink="#000000">
<nobr><img src="white-ogg.png"><img src="vorbisword2.png"></nobr><p>
<h1><font color=#000070>
Ogg Vorbis encoding format documentation
</font></h1>
<em>Last update to this document: July 2, 2002</em><br>
<em>Last update to Vorbis documentation: July 2, 2002</em><p>
<table><tr><td>
<img src=wait.png>
</td><td valign=center>
As of writing, not all the below document
links are live. They will be populated as we complete the
documents.
</td></tr></table>
<p>
<h2>Documents</h2>
<ul>
<li><a href="packet.html">Vorbis packet structure</a>
<li><a href="envelope.html">Temporal envelope shaping and blocksize</a>
<li><a href="mdct.html">Time domain segmentation and MDCT transform</a>
<li><a href="resolution.html">The resolution floor</a>
<li><a href="residuals.html">MDCT-domain fine structure</a><p>
<li><a href="probmodel.html">The Vorbis probability model</a>
<li><a href="bitpack.html">The Vorbis bitpacker</a><p>
<li><a href="oggstream.html">Ogg bitstream overview</a>
<li><a href="framing.html">Ogg logical bitstream and framing spec</a>
<li><a href="vorbis-stream.html">Vorbis packet->Ogg bitstream
mapping</a><p>
<li><a href="programming.html">Programming with libvorbis</a><p>
</ul>
<h2>Description</h2>
Ogg Vorbis is a general purpose compressed audio format
for high quality (44.1-48.0kHz, 16+ bit, polyphonic) audio and music
at moderate fixed and variable bitrates (40-80 kb/s/channel). This
places Vorbis in the same class as audio representations including
MPEG-1 audio layer 3, MPEG-4 audio (AAC and TwinVQ), and PAC.<p>
Vorbis is the first of a planned family of Ogg multimedia coding
formats being developed as part of the Xiph.org Foundation's Ogg multimedia
project. See <a href="http://www.xiph.org/">http://www.xiph.org/</a>
for more information.
<h2>Vorbis technical documents</h2>
A Vorbis encoder takes in overlapping (but contiguous) short-time
segments of audio data. The encoder analyzes the content of the audio
to determine an optimal compact representation; this phase of encoding
is known as <em>analysis</em>. For each short-time block of sound,
the encoder then packs an efficient representation of the signal, as
determined by analysis, into a raw packet much smaller than the size
required by the original signal; this phase is <em>coding</em>.
Lastly, in a streaming environment, the raw packets are then
structured into a continuous stream of octets; this last phase is
<em>streaming</em>. Note that the stream of octets is referred to both
as a 'byte-' and 'bit-'stream; the latter usage is acceptible as the
stream of octets is a physical representation of a true logical
bit-by-bit stream.<p>
A Vorbis decoder performs a mirror image process of extracting the
original sequence of raw packets from an Ogg stream (<em>stream
decomposition</em>), reconstructing the signal representation from the
raw data in the packet (<em>decoding</em>) and them reconstituting an
audio signal from the decoded representation (<em>synthesis</em>).<p>
The <a href="programming.html">Programming with libvorbis</a>
documents discuss use of the reference Vorbis codec library
(libvorbis) produced by the Xiph.org Foundation.<p>
The data representations and algorithms necessary at each step to
encode and decode Ogg Vorbis bitstreams are described by the below
documents in sufficient detail to construct a complete Vorbis codec.
Note that at the time of writing, Vorbis is still in a 'Request For
Comments' stage of development; despite being in advanced stages of
development, input from the multimedia community is welcome.<p>
<h3>Vorbis analysis and synthesis</h3>
Analysis begins by seperating an input audio stream into individual,
overlapping short-time segments of audio data. These segments are
then transformed into an alternate representation, seeking to
represent the original signal in a more efficient form that codes into
a smaller number of bytes. The analysis and transformation stage is
the most complex element of producing a Vorbis bitstream.<p>
The corresponding synthesis step in the decoder is simpler; there is
no analysis to perform, merely a mechanical, deterministic
reconstruction of the original audio data from the transform-domain
representation.<p>
<ul>
<li><a href="packet.html">Vorbis packet structure</a>: Describes the basic analysis components necessary to produce Vorbis packets and the structure of the packet itself.
<li><a href="envelope.html">Temporal envelope shaping and blocksize</a>: Use of temporal envelope shaping and variable blocksize to minimize time-domain energy leakage during wide dynamic range and spectral energy swings. Also discusses time-related principles of psychoacoustics.
<li><a href="mdct.html">Time domain segmentation and MDCT transform</a>: Division of time domain data into individual overlapped, windowed short-time vectors and transformation using the MDCT
<li><a href="resolution.html">The resolution floor</a>: Use of frequency doamin psychoacoustics, and the MDCT-domain noise, masking and resolution floors
<li><a href="residuals.html">MDCT-domain fine structure</a>: Production, quantization and massaging of MDCT-spectrum fine structure
</ul>
<h3>Vorbis coding and decoding</h3>
Coding and decoding converts the transform-domain representation of
the original audio produced by analysis to and from a bitwise packed
raw data packet. Coding and decoding consist of two logically
orthogonal concepts, <em>back-end coding</em> and <em>bitpacking</em>.<p>
<em>Back-end coding</em> uses a probability model to represent the raw numbers
of the audio representation in as few physical bits as possible;
familiar examples of back-end coding include Huffman coding and Vector
Quantization.<p>
<em>Bitpacking</em> arranges the variable sized words of the back-end
coding into a vector of octets without wasting space. The octets
produced by coding a single short-time audio segment is one raw Vorbis
packet.<p>
<ul>
<li><a href="probmodel.html">The Vorbis probability model</a>
<li><a href="bitpack.html">The Vorbis bitpacker</a>: Arrangement of
variable bit-length words into an octet-aligned packet.
</ul>
<h3>Vorbis streaming and stream decomposition</h3>
Vorbis packets contain the raw, bitwise-compressed representation of a
snippet of audio. These packets contain no structure and cannot be
strung together directly into a stream; for streamed transmission and
storage, Vorbis packets are encoded into an Ogg bitstream.<p>
<ul>
<li><a href="oggstream.html">Ogg bitstream overview</a>: High-level
description of Ogg logical bitstreams, how logical bitstreams
(of mixed media types) can be combined into physical bitstreams, and
restrictions on logical-to-physical mapping. Note that this document is
not specific only to Ogg Vorbis.
<li><a href="framing.html">Ogg logical bitstream and framing
spec</a>: Low level, complete specification of Ogg logical
bitstream pages. Note that this document is not specific only to Ogg
Vorbis.
<li><a href="vorbis-stream.html">Vorbis bitstream mapping</a>:
Specifically describes mapping Vorbis data into an
Ogg physical bitstream.
</ul>
<hr>
<a href="http://www.xiph.org/">
<img src="white-xifish.png" align=left border=0>
</a>
<font size=-2 color=#505050>
Ogg is a <a href="http://www.xiph.org">Xiph.org Foundation</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="http://www.xiph.org/about.html">About
the Xiph.org Foundation</a> for details.
<p>
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, the Xiph.org Foundation and
the Ogg project (xiph.org) reserve the right to set the Ogg Vorbis
specification and certify specification compliance.<p>
Xiph.org's Vorbis software CODEC implementation is distributed under a
BSD-like license. This does not restrict third parties from
distributing independent implementations of Vorbis software under
other licenses.<p>
Ogg, Vorbis, Xiph.org Foundation and their logos are trademarks (tm)
of the <a href="http://www.xiph.org/">Xiph.org Foundation</a>. These
pages are copyright (C) 1994-2002 Xiph.org Foundation. All rights
reserved.<p>
</body>
etc/Library/OggVobisSDK/doc/vorbis/vorbisenc/Makefile.am
+11
View File
@@ -0,0 +1,11 @@
## Process this file with automake to produce Makefile.in
AUTOMAKE_OPTIONS = foreign
docdir = $(datadir)/doc/$(PACKAGE)-$(VERSION)/vorbisenc
doc_DATA = index.html overview.html reference.html style.css\
vorbis_encode_ctl.html vorbis_encode_init.html vorbis_info.html\
vorbis_encode_init_vbr.html
EXTRA_DIST = $(doc_DATA)
etc/Library/OggVobisSDK/doc/vorbis/vorbisenc/index.html
+38
View File
@@ -0,0 +1,38 @@
<html>
<head>
<title>libvorbisenc - Documentation</title>
<link rel=stylesheet href="style.css" type="text/css">
</head>
<body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
<table border=0 width=100%>
<tr>
<td><p class=tiny>libvorbisenc documentation</p></td>
<td align=right><p class=tiny>libvorbisenc version 1.1.2.2 - 20001104</p></td>
</tr>
</table>
<h1>Libvorbisenc Documentation</h1>
<p>
Libvorbisenc is a convenient API for setting up an encoding environment using libvorbis. Libvorbisenc encapsulates the actions needed to set up the encoder properly.
<p>
<a href="overview.html">libvorbisenc api overview</a><br>
<a href="reference.html">libvorbisenc api reference</a><br>
<br><br>
<hr noshade>
<table border=0 width=100%>
<tr valign=top>
<td><p class=tiny>copyright &copy; 2000 vorbis team</p></td>
<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a><br><a href="mailto:[email protected]">[email protected]</a></p></td>
</tr><tr>
<td><p class=tiny>vorbisfile documentation</p></td>
<td align=right><p class=tiny>vorbisfile version 1.25 - 20000615</p></td>
</tr>
</table>
</body>
</html>
etc/Library/OggVobisSDK/doc/vorbis/vorbisenc/overview.html
+58
View File
@@ -0,0 +1,58 @@
<html>
<head>
<title>libvorbisenc - API Overview</title>
<link rel=stylesheet href="style.css" type="text/css">
</head>
<body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
<table border=0 width=100%>
<tr>
<td><p class=tiny>libvorbisenc documentation</p></td>
<td align=right><p class=tiny>libvorbisenc version 1.1.2.2 - 20001104</p></td>
</tr>
</table>
<h1>Libvorbisenc API Overview</h1>
<p>The current version of libvorbisenc is very simple. It contains an initialization function to set up the encoding engine properly.
It also contains a control function to be used in the future to tweak encoder settings.
<p>
All the <b>libvorbisenc</b> routines are declared in "vorbis/vorbisenc.h".
<p>
<table border=1 color=black width=50% cellspacing=0 cellpadding=7>
<tr bgcolor=#cccccc>
<td><b>function</b></td>
<td><b>purpose</b></td>
</tr>
<tr valign=top>
<td><a href="vorbis_encode_init.html">vorbis_encode_init</a></td>
<td>This function takes a <a href="vorbis_info.html">vorbis_info</a> struct and encoding parameters and sets up a proper encoding environment.</tt></a>.</td>
</tr>
<tr valign=top>
<td><a href="vorbis_encode_init_vbr.html">vorbis_encode_init_vbr</a></td>
<td>This function takes a <a href="vorbis_info.html">vorbis_info</a> struct
and encoding parameters for VBR encoding.</td>
</tr>
<tr valign=top>
<td><a href="vorbis_encode_ctl.html">vorbis_encode_ctl</a></td>
<td>Function in progress, to be used in future versions of this API.</td>
</tr>
</table>
<br><br>
<hr noshade>
<table border=0 width=100%>
<tr valign=top>
<td><p class=tiny>copyright &copy; 2000 vorbis team</p></td>
<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/index.html">Ogg Vorbis</a><br><a href="mailto:[email protected]">[email protected]</a></p></td>
</tr><tr>
<td><p class=tiny>vorbisfile documentation</p></td>
<td align=right><p class=tiny>vorbisfile version 1.25 - 20000615</p></td>
</tr>
</table>
</body>
</html>
etc/Library/OggVobisSDK/doc/vorbis/vorbisenc/reference.html
+66
View File
@@ -0,0 +1,66 @@
<html>
<head>
<title>Vorbisfile API Reference</title>
<link rel=stylesheet href="style.css" type="text/css">
</head>
<body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
<table border=0 width=100%>
<tr>
<td><p class=tiny>vorbisfile documentation</p></td>
<td align=right><p class=tiny>vorbisfile version 1.25 - 20000615</p></td>
</tr>
</table>
<h1>Vorbisfile API Reference</h1>
<p>
<b>Data Structures</b><br>
<a href="OggVorbis_File.html">OggVorbis_File</a><br>
<a href="vorbis_comment.html">vorbis_comment</a><br>
<a href="vorbis_info.html">vorbis_info</a><br>
<a href="ov_callbacks.html">ov_callbacks</a><br>
<br>
<b>Setup/Teardown</b><br>
<a href="ov_open.html">ov_open()</a><br>
<a href="ov_open_callbacks.html">ov_open_callbacks()</a><br>
<a href="ov_clear.html">ov_clear()</a><br>
<br>
<b>Decoding</b><br>
<a href="ov_read.html">ov_read()</a><br>
<br>
<b>Seeking</b><br>
<a href="ov_raw_seek.html">ov_raw_seek()</a><br>
<a href="ov_pcm_seek.html">ov_pcm_seek()</a><br>
<a href="ov_time_seek.html">ov_time_seek()</a><br>
<br>
<b>File Information</b><br>
<a href="ov_bitrate.html">ov_bitrate()</a><br>
<a href="ov_bitrate_instant.html">ov_bitrate_instant()</a><br>
<a href="ov_streams.html">ov_streams()</a><br>
<a href="ov_seekable.html">ov_seekable()</a><br>
<a href="ov_serialnumber.html">ov_serialnumber()</a><br>
<a href="ov_raw_total.html">ov_raw_total()</a><br>
<a href="ov_pcm_total.html">ov_pcm_total()</a><br>
<a href="ov_time_total.html">ov_time_total()</a><br>
<a href="ov_raw_tell.html">ov_raw_tell()</a><br>
<a href="ov_pcm_tell.html">ov_pcm_tell()</a><br>
<a href="ov_time_tell.html">ov_time_tell()</a><br>
<a href="ov_info.html">ov_info()</a><br>
<a href="ov_comment.html">ov_comment()</a><br>
<br><br>
<hr noshade>
<table border=0 width=100%>
<tr valign=top>
<td><p class=tiny>copyright &copy; 2000 vorbis team</p></td>
<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/index.html">Ogg Vorbis</a><br><a href="mailto:[email protected]">[email protected]</a></p></td>
</tr><tr>
<td><p class=tiny>vorbisfile documentation</p></td>
<td align=right><p class=tiny>vorbisfile version 1.25 - 20000615</p></td>
</tr>
</table>
</body>
</html>
etc/Library/OggVobisSDK/doc/vorbis/vorbisenc/style.css
+7
View File
@@ -0,0 +1,7 @@
BODY { font-family: Helvetica, sans-serif }
TD { font-family: Helvetica, sans-serif }
P { font-family: Helvetica, sans-serif }
H1 { font-family: Helvetica, sans-serif }
H2 { font-family: Helvetica, sans-serif }
H4 { font-family: Helvetica, sans-serif }
P.tiny { font-size: 8pt }
etc/Library/OggVobisSDK/doc/vorbis/vorbisenc/vorbis_encode_ctl.html
+67
View File
@@ -0,0 +1,67 @@
<html>
<head>
<title>libvorbisenc - function - vorbis_encode_ctl</title>
<link rel=stylesheet href="style.css" type="text/css">
</head>
<body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
<table border=0 width=100%>
<tr>
<td><p class=tiny>libvorbisenc documentation</p></td>
<td align=right><p class=tiny>libvorbisenc version 1.1.2.2 - 20001104</p></td>
</tr>
</table>
<h1>vorbis_encode_ctl</h1>
<p><i>declared in "vorbis/libvorbisenc.h";</i></p>
<p>This function is part of the libvorbisenc API, but has not yet been implemented.
<p>However, the API call is set and will not change.
<p>
<br><br>
<table border=0 color=black cellspacing=0 cellpadding=7>
<tr bgcolor=#cccccc>
<td>
<pre><b>
extern int vorbis_encode_ctl(vorbis_info *vi,int number,void *arg);
</b></pre>
</td>
</tr>
</table>
<h3>Parameters</h3>
<dl>
<dt><i>vi</i></dt>
<dd>File pointer to an initialized <a href="vorbis_info.html">vorbis_info</a> struct.</dd>
<dt><i>number</i></dt>
<dd>Not yet implemented.</dd>
<dt><i>arg</i></dt>
<dd>Not yet implemented.</dd>
<h3>Return Values</h3>
<blockquote>
<li>
<li>OV_EIMPL is always returned, as this function has not yet been implemented.</li>
</blockquote>
<p>
<br><br>
<hr noshade>
<table border=0 width=100%>
<tr valign=top>
<td><p class=tiny>copyright &copy; 2000 xiph.org</p></td>
<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/index.html">Ogg Vorbis</a><br><a href="mailto:[email protected]">[email protected]</a></p></td>
</tr><tr>
<td><p class=tiny>libvorbisenc documentation</p></td>
<td align=right><p class=tiny>libvorbisenc version 1.1.2.2 - 20001106</p></td>
</tr>
</table>
</body>
</html>
etc/Library/OggVobisSDK/doc/vorbis/vorbisenc/vorbis_encode_init.html
+86
View File
@@ -0,0 +1,86 @@
<html>
<head>
<title>libvorbisenc - function - vorbis_encode_init</title>
<link rel=stylesheet href="style.css" type="text/css">
</head>
<body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
<table border=0 width=100%>
<tr>
<td><p class=tiny>libvorbisenc documentation</p></td>
<td align=right><p class=tiny>libvorbisenc version 1.1.2.2 - 20001104</p></td>
</tr>
</table>
<h1>vorbis_encode_init</h1>
<p><i>declared in "vorbis/libvorbisenc.h";</i></p>
<p>This is the primary function within libvorbisenc. This is used to properly set up an encoding environment using libvorbisenc.
<p>Before this function is called, the <a href="vorbis_info.html">vorbis_info</a> struct should be initialized by using vorbis_info_init() from the libvorbis API. After encoding, vorbis_info_clear should be called.
<p>The max_bitrate, nominal_bitrate, and min_bitrate settings are used to set constraints for the encoded file. This function uses these settings to select the appropriate encoding mode and set it up.
<p>
<br><br>
<table border=0 color=black cellspacing=0 cellpadding=7>
<tr bgcolor=#cccccc>
<td>
<pre><b>
extern int vorbis_encode_init(<a href="vorbis_info.html">vorbis_info</a> *vi,
long channels,
long rate,
long max_bitrate,
long nominal_bitrate,
long min_bitrate);
</b></pre>
</td>
</tr>
</table>
<h3>Parameters</h3>
<dl>
<dt><i>vi</i></dt>
<dd>File pointer to an initialized <a href="vorbis_info.html">vorbis_info</a> struct.</dd>
<dt><i>channels</i></dt>
<dd>The number of channels to be encoded.</dd>
<dt><i>rate</i></dt>
<dd>The sampling rate of the source audio.</dd>
<dt><i>max_bitrate</i></dt>
<dd>Desired maximum bitrate (limit).</dd>
<dt><i>nominal_bitrate</i></dt>
<dd>Desired average, or central, bitrate.</dd>
<dt><i>min_bitrate</i></dt>
<dd>Desired minimum bitrate.</dd>
</dl>
<h3>Return Values</h3>
<blockquote>
<li>
0 for success</li>
<li>less than zero for failure:</li>
<ul>
<li>OV_EFAULT - Internal logic fault; indicates a bug or heap/stack corruption.</li>
</ul>
</blockquote>
<p>
<br><br>
<hr noshade>
<table border=0 width=100%>
<tr valign=top>
<td><p class=tiny>copyright &copy; 2000 xiph.org</p></td>
<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/index.html">Ogg Vorbis</a><br><a href="mailto:[email protected]">[email protected]</a></p></td>
</tr><tr>
<td><p class=tiny>libvorbisenc documentation</p></td>
<td align=right><p class=tiny>libvorbisenc version 1.1.2.2 - 20001106</p></td>
</tr>
</table>
</body>
</html>
etc/Library/OggVobisSDK/doc/vorbis/vorbisenc/vorbis_encode_init_vbr.html
+80
View File
@@ -0,0 +1,80 @@
<html>
<head>
<title>libvorbisenc - function - vorbis_encode_init_vbr</title>
<link rel=stylesheet href="style.css" type="text/css">
</head>
<body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
<table border=0 width=100%>
<tr>
<td><p class=tiny>libvorbisenc documentation</p></td>
<td align=right><p class=tiny>libvorbisenc - 20011218</p></td>
</tr>
</table>
<h1>vorbis_encode_init_vbr</h1>
<p><i>declared in "vorbis/libvorbisenc.h";</i></p>
<p>This is the primary function within libvorbisenc. This is used to properly set up an encoding environment using libvorbisenc.
<p>Before this function is called, the <a href="vorbis_info.html">vorbis_info</a> struct should be initialized by using vorbis_info_init() from the libvorbis API. After encoding, vorbis_info_clear should be called.
<p>The max_bitrate, nominal_bitrate, and min_bitrate settings are used to set constraints for the encoded file. This function uses these settings to select the appropriate encoding mode and set it up.
<p>
<br><br>
<table border=0 color=black cellspacing=0 cellpadding=7>
<tr bgcolor=#cccccc>
<td>
<pre><b>
extern int vorbis_encode_init_vbr(<a href="vorbis_info.html">vorbis_info</a> *vi,
long channels,
long rate,
float base_quality /* from 0. (lo) to 1. (hi) */);
</b></pre>
</td>
</tr>
</table>
<h3>Parameters</h3>
<dl>
<dt><i>vi</i></dt>
<dd>File pointer to an initialized <a href="vorbis_info.html">vorbis_info</a> struct.</dd>
<dt><i>channels</i></dt>
<dd>The number of channels to be encoded.</dd>
<dt><i>rate</i></dt>
<dd>The sampling rate of the source audio.</dd>
<dt><i>base_quality</i></dt>
<dd>Desired quality level from 0.0 to 1.0 (lo to hi).</dd>
</dl>
<h3>Return Values</h3>
<blockquote>
<li>
0 for success</li>
<li>less than zero for failure:</li>
<ul>
<li>OV_EFAULT - Internal logic fault; indicates a bug or heap/stack corruption.</li>
</ul>
</blockquote>
<p>
<br><br>
<hr noshade>
<table border=0 width=100%>
<tr valign=top>
<td><p class=tiny>copyright &copy; 2000 xiph.org</p></td>
<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/index.html">Ogg Vorbis</a><br><a href="mailto:[email protected]">[email protected]</a></p></td>
</tr><tr>
<td><p class=tiny>libvorbisenc documentation</p></td>
<td align=right><p class=tiny>libvorbisenc version 1.1.2.2 - 20001106</p></td>
</tr>
</table>
</body>
</html>
etc/Library/OggVobisSDK/doc/vorbis/vorbisenc/vorbis_info.html
+102
View File
@@ -0,0 +1,102 @@
<html>
<head>
<title>vorbis - datatype - vorbis_info</title>
<link rel=stylesheet href="style.css" type="text/css">
</head>
<body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
<table border=0 width=100%>
<tr>
<td><p class=tiny>vorbisfile documentation</p></td>
<td align=right><p class=tiny>vorbisfile version 1.25 - 20000615</p></td>
</tr>
</table>
<h1>vorbis_info</h1>
<p><i>declared in "vorbis/codec.h"</i></p>
<p>
The vorbis_info structure contains information about a vorbis bitstream. Most of the information in this struct is more complex and in-depth than we need when using basic API calls.
<p>
<table border=0 width=100% color=black cellspacing=0 cellpadding=7>
<tr bgcolor=#cccccc>
<td>
<pre><b>typedef struct vorbis_info{
int version;
int channels;
long rate;
long bitrate_upper;
long bitrate_nominal;
long bitrate_lower;
long blocksizes[2];
int modes;
int maps;
int times;
int floors;
int residues;
int books;
int psys; /* encode only */
vorbis_info_mode *mode_param[64];
int map_type[64];
vorbis_info_mapping *map_param[64];
int time_type[64];
vorbis_info_time *time_param[64];
int floor_type[64];
vorbis_info_floor *floor_param[64];
int residue_type[64];
vorbis_info_residue *residue_param[64];
static_codebook *book_param[256];
vorbis_info_psy *psy_param[64]; /* encode only */
/* for block long/sort tuning; encode only */
int envelopesa;
double preecho_thresh;
double preecho_clamp;
} vorbis_info;</b></pre>
</td>
</tr>
</table>
<h3>Relevant Struct Members</h3>
<dl>
<dt><i>version</i></dt>
<dd>Vorbis encoder version used to create this bitstream.</dd>
<dt><i>channels</i></dt>
<dd>Int signifying number of channels in bitstream.</dd>
<dt><i>rate</i></dt>
<dd>Sampling rate of the bitstream.</dd>
<dt><i>bitrate_upper</i></dt>
<dd>Specifies the upper limit in a VBR bitstream. If the value matches the bitrate_nominal and bitrate_lower parameters, the stream is fixed bitrate. May be unset if no limit exists.</dd>
<dt><i>bitrate_nominal</i></dt>
<dd>Specifies the average bitrate for a VBR bitstream. May be unset. If the bitrate_upper and bitrate_lower parameters match, the stream is fixed bitrate.</dd>
<dt><i>bitrate_lower</i></dt>
<dd>Specifies the lower limit in a VBR bitstream. If the value matches the bitrate_nominal and bitrate_upper parameters, the stream is fixed bitrate. May be unset if no limit exists.</dd>
<dt><i>blocksizes[2]</i></dt>
<dd>Contains the sizes of the long and short blocks for this particular bitstream. These are variable and can be set by the encoder. Vorbis only supports two sizes, long and short.</dd>
</dl>
<br><br>
<hr noshade>
<table border=0 width=100%>
<tr valign=top>
<td><p class=tiny>copyright &copy; 2000 vorbis team</p></td>
<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/index.html">Ogg Vorbis</a><br><a href="mailto:[email protected]">[email protected]</a></p></td>
</tr><tr>
<td><p class=tiny>vorbisfile documentation</p></td>
<td align=right><p class=tiny>vorbisfile version 1.25 - 20000615</p></td>
</tr>
</table>
</body>
</html>
etc/Library/OggVobisSDK/doc/vorbis/vorbisfile/Makefile.am
+21
View File
@@ -0,0 +1,21 @@
## Process this file with automake to produce Makefile.in
AUTOMAKE_OPTIONS = foreign
docdir = $(datadir)/doc/$(PACKAGE)-$(VERSION)/vorbisfile
doc_DATA = OggVorbis_File.html chaining_example_c.html chainingexample.html\
datastructures.html decoding.html example.html exampleindex.html\
fileinfo.html index.html initialization.html ov_bitrate.html\
ov_bitrate_instant.html ov_callbacks.html ov_clear.html\
ov_comment.html ov_info.html ov_open.html ov_open_callbacks.html\
ov_pcm_seek.html ov_pcm_tell.html ov_pcm_total.html ov_raw_seek.html\
ov_raw_tell.html ov_raw_total.html ov_read.html ov_seekable.html\
ov_serialnumber.html ov_streams.html ov_time_seek.html\
ov_time_tell.html ov_time_total.html overview.html reference.html\
seekexample.html seeking.html seeking_test_c.html seekingexample.html\
style.css vorbis_comment.html vorbis_info.html\
vorbisfile_example_c.html ov_read_float.html ov_test.html\
ov_test_open.html ov_test_callbacks.html
EXTRA_DIST = $(doc_DATA)
etc/Library/OggVobisSDK/doc/vorbis/vorbisfile/OggVorbis_File.html
+121
View File
@@ -0,0 +1,121 @@
<html>
<head>
<title>Vorbisfile - datatype - OggVorbis_File</title>
<link rel=stylesheet href="style.css" type="text/css">
</head>
<body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
<table border=0 width=100%>
<tr>
<td><p class=tiny>Vorbisfile documentation</p></td>
<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
</tr>
</table>
<h1>OggVorbis_File</h1>
<p><i>declared in "vorbis/vorbisfile.h"</i></p>
<p>
The OggVorbis_File structure defines an Ogg Vorbis file.
<p>
This structure is used in all libvorbisfile routines. Before it can be used,
it must be initialized by <a href="ov_open.html">ov_open()</a> or <a
href="ov_open_callbacks.html">ov_open_callbacks()</a>.
<p>
After use, the OggVorbis_File structure must be deallocated with a
call to <a href="ov_clear.html">ov_clear()</a>.
<p>
Once a file or data source is opened successfully by libvorbisfile
(using <a href="ov_open.html">ov_open()</a> or <a
href="ov_open_callbacks.html">ov_open_callbacks()</a>), it is owned by
libvorbisfile. The file should not be used by any other applications or
functions outside of the libvorbisfile API. The file must not be closed
directly by the application at any time after a successful open;
libvorbisfile expects to close the file within <a
href="ov_clear.html">ov_clear()</a>.
<p>
If the call to <a href="ov_open.html">ov_open()</a> or <a
href="ov_open_callbacks.html">ov_open_callbacks()</a> <b>fails</b>,
libvorbisfile does <b>not</b> assume ownership of the file and the
application is expected to close it if necessary.
<br><br>
<table border=0 width=100% color=black cellspacing=0 cellpadding=7>
<tr bgcolor=#cccccc>
<td>
<pre><b>typedef struct {
void *datasource; /* Pointer to a FILE *, etc. */
int seekable;
ogg_int64_t offset;
ogg_int64_t end;
ogg_sync_state oy;
/* If the FILE handle isn't seekable (eg, a pipe), only the current
stream appears */
int links;
ogg_int64_t *offsets;
ogg_int64_t *dataoffsets;
long *serialnos;
ogg_int64_t *pcmlengths;
vorbis_info *vi;
vorbis_comment *vc;
/* Decoding working state local storage */
ogg_int64_t pcm_offset;
int ready_state;
long current_serialno;
int current_link;
ogg_int64_t bittrack;
ogg_int64_t samptrack;
ogg_stream_state os; /* take physical pages, weld into a logical
stream of packets */
vorbis_dsp_state vd; /* central working state for the packet->PCM decoder */
vorbis_block vb; /* local working space for packet->PCM decode */
<a href="ov_callbacks.html">ov_callbacks</a> callbacks;
} OggVorbis_File;</b></pre>
</td>
</tr>
</table>
<h3>Relevant Struct Members</h3>
<dl>
<dt><i>datasource</i></dt>
<dd>Pointer to file or other ogg source. When using stdio based
file/stream access, this field contains a <tt>FILE</tt> pointer. When using
custom IO via callbacks, libvorbisfile treats this void pointer as a
black box only to be passed to the callback routines provided by the
application.</dd>
<dt><i>seekable</i></dt>
<dd>Read-only int indicating whether file is seekable. E.g., a physical file is seekable, a pipe isn't.</dd>
<dt><i>links</i></dt>
<dd>Read-only int indicating the number of logical bitstreams within the physical bitstream.</dd>␍
<dt><i>ov_callbacks</i></dt>␍
<dd>Collection of file manipulation routines to be used on this data source. When using stdio/FILE access via <a href="ov_open.html">ov_open()</a>, the callbacks will be filled in with stdio calls or wrappers to stdio calls.</dd>
</dl>
<br><br>
<hr noshade>
<table border=0 width=100%>
<tr valign=top>
<td><p class=tiny>copyright &copy; 2002 Xiph.org</p></td>
<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td>
</tr><tr>
<td><p class=tiny>Vorbisfile documentation</p></td>
<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
</tr>
</table>
</body>
</html>
etc/Library/OggVobisSDK/doc/vorbis/vorbisfile/callbacks.html
+113
View File
@@ -0,0 +1,113 @@
<html>
<head>
<title>Vorbisfile - Callbacks and non-stdio I/O</title>
<link rel=stylesheet href="style.css" type="text/css">
</head>
<body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
<table border=0 width=100%>
<tr>
<td><p class=tiny>Vorbisfile documentation</p></td>
<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
</tr>
</table>
<h1>Callbacks and non-stdio I/O</h1>
Although stdio is convenient and nearly universally implemented as per
ANSI C, it is not suited to all or even most potential uses of Vorbis.
For additional flexibility, embedded applications may provide their
own I/O functions for use with Vorbisfile when stdio is unavailable or not
suitable. One common example is decoding a Vorbis stream from a
memory buffer.<p>
Use custom I/O functions by populating an <a
href="ov_callbacks.html">ov_callbacks</a> structure and calling <a
href="ov_open_callbacks.html">ov_open_callbacks()</a> or <a
href="ov_test_callbacks.html">ov_test_callbacks()</a> rather than the
typical <a href="ov_open.html">ov_open()</a> or <a
href="ov_test.html">ov_test()</a>. Past the open call, use of
libvorbisfile is identical to using it with stdio.
<h2>Read function</h2>
The read-like function provided in the <tt>read_func</tt> field is
used to fetch the requested amount of data. It expects the fetch
operation to function similar to file-access, that is, a multiple read
operations will retrieve contiguous sequential pieces of data,
advancing a position cursor after each read.<p>
The following behaviors are also expected:<p>
<ul>
<li>a return of '0' indicates end-of-data (if the by-thread errno is unset)
<li>short reads mean nothing special (short reads are not treated as error conditions)
<li>a return of zero with the by-thread errno set to nonzero indicates a read error
</ul>
<p>
<h2>Seek function</h2>
The seek-like function provided in the <tt>seek_func</tt> field is
used to request non-sequential data access by libvorbisfile, moving
the access cursor to the requested position.<p>
libvorbisfile expects the following behavior:
<ul>
<li>The seek function must always return -1 (failure) if the given
data abstraction is not seekable. It may choose to always return -1
if the application desires libvorbisfile to treat the Vorbis data
strictly as a stream (which makes for a less expensive open
operation).<p>
<li>If the seek function initially indicates seekability, it must
always succeed upon being given a valid seek request.<p>
<li>The seek function must implement all of SEEK_SET, SEEK_CUR and
SEEK_END. The implementation of SEEK_END should set the access cursor
one past the last byte of accessible data, as would stdio
<tt>fseek()</tt><p>
</ul>
<h2>Close function</h2>
The close function should deallocate any access state used by the
passed in instance of the data access abstraction and invalidate the
instance handle. The close function is assumed to succeed.<p>
One common use of callbacks and the close function is to change the
behavior of libvorbisfile with respect to file closure for applications
that <em>must</em> <tt>fclose</tt> data files themselves. By passing
the normal stdio calls as callback functions, but passing a
<tt>close_func</tt> that does nothing, an application may call <a
href="ov_clear.html">ov_clear()</a> and then <tt>fclose()</tt> the
file originally passed to libvorbisfile.
<h2>Tell function</h2>
The tell function is intended to mimic the
behavior of <tt>ftell()</tt> and must return the byte position of the
next data byte that would be read. If the data access cursor is at
the end of the 'file' (pointing to one past the last byte of data, as
it would be after calling <tt>fseek(file,SEEK_END,0)</tt>), the tell
function must return the data position (and thus the total file size),
not an error.<p>
The tell function need not be provided if the data IO abstraction is
not seekable.<p>
<br><br>
<hr noshade>
<table border=0 width=100%>
<tr valign=top>
<td><p class=tiny>copyright &copy; 2002 Xiph.org</p></td>
<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td>
</tr><tr>
<td><p class=tiny>Vorbisfile documentation</p></td>
<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
</tr>
</table>
</body>
</html>
etc/Library/OggVobisSDK/doc/vorbis/vorbisfile/chaining_example_c.html
+86
View File
@@ -0,0 +1,86 @@
<html>
<head>
<title>vorbisfile - chaining_example.c</title>
<link rel=stylesheet href="style.css" type="text/css">
</head>
<body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
<table border=0 width=100%>
<tr>
<td><p class=tiny>vorbisfile documentation</p></td>
<td align=right><p class=tiny>vorbisfile version 1.25 - 20000615</p></td>
</tr>
</table>
<h1>chaining_example.c</h1>
<p>
The example program source:
<br><br>
<table border=0 width=100% color=black cellspacing=0 cellpadding=7>
<tr bgcolor=#cccccc>
<td>
<pre><b>
#include <vorbis/codec.h>
#include <vorbis/vorbisfile.h>
int main(){
OggVorbis_File ov;
int i;
/* open the file/pipe on stdin */
if(ov_open(stdin,&ov,NULL,-1)<0){
printf("Could not open input as an OggVorbis file.\n\n");
exit(1);
}
/* print details about each logical bitstream in the input */
if(ov_seekable(&ov)){
printf("Input bitstream contained %ld logical bitstream section(s).\n",
ov_streams(&ov));
printf("Total bitstream playing time: %ld seconds\n\n",
(long)ov_time_total(&ov,-1));
}else{
printf("Standard input was not seekable.\n"
"First logical bitstream information:\n\n");
}
for(i=0;i<ov_streams(&ov);i++){
vorbis_info *vi=ov_info(&ov,i);
printf("\tlogical bitstream section %d information:\n",i+1);
printf("\t\t%ldHz %d channels bitrate %ldkbps serial number=%ld\n",
vi->rate,vi->channels,ov_bitrate(&ov,i)/1000,
ov_serialnumber(&ov,i));
printf("\t\tcompressed length: %ld bytes ",(long)(ov_raw_total(&ov,i)));
printf(" play time: %lds\n",(long)ov_time_total(&ov,i));
}
ov_clear(&ov);
return 0;
}
</b></pre>
</td>
</tr>
</table>
<br><br>
<hr noshade>
<table border=0 width=100%>
<tr valign=top>
<td><p class=tiny>copyright &copy; 2000 vorbis team</p></td>
<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/index.html">Ogg Vorbis</a><br><a href="mailto:[email protected]">[email protected]</a></p></td>
</tr><tr>
<td><p class=tiny>vorbisfile documentation</p></td>
<td align=right><p class=tiny>vorbisfile version 1.25 - 20000615</p></td>
</tr>
</table>
</body>
</html>
etc/Library/OggVobisSDK/doc/vorbis/vorbisfile/chainingexample.html
+158
View File
@@ -0,0 +1,158 @@
<html>
<head>
<title>vorbisfile - Example Code</title>
<link rel=stylesheet href="style.css" type="text/css">
</head>
<body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
<table border=0 width=100%>
<tr>
<td><p class=tiny>vorbisfile documentation</p></td>
<td align=right><p class=tiny>vorbisfile version 1.25 - 20000615</p></td>
</tr>
</table>
<h1>Chaining Example Code</h1>
<p>
The following is a run-through of the chaining example program supplied
with vorbisfile - <a href="chaining_example_c.html">chaining_example.c</a>.
This program demonstrates how to work with a chained bitstream.
<p>
First, relevant headers, including vorbis-specific "codec.h" and "vorbisfile.h" have to be included.
<br><br>
<table border=0 width=100% color=black cellspacing=0 cellpadding=7>
<tr bgcolor=#cccccc>
<td>
<pre><b>
#include "vorbis/codec.h"
#include "vorbis/vorbisfile.h"
#include "../lib/misc.h"
</b></pre>
</td>
</tr>
</table>
<p>Inside main(), we declare our primary OggVorbis_File structure. We also declare a other helpful variables to track our progress within the file.
<br><br>
<table border=0 width=100% color=black cellspacing=0 cellpadding=7>
<tr bgcolor=#cccccc>
<td>
<pre><b>
int main(){
OggVorbis_File ov;
int i;
</b></pre>
</td>
</tr>
</table>
<p><a href="ov_open.html">ov_open()</a> must be
called to initialize the <a href="OggVorbis_File.html">OggVorbis_File</a> structure with default values.
<a href="ov_open.html">ov_open()</a> also checks to ensure that we're reading Vorbis format and not something else.
<br><br>
<table border=0 width=100% color=black cellspacing=0 cellpadding=7>
<tr bgcolor=#cccccc>
<td>
<pre><b>
if(ov_open(stdin,&ov,NULL,-1)<0){
printf("Could not open input as an OggVorbis file.\n\n");
exit(1);
}
</b></pre>
</td>
</tr>
</table>
<p>
First we check to make sure the stream is seekable using <a href="ov_seekable.html">ov_seekable</a>.
<p>Then we're going to find the number of logical bitstreams in the physical bitstream using <a href="ov_streams.html">ov_streams</a>.
<p>We use <a href="ov_time_total.html">ov_time_total</a> to determine the total length of the physical bitstream. We specify that we want the entire bitstream by using the argument <tt>-1</tt>.
<br><br>
<table border=0 width=100% color=black cellspacing=0 cellpadding=7>
<tr bgcolor=#cccccc>
<td>
<pre><b>
if(ov_seekable(&ov)){
printf("Input bitstream contained %ld logical bitstream section(s).\n",
ov_streams(&ov));
printf("Total bitstream playing time: %ld seconds\n\n",
(long)ov_time_total(&ov,-1));
}else{
printf("Standard input was not seekable.\n"
"First logical bitstream information:\n\n");
}
</b></pre>
</td>
</tr>
</table>
<p>Now we're going to iterate through each logical bitstream and print information about that bitstream.
<p>We use <a href="ov_info.html">ov_info</a> to pull out the <a href="vorbis_info.html">vorbis_info</a> struct for each logical bitstream. This struct contains bitstream-specific info.
<p><a href="ov_serialnumber.html">ov_serialnumber</a> retrieves the unique serial number for the logical bistream. <a href="ov_raw_total.html">ov_raw_total</a> gives the total compressed bytes for the logical bitstream, and <a href="ov_time_total.html">ov_time_total</a> gives the total time in the logical bitstream.
<br><br>
<table border=0 width=100% color=black cellspacing=0 cellpadding=7>
<tr bgcolor=#cccccc>
<td>
<pre><b>
for(i=0;i<ov_streams(&ov);i++){
vorbis_info *vi=ov_info(&ov,i);
printf("\tlogical bitstream section %d information:\n",i+1);
printf("\t\t%ldHz %d channels bitrate %ldkbps serial number=%ld\n",
vi->rate,vi->channels,ov_bitrate(&ov,i)/1000,
ov_serialnumber(&ov,i));
printf("\t\tcompressed length: %ld bytes ",(long)(ov_raw_total(&ov,i)));
printf(" play time: %lds\n",(long)ov_time_total(&ov,i));
}
</b></pre>
</td>
</tr>
</table>
<p>
When we're done with the entire physical bitstream, we need to call <a href="ov_clear.html">ov_clear()</a> to release the bitstream.
<br><br>
<table border=0 width=100% color=black cellspacing=0 cellpadding=7>
<tr bgcolor=#cccccc>
<td>
<pre><b>
ov_clear(&ov);
return 0;
}
</b></pre>
</td>
</tr>
</table>
<p>
The full source for chaining_example.c can be found with the vorbis
distribution in <a href="chaining_example_c.html">chaining_example.c</a>.
<br><br>
<hr noshade>
<table border=0 width=100%>
<tr valign=top>
<td><p class=tiny>copyright &copy; 2000 vorbis team</p></td>
<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a><br><a href="mailto:[email protected]">[email protected]</a></p></td>
</tr><tr>
<td><p class=tiny>vorbisfile documentation</p></td>
<td align=right><p class=tiny>vorbisfile version 1.25 - 20000615</p></td>
</tr>
</table>
</body>
</html>
etc/Library/OggVobisSDK/doc/vorbis/vorbisfile/datastructures.html
+61
View File
@@ -0,0 +1,61 @@
<html>
<head>
<title>Vorbisfile - Base Data Structures</title>
<link rel=stylesheet href="style.css" type="text/css">
</head>
<body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
<table border=0 width=100%>
<tr>
<td><p class=tiny>Vorbisfile documentation</p></td>
<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
</tr>
</table>
<h1>Base Data Structures</h1>
<p>There are several data structures used to hold file and bitstream information during libvorbisfile decoding. These structures are declared in "vorbis/vorbisfile.h" and "vorbis/codec.h".
<p>
<p>When using libvorbisfile, it's not necessary to know about most of the contents of these data structures, but it may be helpful to understand what they contain.
<br><br>
<table border=1 color=black width=50% cellspacing=0 cellpadding=7>
<tr bgcolor=#cccccc>
<td><b>datatype</b></td>
<td><b>purpose</b></td>
</tr>
<tr valign=top>
<td><a href="OggVorbis_File.html">OggVorbis_File</a></td>
<td>This structure represents the basic file information. It contains
a pointer to the physical file or bitstream and various information about that bitstream.</td>
</tr>
<tr valign=top>
<td><a href="vorbis_comment.html">vorbis_comment</a></td>
<td>This structure contains the file comments. It contains
a pointer to unlimited user comments, information about the number of comments, and a vendor description.</td>
</tr>
<tr valign=top>
<td><a href="vorbis_info.html">vorbis_info</a></td>
<td>This structure contains encoder-related information about the bitstream. It includes encoder info, channel info, and bitrate limits.</td>
</tr>
<tr valign=top>
<td><a href="ov_callbacks.html">ov_callbacks</a></td>
<td>This structure contains pointers to the application-specified file manipulation routines set for use by <a href="ov_open_callbacks.html">ov_open_callbacks()</a>. See also the <a href="callbacks.html">provided document on using application-provided callbacks instead of stdio</a>.</td>
</tr>
</table>
<br><br>
<hr noshade>
<table border=0 width=100%>
<tr valign=top>
<td><p class=tiny>copyright &copy; 2002 Xiph.org</p></td>
<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td>
</tr><tr>
<td><p class=tiny>Vorbisfile documentation</p></td>
<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
</tr>
</table>
</body>
</html>
etc/Library/OggVobisSDK/doc/vorbis/vorbisfile/decoding.html
+86
View File
@@ -0,0 +1,86 @@
<html>
<head>
<title>Vorbisfile - Decoding</title>
<link rel=stylesheet href="style.css" type="text/css">
</head>
<body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
<table border=0 width=100%>
<tr>
<td><p class=tiny>Vorbisfile documentation</p></td>
<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
</tr>
</table>
<h1>Decoding</h1>
<p>
All libvorbisfile decoding routines are declared in "vorbis/vorbisfile.h".
<p>
After <a href="initialization.html">initialization</a>, decoding audio
is as simple as calling <a href="ov_read.html">ov_read()</a>. This
function works similarly to reading from a normal file using
<tt>read()</tt>.<p>
However, a few differences are worth noting:
<h2>multiple stream links</h2>
A Vorbis stream may consist of multiple sections (called links) that
encode differing numbers of channels or sample rates. It is vitally
important to pay attention to the link numbers returned by <a
href="ov_read.html">ov_read</a> and handle audio changes that may
occur at link boundaries. Such multi-section files do exist in the
wild and are not merely a specification curiosity.
<h2>returned data amount</h2>
<a href="ov_read.html">ov_read</a> does not attempt to completely fill
a large, passed in data buffer; it merely guarantees that the passed
back data does not overflow the passed in buffer size. Large buffers
may be filled by iteratively looping over calls to <a
href="ov_read.html">ov_read</a> (incrementing the buffer pointer)
until the original buffer is filled.
<h2>file cursor position</h2>
Vorbis files do not necessarily start at a sample number or time offset
of zero. Do not be surprised if a file begins at a positive offset of
several minutes or hours, such as would happen if a large stream (such
as a concert recording) is chopped into multiple seperate files.
<p>
<table border=1 color=black width=50% cellspacing=0 cellpadding=7>
<tr bgcolor=#cccccc>
<td><b>function</b></td>
<td><b>purpose</b></td>
</tr>
<tr valign=top>
<td><a href="ov_read.html">ov_read</a></td>
<td>This function makes up the main chunk of a decode loop. It takes an
OggVorbis_File structure, which must have been initialized by a previous
call to <a href="ov_open.html"><tt>ov_open()</tt></a>.</td>
</tr>
<tr valign=top>
<td><a href="ov_read_float.html">ov_read_float</a></td>
<td>This function decodes to floats instead of integer samples.</td>
</tr>
</table>
<br><br>
<hr noshade>
<table border=0 width=100%>
<tr valign=top>
<td><p class=tiny>copyright &copy; 2002 Xiph.org</p></td>
<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td>
</tr><tr>
<td><p class=tiny>Vorbisfile documentation</p></td>
<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
</tr>
</table>
</body>
</html>
etc/Library/OggVobisSDK/doc/vorbis/vorbisfile/example.html
+205
View File
@@ -0,0 +1,205 @@
<html>
<head>
<title>Vorbisfile - Example Code</title>
<link rel=stylesheet href="style.css" type="text/css">
</head>
<body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
<table border=0 width=100%>
<tr>
<td><p class=tiny>Vorbisfile documentation</p></td>
<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
</tr>
</table>
<h1>Example Code</h1>
<p>
The following is a run-through of the decoding example program supplied
with libvorbisfile, vorbisfile_example.c.
This program takes a vorbis bitstream from stdin and writes raw pcm to stdout.
<p>
First, relevant headers, including vorbis-specific "vorbis/codec.h" and "vorbisfile.h" have to be included.
<br><br>
<table border=0 width=100% color=black cellspacing=0 cellpadding=7>
<tr bgcolor=#cccccc>
<td>
<pre><b>
#include &lt;stdio.h&gt;
#include &lt;stdlib.h&gt;
#include &lt;math.h&gt;
#include "vorbis/codec.h"
#include "vorbisfile.h"
</b></pre>
</td>
</tr>
</table>
<p>
We also have to make a concession to Windows users here. If we are using windows for decoding, we must declare these libraries so that we can set stdin/stdout to binary.
<br><br>
<table border=0 width=100% color=black cellspacing=0 cellpadding=7>
<tr bgcolor=#cccccc>
<td>
<pre><b>
#ifdef _WIN32
#include &lt;io.h&gt;
#include &lt;fcntl.h&gt;
#endif
</b></pre>
</td>
</tr>
</table>
<p>
Next, a buffer for the pcm audio output is declared.
<br><br>
<table border=0 width=100% color=black cellspacing=0 cellpadding=7>
<tr bgcolor=#cccccc>
<td>
<pre><b>
char pcmout[4096];
</b></pre>
</td>
</tr>
</table>
<p>Inside main(), we declare our primary OggVorbis_File structure. We also declare a few other helpful variables to track out progress within the file.
Also, we make our final concession to Windows users by setting the stdin and stdout to binary mode.
<br><br>
<table border=0 width=100% color=black cellspacing=0 cellpadding=7>
<tr bgcolor=#cccccc>
<td>
<pre><b>
int main(int argc, char **argv){
OggVorbis_File vf;
int eof=0;
int current_section;
#ifdef _WIN32
_setmode( _fileno( stdin ), _O_BINARY );
_setmode( _fileno( stdout ), _O_BINARY );
#endif
</b></pre>
</td>
</tr>
</table>
<p><a href="ov_open.html">ov_open()</a> must be
called to initialize the <b>OggVorbis_File</b> structure with default values.
<a href="ov_open.html">ov_open()</a> also checks to ensure that we're reading Vorbis format and not something else.
<br><br>
<table border=0 width=100% color=black cellspacing=0 cellpadding=7>
<tr bgcolor=#cccccc>
<td>
<pre><b>
if(ov_open(stdin, &vf, NULL, 0) < 0) {
fprintf(stderr,"Input does not appear to be an Ogg bitstream.\n");
exit(1);
}
</b></pre>
</td>
</tr>
</table>
<p>
We're going to pull the channel and bitrate info from the file using <a href="ov_info.html">ov_info()</a> and show them to the user.
We also want to pull out and show the user a comment attached to the file using <a href="ov_comment.html">ov_comment()</a>.
<br><br>
<table border=0 width=100% color=black cellspacing=0 cellpadding=7>
<tr bgcolor=#cccccc>
<td>
<pre><b>
{
char **ptr=ov_comment(&vf,-1)->user_comments;
vorbis_info *vi=ov_info(&vf,-1);
while(*ptr){
fprintf(stderr,"%s\n",*ptr);
++ptr;
}
fprintf(stderr,"\nBitstream is %d channel, %ldHz\n",vi->channels,vi->rate);
fprintf(stderr,"\nDecoded length: %ld samples\n",
(long)ov_pcm_total(&vf,-1));
fprintf(stderr,"Encoded by: %s\n\n",ov_comment(&vf,-1)->vendor);
}
</b></pre>
</td>
</tr>
</table>
<p>
Here's the read loop:
<br><br>
<table border=0 width=100% color=black cellspacing=0 cellpadding=7>
<tr bgcolor=#cccccc>
<td>
<pre><b>
while(!eof){
long ret=ov_read(&vf,pcmout,sizeof(pcmout),&current_section);
if (ret == 0) {
/* EOF */
eof=1;
} else if (ret < 0) {
/* error in the stream. Not a problem, just reporting it in
case we (the app) cares. In this case, we don't. */
} else {
/* we don't bother dealing with sample rate changes, etc, but
you'll have to*/
fwrite(pcmout,1,ret,stdout);
}
}
</b></pre>
</td>
</tr>
</table>
<p>
The code is reading blocks of data using <a href="ov_read.html">ov_read()</a>.
Based on the value returned, we know if we're at the end of the file or have invalid data. If we have valid data, we write it to the pcm output.
<p>
Now that we've finished playing, we can pack up and go home. It's important to call <a href="ov_clear.html">ov_clear()</a> when we're finished.
<br><br>
<table border=0 width=100% color=black cellspacing=0 cellpadding=7>
<tr bgcolor=#cccccc>
<td>
<pre><b>
ov_clear(&vf);
fprintf(stderr,"Done.\n");
return(0);
}
</b></pre>
</td>
</tr>
</table>
<p>
<br><br>
<hr noshade>
<table border=0 width=100%>
<tr valign=top>
<td><p class=tiny>copyright &copy; 2002 Xiph.org</p></td>
<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td>
</tr><tr>
<td><p class=tiny>Vorbisfile documentation</p></td>
<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
</tr>
</table>
</body>
</html>
etc/Library/OggVobisSDK/doc/vorbis/vorbisfile/exampleindex.html
+39
View File
@@ -0,0 +1,39 @@
<html>
<head>
<title>vorbisfile - Documentation</title>
<link rel=stylesheet href="style.css" type="text/css">
</head>
<body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
<table border=0 width=100%>
<tr>
<td><p class=tiny>vorbisfile documentation</p></td>
<td align=right><p class=tiny>vorbisfile version 1.25 - 20000615</p></td>
</tr>
</table>
<h1>VorbisFile Example Code</h1>
<p>
Three sample programs are included with the vorbisfile distribution.
<p>
<a href="example.html">vorbisfile decoding</a><br>
<a href="seekexample.html">vorbisfile seeking</a><br>
<a href="chainingexample.html">vorbisfile bitstream chaining</a><br>
<br><br>
<hr noshade>
<table border=0 width=100%>
<tr valign=top>
<td><p class=tiny>copyright &copy; 2000 vorbis team</p></td>
<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a><br><a href="mailto:[email protected]">[email protected]</a></p></td>
</tr><tr>
<td><p class=tiny>vorbisfile documentation</p></td>
<td align=right><p class=tiny>vorbisfile version 1.25 - 20000615</p></td>
</tr>
</table>
</body>
</html>
etc/Library/OggVobisSDK/doc/vorbis/vorbisfile/fileinfo.html
+95
View File
@@ -0,0 +1,95 @@
<html>␍
␍
<head>␍
<title>Vorbisfile - File Information</title>␍
<link rel=stylesheet href="style.css" type="text/css">␍
</head>␍
␍
<body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">␍
<table border=0 width=100%>␍
<tr>␍
<td><p class=tiny>Vorbisfile documentation</p></td>␍
<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>␍
</tr>␍
</table>␍
␍
<h1>File Information</h1>␍
<p>Libvorbisfile contains many functions to get information about bitstream attributes and decoding status.␍
<p>␍
All libvorbisfile file information routines are declared in "vorbis/vorbisfile.h".␍
<p>␍
␍
<table border=1 color=black width=50% cellspacing=0 cellpadding=7>␍
<tr bgcolor=#cccccc>␍
<td><b>function</b></td>␍
<td><b>purpose</b></td>␍
</tr>␍
<tr valign=top>␍
<td><a href="ov_bitrate.html">ov_bitrate</a></td>␍
<td>Returns the average bitrate of the current logical bitstream.</td>␍
</tr>␍
<tr valign=top>␍
<td><a href="ov_bitrate_instant.html">ov_bitrate_instant</a></td>␍
<td>Returns the exact bitrate since the last call of this function, or -1 if at the beginning of the bitream or no new information is available.</td>␍
</tr>␍
<tr valign=top>␍
<td><a href="ov_streams.html">ov_streams</a></td>␍
<td>Gives the number of logical bitstreams within the current physical bitstream.</td>␍
</tr>␍
<tr valign=top>␍
<td><a href="ov_seekable.html">ov_seekable</a></td>␍
<td>Indicates whether the bitstream is seekable.</td>␍
</tr>␍
<tr valign=top>␍
<td><a href="ov_serialnumber.html">ov_serialnumber</a></td>␍
<td>Returns the unique serial number of the specified logical bitstream.</td>␍
</tr>␍
<tr valign=top>␍
<td><a href="ov_raw_total.html">ov_raw_total</a></td>␍
<td>Returns the total (compressed) bytes in a physical or logical seekable bitstream.</td>␍
</tr>␍
<tr valign=top>␍
<td><a href="ov_pcm_total.html">ov_pcm_total</a></td>␍
<td>Returns the total number of samples in a physical or logical seekable bitstream.</td>␍
</tr>␍
<tr valign=top>␍
<td><a href="ov_time_total.html">ov_time_total</a></td>␍
<td>Returns the total time length in seconds of a physical or logical seekable bitstream.</td>␍
</tr>␍
<tr valign=top>␍
<td><a href="ov_raw_tell.html">ov_raw_tell</a></td>␍
<td>Returns the byte location of the next sample to be read, giving the approximate location in the stream that the decoding engine has reached.</td>␍
</tr>␍
<tr valign=top>␍
<td><a href="ov_pcm_tell.html">ov_pcm_tell</a></td>␍
<td>Returns the sample location of the next sample to be read, giving the approximate location in the stream that the decoding engine has reached.</td>␍
</tr>␍
<tr valign=top>␍
<td><a href="ov_time_tell.html">ov_time_tell</a></td>␍
<td>Returns the time location of the next sample to be read, giving the approximate location in the stream that the decoding engine has reached.</td>␍
</tr>␍
<tr valign=top>␍
<td><a href="ov_info.html">ov_info</a></td>␍
<td>Returns the <a href="vorbis_info.html">vorbis_info</a> struct for a specific bitstream section.</td>␍
</tr>␍
<tr valign=top>␍
<td><a href="ov_comment.html">ov_comment</a></td>␍
<td>Returns attached <a href="vorbis_comment.html">comments</a> for the current bitstream.</td>␍
</tr>␍
</table>␍
␍
<br><br>␍
<hr noshade>␍
<table border=0 width=100%>␍
<tr valign=top>␍
<td><p class=tiny>copyright &copy; 2002 Xiph.org</p></td>␍
<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td>␍
</tr><tr>␍
<td><p class=tiny>Vorbisfile documentation</p></td>␍
<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>␍
</tr>␍
</table>␍
␍
</body>␍
␍
</html>␍
etc/Library/OggVobisSDK/doc/vorbis/vorbisfile/index.html
+49
View File
@@ -0,0 +1,49 @@
<html>
<head>
<title>Vorbisfile - Documentation</title>
<link rel=stylesheet href="style.css" type="text/css">
</head>
<body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
<table border=0 width=100%>
<tr>
<td><p class=tiny>Vorbisfile documentation</p></td>
<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
</tr>
</table>
<h1>Vorbisfile Documentation</h1>
<p>
The Vorbisfile library provides a convenient high-level API for
decoding and basic manipulation of all Vorbis I audio streams.
Libvorbisfile is implemented as a layer on top of Xiph.org's reference
libogg and libvorbis libraries.<p>
Vorbisfile can be used along with any ANSI compliant stdio implementation
for file/stream access, or use custom stream i/o routines provided by
the embedded environment. Both uses are described in detail in this
documentation.
<p>
<a href="overview.html">API overview</a><br>
<a href="reference.html">API reference</a><br>
<a href="example.html">Example code</a><br>
<br><br>
<hr noshade>
<table border=0 width=100%>
<tr valign=top>
<td><p class=tiny>copyright &copy; 2002 Xiph.org</p></td>
<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td>
</tr><tr>
<td><p class=tiny>Vorbisfile documentation</p></td>
<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
</tr>
</table>
</body>
</html>
etc/Library/OggVobisSDK/doc/vorbis/vorbisfile/initialization.html
+101
View File
@@ -0,0 +1,101 @@
<html>
<head>
<title>Vorbisfile - Setup/Teardown</title>
<link rel=stylesheet href="style.css" type="text/css">
</head>
<body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
<table border=0 width=100%>
<tr>
<td><p class=tiny>Vorbisfile documentation</p></td>
<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
</tr>
</table>
<H1>Setup/Teardown</h1> <p>In order to decode audio using
libvorbisfile, a bitstream containing Vorbis audio must be properly
initialized before decoding and cleared when decoding is finished.
The simplest possible case is to use <tt>fopen()</tt> to open a Vorbis
file and then pass the <tt>FILE *</tt> to an <a
href="ov_open.html">ov_open()</a> call. A successful <a
href="return.html">return code</a> from <a
href="ov_open.html">ov_open()</a> indicates the file is ready for use.
Once the file is no longer needed, <a
href="ov_clear.html">ov_clear()</a> is used to close the file and
deallocate decoding resources. </b>Do not</b> call <tt>fclose()</tt> on the
file; libvorbisfile does this in the <a
href="ov_clear.html">ov_clear()</a> call.
<p>
All libvorbisfile initialization and deallocation routines are declared in "vorbis/vorbisfile.h".
<p>
<table border=1 color=black width=50% cellspacing=0 cellpadding=7>
<tr bgcolor=#cccccc>
<td><b>function</b></td>
<td><b>purpose</b></td>
</tr>
<tr valign=top>
<td><a href="ov_open.html">ov_open</a></td>
<td>Initializes the Ogg Vorbis bitstream with a pointer to a bitstream and default values. This must be called before other functions in the library may be
used.</td>
</tr>
<tr valign=top>
<td><a href="ov_open_callbacks.html">ov_open_callbacks</a></td>
<td>Initializes the Ogg Vorbis bitstream with a pointer to a bitstream, default values, and custom file/bitstream manipulation routines. Used instead of <a href="ov_open.html">ov_open()</a> when working with other than stdio based I/O.</td>
</tr>
<tr valign=top>
<td><a href="ov_test.html">ov_test</a></td>
<td>Partially opens a file just far enough to determine if the file
is an Ogg Vorbis file or not. A successful return indicates that the
file appears to be an Ogg Vorbis file, but the <a
href="OggVorbis_File.html">OggVorbis_File</a> struct is not yet fully
initialized for actual decoding. After a <a href="return.html">successful return</a>, the file
may be closed using <a href="ov_clear.html">ov_clear()</a> or fully
opened for decoding using <a
href="ov_test_open.html">ov_test_open()</a>.<p> This call is intended to
be used as a less expensive file open test than a full <a
href="ov_open.html">ov_open()</a>.<p>
Note that libvorbisfile owns the passed in file resource is it returns success; do not <tt>fclose()</tt> files owned by libvorbisfile.</td>
</tr>
<tr valign=top>
<td><a href="ov_test_callbacks.html">ov_test_callbacks</a></td>
<td>As above but allowing application-define I/O callbacks.<p>
Note that libvorbisfile owns the passed in file resource is it returns success; do not <tt>fclose()</tt> files owned by libvorbisfile.</td>
</tr>
<tr valign=top>
<td><a href="ov_test_open.html">ov_test_open</a><td>
Finish opening a file after a successful call to <a href="ov_test.html">ov_test()</a> or <a href="ov_test_callbacks.html">ov_test_callbacks()</a>.</td>
</tr>
<tr valign=top>
<td><a href="ov_clear.html">ov_clear</a></td> <td>Closes the
bitstream and cleans up loose ends. Must be called when
finished with the bitstream. After return, the <a
href="OggVorbis_File.html">OggVorbis_File</a> struct is
invalid and may not be used before being initialized again
before begin reinitialized.
</td>
</tr>
</table>
<br><br>
<hr noshade>
<table border=0 width=100%>
<tr valign=top>
<td><p class=tiny>copyright &copy; 2002 Xiph.org</p></td>
<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td>
</tr><tr>
<td><p class=tiny>Vorbisfile documentation</p></td>
<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
</tr>
</table>
</body>
</html>
etc/Library/OggVobisSDK/doc/vorbis/vorbisfile/ov_bitrate.html
+72
View File
@@ -0,0 +1,72 @@
<html>
<head>
<title>Vorbisfile - function - ov_bitrate</title>
<link rel=stylesheet href="style.css" type="text/css">
</head>
<body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
<table border=0 width=100%>
<tr>
<td><p class=tiny>Vorbisfile documentation</p></td>
<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
</tr>
</table>
<h1>ov_bitrate</h1>
<p><i>declared in "vorbis/vorbisfile.h";</i></p>
<p>This function returns the average bitrate for the specified logical bitstream. This may be different from the <a href=ov_info.html>ov_info->nominal_bitrate</a> value, as it is based on the actual average for this bitstream if the file is seekable.
<p>Nonseekable files will return the nominal bitrate setting or the average of the upper and lower bounds, if any of these values are set.
<p>
<br><br>
<table border=0 color=black cellspacing=0 cellpadding=7>
<tr bgcolor=#cccccc>
<td>
<pre><b>
long ov_bitrate(OggVorbis_File *vf,int i);
</b></pre>
</td>
</tr>
</table>
<h3>Parameters</h3>
<dl>
<dt><i>vf</i></dt>
<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile
functions.</dd>
<dt><i>i</i></dt>
<dd>Link to the desired logical bitstream. For nonseekable files, this argument is ignored. To retrieve the bitrate for the entire bitstream, this parameter should be set to -1.</dd>
</dl>
<h3>Return Values</h3>
<blockquote>
<li>OV_EINVAL indicates that an invalid argument value was submitted or that the stream represented by <tt>vf</tt> is not open.</li>
<li>OV_FALSE means the call returned a 'false' status, which in this case most likely indicates that the file is nonseekable and the upper, lower, and nominal bitrates were unset.
<li><i>n</i> indicates the bitrate for the given logical bitstream or the entire
physical bitstream. If the file is open for random (seekable) access, it will
find the *actual* average bitrate. If the file is streaming (nonseekable), it
returns the nominal bitrate (if set) or else the average of the
upper/lower bounds (if set).</li>
</blockquote>
<p>
<br><br>
<hr noshade>
<table border=0 width=100%>
<tr valign=top>
<td><p class=tiny>copyright &copy; 2002 Xiph.org</p></td>
<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td>
</tr><tr>
<td><p class=tiny>Vorbisfile documentation</p></td>
<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
</tr>
</table>
</body>
</html>
etc/Library/OggVobisSDK/doc/vorbis/vorbisfile/ov_bitrate_instant.html
+65
View File
@@ -0,0 +1,65 @@
<html>
<head>
<title>Vorbisfile - function - ov_bitrate</title>
<link rel=stylesheet href="style.css" type="text/css">
</head>
<body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
<table border=0 width=100%>
<tr>
<td><p class=tiny>Vorbisfile documentation</p></td>
<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
</tr>
</table>
<h1>ov_bitrate_instant</h1>
<p><i>declared in "vorbis/vorbisfile.h";</i></p>
<p>Used to find the most recent bitrate played back within the file. Will return 0 if the bitrate has not changed or it is the beginning of the file.
<br><br>
<table border=0 color=black cellspacing=0 cellpadding=7>
<tr bgcolor=#cccccc>
<td>
<pre><b>
long ov_bitrate_instant(OggVorbis_File *vf);
</b></pre>
</td>
</tr>
</table>
<h3>Parameters</h3>
<dl>
<dt><i>vf</i></dt>
<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile
functions.
</dl>
<h3>Return Values</h3>
<blockquote>
<li>0 indicates the beginning of the file or unchanged bitrate info.</li>
<li><i>n</i> indicates the actual bitrate since the last call.</li>
<li>OV_FALSE indicates that playback is not in progress, and thus there is no instantaneous bitrate information to report.</li>
<li>OV_EINVAL indicates that the stream represented by <tt>vf</tt> is not open.</li>
</blockquote>
<p>
<br><br>
<hr noshade>
<table border=0 width=100%>
<tr valign=top>
<td><p class=tiny>copyright &copy; 2002 Xiph.org</p></td>
<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td>
</tr><tr>
<td><p class=tiny>Vorbisfile documentation</p></td>
<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
</tr>
</table>
</body>
</html>
etc/Library/OggVobisSDK/doc/vorbis/vorbisfile/ov_callbacks.html
+78
View File
@@ -0,0 +1,78 @@
<html>
<head>
<title>Vorbisfile - datatype - ov_callbacks</title>
<link rel=stylesheet href="style.css" type="text/css">
</head>
<body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
<table border=0 width=100%>
<tr>
<td><p class=tiny>Vorbisfile documentation</p></td>
<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
</tr>
</table>
<h1>ov_callbacks</h1>
<p><i>declared in "vorbis/codec.h"</i></p>
<p>
The ov_callbacks structure contains file manipulation function prototypes necessary for opening, closing, seeking, and location.
<p>
The ov_callbacks structure does not need to be user-defined if you are
working with stdio-based file manipulation; the <a
href="ov_open.html">ov_open()</a> call provides default callbacks for
stdio. ov_callbacks are defined and passed to <a
href="ov_open_callbacks.html">ov_open_callbacks()</a> when
implementing non-stdio based stream manipulation (such as playback
from a memory buffer).
<p>
<table border=0 width=100% color=black cellspacing=0 cellpadding=7>
<tr bgcolor=#cccccc>
<td>
<pre><b>typedef struct {
size_t (*read_func) (void *ptr, size_t size, size_t nmemb, void *datasource);
int (*seek_func) (void *datasource, ogg_int64_t offset, int whence);
int (*close_func) (void *datasource);
long (*tell_func) (void *datasource);
} ov_callbacks;</b></pre>
</td>
</tr>
</table>
<h3>Relevant Struct Members</h3>
<dl>
<dt><i>read_func</i></dt>
<dd>Pointer to custom data reading function.</dd>
<dt><i>seek_func</i></dt>
<dd>Pointer to custom data seeking function. If the data source is not seekable (or the application wants the data source to be treated as unseekable at all times), the provided seek callback should always return -1 (failure).</dd>
<dt><i>close_func</i></dt>
<dd>Pointer to custom data source closure function.</dd>
<dt><i>tell_func</i></dt>
<dd>Pointer to custom data location function.</dd>
</dl>
<p>
See <a href="callbacks.html">the callbacks and non-stdio I/O document</a> for more
detailed information on required behavior of the various callback
functions.<p>
<br><br>
<hr noshade>
<table border=0 width=100%>
<tr valign=top>
<td><p class=tiny>copyright &copy; 2002 Xiph.org</p></td>
<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td>
</tr><tr>
<td><p class=tiny>Vorbisfile documentation</p></td>
<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
</tr>
</table>
</body>
</html>
etc/Library/OggVobisSDK/doc/vorbis/vorbisfile/ov_clear.html
+64
View File
@@ -0,0 +1,64 @@
<html>
<head>
<title>Vorbisfile - function - ov_clear</title>
<link rel=stylesheet href="style.css" type="text/css">
</head>
<body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
<table border=0 width=100%>
<tr>
<td><p class=tiny>Vorbisfile documentation</p></td>
<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
</tr>
</table>
<h1>ov_clear</h1>
<p><i>declared in "vorbis/vorbisfile.h";</i></p>
<p> After a bitstream has been opened using <a href="ov_open.html">ov_open()</a>/<a href="ov_open_callbacks.html">ov_open_callbacks()</a> and decoding is complete, the application must call <tt>ov_clear()</tt> to clear
the decoder's buffers and close the file.<p>
<tt>ov_clear()</tt> must also be called after a successful call to <a href="ov_test.html">ov_test()</a> or <a href="ov_test_callbacks.html">ov_test_callbacks()</a>.<p>
<br><br>
<table border=0 color=black cellspacing=0 cellpadding=7>
<tr bgcolor=#cccccc>
<td>
<pre><b>
int ov_clear(OggVorbis_File *vf);
</b></pre>
</td>
</tr>
</table>
<h3>Parameters</h3>
<dl>
<dt><i>vf</i></dt>
<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile
functions. After <tt>ov_clear</tt> has been called, the structure is deallocated and can no longer be used.</dd>
</dl>
<h3>Return Values</h3>
<blockquote>
<li>0 for success</li>
</blockquote>
<br><br>
<hr noshade>
<table border=0 width=100%>
<tr valign=top>
<td><p class=tiny>copyright &copy; 2002 Xiph.org</p></td>
<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td>
</tr><tr>
<td><p class=tiny>Vorbisfile documentation</p></td>
<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
</tr>
</table>
</body>
</html>
etc/Library/OggVobisSDK/doc/vorbis/vorbisfile/ov_comment.html
+66
View File
@@ -0,0 +1,66 @@
<html>
<head>
<title>Vorbisfile - function - ov_bitrate</title>
<link rel=stylesheet href="style.css" type="text/css">
</head>
<body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
<table border=0 width=100%>
<tr>
<td><p class=tiny>Vorbisfile documentation</p></td>
<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
</tr>
</table>
<h1>ov_comment</h1>
<p><i>declared in "vorbis/vorbisfile.h";</i></p>
<p>Returns a pointer to the <a href="vorbis_comment.html">vorbis_comment</a> struct for the specified bitstream. For nonseekable streams, returns the struct for the current bitstream.
<p>
<br><br>
<table border=0 color=black cellspacing=0 cellpadding=7>
<tr bgcolor=#cccccc>
<td>
<pre><b>
vorbis_comment *ov_comment(OggVorbis_File *vf,int link);
</b></pre>
</td>
</tr>
</table>
<h3>Parameters</h3>
<dl>
<dt><i>vf</i></dt>
<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile
functions.</dd>
<dt><i>i</i></dt>
<dd>Link to the desired logical bitstream. For nonseekable files, this argument is ignored. To retrieve the <a href="vorbis_comment.html">vorbis_comment</a> struct for the current bitstream, this parameter should be set to -1.</dd>
</dl>
<h3>Return Values</h3>
<blockquote>
<li>Returns the vorbis_comment struct for the specified bitstream.</li>
<li>NULL if the specified bitstream does not exist or the file has been initialized improperly.</li>
</blockquote>
<p>
<br><br>
<hr noshade>
<table border=0 width=100%>
<tr valign=top>
<td><p class=tiny>copyright &copy; 2002 Xiph.org</p></td>
<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td>
</tr><tr>
<td><p class=tiny>Vorbisfile documentation</p></td>
<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
</tr>
</table>
</body>
</html>
etc/Library/OggVobisSDK/doc/vorbis/vorbisfile/ov_info.html
+64
View File
@@ -0,0 +1,64 @@
<html>
<head>
<title>Vorbisfile - function - ov_info</title>
<link rel=stylesheet href="style.css" type="text/css">
</head>
<body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
<table border=0 width=100%>
<tr>
<td><p class=tiny>Vorbisfile documentation</p></td>
<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
</tr>
</table>
<h1>ov_info</h1>
<p><i>declared in "vorbis/vorbisfile.h";</i></p>
<p>Returns the <a href="vorbis_info.html">vorbis_info</a> struct for the specified bitstream. For nonseekable files, always returns the current vorbis_info struct.
<br><br>
<table border=0 color=black cellspacing=0 cellpadding=7>
<tr bgcolor=#cccccc>
<td>
<pre><b>
vorbis_info *ov_info(<a href="OggVorbis_File.html">OggVorbis_File</a> *vf,int link);
</b></pre>
</td>
</tr>
</table>
<h3>Parameters</h3>
<dl>
<dt><i>vf</i></dt>
<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile
functions. </dd>
<dt><i>i</i></dt>
<dd>Link to the desired logical bitstream. For nonseekable files, this argument is ignored. To retrieve the <a href="vorbis_info.html">vorbis_info</a> struct for the current bitstream, this parameter should be set to -1.</dd>
</dl>
<h3>Return Values</h3>
<blockquote>
<li>Returns the vorbis_info struct for the specified bitstream. Returns vorbis_info for current bitstream if the file is nonseekable or i=-1.</li>
<li>NULL if the specified bitstream does not exist or the file has been initialized improperly.</li>
</blockquote>
<p>
<br><br>
<hr noshade>
<table border=0 width=100%>
<tr valign=top>
<td><p class=tiny>copyright &copy; 2002 Xiph.org</p></td>
<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td>
</tr><tr>
<td><p class=tiny>Vorbisfile documentation</p></td>
<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
</tr>
</table>
</body>
</html>
etc/Library/OggVobisSDK/doc/vorbis/vorbisfile/ov_open.html
+115
View File
@@ -0,0 +1,115 @@
<html>
<head>
<title>Vorbisfile - function - ov_open</title>
<link rel=stylesheet href="style.css" type="text/css">
</head>
<body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
<table border=0 width=100%>
<tr>
<td><p class=tiny>Vorbisfile documentation</p></td>
<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
</tr>
</table>
<h1>ov_open</h1>
<p><i>declared in "vorbis/vorbisfile.h";</i></p>
<p>This is the main function used to open and initialize an OggVorbis_File
structure. It sets up all the related decoding structure.
<p>The first argument must be a file pointer to an already opened file
or pipe (it need not be seekable--though this obviously restricts what
can be done with the bitstream). <tt>vf</tt> should be a pointer to the
OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile
functions. Once this has been called, the same <a href="OggVorbis_File.html">OggVorbis_File</a>
struct should be passed to all the libvorbisfile functions.
<p>Also, you should be aware that ov_open(), once successful, takes complete possession of the file resource. After you have opened a file using ov_open(), you MUST close it using <a href="ov_clear.html">ov_clear()</a>, not fclose() or any other function.
<p>
It is often useful to call <tt>ov_open()</tt>
simply to determine whether a given file is a vorbis bitstream. If the
<tt>ov_open()</tt>
call fails, then the file is not recognizable as such.
When you use <tt>ov_open()
</tt>for
this, you should <tt>fclose()</tt> the file pointer if, and only if, the
<tt>ov_open()</tt>
call fails. If it succeeds, you must call <a href="ov_clear.html">ov_clear()</a> to clear
the decoder's buffers and close the file for you.<p>
(Note that <a href="ov_test.html">ov_test()</a> provides a less expensive way to test a file for Vorbisness.)<p>
<br><br>
<table border=0 color=black cellspacing=0 cellpadding=7>
<tr bgcolor=#cccccc>
<td>
<pre><b>
int ov_open(FILE *f,<a href="OggVorbis_File.html">OggVorbis_File</a> *vf,char *initial,long ibytes);
</b></pre>
</td>
</tr>
</table>
<h3>Parameters</h3>
<dl>
<dt><i>f</i></dt>
<dd>File pointer to an already opened file
or pipe (it need not be seekable--though this obviously restricts what
can be done with the bitstream).</dd>
<dt><i>vf</i></dt>
<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile
functions. Once this has been called, the same <tt>OggVorbis_File</tt>
struct should be passed to all the libvorbisfile functions.</dd>
<dt><i>initial</i></dt>
<dd>Typically set to NULL. This parameter is useful if some data has already been
read from the file and the stream is not seekable. It is used in conjunction with <tt>ibytes</tt>. In this case, <tt>initial</tt>
should be a pointer to a buffer containing the data read.</dd>
<dt><i>ibytes</i></dt>
<dd>Typically set to 0. This parameter is useful if some data has already been
read from the file and the stream is not seekable. In this case, <tt>ibytes</tt>
should contain the length (in bytes) of the buffer. Used together with <tt>initial</tt></dd>
</dl>
<h3>Return Values</h3>
<blockquote>
<li>0 indicates success</li>
<li>less than zero for failure:</li>
<ul>
<li>OV_EREAD - A read from media returned an error.</li>
<li>OV_ENOTVORBIS - Bitstream is not Vorbis data.</li>
<li>OV_EVERSION - Vorbis version mismatch.</li>
<li>OV_EBADHEADER - Invalid Vorbis bitstream header.</li>
<li>OV_EFAULT - Internal logic fault; indicates a bug or heap/stack corruption.</li>
</ul>
</blockquote>
<p>
<h3>Notes</h3>
<p>If your decoder is threaded, it is recommended that you NOT call
<tt>ov_open()</tt>
in the main control thread--instead, call <tt>ov_open()</tt> IN your decode/playback
thread. This is important because <tt>ov_open()</tt> may be a fairly time-consuming
call, given that the full structure of the file is determined at this point,
which may require reading large parts of the file under certain circumstances
(determining all the logical bitstreams in one physical bitstream, for
example). See <a href="threads.html">Thread Safety</a> for other information on using libvorbisfile with threads.
<br><br>
<hr noshade>
<table border=0 width=100%>
<tr valign=top>
<td><p class=tiny>copyright &copy; 2002 Xiph.org</p></td>
<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td>
</tr><tr>
<td><p class=tiny>Vorbisfile documentation</p></td>
<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
</tr>
</table>
</body>
</html>
etc/Library/OggVobisSDK/doc/vorbis/vorbisfile/ov_open_callbacks.html
+110
View File
@@ -0,0 +1,110 @@
<html>
<head>
<title>Vorbisfile - function - ov_open_callbacks</title>
<link rel=stylesheet href="style.css" type="text/css">
</head>
<body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
<table border=0 width=100%>
<tr>
<td><p class=tiny>Vorbisfile documentation</p></td>
<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
</tr>
</table>
<h1>ov_open_callbacks</h1>
<p><i>declared in "vorbis/vorbisfile.h";</i></p>
<p>This is an alternative function used to open and initialize an OggVorbis_File
structure when using a data source other than a file. It allows you to specify custom file manipulation routines and sets up all the related decoding structure.
<p>Once this has been called, the same <tt>OggVorbis_File</tt>
struct should be passed to all the libvorbisfile functions.
<p>
It is often useful to call <tt>ov_open_callbacks()</tt>
simply to determine whether a given file is a vorbis bitstream. If the
<tt>ov_open_callbacks()</tt>
call fails, then the file is not recognizable as such. When you use <tt>ov_open_callbacks()
</tt>for
this, you should <tt>fclose()</tt> the file pointer if, and only if, the
<tt>ov_open_callbacks()</tt>
call fails. If it succeeds, you must call <a href=ov_clear.html>ov_clear()</a> to clear
the decoder's buffers and close the file for you.<p>
See also <a href="callbacks.html">Callbacks and Non-stdio I/O</a> for information on designing and specifying the required callback functions.<p>
<br><br>
<table border=0 color=black cellspacing=0 cellpadding=7>
<tr bgcolor=#cccccc>
<td>
<pre><b>
int ov_open_callbacks(void *datasource, <a href="OggVorbis_File.html">OggVorbis_File</a> *vf, char *initial, long ibytes, <a href="ov_callbacks.html">ov_callbacks</a> callbacks);
</b></pre>
</td>
</tr>
</table>
<h3>Parameters</h3>
<dl>
<dt><i>f</i></dt>
<dd>File pointer to an already opened file
or pipe (it need not be seekable--though this obviously restricts what
can be done with the bitstream).</dd>
<dt><i>vf</i></dt>
<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile
functions. Once this has been called, the same <tt>OggVorbis_File</tt>
struct should be passed to all the libvorbisfile functions.</dd>
<dt><i>initial</i></dt>
<dd>Typically set to NULL. This parameter is useful if some data has already been
read from the file and the stream is not seekable. It is used in conjunction with <tt>ibytes</tt>. In this case, <tt>initial</tt>
should be a pointer to a buffer containing the data read.</dd>
<dt><i>ibytes</i></dt>
<dd>Typically set to 0. This parameter is useful if some data has already been
read from the file and the stream is not seekable. In this case, <tt>ibytes</tt>
should contain the length (in bytes) of the buffer. Used together with <tt>initial</tt>.</dd>
<dt><i>callbacks</i></dt>
<dd>Pointer to a completed <a href="ov_callbacks.html">ov_callbacks</a> struct which indicates desired custom file manipulation routines.</dd>
</dl>
<h3>Return Values</h3>
<blockquote>
<li>0 for success</li>
<li>less than zero for failure:</li>
<ul>
<li>OV_EREAD - A read from media returned an error.</li>
<li>OV_ENOTVORBIS - Bitstream is not Vorbis data.</li>
<li>OV_EVERSION - Vorbis version mismatch.</li>
<li>OV_EBADHEADER - Invalid Vorbis bitstream header.</li>
<li>OV_EFAULT - Internal logic fault; indicates a bug or heap/stack corruption.</li>
</ul>
</blockquote>
<p>
<h3>Notes</h3>
<p>If your decoder is threaded, it is recommended that you NOT call
<tt>ov_open_callbacks()</tt>
in the main control thread--instead, call <tt>ov_open_callbacks()</tt> IN your decode/playback
thread. This is important because <tt>ov_open_callbacks()</tt> may be a fairly time-consuming
call, given that the full structure of the file is determined at this point,
which may require reading large parts of the file under certain circumstances
(determining all the logical bitstreams in one physical bitstream, for
example).
See <a href="threads.html">Thread Safety</a> for other information on using libvorbisfile with threads.
<br><br>
<hr noshade>
<table border=0 width=100%>
<tr valign=top>
<td><p class=tiny>copyright &copy; 2002 Xiph.org</p></td>
<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td>
</tr><tr>
<td><p class=tiny>Vorbisfile documentation</p></td>
<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
</tr>
</table>
</body>
</html>
etc/Library/OggVobisSDK/doc/vorbis/vorbisfile/ov_pcm_seek.html
+81
View File
@@ -0,0 +1,81 @@
<html>
<head>
<title>Vorbisfile - function - ov_pcm_seek</title>
<link rel=stylesheet href="style.css" type="text/css">
</head>
<body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
<table border=0 width=100%>
<tr>
<td><p class=tiny>Vorbisfile documentation</p></td>
<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
</tr>
</table>
<h1>ov_pcm_seek</h1>
<p><i>declared in "vorbis/vorbisfile.h";</i></p>
<p>Seeks to the offset specified (in pcm samples) within the physical bitstream. This function only works for seekable streams.
<p>This also updates everything needed within the
decoder, so you can immediately call <a href="ov_read.html">ov_read()</a> and get data from
the newly seeked to position.
<p>
<br><br>
<table border=0 color=black cellspacing=0 cellpadding=7>
<tr bgcolor=#cccccc>
<td>
<pre><b>
int ov_pcm_seek(OggVorbis_File *vf,ogg_int64_t pos);
</b></pre>
</td>
</tr>
</table>
<h3>Parameters</h3>
<dl>
<dt><i>vf</i></dt>
<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile
functions.</dd>
<dt><i>pos</i></dt>
<dd>Position in pcm samples to seek to in the bitstream.</dd>
</dl>
<h3>Return Values</h3>
<blockquote>
<li>0 for success</li>
<li>
nonzero indicates failure, described by several error codes:</li>
<ul>
<li>OV_ENOSEEK - Bitstream is not seekable.
</li>
<li>OV_EINVAL - Invalid argument value.
</li>
<li>OV_EREAD - A read from media returned an error.
</li>
<li>OV_EFAULT - Internal logic fault; indicates a bug or heap/stack
corruption.
</li>
<li>OV_EBADLINK - Invalid stream section supplied to libvorbisfile, or the requested link is corrupt.
</li>
</ul></blockquote>
<br><br>
<hr noshade>
<table border=0 width=100%>
<tr valign=top>
<td><p class=tiny>copyright &copy; 2002 Xiph.org</p></td>
<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td>
</tr><tr>
<td><p class=tiny>Vorbisfile documentation</p></td>
<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
</tr>
</table>
</body>
</html>
etc/Library/OggVobisSDK/doc/vorbis/vorbisfile/ov_pcm_seek_page.html
+83
View File
@@ -0,0 +1,83 @@
<html>
<head>
<title>Vorbisfile - function - ov_pcm_seek_page</title>
<link rel=stylesheet href="style.css" type="text/css">
</head>
<body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
<table border=0 width=100%>
<tr>
<td><p class=tiny>Vorbisfile documentation</p></td>
<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
</tr>
</table>
<h1>ov_pcm_seek_page</h1>
<p><i>declared in "vorbis/vorbisfile.h";</i></p>
<p>Seeks to the closest page preceding the specified location (in pcm samples) within the physical bitstream. This function only works for seekable streams.
<p>This function is faster than <a href="ov_pcm_seek.html">ov_pcm_seek</a> because the function can begin decoding at a page boundary rather than seeking through any remaining samples before the specified location. However, it is less accurate.
<p>This also updates everything needed within the
decoder, so you can immediately call <a href="ov_read.html">ov_read()</a> and get data from
the newly seeked to position.
<p>
<br><br>
<table border=0 color=black cellspacing=0 cellpadding=7>
<tr bgcolor=#cccccc>
<td>
<pre><b>
int ov_pcm_seek_page(OggVorbis_File *vf,ogg_int64_t pos);
</b></pre>
</td>
</tr>
</table>
<h3>Parameters</h3>
<dl>
<dt><i>vf</i></dt>
<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile
functions.</dd>
<dt><i>pos</i></dt>
<dd>Position in pcm samples to seek to in the bitstream.</dd>
</dl>
<h3>Return Values</h3>
<blockquote>
<li>
0 for success</li>
<li>
nonzero indicates failure, described by several error codes:</li>
<ul>
<li>OV_ENOSEEK - Bitstream is not seekable.
</li>
<li>OV_EINVAL - Invalid argument value.
</li>
<li>OV_EREAD - A read from media returned an error.
</li>
<li>OV_EFAULT - Internal logic fault; indicates a bug or heap/stack
corruption.
</li>
<li>OV_EBADLINK - Invalid stream section supplied to libvorbisfile, or the requested link is corrupt.
</li>
</ul></blockquote>
<br><br>
<hr noshade>
<table border=0 width=100%>
<tr valign=top>
<td><p class=tiny>copyright &copy; 2002 Xiph.org</p></td>
<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td>
</tr><tr>
<td><p class=tiny>Vorbisfile documentation</p></td>
<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
</tr>
</table>
</body>
</html>
etc/Library/OggVobisSDK/doc/vorbis/vorbisfile/ov_pcm_tell.html
+63
View File
@@ -0,0 +1,63 @@
<html>
<head>
<title>Vorbisfile - function - ov_pcm_tell</title>
<link rel=stylesheet href="style.css" type="text/css">
</head>
<body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
<table border=0 width=100%>
<tr>
<td><p class=tiny>Vorbisfile documentation</p></td>
<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
</tr>
</table>
<h1>ov_pcm_tell</h1>
<p><i>declared in "vorbis/vorbisfile.h";</i></p>
<p>Returns the current offset in samples.
<br><br>
<table border=0 color=black cellspacing=0 cellpadding=7>
<tr bgcolor=#cccccc>
<td>
<pre><b>
ogg_int64_t ov_pcm_tell(OggVorbis_File *vf);
</b></pre>
</td>
</tr>
</table>
<h3>Parameters</h3>
<dl>
<dt><i>vf</i></dt>
<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile
functions.</dd>
</dl>
<h3>Return Values</h3>
<blockquote>
<li><i>n</i> indicates the current offset in samples.</li>
<li>OV_EINVAL means that the argument was invalid. In this case, the requested bitstream did not exist.</li>
</blockquote>
<p>
<br><br>
<hr noshade>
<table border=0 width=100%>
<tr valign=top>
<td><p class=tiny>copyright &copy; 2002 Xiph.org</p></td>
<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td>
</tr><tr>
<td><p class=tiny>Vorbisfile documentation</p></td>
<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
</tr>
</table>
</body>
</html>
etc/Library/OggVobisSDK/doc/vorbis/vorbisfile/ov_pcm_total.html
+67
View File
@@ -0,0 +1,67 @@
<html>
<head>
<title>Vorbisfile - function - ov_pcm_total</title>
<link rel=stylesheet href="style.css" type="text/css">
</head>
<body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
<table border=0 width=100%>
<tr>
<td><p class=tiny>Vorbisfile documentation</p></td>
<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
</tr>
</table>
<h1>ov_pcm_total</h1>
<p><i>declared in "vorbis/vorbisfile.h";</i></p>
<p>Returns the total pcm samples of the physical bitstream or a specified logical bitstream.
<br><br>
<table border=0 color=black cellspacing=0 cellpadding=7>
<tr bgcolor=#cccccc>
<td>
<pre><b>
ogg_int64_t ov_pcm_total(OggVorbis_File *vf,int i);
</b></pre>
</td>
</tr>
</table>
<h3>Parameters</h3>
<dl>
<dt><i>vf</i></dt>
<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile
functions.</dd>
<dt><i>i</i></dt>
<dd>Link to the desired logical bitstream. To retrieve the total pcm samples for the entire physical bitstream, this parameter should be set to -1.</dd>
</dl>
<h3>Return Values</h3>
<blockquote>
<li>OV_EINVAL means that the argument was invalid. In this case, the requested bitstream did not exist or the bitstream is unseekable.</li>
<li>
total length in pcm samples of content if i=-1.</li>
<li>length in pcm samples of logical bitstream if i=1 to n.</li>
</blockquote>
<p>
<br><br>
<hr noshade>
<table border=0 width=100%>
<tr valign=top>
<td><p class=tiny>copyright &copy; 2002 Xiph.org</p></td>
<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td>
</tr><tr>
<td><p class=tiny>Vorbisfile documentation</p></td>
<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
</tr>
</table>
</body>
</html>
etc/Library/OggVobisSDK/doc/vorbis/vorbisfile/ov_raw_seek.html
+75
View File
@@ -0,0 +1,75 @@
<html>
<head>
<title>Vorbisfile - function - ov_raw_seek</title>
<link rel=stylesheet href="style.css" type="text/css">
</head>
<body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
<table border=0 width=100%>
<tr>
<td><p class=tiny>Vorbisfile documentation</p></td>
<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
</tr>
</table>
<h1>ov_raw_seek</h1>
<p><i>declared in "vorbis/vorbisfile.h";</i></p>
<p>Seeks to the offset specified (in compressed raw bytes) within the physical bitstream. This function only works for seekable streams.
<p>This also updates everything needed within the
decoder, so you can immediately call <a href="ov_read.html">ov_read()</a> and get data from
the newly seeked to position.
<p>When seek speed is a priority, this is the best seek funtion to use.
<br><br>
<table border=0 color=black cellspacing=0 cellpadding=7>
<tr bgcolor=#cccccc>
<td>
<pre><b>
int ov_raw_seek(OggVorbis_File *vf,long pos);
</b></pre>
</td>
</tr>
</table>
<h3>Parameters</h3>
<dl>
<dt><i>vf</i></dt>
<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile
functions.</dd>
<dt><i>pos</i></dt>
<dd>Position in compressed bytes to seek to in the bitstream.</dd>
</dl>
<h3>Return Values</h3>
<blockquote>
<li>0 indicates success</li>
<li>nonzero indicates failure, described by several error codes:</li>
<ul>
<li>OV_ENOSEEK - Bitstream is not seekable.
</li>
<li>OV_EINVAL - Invalid argument value.
</li>
<li>OV_EBADLINK - Invalid stream section supplied to libvorbisfile, or the requested link is corrupt.
</li>
</ul>
</blockquote>
<p>
<br><br>
<hr noshade>
<table border=0 width=100%>
<tr valign=top>
<td><p class=tiny>copyright &copy; 2002 Xiph.org</p></td>
<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td>
</tr><tr>
<td><p class=tiny>Vorbisfile documentation</p></td>
<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
</tr>
</table>
</body>
</html>
etc/Library/OggVobisSDK/doc/vorbis/vorbisfile/ov_raw_tell.html
+63
View File
@@ -0,0 +1,63 @@
<html>
<head>
<title>Vorbisfile - function - ov_raw_tell</title>
<link rel=stylesheet href="style.css" type="text/css">
</head>
<body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
<table border=0 width=100%>
<tr>
<td><p class=tiny>Vorbisfile documentation</p></td>
<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
</tr>
</table>
<h1>ov_raw_tell</h1>
<p><i>declared in "vorbis/vorbisfile.h";</i></p>
<p>Returns the current offset in raw compressed bytes.
<br><br>
<table border=0 color=black cellspacing=0 cellpadding=7>
<tr bgcolor=#cccccc>
<td>
<pre><b>
ogg_int64_t ov_raw_tell(OggVorbis_File *vf);
</b></pre>
</td>
</tr>
</table>
<h3>Parameters</h3>
<dl>
<dt><i>vf</i></dt>
<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile
functions.</dd>
</dl>
<h3>Return Values</h3>
<blockquote>
<li><i>n</i> indicates the current offset in bytes.</li>
<li>OV_EINVAL means that the argument was invalid. In this case, the requested bitstream did not exist.</li>
</blockquote>
<p>
<br><br>
<hr noshade>
<table border=0 width=100%>
<tr valign=top>
<td><p class=tiny>copyright &copy; 2002 Xiph.org</p></td>
<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td>
</tr><tr>
<td><p class=tiny>Vorbisfile documentation</p></td>
<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
</tr>
</table>
</body>
</html>
etc/Library/OggVobisSDK/doc/vorbis/vorbisfile/ov_raw_total.html
+68
View File
@@ -0,0 +1,68 @@
<html>
<head>
<title>Vorbisfile - function - ov_raw_total</title>
<link rel=stylesheet href="style.css" type="text/css">
</head>
<body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
<table border=0 width=100%>
<tr>
<td><p class=tiny>Vorbisfile documentation</p></td>
<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
</tr>
</table>
<h1>ov_raw_total</h1>
<p><i>declared in "vorbis/vorbisfile.h";</i></p>
<p>Returns the total (compressed) bytes of the physical bitstream or a specified logical bitstream.
<br><br>
<table border=0 color=black cellspacing=0 cellpadding=7>
<tr bgcolor=#cccccc>
<td>
<pre><b>
ogg_int64_t ov_raw_total(OggVorbis_File *vf,int i);
</b></pre>
</td>
</tr>
</table>
<h3>Parameters</h3>
<dl>
<dt><i>vf</i></dt>
<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile
functions.</dd>
<dt><i>i</i></dt>
<dd>Link to the desired logical bitstream. To retrieve the total bytes for the entire physical bitstream, this parameter should be set to -1.</dd>
</dl>
<h3>Return Values</h3>
<blockquote>
<li>OV_EINVAL means that the argument was invalid. In this case, the requested bitstream did not exist or the bitstream is nonseekable</li>
<li><tt>n</tt>
total length in compressed bytes of content if i=-1.</li>
<li><tt>n</tt> length in compressed bytes of logical bitstream if i=1 to n.</li>
</blockquote>
<p>
<br><br>
<hr noshade>
<table border=0 width=100%>
<tr valign=top>
<td><p class=tiny>copyright &copy; 2002 Xiph.org</p></td>
<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td>
</tr><tr>
<td><p class=tiny>Vorbisfile documentation</p></td>
<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
</tr>
</table>
</body>
</html>
etc/Library/OggVobisSDK/doc/vorbis/vorbisfile/ov_read.html
+123
View File
@@ -0,0 +1,123 @@
<html>
<head>
<title>Vorbisfile - function - ov_read</title>
<link rel=stylesheet href="style.css" type="text/css">
</head>
<body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
<table border=0 width=100%>
<tr>
<td><p class=tiny>Vorbisfile documentation</p></td>
<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
</tr>
</table>
<h1>ov_read()</h1>
<p><i>declared in "vorbis/vorbisfile.h";</i></p>
<p>
This is the main function used to decode a Vorbis file within a
loop. It returns up to the specified number of bytes of decoded PCM audio
in the requested endianness, signedness, and word size. If the audio is
multichannel, the channels are interleaved in the output buffer.
If the passed in buffer is large, <tt>ov_read()</tt> will not fill
it; the passed in buffer size is treated as a <em>limit</em> and
not a request.
<p>
Note that up to this point, the Vorbisfile API could more or less hide the
multiple logical bitstream nature of chaining from the toplevel
application if the toplevel application didn't particularly care.
However, when reading audio back, the application must be aware
that multiple bitstream sections do not necessarily use the same
number of channels or sampling rate. <p> <tt>ov_read()</tt> passes
back the index of the sequential logical bitstream currently being
decoded (in <tt>*bitstream</tt>) along with the PCM data in order
that the toplevel application can handle channel and/or sample
rate changes. This number will be incremented at chaining
boundaries even for non-seekable streams. For seekable streams, it
represents the actual chaining index within the physical bitstream.
<p>
<br><br>
<table border=0 color=black cellspacing=0 cellpadding=7>
<tr bgcolor=#cccccc>
<td>
<pre><b>
long ov_read(<a href="OggVorbis_File.html">OggVorbis_File</a> *vf, char *buffer, int length, int bigendianp, int word, int sgned, int *bitstream);
</b></pre>
</td>
</tr>
</table>
<h3>Parameters</h3>
<dl>
<dt><i>vf</i></dt>
<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile
functions.</dd>
<dt><i>buffer</i></dt>
<dd>A pointer to an output buffer. The decoded output is inserted into this buffer.</dd>
<dt><i>length</i></dt>
<dd>Number of bytes to be read into the buffer. Should be the same size as the buffer. A typical value is 4096.</dd>
<dt><i>bigendianp</i></dt>
<dd>Specifies big or little endian byte packing. 0 for little endian, 1 for b
ig endian. Typical value is 0.</dd>
<dt><i>word</i></dt>
<dd>Specifies word size. Possible arguments are 1 for 8-bit samples, or 2 or
16-bit samples. Typical value is 2.</dd>
<dt><i>sgned</i></dt>
<dd>Signed or unsigned data. 0 for unsigned, 1 for signed. Typically 1.</dd>
<dt><i>bitstream</i></dt>
<dd>A pointer to the number of the current logical bitstream.</dd>
</dl>
<h3>Return Values</h3>
<blockquote>
<dl>
<dt>OV_HOLE</dt>
<dd>indicates there was an interruption in the data.
<br>(one of: garbage between pages, loss of sync followed by
recapture, or a corrupt page)</dd>
<dt>OV_EBADLINK</dt>
<dd>indicates that an invalid stream section was supplied to
libvorbisfile, or the requested link is corrupt.</dd>
<dt>0</dt>
<dd>indicates EOF</dd>
<dt><i>n</i></dt>
<dd>indicates actual number of bytes read. <tt>ov_read()</tt> will
decode at most one vorbis packet per invocation, so the value
returned will generally be less than <tt>length</tt>.
</dl>
</blockquote>
<h3>Notes</h3>
<p><b>Typical usage:</b>
<blockquote>
<tt>bytes_read = ov_read(&amp;vf,
buffer, 4096,0,2,1,&amp;current_section)</tt>
</blockquote>
This reads up to 4096 bytes into a buffer, with signed 16-bit
little-endian samples.
</p>
<br><br>
<hr noshade>
<table border=0 width=100%>
<tr valign=top>
<td><p class=tiny>copyright &copy; 2002 Xiph.org</p></td>
<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td>
</tr><tr>
<td><p class=tiny>Vorbisfile documentation</p></td>
<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
</tr>
</table>
</body>
</html>
etc/Library/OggVobisSDK/doc/vorbis/vorbisfile/ov_read_float.html
+99
View File
@@ -0,0 +1,99 @@
<html>
<head>
<title>Vorbisfile - function - ov_read_float</title>
<link rel=stylesheet href="style.css" type="text/css">
</head>
<body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
<table border=0 width=100%>
<tr>
<td><p class=tiny>vorbisfile documentation</p></td>
<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
</tr>
</table>
<h1>ov_read_float()</h1>
<p><i>declared in "vorbis/vorbisfile.h";</i></p>
<p>
This is the function used to decode a Vorbis file within a loop, but
returns samples in native float format instead of in integer formats.
</p><p>
For more information on how ov_read_float() deals with the complex issues
of chaining, etc, refer to the documentation for <a href="ov_read.html">ov_read()</a>.
</p>
<br><br>
<table border=0 color=black cellspacing=0 cellpadding=7>
<tr bgcolor=#cccccc>
<td>
<pre><b>
long ov_read(<a href="OggVorbis_File.html">OggVorbis_File</a> *vf, float ***pcm_channels, int *bitstream);
</b></pre>
</td>
</tr>
</table>
<h3>Parameters</h3>
<dl>
<dt><i>vf</i></dt>
<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible vorbisfile
functions.</dd>
<dt><i>pcm_channels</i></dt>
<dd>A pointer to an output buffer. The pointer will be set to the decoded output buffer.</dd>
<dt><i>bitstream</i></dt>
<dd>A pointer to the number of the current logical bitstream.</dd>
</dl>
<h3>Return Values</h3>
<blockquote>
<dl>
<dt>OV_HOLE</dt>
<dd>indicates there was an interruption in the data.
<br>(one of: garbage between pages, loss of sync followed by
recapture, or a corrupt page)</dd>
<dt>OV_EBADLINK</dt>
<dd>indicates that an invalid stream section was supplied to
libvorbisfile, or the requested link is corrupt.</dd>
<dt>0</dt>
<dd>indicates EOF</dd>
<dt><i>n</i></dt>
<dd>indicates actual number of bytes read. <tt>ov_read()</tt> will
decode at most one vorbis packet per invocation, so the value
returned will generally be less than <tt>length</tt>.
</dl>
</blockquote>
<h3>Notes</h3>
<p><b>Typical usage:</b>
<blockquote>
<tt>float **pcm;
bytes_read = ov_read_float(&amp;vf,pcm,&amp;current_section)</tt>
</blockquote>
This decodes one packet's worth of float samples.
</p>
<br>
<br><br>
<hr noshade>
<table border=0 width=100%>
<tr valign=top>
<td><p class=tiny>copyright &copy; 2002 vorbis team</p></td>
<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/index.html">Ogg Vorbis</a><br><a href="mailto:[email protected]">[email protected]</a></p></td>
</tr><tr>
<td><p class=tiny>vorbisfile documentation</p></td>
<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
</tr>
</table>
</body>
</html>
etc/Library/OggVobisSDK/doc/vorbis/vorbisfile/ov_seekable.html
+63
View File
@@ -0,0 +1,63 @@
<html>
<head>
<title>Vorbisfile - function - ov_seekable</title>
<link rel=stylesheet href="style.css" type="text/css">
</head>
<body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
<table border=0 width=100%>
<tr>
<td><p class=tiny>Vorbisfile documentation</p></td>
<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
</tr>
</table>
<h1>ov_seekable</h1>
<p><i>declared in "vorbis/vorbisfile.h";</i></p>
<p>This indicates whether or not the bitstream is seekable.
<br><br>
<table border=0 color=black cellspacing=0 cellpadding=7>
<tr bgcolor=#cccccc>
<td>
<pre><b>
long ov_seekable(OggVorbis_File *vf);
</b></pre>
</td>
</tr>
</table>
<h3>Parameters</h3>
<dl>
<dt><i>vf</i></dt>
<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile
functions.</dd>
</dl>
<h3>Return Values</h3>
<blockquote>
<li>0 indicates that the file is not seekable.</li>
<li>nonzero indicates that the file is seekable.</li>
</blockquote>
<p>
<br><br>
<hr noshade>
<table border=0 width=100%>
<tr valign=top>
<td><p class=tiny>copyright &copy; 2002 Xiph.org</p></td>
<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td>
</tr><tr>
<td><p class=tiny>Vorbisfile documentation</p></td>
<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
</tr>
</table>
</body>
</html>
etc/Library/OggVobisSDK/doc/vorbis/vorbisfile/ov_serialnumber.html
+67
View File
@@ -0,0 +1,67 @@
<html>
<head>
<title>Vorbisfile - function - ov_serialnumber</title>
<link rel=stylesheet href="style.css" type="text/css">
</head>
<body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
<table border=0 width=100%>
<tr>
<td><p class=tiny>Vorbisfile documentation</p></td>
<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
</tr>
</table>
<h1>ov_serialnumber</h1>
<p><i>declared in "vorbis/vorbisfile.h";</i></p>
<p>Returns the serialnumber of the specified logical bitstream link number within the overall physical bitstream.
<br><br>
<table border=0 color=black cellspacing=0 cellpadding=7>
<tr bgcolor=#cccccc>
<td>
<pre><b>
long ov_serialnumber(OggVorbis_File *vf,int i);
</b></pre>
</td>
</tr>
</table>
<h3>Parameters</h3>
<dl>
<dt><i>vf</i></dt>
<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile
functions.</dd>
<dt><i>i</i></dt>
<dd>Link to the desired logical bitstream. For nonseekable files, this argument is ignored. To retrieve the serial number of the current bitstream, this parameter should be set to -1.</dd>
</dl>
<h3>Return Values</h3>
<blockquote>
<li>
-1 if the specified logical bitstream <i>i</i> does not exist.</li>
<li>Returns the serial number of the logical bitstream <i>i</i> or the serial number of the current bitstream if the file is nonseekable.</li>
</blockquote>
<p>
<br><br>
<hr noshade>
<table border=0 width=100%>
<tr valign=top>
<td><p class=tiny>copyright &copy; 2002 Xiph.org</p></td>
<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td>
</tr><tr>
<td><p class=tiny>Vorbisfile documentation</p></td>
<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
</tr>
</table>
</body>
</html>
etc/Library/OggVobisSDK/doc/vorbis/vorbisfile/ov_streams.html
+64
View File
@@ -0,0 +1,64 @@
<html>
<head>
<title>Vorbisfile - function - ov_streams</title>
<link rel=stylesheet href="style.css" type="text/css">
</head>
<body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
<table border=0 width=100%>
<tr>
<td><p class=tiny>Vorbisfile documentation</p></td>
<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
</tr>
</table>
<h1>ov_streams</h1>
<p><i>declared in "vorbis/vorbisfile.h";</i></p>
<p>Returns the number of logical bitstreams within our physical bitstream.
<br><br>
<table border=0 color=black cellspacing=0 cellpadding=7>
<tr bgcolor=#cccccc>
<td>
<pre><b>
long ov_streams(OggVorbis_File *vf);
</b></pre>
</td>
</tr>
</table>
<h3>Parameters</h3>
<dl>
<dt><i>vf</i></dt>
<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile
functions. </dd>
</dl>
<h3>Return Values</h3>
<blockquote>
<li>
1 indicates a single logical bitstream or an unseekable file.</li>
<li><i>n</i> indicates the number of logical bitstreams.</li>
</blockquote>
<p>
<br><br>
<hr noshade>
<table border=0 width=100%>
<tr valign=top>
<td><p class=tiny>copyright &copy; 2002 Xiph.org</p></td>
<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td>
</tr><tr>
<td><p class=tiny>Vorbisfile documentation</p></td>
<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
</tr>
</table>
</body>
</html>
etc/Library/OggVobisSDK/doc/vorbis/vorbisfile/ov_test.html
+89
View File
@@ -0,0 +1,89 @@
<html>
<head>
<title>Vorbisfile - function - ov_test</title>
<link rel=stylesheet href="style.css" type="text/css">
</head>
<body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
<table border=0 width=100%>
<tr>
<td><p class=tiny>Vorbisfile documentation</p></td>
<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
</tr>
</table>
<h1>ov_test</h1>
<p><i>declared in "vorbis/vorbisfile.h";</i></p>
<p>
This partially opens a vorbis file to test for Vorbis-ness. It loads
the headers for the first chain, and tests for seekability (but does not seek).
Use <a href="ov_test_open.html">ov_test_open()</a> to finish opening the file
or <a href="ov_clear.html">ov_clear</a> to close/free it.
<p>
<table border=0 color=black cellspacing=0 cellpadding=7>
<tr bgcolor=#cccccc>
<td>
<pre><b>
int ov_test(FILE *f,<a href="OggVorbis_File.html">OggVorbis_File</a> *vf,char *initial,long ibytes);
</b></pre>
</td>
</tr>
</table>
<h3>Parameters</h3>
<dl>
<dt><i>f</i></dt>
<dd>File pointer to an already opened file
or pipe (it need not be seekable--though this obviously restricts what
can be done with the bitstream).</dd>
<dt><i>vf</i></dt>
<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile
functions. Once this has been called, the same <tt>OggVorbis_File</tt>
struct should be passed to all the libvorbisfile functions.</dd>
<dt><i>initial</i></dt>
<dd>Typically set to NULL. This parameter is useful if some data has already been
read from the file and the stream is not seekable. It is used in conjunction with <tt>ibytes</tt>. In this case, <tt>initial</tt>
should be a pointer to a buffer containing the data read.</dd>
<dt><i>ibytes</i></dt>
<dd>Typically set to 0. This parameter is useful if some data has already been
read from the file and the stream is not seekable. In this case, <tt>ibytes</tt>
should contain the length (in bytes) of the buffer. Used together with <tt>initial</tt></dd>
</dl>
<h3>Return Values</h3>
<blockquote>
<li>0 for success</li>
<li>less than zero for failure:</li>
<ul>
<li>OV_EREAD - A read from media returned an error.</li>
<li>OV_ENOTVORBIS - Bitstream is not Vorbis data.</li>
<li>OV_EVERSION - Vorbis version mismatch.</li>
<li>OV_EBADHEADER - Invalid Vorbis bitstream header.</li>
<li>OV_EFAULT - Internal logic fault; indicates a bug or heap/stack corruption.</li>
</ul>
</blockquote>
<p>
<br><br>
<hr noshade>
<table border=0 width=100%>
<tr valign=top>
<td><p class=tiny>copyright &copy; 2002 Xiph.org</p></td>
<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td>
</tr><tr>
<td><p class=tiny>Vorbisfile documentation</p></td>
<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
</tr>
</table>
</body>
</html>
etc/Library/OggVobisSDK/doc/vorbis/vorbisfile/ov_test_callbacks.html
+90
View File
@@ -0,0 +1,90 @@
<html>
<head>
<title>Vorbisfile - function - ov_test_callbacks</title>
<link rel=stylesheet href="style.css" type="text/css">
</head>
<body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
<table border=0 width=100%>
<tr>
<td><p class=tiny>Vorbisfile documentation</p></td>
<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
</tr>
</table>
<h1>ov_test_callbacks</h1>
<p><i>declared in "vorbis/vorbisfile.h";</i></p>
<p>This is an alternative function used to open and test an OggVorbis_File
structure when using a data source other than a file. It allows you to specify custom file manipulation routines and sets up all the related decoding structures.
<p>Once this has been called, the same <tt>OggVorbis_File</tt>
struct should be passed to all the libvorbisfile functions.
<p>
<br><br>
<table border=0 color=black cellspacing=0 cellpadding=7>
<tr bgcolor=#cccccc>
<td>
<pre><b>
int ov_test_callbacks(void *datasource, <a href="OggVorbis_File.html">OggVorbis_File</a> *vf, char *initial, long ibytes, <a href="ov_callbacks.html">ov_callbacks</a> callbacks);
</b></pre>
</td>
</tr>
</table>
<h3>Parameters</h3>
<dl>
<dt><i>f</i></dt>
<dd>File pointer to an already opened file
or pipe (it need not be seekable--though this obviously restricts what
can be done with the bitstream).</dd>
<dt><i>vf</i></dt>
<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile
functions. Once this has been called, the same <tt>OggVorbis_File</tt>
struct should be passed to all the libvorbisfile functions.</dd>
<dt><i>initial</i></dt>
<dd>Typically set to NULL. This parameter is useful if some data has already been
read from the file and the stream is not seekable. It is used in conjunction with <tt>ibytes</tt>. In this case, <tt>initial</tt>
should be a pointer to a buffer containing the data read.</dd>
<dt><i>ibytes</i></dt>
<dd>Typically set to 0. This parameter is useful if some data has already been
read from the file and the stream is not seekable. In this case, <tt>ibytes</tt>
should contain the length (in bytes) of the buffer. Used together with <tt>initial</tt>.</dd>
<dt><i>callbacks</i></dt>
<dd>Pointer to a completed <a href="ov_callbacks.html">ov_callbacks</a> struct which indicates desired custom file manipulation routines.</dd>
</dl>
<h3>Return Values</h3>
<blockquote>
<li>0 for success</li>
<li>less than zero for failure:</li>
<ul>
<li>OV_EREAD - A read from media returned an error.</li>
<li>OV_ENOTVORBIS - Bitstream is not Vorbis data.</li>
<li>OV_EVERSION - Vorbis version mismatch.</li>
<li>OV_EBADHEADER - Invalid Vorbis bitstream header.</li>
<li>OV_EFAULT - Internal logic fault; indicates a bug or heap/stack corruption.</li>
</ul>
</blockquote>
<p>
<br><br>
<hr noshade>
<table border=0 width=100%>
<tr valign=top>
<td><p class=tiny>copyright &copy; 2002 Xiph.org</p></td>
<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td>
</tr><tr>
<td><p class=tiny>Vorbisfile documentation</p></td>
<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
</tr>
</table>
</body>
</html>
etc/Library/OggVobisSDK/doc/vorbis/vorbisfile/ov_test_open.html
+82
View File
@@ -0,0 +1,82 @@
<html>
<head>
<title>Vorbisfile - function - ov_test_open</title>
<link rel=stylesheet href="style.css" type="text/css">
</head>
<body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
<table border=0 width=100%>
<tr>
<td><p class=tiny>Vorbisfile documentation</p></td>
<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
</tr>
</table>
<h1>ov_test_open</h1>
<p><i>declared in "vorbis/vorbisfile.h";</i></p>
<p>
Finish opening a file partially opened with <a href="ov_test.html">ov_test()</a>
or <a href="ov_test_callbacks.html">ov_test_callbacks()</a>.
<p>
<table border=0 color=black cellspacing=0 cellpadding=7>
<tr bgcolor=#cccccc>
<td>
<pre><b>
int ov_test_open(<a href="OggVorbis_File.html">OggVorbis_File</a> *vf);
</b></pre>
</td>
</tr>
</table>
<h3>Parameters</h3>
<dl>
<dt><i>vf</i></dt>
<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile
functions. Once this has been called, the same <tt>OggVorbis_File</tt>
struct should be passed to all the libvorbisfile functions.</dd>
</dl>
<h3>Return Values</h3>
<blockquote>
<li>
0 for success</li>
<li>less than zero for failure:</li>
<ul>
<li>OV_EREAD - A read from media returned an error.</li>
<li>OV_ENOTVORBIS - Bitstream is not Vorbis data.</li>
<li>OV_EVERSION - Vorbis version mismatch.</li>
<li>OV_EBADHEADER - Invalid Vorbis bitstream header.</li>
<li>OV_EFAULT - Internal logic fault; indicates a bug or heap/stack corruption.</li>
</ul>
</blockquote>
<p>
<br><br>
<hr noshade>
<table border=0 width=100%>
<tr valign=top>
<td><p class=tiny>copyright &copy; 2002 Xiph.org</p></td>
<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td>
</tr><tr>
<td><p class=tiny>Vorbisfile documentation</p></td>
<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
</tr>
</table>
</body>
</html>
etc/Library/OggVobisSDK/doc/vorbis/vorbisfile/ov_time_seek.html
+70
View File
@@ -0,0 +1,70 @@
<html>
<head>
<title>Vorbisfile - function - ov_time_seek</title>
<link rel=stylesheet href="style.css" type="text/css">
</head>
<body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
<table border=0 width=100%>
<tr>
<td><p class=tiny>Vorbisfile documentation</p></td>
<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
</tr>
</table>
<h1>ov_time_seek</h1>
<p><i>declared in "vorbis/vorbisfile.h";</i></p>
<p>For seekable
streams, this seeks to the given time. For implementing seeking in a player,
this is the only function generally needed. This also updates everything needed within the
decoder, so you can immediately call <a href="ov_read.html">ov_read()</a> and get data from
the newly seeked to position. This function does not work for unseekable streams.
<br><br>
<table border=0 color=black cellspacing=0 cellpadding=7>
<tr bgcolor=#cccccc>
<td>
<pre><b>
int ov_time_seek(<a href="OggVorbis_File.html">OggVorbis_File</a> *vf, double s);
</b></pre>
</td>
</tr>
</table>
<h3>Parameters</h3>
<dl>
<dt><i>vf</i></dt>
<dd>Pointer to our already opened and initialized OggVorbis_File structure.</dd>
<dt><i>ms</i></dt>
<dd>Location to seek to within the file, specified in seconds.</dd>
</dl>
<h3>Return Values</h3>
<blockquote>
<li>
0 for success</li>
<li>
Nonzero for failure</li>
</blockquote>
<br><br>
<hr noshade>
<table border=0 width=100%>
<tr valign=top>
<td><p class=tiny>copyright &copy; 2002 Xiph.org</p></td>
<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td>
</tr><tr>
<td><p class=tiny>Vorbisfile documentation</p></td>
<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
</tr>
</table>
</body>
</html>
etc/Library/OggVobisSDK/doc/vorbis/vorbisfile/ov_time_seek_page.html
+83
View File
@@ -0,0 +1,83 @@
<html>
<head>
<title>Vorbisfile - function - ov_time_seek_page</title>
<link rel=stylesheet href="style.css" type="text/css">
</head>
<body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
<table border=0 width=100%>
<tr>
<td><p class=tiny>Vorbisfile documentation</p></td>
<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
</tr>
</table>
<h1>ov_time_seek_page</h1>
<p><i>declared in "vorbis/vorbisfile.h";</i></p>
<p>For seekable
streams, this seeks to closest full page preceding the given time. This function is faster than <a href="ov_time_seek.html">ov_time_seek</a> because it doesn't seek through the last few samples to reach an exact time, but it is also less accurate. This should be used when speed is important.
<p>This function also updates everything needed within the
decoder, so you can immediately call <a href="ov_read.html">ov_read()</a> and get data from
the newly seeked to position.
<p>This function does not work for unseekable streams.
<br><br>
<table border=0 color=black cellspacing=0 cellpadding=7>
<tr bgcolor=#cccccc>
<td>
<pre><b>
int ov_time_seek_page(<a href="OggVorbis_File.html">OggVorbis_File</a> *vf, double s);
</b></pre>
</td>
</tr>
</table>
<h3>Parameters</h3>
<dl>
<dt><i>vf</i></dt>
<dd>Pointer to our already opened and initialized OggVorbis_File structure.</dd>
<dt><i>ms</i></dt>
<dd>Location to seek to within the file, specified in seconds.</dd>
</dl>
<h3>Return Values</h3>
<blockquote>
<li>
0 for success</li>
<li>
nonzero indicates failure, described by several error codes:</li>
<ul>
<li>OV_ENOSEEK - Bitstream is not seekable.
</li>
<li>OV_EINVAL - Invalid argument value.
</li>
<li>OV_EREAD - A read from media returned an error.
</li>
<li>OV_EFAULT - Internal logic fault; indicates a bug or heap/stack
corruption.
</li>
<li>OV_EBADLINK - Invalid stream section supplied to libvorbisfile, or the requested link is corrupt.
</li>
</ul></blockquote>
<br><br>
<hr noshade>
<table border=0 width=100%>
<tr valign=top>
<td><p class=tiny>copyright &copy; 2002 Xiph.org</p></td>
<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td>
</tr><tr>
<td><p class=tiny>Vorbisfile documentation</p></td>
<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
</tr>
</table>
</body>
</html>
etc/Library/OggVobisSDK/doc/vorbis/vorbisfile/ov_time_tell.html
+63
View File
@@ -0,0 +1,63 @@
<html>
<head>
<title>Vorbisfile - function - ov_time_tell</title>
<link rel=stylesheet href="style.css" type="text/css">
</head>
<body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
<table border=0 width=100%>
<tr>
<td><p class=tiny>Vorbisfile documentation</p></td>
<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
</tr>
</table>
<h1>ov_time_tell</h1>
<p><i>declared in "vorbis/vorbisfile.h";</i></p>
<p>Returns the current decoding offset in seconds.
<br><br>
<table border=0 color=black cellspacing=0 cellpadding=7>
<tr bgcolor=#cccccc>
<td>
<pre><b>
double ov_time_tell(OggVorbis_File *vf);
</b></pre>
</td>
</tr>
</table>
<h3>Parameters</h3>
<dl>
<dt><i>vf</i></dt>
<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile
functions.</dd>
</dl>
<h3>Return Values</h3>
<blockquote>
<li><i>n</i> indicates the current decoding time offset in seconds.</li>
<li>OV_EINVAL means that the argument was invalid. In this case, the requested bitstream did not exist.</li>
</blockquote>
<p>
<br><br>
<hr noshade>
<table border=0 width=100%>
<tr valign=top>
<td><p class=tiny>copyright &copy; 2002 Xiph.org</p></td>
<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td>
</tr><tr>
<td><p class=tiny>Vorbisfile documentation</p></td>
<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
</tr>
</table>
</body>
</html>
etc/Library/OggVobisSDK/doc/vorbis/vorbisfile/ov_time_total.html
+67
View File
@@ -0,0 +1,67 @@
<html>
<head>
<title>Vorbisfile - function - ov_time_total</title>
<link rel=stylesheet href="style.css" type="text/css">
</head>
<body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
<table border=0 width=100%>
<tr>
<td><p class=tiny>Vorbisfile documentation</p></td>
<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
</tr>
</table>
<h1>ov_time_total</h1>
<p><i>declared in "vorbis/vorbisfile.h";</i></p>
<p>Returns the total time in seconds of the physical bitstream or a specified logical bitstream.
<br><br>
<table border=0 color=black cellspacing=0 cellpadding=7>
<tr bgcolor=#cccccc>
<td>
<pre><b>
double ov_time_total(OggVorbis_File *vf,int i);
</b></pre>
</td>
</tr>
</table>
<h3>Parameters</h3>
<dl>
<dt><i>vf</i></dt>
<dd>A pointer to the OggVorbis_File structure--this is used for ALL the externally visible libvorbisfile
functions.</dd>
<dt><i>i</i></dt>
<dd>Link to the desired logical bitstream. To retrieve the time total for the entire physical bitstream, this parameter should be set to -1.</b></dd>
</dl>
<h3>Return Values</h3>
<blockquote>
<li>OV_EINVAL means that the argument was invalid. In this case, the requested bitstream did not exist or the bitstream is nonseekable.</li>
<li><tt>n</tt> total length in seconds of content if i=-1.</li>
<li><tt>n</tt> length in seconds of logical bitstream if i=1 to n.</li>
</blockquote>
<p>
<br><br>
<hr noshade>
<table border=0 width=100%>
<tr valign=top>
<td><p class=tiny>copyright &copy; 2002 Xiph.org</p></td>
<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td>
</tr><tr>
<td><p class=tiny>Vorbisfile documentation</p></td>
<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
</tr>
</table>
</body>
</html>
etc/Library/OggVobisSDK/doc/vorbis/vorbisfile/overview.html
+60
View File
@@ -0,0 +1,60 @@
<html>
<head>
<title>Vorbisfile - API Overview</title>
<link rel=stylesheet href="style.css" type="text/css">
</head>
<body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
<table border=0 width=100%>
<tr>
<td><p class=tiny>Vorbisfile documentation</p></td>
<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
</tr>
</table>
<h1>Vorbisfile API Overview</h1>
<p>The makeup of the Vorbisfile libvorbisfile library API is relatively
simple. It revolves around a single file resource. This file resource is
passed to libvorbisfile, where it is opened, manipulated, and closed,
in the form of an <a href="OggVorbis_File.html">OggVorbis_File</a>
struct.
<p>
The Vorbisfile API consists of the following functional categories:
<p>
<ul>
<li><p><a href="datastructures.html">Base data structures</a>
<li><p><a href="initialization.html">Setup/Teardown</a>
<li><p><a href="decoding.html">Decoding</a>
<li><p><a href="seeking.html">Seeking</a>
<li><p><a href="fileinfo.html">File Information</a>
</ul>
<p>
In addition, the following subjects deserve attention additional to
the above general overview:
<p>
<ul>
<li><p><a href="threads.html">Threading and thread safety</a>
<li><p><a href="callbacks.html">Using [non stdio] custom stream I/O
via callbacks</a>
</ul>
<p>
<br><br>
<hr noshade>
<table border=0 width=100%>
<tr valign=top>
<td><p class=tiny>copyright &copy; 2002 Xiph.org</p></td>
<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td>
</tr><tr>
<td><p class=tiny>Vorbisfile documentation</p></td>
<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
</tr>
</table>
</body>
</html>
etc/Library/OggVobisSDK/doc/vorbis/vorbisfile/reference.html
+75
View File
@@ -0,0 +1,75 @@
<html>
<head>
<title>Vorbisfile API Reference</title>
<link rel=stylesheet href="style.css" type="text/css">
</head>
<body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
<table border=0 width=100%>
<tr>
<td><p class=tiny>Vorbisfile documentation</p></td>
<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
</tr>
</table>
<h1>Vorbisfile API Reference</h1>
<p>
<b>Data Structures</b><br>
<a href="OggVorbis_File.html">OggVorbis_File</a><br>
<a href="vorbis_comment.html">vorbis_comment</a><br>
<a href="vorbis_info.html">vorbis_info</a><br>
<a href="ov_callbacks.html">ov_callbacks</a><br>
<br>
<b>Setup/Teardown</b><br>
<a href="ov_open.html">ov_open()</a><br>
<a href="ov_open_callbacks.html">ov_open_callbacks()</a><br>
<a href="ov_clear.html">ov_clear()</a><br>
<a href="ov_test.html">ov_test()</a><br>
<a href="ov_test_callbacks.html">ov_test_callbacks()</a><br>
<a href="ov_test_open.html">ov_test_open()</a><br>
<br>
<b>Decoding</b><br>
<a href="ov_read.html">ov_read()</a><br>
<br>
<b>Seeking</b><br>
<a href="ov_raw_seek.html">ov_raw_seek()</a><br>
<a href="ov_pcm_seek.html">ov_pcm_seek()</a><br>
<a href="ov_time_seek.html">ov_time_seek()</a><br>
<a href="ov_pcm_seek_page.html">ov_pcm_seek_page()</a><br>
<a href="ov_time_seek_page.html">ov_time_seek_page()</a><br>
<br>
<b>File Information</b><br>
<a href="ov_bitrate.html">ov_bitrate()</a><br>
<a href="ov_bitrate_instant.html">ov_bitrate_instant()</a><br>
<a href="ov_streams.html">ov_streams()</a><br>
<a href="ov_seekable.html">ov_seekable()</a><br>
<a href="ov_serialnumber.html">ov_serialnumber()</a><br>
<a href="ov_raw_total.html">ov_raw_total()</a><br>
<a href="ov_pcm_total.html">ov_pcm_total()</a><br>
<a href="ov_time_total.html">ov_time_total()</a><br>
<a href="ov_raw_tell.html">ov_raw_tell()</a><br>
<a href="ov_pcm_tell.html">ov_pcm_tell()</a><br>
<a href="ov_time_tell.html">ov_time_tell()</a><br>
<a href="ov_info.html">ov_info()</a><br>
<a href="ov_comment.html">ov_comment()</a><br>
<br>
<b><a href="return.html">Return Codes</a></b><br>
<br><br>
<hr noshade>
<table border=0 width=100%>
<tr valign=top>
<td><p class=tiny>copyright &copy; 2002 Xiph.org</p></td>
<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td>
</tr><tr>
<td><p class=tiny>Vorbisfile documentation</p></td>
<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
</tr>
</table>
</body>
</html>
etc/Library/OggVobisSDK/doc/vorbis/vorbisfile/return.html
+77
View File
@@ -0,0 +1,77 @@
<html>
<head>
<title>Vorbisfile - Return Codes</title>
<link rel=stylesheet href="style.css" type="text/css">
</head>
<body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
<table border=0 width=100%>
<tr>
<td><p class=tiny>Vorbisfile documentation</p></td>
<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
</tr>
</table>
<h1>Return Codes</h1>
<p>
The following return codes are <tt>#define</tt>d in "vorbis/codec.h"
may be returned by libvorbisfile. Descriptions of a code relevant to
a specific function are found in the reference description of that
function.
<dl>
<dt>OV_FALSE</dt>
<dd>Not true, or no data available</dd>
<dt>OV_HOLE</dt>
<dd>Vorbisfile encoutered missing or corrupt data in the bitstream. Recovery
is normally automatic and this return code is for informational purposes only.</dd>
<dt>OV_EREAD</dt>
<dd>Read error while fetching compressed data for decode</dd>
<dt>OV_EFAULT</dt>
<dd>Internal inconsistency in decode state. Continuing is likely not possible.</dd>
<dt>OV_EIMPL</dt>
<dd>Feature not implemented</dd>
<dt>OV_EINVAL</dt>
<dd>Either an invalid argument, or incompletely initialized argument passed to libvorbisfile call</dd>
<dt>OV_ENOTVORBIS</dt>
<dd>The given file/data was not recognized as Ogg Vorbis data.</dd>
<dt>OV_EBADHEADER</dt>
<dd>The file/data is apparently an Ogg Vorbis stream, but contains a corrupted or undecipherable header.</dd>
<dt>OV_EVERSION</dt>
<dd>The bitstream format revision of the given stream is not supported.</dd>
<dt>OV_EBADLINK</dt>
<dd>The given link exists in the Vorbis data stream, but is not decipherable due to garbacge or corruption.</dd>
<dt>OV_ENOSEEK</dt>
<dd>The given stream is not seekable</dd>
</dl>
<br><br>
<hr noshade>
<table border=0 width=100%>
<tr valign=top>
<td><p class=tiny>copyright &copy; 2002 Xiph.org</p></td>
<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td>
</tr><tr>
<td><p class=tiny>Vorbisfile documentation</p></td>
<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
</tr>
</table>
</body>
</html>
etc/Library/OggVobisSDK/doc/vorbis/vorbisfile/seekexample.html
+139
View File
@@ -0,0 +1,139 @@
<html>
<head>
<title>vorbisfile - Example Code</title>
<link rel=stylesheet href="style.css" type="text/css">
</head>
<body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
<table border=0 width=100%>
<tr>
<td><p class=tiny>vorbisfile documentation</p></td>
<td align=right><p class=tiny>vorbisfile version 1.25 - 20000615</p></td>
</tr>
</table>
<h1>Example Code</h1>
<p>
The following is a run-through of the seeking example program supplied
with vorbisfile - <a href="seeking_test_c.html">seeking_test.c</a>.
This program tests the vorbisfile <a href="ov_time_seek.html">ov_time_seek</a> function by seeking to random points within the file.
<p>
First, relevant headers, including vorbis-specific "codec.h" and "vorbisfile.h" have to be included.
<br><br>
<table border=0 width=100% color=black cellspacing=0 cellpadding=7>
<tr bgcolor=#cccccc>
<td>
<pre><b>
#include &lt;stdlib.h>
#include &lt;stdio.h>
#include "vorbis/codec.h"
#include "vorbis/vorbisfile.h"
#include "../lib/misc.h"
</b></pre>
</td>
</tr>
</table>
<p>Inside main(), we declare our primary OggVorbis_File structure. We also declare a other helpful variables to track our progress within the file.
<br><br>
<table border=0 width=100% color=black cellspacing=0 cellpadding=7>
<tr bgcolor=#cccccc>
<td>
<pre><b>
int main(){
OggVorbis_File ov;
int i;
</b></pre>
</td>
</tr>
</table>
<p><a href="ov_open.html">ov_open()</a> must be
called to initialize the <a href="OggVorbis_File.html">OggVorbis_File</a> structure with default values.
<a href="ov_open.html">ov_open()</a> also checks to ensure that we're reading Vorbis format and not something else.
<br><br>
<table border=0 width=100% color=black cellspacing=0 cellpadding=7>
<tr bgcolor=#cccccc>
<td>
<pre><b>
if(ov_open(stdin,&ov,NULL,-1)<0){
printf("Could not open input as an OggVorbis file.\n\n");
exit(1);
}
</b></pre>
</td>
</tr>
</table>
<p>
First we check to make sure the stream is seekable using <a href="ov_seekable.html">ov_seekable</a>.
<p>Then we seek to 100 random spots in the bitstream using <a href="ov_time_seek.html">ov_time_seek</a> with randomly generated values.
<br><br>
<table border=0 width=100% color=black cellspacing=0 cellpadding=7>
<tr bgcolor=#cccccc>
<td>
<pre><b>
/* print details about each logical bitstream in the input */
if(ov_seekable(&ov)){
double length=ov_time_total(&ov,-1);
printf("testing seeking to random places in %g seconds....\n",length);
for(i=0;i<100;i++){
double val=(double)rand()/RAND_MAX*length;
ov_time_seek(&ov,val);
printf("\r\t%d [%gs]... ",i,val);
fflush(stdout);
}
printf("\r \nOK.\n\n");
}else{
printf("Standard input was not seekable.\n");
}
</b></pre>
</td>
</tr>
</table>
<p>
When we're done seeking, we need to call <a href="ov_clear.html">ov_clear()</a> to release the bitstream.
<br><br>
<table border=0 width=100% color=black cellspacing=0 cellpadding=7>
<tr bgcolor=#cccccc>
<td>
<pre><b>
ov_clear(&ov);
return 0;
}
</b></pre>
</td>
</tr>
</table>
<p>
The full source for seeking_test.c can be found with the vorbis
distribution in <a href="seeking_test_c.html">seeking_test.c</a>.
<br><br>
<hr noshade>
<table border=0 width=100%>
<tr valign=top>
<td><p class=tiny>copyright &copy; 2000 vorbis team</p></td>
<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a><br><a href="mailto:[email protected]">[email protected]</a></p></td>
</tr><tr>
<td><p class=tiny>vorbisfile documentation</p></td>
<td align=right><p class=tiny>vorbisfile version 1.25 - 20000615</p></td>
</tr>
</table>
</body>
</html>
etc/Library/OggVobisSDK/doc/vorbis/vorbisfile/seeking.html
+74
View File
@@ -0,0 +1,74 @@
<html>␍
␍
<head>␍
<title>Vorbisfile - Seeking</title>␍
<link rel=stylesheet href="style.css" type="text/css">␍
</head>␍
␍
<body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">␍
<table border=0 width=100%>␍
<tr>␍
<td><p class=tiny>Vorbisfile documentation</p></td>␍
<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>␍
</tr>␍
</table>␍
␍
<h1>Seeking</h1>␍
<p>Seeking functions allow you to specify a specific point in the stream to begin or continue decoding.␍
<p>␍
All libvorbisfile seeking routines are declared in "vorbis/vorbisfile.h".␍
␍
<p>Certain seeking functions are best suited to different situations.␍
When speed is important and exact positioning isn't required,␍
page-level seeking should be used. Note also that Vorbis files do not␍
necessarily start at a sample number or time offset of zero. Do not␍
be surprised if a file begins at a positive offset of several minutes␍
or hours, such as would happen if a large stream (such as a concert␍
recording) is chopped into multiple separate files. Requesting to␍
seek to a position before the beginning of such a file will seek to␍
the position where audio begins.<p>␍
␍
</ul>␍
␍
<table border=1 color=black width=50% cellspacing=0 cellpadding=7>␍
<tr bgcolor=#cccccc>␍
<td><b>function</b></td>␍
<td><b>purpose</b></td>␍
</tr>␍
<tr valign=top>␍
<td><a href="ov_raw_seek.html">ov_raw_seek</a></td>␍
<td>This function seeks to a position specified in the compressed bitstream, specified in bytes.</td>␍
</tr>␍
<tr valign=top>␍
<td><a href="ov_pcm_seek.html">ov_pcm_seek</a></td>␍
<td>This function seeks to a specific audio sample number, specified in pcm samples.</td>␍
</tr>␍
<tr valign=top>␍
<td><a href="ov_pcm_seek_page.html">ov_pcm_seek_page</a></td>␍
<td>This function seeks to the closest page preceding the specified audio sample number, specified in pcm samples.</td>␍
</tr>␍
<tr valign=top>␍
<td><a href="ov_time_seek.html">ov_time_seek</a></td>␍
<td>This function seeks to the specific time location in the bitstream, specified in seconds </td>␍
</tr>␍
<tr valign=top>␍
<td><a href="ov_time_seek_page.html">ov_time_seek_page</a></td>␍
<td>This function seeks to the closest page preceding the specified time position in the bitstream</td>␍
</tr>␍
</table>␍
␍
<br><br>␍
<hr noshade>␍
<table border=0 width=100%>␍
<tr valign=top>␍
<td><p class=tiny>copyright &copy; 2002 Xiph.org</p></td>␍
<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td>␍
</tr><tr>␍
<td><p class=tiny>Vorbisfile documentation</p></td>␍
<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>␍
</tr>␍
</table>␍
␍
</body>␍
␍
</html>␍
etc/Library/OggVobisSDK/doc/vorbis/vorbisfile/seeking_example_c.html
+83
View File
@@ -0,0 +1,83 @@
<html>
<head>
<title>vorbisfile - seeking_test.c</title>
<link rel=stylesheet href="style.css" type="text/css">
</head>
<body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
<table border=0 width=100%>
<tr>
<td><p class=tiny>vorbisfile documentation</p></td>
<td align=right><p class=tiny>vorbisfile version 1.25 - 20000615</p></td>
</tr>
</table>
<h1>seeking_test.c</h1>
<p>
The example program source:
<br><br>
<table border=0 width=100% color=black cellspacing=0 cellpadding=7>
<tr bgcolor=#cccccc>
<td>
<pre><b>
#include <stdlib.h>
#include <stdio.h>
#include "vorbis/codec.h"
#include "vorbis/vorbisfile.h"
#include "../lib/misc.h"
int main(){
OggVorbis_File ov;
int i;
/* open the file/pipe on stdin */
if(ov_open(stdin,&ov,NULL,-1)==-1){
printf("Could not open input as an OggVorbis file.\n\n");
exit(1);
}
/* print details about each logical bitstream in the input */
if(ov_seekable(&ov)){
double length=ov_time_total(&ov,-1);
printf("testing seeking to random places in %g seconds....\n",length);
for(i=0;i<100;i++){
double val=(double)rand()/RAND_MAX*length;
ov_time_seek(&ov,val);
printf("\r\t%d [%gs]... ",i,val);
fflush(stdout);
}
printf("\r \nOK.\n\n");
}else{
printf("Standard input was not seekable.\n");
}
ov_clear(&ov);
return 0;
}
</b></pre>
</td>
</tr>
</table>
<br><br>
<hr noshade>
<table border=0 width=100%>
<tr valign=top>
<td><p class=tiny>copyright &copy; 2000 vorbis team</p></td>
<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/index.html">Ogg Vorbis</a><br><a href="mailto:[email protected]">[email protected]</a></p></td>
</tr><tr>
<td><p class=tiny>vorbisfile documentation</p></td>
<td align=right><p class=tiny>vorbisfile version 1.25 - 20000615</p></td>
</tr>
</table>
</body>
</html>
etc/Library/OggVobisSDK/doc/vorbis/vorbisfile/seeking_test_c.html
+83
View File
@@ -0,0 +1,83 @@
<html>
<head>
<title>vorbisfile - seeking_test.c</title>
<link rel=stylesheet href="style.css" type="text/css">
</head>
<body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
<table border=0 width=100%>
<tr>
<td><p class=tiny>vorbisfile documentation</p></td>
<td align=right><p class=tiny>vorbisfile version 1.25 - 20000615</p></td>
</tr>
</table>
<h1>seeking_test.c</h1>
<p>
The example program source:
<br><br>
<table border=0 width=100% color=black cellspacing=0 cellpadding=7>
<tr bgcolor=#cccccc>
<td>
<pre><b>
#include <stdlib.h>
#include <stdio.h>
#include "vorbis/codec.h"
#include "vorbis/vorbisfile.h"
#include "../lib/misc.h"
int main(){
OggVorbis_File ov;
int i;
/* open the file/pipe on stdin */
if(ov_open(stdin,&ov,NULL,-1)==-1){
printf("Could not open input as an OggVorbis file.\n\n");
exit(1);
}
/* print details about each logical bitstream in the input */
if(ov_seekable(&ov)){
double length=ov_time_total(&ov,-1);
printf("testing seeking to random places in %g seconds....\n",length);
for(i=0;i<100;i++){
double val=(double)rand()/RAND_MAX*length;
ov_time_seek(&ov,val);
printf("\r\t%d [%gs]... ",i,val);
fflush(stdout);
}
printf("\r \nOK.\n\n");
}else{
printf("Standard input was not seekable.\n");
}
ov_clear(&ov);
return 0;
}
</b></pre>
</td>
</tr>
</table>
<br><br>
<hr noshade>
<table border=0 width=100%>
<tr valign=top>
<td><p class=tiny>copyright &copy; 2000 vorbis team</p></td>
<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/index.html">Ogg Vorbis</a><br><a href="mailto:[email protected]">[email protected]</a></p></td>
</tr><tr>
<td><p class=tiny>vorbisfile documentation</p></td>
<td align=right><p class=tiny>vorbisfile version 1.25 - 20000615</p></td>
</tr>
</table>
</body>
</html>
etc/Library/OggVobisSDK/doc/vorbis/vorbisfile/seekingexample.html
+204
View File
@@ -0,0 +1,204 @@
<html>
<head>
<title>vorbisfile - Example Code</title>
<link rel=stylesheet href="style.css" type="text/css">
</head>
<body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
<table border=0 width=100%>
<tr>
<td><p class=tiny>vorbisfile documentation</p></td>
<td align=right><p class=tiny>vorbisfile version 1.25 - 20000615</p></td>
</tr>
</table>
<h1>Example Code</h1>
<p>
The following is a run-through of the decoding example program supplied
with vorbisfile - <a href="vorbisfile_example_c.html">vorbisfile_example.c</a>.
This program takes a vorbis bitstream from stdin and writes raw pcm to stdout.
<p>
First, relevant headers, including vorbis-specific "codec.h" and "vorbisfile.h" have to be included.
<br><br>
<table border=0 width=100% color=black cellspacing=0 cellpadding=7>
<tr bgcolor=#cccccc>
<td>
<pre><b>
#include &lt;stdio.h&gt;
#include &lt;stdlib.h&gt;
#include &lt;math.h&gt;
#include "vorbis/codec.h"
#include "vorbis/vorbisfile.h"
</b></pre>
</td>
</tr>
</table>
<p>
We also have to make a concession to Windows users here. If we are using windows for decoding, we must declare these libraries so that we can set stdin/stdout to binary.
<br><br>
<table border=0 width=100% color=black cellspacing=0 cellpadding=7>
<tr bgcolor=#cccccc>
<td>
<pre><b>
#ifdef _WIN32
#include &lt;io.h&gt;
#include &lt;fcntl.h&gt;
#endif
</b></pre>
</td>
</tr>
</table>
<p>
Next, a buffer for the pcm audio output is declared.
<br><br>
<table border=0 width=100% color=black cellspacing=0 cellpadding=7>
<tr bgcolor=#cccccc>
<td>
<pre><b>
char pcmout[4096];
</b></pre>
</td>
</tr>
</table>
<p>Inside main(), we declare our primary OggVorbis_File structure. We also declare a few other helpful variables to track out progress within the file.
Also, we make our final concession to Windows users by setting the stdin and stdout to binary mode.
<br><br>
<table border=0 width=100% color=black cellspacing=0 cellpadding=7>
<tr bgcolor=#cccccc>
<td>
<pre><b>
int main(int argc, char **argv){
OggVorbis_File vf;
int eof=0;
int current_section;
#ifdef _WIN32
_setmode( _fileno( stdin ), _O_BINARY );
_setmode( _fileno( stdout ), _O_BINARY );
#endif
</b></pre>
</td>
</tr>
</table>
<p><a href="ov_open.html">ov_open()</a> must be
called to initialize the <b>OggVorbis_File</b> structure with default values.
<a href="ov_open.html">ov_open()</a> also checks to ensure that we're reading Vorbis format and not something else.
<br><br>
<table border=0 width=100% color=black cellspacing=0 cellpadding=7>
<tr bgcolor=#cccccc>
<td>
<pre><b>
if(ov_open(stdin, &vf, NULL, 0) < 0) {
fprintf(stderr,"Input does not appear to be an Ogg bitstream.\n");
exit(1);
}
</b></pre>
</td>
</tr>
</table>
<p>
We're going to pull the channel and bitrate info from the file using <a href="ov_info.html">ov_info()</a> and show them to the user.
We also want to pull out and show the user a comment attached to the file using <a href="ov_comment.html">ov_comment()</a>.
<br><br>
<table border=0 width=100% color=black cellspacing=0 cellpadding=7>
<tr bgcolor=#cccccc>
<td>
<pre><b>
{
char **ptr=ov_comment(&vf,-1)->user_comments;
vorbis_info *vi=ov_info(&vf,-1);
while(*ptr){
fprintf(stderr,"%s\n",*ptr);
++ptr;
}
fprintf(stderr,"\nBitstream is %d channel, %ldHz\n",vi->channels,vi->rate);
fprintf(stderr,"Encoded by: %s\n\n",ov_comment(&vf,-1)->vendor);
}
</b></pre>
</td>
</tr>
</table>
<p>
Here's the read loop:
<br><br>
<table border=0 width=100% color=black cellspacing=0 cellpadding=7>
<tr bgcolor=#cccccc>
<td>
<pre><b>
while(!eof){
long ret=ov_read(&vf,pcmout,sizeof(pcmout),0,2,1,&current_section);
switch(ret){
case 0:
/* EOF */
eof=1;
break;
case -1:
break;
default:
fwrite(pcmout,1,ret,stdout);
break;
}
}
</b></pre>
</td>
</tr>
</table>
<p>
The code is reading blocks of data using <a href="ov_read.html">ov_read()</a>.
Based on the value returned, we know if we're at the end of the file or have invalid data. If we have valid data, we write it to the pcm output.
<p>
Now that we've finished playing, we can pack up and go home. It's important to call <a href="ov_clear.html">ov_clear()</a> when we're finished.
<br><br>
<table border=0 width=100% color=black cellspacing=0 cellpadding=7>
<tr bgcolor=#cccccc>
<td>
<pre><b>
ov_clear(&vf);
fprintf(stderr,"Done.\n");
return(0);
}
</b></pre>
</td>
</tr>
</table>
<p>
The full source for vorbisfile_example.c can be found with the vorbis
distribution in <a href="vorbisfile_example_c.html">vorbisfile_example.c</a>.
<br><br>
<hr noshade>
<table border=0 width=100%>
<tr valign=top>
<td><p class=tiny>copyright &copy; 2000 vorbis team</p></td>
<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a><br><a href="mailto:[email protected]">[email protected]</a></p></td>
</tr><tr>
<td><p class=tiny>vorbisfile documentation</p></td>
<td align=right><p class=tiny>vorbisfile version 1.25 - 20000615</p></td>
</tr>
</table>
</body>
</html>
etc/Library/OggVobisSDK/doc/vorbis/vorbisfile/style.css
+7
View File
@@ -0,0 +1,7 @@
BODY { font-family: Helvetica, sans-serif }
TD { font-family: Helvetica, sans-serif }
P { font-family: Helvetica, sans-serif }
H1 { font-family: Helvetica, sans-serif }
H2 { font-family: Helvetica, sans-serif }
H4 { font-family: Helvetica, sans-serif }
P.tiny { font-size: 8pt }
etc/Library/OggVobisSDK/doc/vorbis/vorbisfile/threads.html
+50
View File
@@ -0,0 +1,50 @@
<html>
<head>
<title>Vorbisfile - Thread Safety</title>
<link rel=stylesheet href="style.css" type="text/css">
</head>
<body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
<table border=0 width=100%>
<tr>
<td><p class=tiny>Vorbisfile documentation</p></td>
<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
</tr>
</table>
<h1>Thread Safety</h1>
Vorbisfile's libvorbisfile may be used safely in a threading environment
so long as thread access to individual <a
href="OggVorbis_File.html">OggVorbis_File</a> instances is serialized.
<ul>
<li>Only one thread at a time may enter a function that takes a given <a
href="OggVorbis_File.html">OggVorbis_File</a> instance, even if the
functions involved appear to be read-only.<p>
<li>Multiple threads may enter
libvorbisfile at a given time, so long as each thread's function calls
are using different <a href="OggVorbis_File.html">OggVorbis_File</a>
instances. <p>
<li>Any one <a
href="OggVorbis_File.html">OggVorbis_File</a> instance may be used safely from multiple threads so long as only one thread at a time is making calls using that instance.<p>
</ul>
<br><br>
<hr noshade>
<table border=0 width=100%>
<tr valign=top>
<td><p class=tiny>copyright &copy; 2002 Xiph.org</p></td>
<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td>
</tr><tr>
<td><p class=tiny>Vorbisfile documentation</p></td>
<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
</tr>
</table>
</body>
</html>
etc/Library/OggVobisSDK/doc/vorbis/vorbisfile/vorbis_comment.html
+70
View File
@@ -0,0 +1,70 @@
<html>
<head>
<title>Vorbisfile - datatype - vorbis_comment</title>
<link rel=stylesheet href="style.css" type="text/css">
</head>
<body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
<table border=0 width=100%>
<tr>
<td><p class=tiny>Vorbisfile documentation</p></td>
<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
</tr>
</table>
<h1>vorbis_comment</h1>
<p><i>declared in "vorbis/codec.h"</i></p>
<p>
The vorbis_comment structure defines an Ogg Vorbis comment.
<p>
Only the fields the program needs must be defined. If a field isn't
defined by the application, it will either be blank (if it's a string value)
or set to some reasonable default (usually 0).
<p>
<table border=0 width=100% color=black cellspacing=0 cellpadding=7>
<tr bgcolor=#cccccc>
<td>
<pre><b>typedef struct vorbis_comment{
/* unlimited user comment fields. */
char **user_comments;
int *comment_lengths;
int comments;
char *vendor;
} vorbis_comment;</b></pre>
</td>
</tr>
</table>
<h3>Parameters</h3>
<dl>
<dt><i>user_comments</i></dt>
<dd>Unlimited user comment array. The individual strings in the array are 8 bit clean, by the Vorbis specification, and as such the <tt>comment_lengths</tt> array should be consulted to determine string length. For convenience, each string is also NULL-terminated by the decode library (although Vorbis comments are not NULL terminated within the bitstream itself).</dd>
<dt><i>comment_lengths</i></dt>
<dd>An int array that stores the length of each comment string</dd>
<dt><i>comments</i></dt>
<dd>Int signifying number of user comments in user_comments field.</dd>
<dt><i>vendor</i></dt>
<dd>Information about the creator of the file. Stored in a standard C 0-terminated string.</dd>
</dl>
<br><br>
<hr noshade>
<table border=0 width=100%>
<tr valign=top>
<td><p class=tiny>copyright &copy; 2002 Xiph.org</p></td>
<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td>
</tr><tr>
<td><p class=tiny>Vorbisfile documentation</p></td>
<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
</tr>
</table>
</body>
</html>
etc/Library/OggVobisSDK/doc/vorbis/vorbisfile/vorbis_info.html
+80
View File
@@ -0,0 +1,80 @@
<html>
<head>
<title>Vorbisfile - datatype - vorbis_info</title>
<link rel=stylesheet href="style.css" type="text/css">
</head>
<body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
<table border=0 width=100%>
<tr>
<td><p class=tiny>Vorbisfile documentation</p></td>
<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
</tr>
</table>
<h1>vorbis_info</h1>
<p><i>declared in "vorbis/codec.h"</i></p>
<p>
The vorbis_info structure contains basic information about the audio in a vorbis bitstream.
<p>
<table border=0 width=100% color=black cellspacing=0 cellpadding=7>
<tr bgcolor=#cccccc>
<td>
<pre><b>typedef struct vorbis_info{
int version;
int channels;
long rate;
long bitrate_upper;
long bitrate_nominal;
long bitrate_lower;
long bitrate_window;
void *codec_setup;
} vorbis_info;</b></pre>
</td>
</tr>
</table>
<h3>Relevant Struct Members</h3>
<dl>
<dt><i>version</i></dt>
<dd>Vorbis encoder version used to create this bitstream.</dd>
<dt><i>channels</i></dt>
<dd>Int signifying number of channels in bitstream.</dd>
<dt><i>rate</i></dt>
<dd>Sampling rate of the bitstream.</dd>
<dt><i>bitrate_upper</i></dt>
<dd>Specifies the upper limit in a VBR bitstream. If the value matches the bitrate_nominal and bitrate_lower parameters, the stream is fixed bitrate. May be unset if no limit exists.</dd>
<dt><i>bitrate_nominal</i></dt>
<dd>Specifies the average bitrate for a VBR bitstream. May be unset. If the bitrate_upper and bitrate_lower parameters match, the stream is fixed bitrate.</dd>
<dt><i>bitrate_lower</i></dt>
<dd>Specifies the lower limit in a VBR bitstream. If the value matches the bitrate_nominal and bitrate_upper parameters, the stream is fixed bitrate. May be unset if no limit exists.</dd>
<dt><i>bitrate_window</i></dt>
<dd>Currently unset.</dd>
<dt><i>codec_setup</i></dt>
<dd>Internal structure that contains the detailed/unpacked configuration for decoding the current Vorbis bitstream.</dd>
</dl>
<br><br>
<hr noshade>
<table border=0 width=100%>
<tr valign=top>
<td><p class=tiny>copyright &copy; 2002 Xiph.org</p></td>
<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/">Ogg Vorbis</a></p></td>
</tr><tr>
<td><p class=tiny>Vorbisfile documentation</p></td>
<td align=right><p class=tiny>libVorbisfile version 1.65 - 20020702</p></td>
</tr>
</table>
</body>
</html>
etc/Library/OggVobisSDK/doc/vorbis/vorbisfile/vorbisfile_example_c.html
+106
View File
@@ -0,0 +1,106 @@
<html>
<head>
<title>vorbisfile - vorbisfile_example.c</title>
<link rel=stylesheet href="style.css" type="text/css">
</head>
<body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
<table border=0 width=100%>
<tr>
<td><p class=tiny>vorbisfile documentation</p></td>
<td align=right><p class=tiny>vorbisfile version 1.25 - 20000615</p></td>
</tr>
</table>
<h1>vorbisfile_example.c</h1>
<p>
The example program source:
<br><br>
<table border=0 width=100% color=black cellspacing=0 cellpadding=7>
<tr bgcolor=#cccccc>
<td>
<pre><b>
#include &lt;stdio.h&gt;
#include &lt;stdlib.h&gt;
#include &lt;math.h&gt;
#include "vorbis/codec.h"
#include "vorbis/vorbisfile.h"
#ifdef _WIN32
#include &lt;io.h&gt;
#include &lt;fcntl.h&gt;
#endif
char pcmout[4096];
int main(int argc, char **argv){
OggVorbis_File vf;
int eof=0;
int current_section;
#ifdef _WIN32
_setmode( _fileno( stdin ), _O_BINARY );
_setmode( _fileno( stdout ), _O_BINARY );
#endif
if(ov_open(stdin, &vf, NULL, 0) < 0) {
fprintf(stderr,"Input does not appear to be an Ogg bitstream.\n");
exit(1);
}
{
char **ptr=ov_comment(&vf,-1)->user_comments;
vorbis_info *vi=ov_info(&vf,-1);
while(*ptr){
fprintf(stderr,"%s\n",*ptr);
++ptr;
}
fprintf(stderr,"\nBitstream is %d channel, %ldHz\n",vi->channels,vi->rate);
fprintf(stderr,"Encoded by: %s\n\n",ov_comment(&vf,-1)->vendor);
}
while(!eof){
long ret=ov_read(&vf,pcmout,sizeof(pcmout),0,2,1,&current_section);
if (ret == 0) {
/* EOF */
eof=1;
} else if (ret < 0) {
/* error in the stream. Not a problem, just reporting it in
case we (the app) cares. In this case, we don't. */
} else {
/* we don't bother dealing with sample rate changes, etc, but
you'll have to*/
fwrite(pcmout,1,ret,stdout);
}
}
ov_clear(&vf);
fprintf(stderr,"Done.\n");
return(0);
}
</b></pre>
</td>
</tr>
</table>
<br><br>
<hr noshade>
<table border=0 width=100%>
<tr valign=top>
<td><p class=tiny>copyright &copy; 2000 vorbis team</p></td>
<td align=right><p class=tiny><a href="http://www.xiph.org/ogg/vorbis/index.html">Ogg Vorbis</a><br><a href="mailto:[email protected]">[email protected]</a></p></td>
</tr><tr>
<td><p class=tiny>vorbisfile documentation</p></td>
<td align=right><p class=tiny>vorbisfile version 1.25 - 20000615</p></td>
</tr>
</table>
</body>
</html>
Loaded 100 of 20588 files, more files were not shown because too many files have changed in this diff. Show more