xiph.org: Ogg Vorbis documentation

# Ogg Vorbis I format specification: floor type 0 setup and decode

Last update to this document: July 19, 2002

# Overview

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.

# Floor 0 format

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.

## header decode

Configuration information for instances of floor zero decodes from the codec setup header (third packet). configuration decode proceeds as follows:

      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;

An end-of-packet condition during any of these bitstream reads renders this stream undecodable. In addition, any element of the array `[floor0_book_list]` that is greater than the maximum codebook number for this bitstream is an error condition that also renders the stream undecodable.

## packet decode

Extracting a floor0 curve from an audio packet consists of first decoding the curve amplitude and `[floor0_order]` LSP coefficient values from the bitstream, and then computing the floor curve, which is defined as the frequency response of the decoded LSP filter.

Packet decode proceeds as follows:

      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 ilog( [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.

Take note of the following properties of decode:

- An `[amplitude]` 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.

- 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 `[amplitude]` value had read zero at the beginning of decode.
- The book number used for decode can, in fact, be stored in the bitstream in ilog( `[floor0_number_of_books]` - 1 ) bits. Nevertheless, the above specification is correct and values greater than the maximum possible book value are reserved.

- The number of scalars read into the vector `[coefficients]` may be greater than `[floor0_order]`, the number actually required for curve computation. For example, if the VQ codebook used for the floor currently being decoded has a `[codebook_dimensions]` value of three and `[floor0_order]` is ten, the only way to fill all the needed scalars in `[coefficients]` 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.

## curve computation

Given an `[amplitude]` integer and `[coefficients]` 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 `[n]` specified by the decode process, we compute a floor output vector.

If the value `[amplitude]` is zero, the return value is a length `[n]` vector with all-zero scalars. Otherwise, begin by assuming the following definitions for the given vector to be synthesized:

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:

      1) [i] = 0
      2) if ( [floor0_order] is odd ) {

           3) calculate [p] and [q] according to:

         } else [floor0_order] is even {

           4) calculate [p] and [q] according to:

         }

      5) calculate [linear_floor_value] according to:

      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

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.

Ogg, Vorbis, Xiph.org Foundation and their logos are trademarks (tm) of the Xiph.org Foundation. These pages are copyright (C) 1994-2002 Xiph.org Foundation. All rights reserved.