From fecd42c34f20acdd1d37fa9249f168a8deb66a16 Mon Sep 17 00:00:00 2001 From: Monty Date: Sun, 14 Jul 2002 05:25:59 +0000 Subject: [PATCH] Spec intro first draft svn path=/trunk/vorbis/; revision=3628 --- doc/vorbis-spec-intro.html | 532 +++++++++++++++++++++++++++++++++++++++++++++ doc/window1.png | Bin 0 -> 2332 bytes doc/window2.png | Bin 0 -> 2161 bytes 3 files changed, 532 insertions(+) create mode 100644 doc/vorbis-spec-intro.html create mode 100644 doc/window1.png create mode 100644 doc/window2.png diff --git a/doc/vorbis-spec-intro.html b/doc/vorbis-spec-intro.html new file mode 100644 index 0000000..361d401 --- /dev/null +++ b/doc/vorbis-spec-intro.html @@ -0,0 +1,532 @@ +xiph.org: Ogg Vorbis documentation + +

+ +

+Ogg Vorbis I format specification: high-level description +

+ +Last update to this document: July 13, 2002
+ +

Overview

+ +This document provides a high level description of the Vorbis codec's +construction. A bit-by-bit specification appears in the packet specification and reference +document. The full reference document assumes a high-level +understanding of the Vorbis decode process, which is provided in this +document.

+ +

Application

+ +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).

+ +

Classification

+ +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. + +

Assumptions

+ +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.

+ +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.

+ +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.

+ +The specifications for embedding Vorbis into +an Ogg transport stream is in a separate document.

+ +

Codec Setup and Probability Model

+ +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.

+ +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].

+ +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).

+ +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.

+ +

Format Specification

+ +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.

+ +

Hardware Profile

+ +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.

+ +

Decoder Configuration

+ +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:

+ +

Global Config

+ +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.

+ +

Mode

+Each Vorbis frame is coded according to a master 'mode'. A bitstream +may use one or many modes.

+ +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.

+ +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.

+ +

Mapping

+ +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.

+ +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.

+ +As an example:

+ +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.

+ +

Floor

+ +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.

+ +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.

+ +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.

+ +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.

+ +

Residue

+ +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.

+ +

Codebooks

+ +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.

+ +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.

+ +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).

+ + +

High-level Decode Process

+ +

Decode setup

+ +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.

+ +The header packets are, in order, the identification +header, the comments header, and the setup header.

+ +

Identification Header

+ +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.

+ +

Comment Header

+ +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 the Ogg Vorbis comment field specification.

+ +

Setup Header

+ +The setup header includes extensive CODEC setup information as well as +the complete VQ and Huffman codebooks needed for decode.

+ +

Decode Procedure

+ +The decoding and synthesis procedure for all audio packets is +fundamentally the same. +

decode packet type flag +
decode mode number +
decode window shape [long windows only] +
decode floor +
decode residue into residue vectors +
inverse channel coupling of residue vectors +
generate floor curve from decoded floor data +
compute dot product of floor and residue, producing audio spectrum vector +
inverse monolithic transform of audio spectrum vector, always an MDCT in Vorbis I +
overlap/add left-hand output of transform with right-hand output of previous frame +
store right hand-data from transform of current frame for future lapping. +
if not first frame, return results of overlap/add as audio result of current frame +

+ +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 entirely mathematically equivalent to the +specification, it need not be a literal semantic implementation. + +

Packet type decode

+ +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.

+ +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; 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. + +

Mode decode

+ +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.

+ +

Window shape decode [long windows only]

+ +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.

+ +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.

+ +This is easy to visualize in the case of equal sized-windows:

+ + +And slightly more complex in the case of overlapping unequal sized +windows:

+ +

+ +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.

+ +A description of valid window functions for use with an inverse MDCT +can be found in the paper _The +use of multirate filter banks for coding of high quality digital +audio_, by T. Sporer, K. Brandenburg and B. Edler. Vorbis windows +all use the slope function y=sin(2PI*sin^2((x+.5)/n)).

+ +

floor decode

+ +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.

+ +

residue decode

+ +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.

+ +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.

+ +

inverse channel coupling

+ +A detailed discussion of stereo in the Vorbis codec can be found in +the document _Stereo Channel Coupling in the +Vorbis CODEC_. Vorbis is not limited to only stereo coupling, but +the stereo document also gives a good overview of the generic coupling +mechanism.

+ +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.

+ +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.

+ +

generate floor curve

+ +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.

+ +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.

+ +

compute floor/residue dot product

+ +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.

+ +One point is worth mentioning about this dot product (the bit-level +specification document goes into more detail about this); a common +mistake in a fixed point implementation is 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.

+ +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.

+ +

inverse monolithic transform (MDCT)

+ +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 _The +use of multirate filter banks for coding of high quality digital +audio_, by T. Sporer, K. Brandenburg and B. Edler.

+ +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.

+ +

overlap/add data

+ +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.

+ + +

cache right hand data

+ +The decoder must cache the right hand portion of the current frame to +be lapped with the left hand portion of the next frame. + +

return finished audio data

+ +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:

+window_blocksize(previous_window)/4+window_blocksize(current_window)/4 +from the center of the previous window to the center of the current +window..

+ +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).

+ +

+ + + +Ogg is a Xiph.org Foundation 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 About +the Xiph.org Foundation for details. +

+ +Ogg Vorbis is the first Ogg audio CODEC. Anyone may freely use and +distribute the Ogg and Vorbis specification, whether in a private, +public or corporate capacity. However, the Xiph.org Foundation and +the Ogg project (xiph.org) reserve the right to set the Ogg Vorbis +specification and certify specification compliance.

+ +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.

+ + + diff --git a/doc/window1.png b/doc/window1.png new file mode 100644 index 0000000000000000000000000000000000000000..e4276974c53f6b08efc61cf5bafd3f4dd5b0a434 GIT binary patch literal 2332 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