From 373dc625f82b47096893add42c4472e4a57ab7eb Mon Sep 17 00:00:00 2001 From: Aki Date: Wed, 9 Feb 2022 22:23:03 +0100 Subject: Moved third-party libraries to a separate subdirectory --- vorbis/doc/01-introduction.tex | 528 ----------------------------------------- 1 file changed, 528 deletions(-) delete mode 100644 vorbis/doc/01-introduction.tex (limited to 'vorbis/doc/01-introduction.tex') diff --git a/vorbis/doc/01-introduction.tex b/vorbis/doc/01-introduction.tex deleted file mode 100644 index d7767df..0000000 --- a/vorbis/doc/01-introduction.tex +++ /dev/null @@ -1,528 +0,0 @@ -% -*- mode: latex; TeX-master: "Vorbis_I_spec"; -*- -%!TEX root = Vorbis_I_spec.tex -\section{Introduction and Description} \label{vorbis:spec:intro} - -\subsection{Overview} - -This document provides a high level description of the Vorbis codec's -construction. A bit-by-bit specification appears beginning in -\xref{vorbis:spec:codec}. -The later sections assume a high-level -understanding of the Vorbis decode process, which is -provided here. - -\subsubsection{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 48kbps -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). - - -\subsubsection{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. - - -\subsubsection{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 variable bit rate (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 specification for embedding Vorbis into -an Ogg transport stream is in \xref{vorbis:over:ogg}. - - - -\subsubsection{Codec Setup and Probability Model} - -Vorbis' 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 of 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. - - -\begin{note} -Vorbis \emph{can} initiate decode at any arbitrary packet within a -bitstream so long as the codec has been initialized/setup with the -setup headers. -\end{note} - -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 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' suitable application space. - - -\subsubsection{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. - -\subsubsection{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. - - -\subsection{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: - -\begin{center} -\includegraphics[width=\textwidth]{components} -\captionof{figure}{decoder pipeline configuration} -\end{center} - -\subsubsection{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. - -\subsubsection{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. - - -\subsubsection{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. - - -\subsubsection{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. - - -\subsubsection{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. - -\subsubsection{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). - - - -\subsection{High-level Decode Process} - -\subsubsection{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. - -\paragraph{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. - -\paragraph{Comment Header} -The comment header includes user text comments (``tags'') and a vendor -string for the application/library that produced the bitstream. The -encoding and proper use of the comment header is described in \xref{vorbis:spec:comment}. - -\paragraph{Setup Header} -The setup header includes extensive CODEC setup information as well as -the complete VQ and Huffman codebooks needed for decode. - - -\subsubsection{Decode Procedure} - -The decoding and synthesis procedure for all audio packets is -fundamentally the same. -\begin{enumerate} -\item decode packet type flag -\item decode mode number -\item decode window shape (long windows only) -\item decode floor -\item decode residue into residue vectors -\item inverse channel coupling of residue vectors -\item generate floor curve from decoded floor data -\item compute dot product of floor and residue, producing audio spectrum vector -\item inverse monolithic transform of audio spectrum vector, always an MDCT in Vorbis I -\item overlap/add left-hand output of transform with right-hand output of previous frame -\item store right hand-data from transform of current frame for future lapping -\item if not first frame, return results of overlap/add as audio result of current frame -\end{enumerate} - -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 \emph{entirely mathematically equivalent} to the -specification, it need not be a literal semantic implementation. - -\paragraph{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 other packet types are reserved; packets -marked with a reserved 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; \emph{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}. - - - - -\paragraph{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. - - -\paragraph{Window shape decode (long windows only)} \label{vorbis:spec:window} - -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: - -\begin{center} -\includegraphics[width=\textwidth]{window1} -\captionof{figure}{overlap of two equal-sized windows} -\end{center} - -And slightly more complex in the case of overlapping unequal sized -windows: - -\begin{center} -\includegraphics[width=\textwidth]{window2} -\captionof{figure}{overlap of a long and a short window} -\end{center} - -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 \cite{Sporer/Brandenburg/Edler}. Vorbis windows -all use the slope function -\[ y = \sin(.5*\pi \, \sin^2((x+.5)/n*\pi)) . \] - - - -\paragraph{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. - - -\paragraph{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. - - - -\paragraph{inverse channel coupling} - -A detailed discussion of stereo in the Vorbis codec can be found in -the document \href{stereo.html}{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 residue 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, -the resulting residue vectors represent the fine spectral detail -of each output channel. - - - -\paragraph{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. - - - -\paragraph{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. - -% TODO/FIXME: The following two paragraphs have identical twins -% in section 4 (under "dot product") -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. - -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 -$-140$dB, it must be able to span 0 to $+140$dB. For the residue vector -to reach full scale if the floor is nailed at 0dB, it must be able to -represent $-140$dB to $+0$dB. Thus, in order to handle full range -dynamics, a residue vector may span $-140$dB to $+140$dB 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. - - - -\paragraph{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 \cite{Sporer/Brandenburg/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. - - - -\paragraph{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. - - -\paragraph{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. - - - -\paragraph{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: - -\begin{Verbatim}[commandchars=\\\{\}] -window\_blocksize(previous\_window)/4+window\_blocksize(current\_window)/4 -\end{Verbatim} - -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). -- cgit v1.1