Vorbis dev - Feb 2008 - The one thread to solve problems in the Vorbis documentation

Since documentation is now becoming an important step in the Xiph
roadmap, I figure we might as well have a thread to discuss possible
problems.

I'd like to bring attention to the following tickets in Trac:
* 1158 [1]
* 1159 [2]
* 1169 [3]

They all seem like sensible concerns and possible solutions should be
discussed here.

-Ivo

[1] https://trac.xiph.org/ticket/1158
[2] https://trac.xiph.org/ticket/1159
[3] https://trac.xiph.org/ticket/1169

On Feb 17, 2008 1:11 PM, Ivo Emanuel Gon?alves <justivo@gmail.com>
wrote:
> [3] https://trac.xiph.org/ticket/1169
Hm. I would have read "The granule position of a page represents the
end PCM sample position of the last packet completed on that page."
correctly ... data past the middle of the MDCT isn't "PCM samples"
yet, since they need to be lapped.

It would probably be reasonable to change the documentation to "The
granule position of a page represents the last completely decodable
PCM sample position of the last packet completed on that page."

Ivo Emanuel Gon?alves schrieb:
> I'd like to bring attention to the following tickets in Trac:
> * 1158 [1]
>   
The objection as mentioned in 1158 is completely valid. If you read 
unsigned numbers, it's obviously not necessary to err later if the 
numbers are negative. On the other side, libvorbis is doing a completely 
different sanity check on the data and checks if any of floor0_order, 
floor0_rate, floor0_bark_map_size or floor0_number_of_books are less 
than one. The check for floor0_number_of_books is not necessary, as it 
is the result of an unsigned value plus one.

In addition, libvorbis also checks the values read into the 
floor0_book_list array for not being less than zero (again, this is not 
possible, as the numbers are read as unsigned numbers) and for being 
less than the number of codebooks from the setup header.
If libvorbis is doing correct sanity checks, I would suggest changing 
6.2.1 of the specification to:

  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 6 bits
  5) [floor0_amplitude_offset] = read an unsigned integer of 8 bits
  6) [floor0_number_of_books] = read an unsigned integer of 4 bits and add 1
  7) if any of [floor0_order], [floor0_rate] or [floor0_bark_map_size] 
are less than one, the stream is not decodable
  8) array [floor0_book_list] = read a list of [floor0_number_of_books] 
unsigned integers of eight bits each;
  9) if any of the numbers in [floor0_book_list] are higher than 
[vorbis_codebook_count] from the setup header,
      the stream is not decodable
> * 1159 [2]
>   
? is usually the symbol for "angular frequency" and equivalent to 2?f,
but for decoding floor type 0, libvorbis assigns it a value of 
?/floor0_bark_map_size. It wouldn't hurt to mention that in the 
specification.

Tor