What I hate about the Theora codec.

TheoraIDHeaderDiagram

For the past three weeks or so, I’ve been writing C code again. It’s been both fun and frustrating, since it’s been probably twenty years or so since I’ve done any serious coding in that language. The application is for a startup, and I can’t reveal the specific task I’m doing, but it involves reading data from a video stream.

I could have used any video technology I wanted, but to avoid patent encumberances I went with the Ogg container format with the Theora video CODEC. Luckily, I don’t need to actually decompress the video stream, I just need to be able to manipulate it at the frame/page level. Shouldn’t be too hard, and for the most part it wasn’t. I started by looking at the reference implementations for Ogg and Theora (libogg and libtheora), but they were a little too full-featured for my application, so I started to roll my own.

Things were going pretty well, until I got into the Theora identification header. I’d read the relevant parts of the spec and did some poking around with a hex viewer on my sample Ogg files. Everything looked good, so I created a C structure definition that I thought matched the header:

 

typedef struct __attribute__ ((__packed__)) _THEORA_ID_HEADER {
THEORA_HEADER HDR; // Common header.
byte VMAJ; // The major version number.
byte VMIN; // The minor version number.
byte VREV; // The version revision number.
uint16 FMBW; // The width of the frame in macro blocks.
uint16 FMBH; // The height of the frame in macro blocks.
uint PICW:24; // The width of the picture region in pixels.
uint PICH:24; // The height of the picture region in pixels.
byte PICX; // The X offset of the picture region in pixels.
byte PICY; // The Y offset of the picture region in pixels.
uint32 FRN; // The frame-rate numerator.
uint32 FRD; // The frame-rate denominator.
uint PARN:24; // The pixel aspect-ratio numerator.
uint PARD:24; // The pixel aspect-ratio denominator.
byte CS; // The color space.
uint NOMBR:24; // The nominal bitrate of the stream, in bits per second.
ushort QUAL:6; // The quality hint.
ushort KFGSHIFT:5; // The amount to shift the key frame number by in the granule position
ushort PF:2; // Pixel format.
ushort RES:3; // Reserved.
} THEORA_ID_HEADER;

The only problem: the values I read from an actual Theora stream didn’t match the header. They almost matched. Except for the one field I actually cared about (of course). I need the KFGSHIFT field to interpret the granule positions of the Ogg stream, and even though it’s apparently hardcoded to 6 in every library out there, my OCD wouldn’t let me get by with that. I wanted the real value from the stream. So, I fired up a hex editor in Atom and started digging.

TheoraHeaderHexDump

After counting bytes, and recounting bytes, I found the offending 16 bit value that contains the bitfields in the header: 00 c0. Or, bitwise:

msb                         lsb
7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0
+---------------+--------------
1 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0

Which didn’t match the diagram in the Theora spec. Looking at that diagram, I was expecting: 80 01.

msb                         lsb
7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0
+---------------+--------------
0 0 0 0 0 0 0 1 1 0 0 0 0 0 0 0

WTF?! I expected QUAL, PF, and RES to all be 0. I expected KFGSHIFT to be 6. Why were the two most-significant bits set? What was going on? So I went back to the Theora spec. I read the code for the Theora reference implementation (libtheora). Finally, buried in section 5.2 of the spec I found the explanation of this craziness.

The decoder logically unpacks integers by first reading the MSb of a binary integer from the logical bitstream, followed by the next most significant bit, etc., until the required number of bits have been read. When unpacking the bytes into bits, the decoder begins by reading the MSb of the integer to be read from the most significant unread bit position of the source byte, followed by the next-most significant bit position of the destination integer, and so on up to the requested number of bits. Note that this differs from the Vorbis I codec, which begins decoding with the LSb of the source integer, reading it from the LSb of the source byte. When all the bits of the current source byte are read, decoding continues with the MSb of the next byte. Any unfilled bits in the last byte of the packet MUST be cleared to zero by the encoder.

So, logically bits are written to the Theora stream most-significant bit first. Okaaaay. A lot of people would look at this and say “well, they must have had a good reason for this”. I’ve been bit-twiddling since the early 80s, and I can unequivocally tell you: they don’t. This scheme is just confusing and crazy.

Sure, if you just write a bit streaming library and call it to read and write all of your values, you’ll never see this aspect. But just look at the structure in figure 6.2 above: only four values cannot be expressed in even byte quantities. A structure with bitfields is a fine way to deal with this problem, but instead of the bit fields in the header being arranged like this:

msb                         lsb
7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0
+---------------+--------------
R R R P P K K K K K Q Q Q Q Q Q
Q = QUAL, K = KFGSHIFT, P = PF, R = RES

They’re actually arranged like this:

msb                         lsb
7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0
+---------------+--------------
K K K P P R R R Q Q Q Q Q Q K K
Q = QUAL, K = KFGSHIFT, P = PF, R = RES

So, yes, that five-bit KFGSHIFT field is arranged so that it is virtually impossible to reference it as a single quantity, bit-wise. You can’t shift, you can’t mask. You have to access each piece separately and combine them. They also bear no resemblance to the diagram in the spec. So, my new, not-so-attractive structure looks like this (most fields omitted for brevity):

typedef struct __attribute__ ((__packed__)) _THEORA_ID_HEADER {
  . . .
  // !!!HACK!!! ok, per the Theora spec, bit fields are
  // "read" and "written" to bytes most-significant bit first. This means
  // that the KFGSHIFT field (which is, of course, the only field I'm interested
  // in here) isn't stored contiguously in the file. The MSBs are in the first
  // byte, the LSBs in the second. Crazy. http://www.theora.org/doc/Theora.pdf
  ushort KFGSHIFT_MSB:2;		// The amount to shift the key frame number by in the granule position
  ushort QUAL:6;		// The quality hint.

  ushort RES:3;     // Reserved.
  ushort PF:2;      // Pixel format.
  ushort KFGSHIFT_LSB:3;		// The amount to shift the key frame number by in the granule position
} THEORA_ID_HEADER;

#define THEORA_GET_KFGSHIFT(th) ((th).KFGSHIFT_MSB << 3 | (th).KFGSHIFT_LSB)

So, that structure along with the helper macro will give me the KFGSHIFT value I wanted, aka 6. Hopefully the next person implementing Theora will find this post and save themselves a head-desk moment.

One comment

  1. Tim Jowers says:

    Totally matches what I’ve found in using libraries – even Java: the edge cases are often not programmed for and end up taking me a few days to create work-arounds. I notice you often roll-your-own when doing UI layer work and have come around to that approach myself. The libraries are just too brittle both in js and in Android.

  2. Ernestoarcal says:
    Your comment is awaiting moderation. This is a preview, your comment will be visible after it has been approved.

    Thanks a lot! Very good stuff!

    compare viagra levitra celias viagra prescription low cost
    viagra 100mg
    eli lily viagra patent – https://genericviagrantx.com

    Keithgence
    Richardtug
    Ernestoarcal

  3. Ernestoarcal says:
    Your comment is awaiting moderation. This is a preview, your comment will be visible after it has been approved.

    Kudos! Plenty of info.

    class action on lawsuit for viagra cheap viagra without prescription usa
    viagra generic
    can women take viagra and hormones – https://genericviagrarcp.com

    Keithgence
    Richardtug
    Ernestoarcal

  4. Ernestoarcal says:
    Your comment is awaiting moderation. This is a preview, your comment will be visible after it has been approved.

    Really all kinds of fantastic material.

    reputable on-line docotrs viagra canadian viagra
    buy generic viagra
    directions for taking viagra – https://genericviagrantx.com

    Keithgence
    Richardtug
    Ernestoarcal

  5. Ernestoarcal says:
    Your comment is awaiting moderation. This is a preview, your comment will be visible after it has been approved.

    Kudos! Ample advice.

    viagra suppositories village pharmacy viagra alternatives cialis
    viagra for women
    fre viagra – https://genericviagrantx.com

    Keithgence
    Richardtug
    Ernestoarcal

  6. Ernestoarcal says:
    Your comment is awaiting moderation. This is a preview, your comment will be visible after it has been approved.

    Truly many of useful information!

    natural compounds in viagra viagra ans cialis
    viagra without a doctor prescription
    cheap viagra forum – https://genericviagrantx.com

    Keithgence
    Richardtug
    Ernestoarcal

  7. Ernestoarcal says:
    Your comment is awaiting moderation. This is a preview, your comment will be visible after it has been approved.

    Useful information. Kudos.

    any medication make viagra less effective generic viagra fast shipping
    viagra 100mg
    irish viagra – https://genericviagramsl.com

    Keithgence
    Richardtug
    Ernestoarcal

  8. Ernestoarcal says:
    Your comment is awaiting moderation. This is a preview, your comment will be visible after it has been approved.

    This is nicely put! !

    viagra to order viagras gelato flavor
    viagra online
    viagra blood low pressure – https://genericviagrantx.com

    Keithgence
    Richardtug
    Ernestoarcal

  9. Ernestoarcal says:
    Your comment is awaiting moderation. This is a preview, your comment will be visible after it has been approved.

    Fine postings. Thanks a lot!

    compra viagra online define viagra
    cheap viagra
    smooth muscle piperazine viagra – https://genericviagrarcp.com

    Keithgence
    Richardtug
    Ernestoarcal

  10. Ernestoarcal says:
    Your comment is awaiting moderation. This is a preview, your comment will be visible after it has been approved.

    Fantastic advice. Appreciate it.

    viagra medicinal safe site to purchase viagra
    cheap viagra
    meth and viagra – https://genericviagrantx.com

    Keithgence
    Richardtug
    Ernestoarcal

  11. Ernestoarcal says:
    Your comment is awaiting moderation. This is a preview, your comment will be visible after it has been approved.

    Fantastic information. Cheers.

    url links viagra blood-pressure een van viagra sex tubes
    viagra 100mg
    kamagra viagra jelly – https://genericviagramsl.com

    Keithgence
    Richardtug
    Ernestoarcal

  12. Ernestoarcal says:
    Your comment is awaiting moderation. This is a preview, your comment will be visible after it has been approved.

    Nicely put. Thank you!

    chinese herb and viagra coffee viagra
    viagra without a doctor prescription
    instructions for taking viagra – https://genericviagrarcp.com

    Keithgence
    Richardtug
    Ernestoarcal

  13. Ernestoarcal says:
    Your comment is awaiting moderation. This is a preview, your comment will be visible after it has been approved.

    Wow all kinds of good data!

    pulmonary in hypertension viagra generic viagra caverta cialis cheap
    viagra pills
    taking viagra after cialis – https://genericviagrantx.com

    Keithgence
    Richardtug
    Ernestoarcal

  14. Ernestoarcal says:
    Your comment is awaiting moderation. This is a preview, your comment will be visible after it has been approved.

    Appreciate it. An abundance of info.

    viagra performance generick viagra
    buy viagra
    mixing zanidip and viagra – https://genericviagrantx.com

    Keithgence
    Richardtug
    Ernestoarcal

  15. Ernestoarcal says:
    Your comment is awaiting moderation. This is a preview, your comment will be visible after it has been approved.

    Really a good deal of great tips.

    everyday viagra out of court settlement for viagra
    viagra online
    generic viagra for under $50.00 – https://genericviagrarcp.com

    Keithgence
    Richardtug
    Ernestoarcal

  16. Ernestoarcal says:
    Your comment is awaiting moderation. This is a preview, your comment will be visible after it has been approved.

    Seriously a lot of fantastic data!

    people using viagra video best prices viagra
    viagra for sale uk
    buy viagra online uk – https://genericviagrarcp.com

    Keithgence
    Richardtug
    Ernestoarcal

  17. Ernestoarcal says:
    Your comment is awaiting moderation. This is a preview, your comment will be visible after it has been approved.

    Helpful information. Thanks.

    viagra celerity stand viagra in india by mail order
    cheap viagra
    51 viagra – https://genericviagramsl.com

    Keithgence
    Richardtug
    Ernestoarcal

  18. Ernestoarcal says:
    Your comment is awaiting moderation. This is a preview, your comment will be visible after it has been approved.

    Wow all kinds of great data!

    four hour hard on viagra viagra pd5
    buy generic viagra
    viagra blue vision – https://genericviagrantx.com

    Keithgence
    Richardtug
    Ernestoarcal

  19. Ernestoarcal says:
    Your comment is awaiting moderation. This is a preview, your comment will be visible after it has been approved.

    This is nicely expressed! !

    patent on viagra using viagra to last longer
    generic viagra 100mg
    buy viagra in budapest – https://genericviagrantx.com

    Keithgence
    Richardtug
    Ernestoarcal

  20. Ernestoarcal says:
    Your comment is awaiting moderation. This is a preview, your comment will be visible after it has been approved.

    Regards, I like this.

    book viagra diaries does viagra make you larger
    cheap viagra
    real viagra without a prescription – https://genericviagrarcp.com

    Keithgence
    Richardtug
    Ernestoarcal

  21. Ernestoarcal says:
    Your comment is awaiting moderation. This is a preview, your comment will be visible after it has been approved.

    Wonderful write ups. Thank you.

    can women use viagra or levitra order viagra on-line
    buy generic viagra
    does alcahol effect viagra – https://genericviagramsl.com

    Keithgence
    Richardtug
    Ernestoarcal

  22. Ernestoarcal says:
    Your comment is awaiting moderation. This is a preview, your comment will be visible after it has been approved.

    Thanks a lot! Loads of content!

    does viagra work on women buy viagra with cashiers check
    generic viagra 100mg
    100 mg viagra us pharmacy – https://genericviagrantx.com

    Keithgence
    Richardtug
    Ernestoarcal

  23. Ernestoarcal says:
    Your comment is awaiting moderation. This is a preview, your comment will be visible after it has been approved.

    Thank you! Helpful information.

    organic viagra dont eat with viagra
    generic viagra 100mg
    viagra cialis bu safe paypal – https://genericviagrarcp.com

    Keithgence
    Richardtug
    Ernestoarcal

  24. Ernestoarcal says:
    Your comment is awaiting moderation. This is a preview, your comment will be visible after it has been approved.

    Nicely put, Thank you.

    virus took over email aol viagra target viagra cost
    viagra pills
    who moved my viagra – https://genericviagramsl.com

    Keithgence
    Richardtug
    Ernestoarcal

  25. Ernestoarcal says:
    Your comment is awaiting moderation. This is a preview, your comment will be visible after it has been approved.

    Thanks a lot. I value it!

    does viagra help keep it up find viagra edinburgh pages search charles
    buy viagra online
    is viagra good for hypertension – https://genericviagramsl.com

    Keithgence
    Richardtug
    Ernestoarcal

  26. Ernestoarcal says:
    Your comment is awaiting moderation. This is a preview, your comment will be visible after it has been approved.

    Fantastic write ups. Kudos.

    cheapest price for viagra and cialis what to know abouth viagra jelly
    generic viagra 100mg
    interaction between eutirox and viagra – https://genericviagrarcp.com

    Keithgence
    Richardtug
    Ernestoarcal

  27. Ernestoarcal says:
    Your comment is awaiting moderation. This is a preview, your comment will be visible after it has been approved.

    Nicely put, Kudos.

    investing in a herbal viagra scam casanovas secret herbal viagra
    viagra 100mg
    viagra sunday dispatch – https://genericviagrarcp.com

    Keithgence
    Richardtug
    Ernestoarcal

  28. Ernestoarcal says:
    Your comment is awaiting moderation. This is a preview, your comment will be visible after it has been approved.

    Fantastic content. Regards.

    viagra geniric viagra for sale in gibralter
    viagra without a doctors prescription
    what if viagra fails – https://genericviagramsl.com

    Keithgence
    Richardtug
    Ernestoarcal

  29. Ernestoarcal says:
    Your comment is awaiting moderation. This is a preview, your comment will be visible after it has been approved.

    Kudos, Very good stuff!

    is viagra safe for teenagers inventor of viagra
    generic viagra online
    viagra boring pages edinburgh search – https://genericviagrantx.com

    Keithgence
    Richardtug
    Ernestoarcal

  30. Ernestoarcal says:
    Your comment is awaiting moderation. This is a preview, your comment will be visible after it has been approved.

    Thanks a lot. Loads of postings.

    teenney transplant viagra generic timetable viagra cialis
    generic viagra
    viagra approved – https://genericviagrarcp.com

    Keithgence
    Richardtug
    Ernestoarcal

  31. Ernestoarcal says:
    Your comment is awaiting moderation. This is a preview, your comment will be visible after it has been approved.

    Seriously plenty of very good tips.

    best source for viagra viagra constapation
    generic viagra
    viagra price cvs walgreen costco – https://genericviagramsl.com

    Keithgence
    Richardtug
    Ernestoarcal

  32. Ernestoarcal says:
    Your comment is awaiting moderation. This is a preview, your comment will be visible after it has been approved.

    You’ve made your point!

    viagra penis pics viagra paypal free shipping
    viagra 100mg
    where do you buy viagra online – https://genericviagrantx.com

    Keithgence
    Richardtug
    Ernestoarcal

  33. Ernestoarcal says:
    Your comment is awaiting moderation. This is a preview, your comment will be visible after it has been approved.

    You have made your stand very clearly.!

    viagra antacid over the counter viagra alternative
    buy viagra
    review viagra cialas levitra – https://genericviagrantx.com

    Keithgence
    Richardtug
    Ernestoarcal

  34. Ernestoarcal says:
    Your comment is awaiting moderation. This is a preview, your comment will be visible after it has been approved.

    You actually suggested that perfectly!

    buy viagra online without prescription uk viagra prescription fill
    viagra without a doctors prescription
    internet viagra – https://genericviagrantx.com

    Keithgence
    Richardtug
    Ernestoarcal

  35. Ernestoarcal says:
    Your comment is awaiting moderation. This is a preview, your comment will be visible after it has been approved.

    Many thanks. Valuable information!

    viagra vs cialis reviews viagra contest
    viagra without a doctor prescription
    cheap viagra credit – https://genericviagramsl.com

    Keithgence
    Richardtug
    Ernestoarcal

  36. Ernestoarcal says:
    Your comment is awaiting moderation. This is a preview, your comment will be visible after it has been approved.

    You actually stated that wonderfully!

    viagra cutting best viagra prices
    generic viagra 100mg
    will viagra work for premature ejaculation – https://genericviagramsl.com

    Keithgence
    Richardtug
    Ernestoarcal

  37. Ernestoarcal says:
    Your comment is awaiting moderation. This is a preview, your comment will be visible after it has been approved.

    You suggested this perfectly.

    viagra dose aion ed viagra cialis
    viagra 100mg
    buying viagra online in australia – https://genericviagrantx.com

    Keithgence
    Richardtug
    Ernestoarcal

  38. Ernestoarcal says:
    Your comment is awaiting moderation. This is a preview, your comment will be visible after it has been approved.

    Tips clearly used.!

    viagra healing viagra full prescribing dosage
    buy generic viagra
    viagra head office – https://genericviagrarcp.com

    Keithgence
    Richardtug
    Ernestoarcal

  39. Ernestoarcal says:
    Your comment is awaiting moderation. This is a preview, your comment will be visible after it has been approved.

    Regards! I like it.

    new viagra tv ad august 2010 order discount viagra
    viagra without a doctors prescription
    viagra find buy cheap search generic – https://genericviagrarcp.com

    Keithgence
    Richardtug
    Ernestoarcal

  40. Ernestoarcal says:
    Your comment is awaiting moderation. This is a preview, your comment will be visible after it has been approved.

    Regards. Ample facts.

    ellis viagra online pharmacy viagra paypal
    generic viagra 100mg
    cheap generic viagra deals – https://genericviagrantx.com

    Keithgence
    Richardtug
    Ernestoarcal

  41. Ernestoarcal says:
    Your comment is awaiting moderation. This is a preview, your comment will be visible after it has been approved.

    Helpful write ups. With thanks.

    viagra lessen side effects target viagra cost
    generic viagra online
    does viagra result in longer erections – https://genericviagramsl.com

    Keithgence
    Richardtug
    Ernestoarcal

  42. Ernestoarcal says:
    Your comment is awaiting moderation. This is a preview, your comment will be visible after it has been approved.

    You actually revealed it terrifically!

    how often can you take viagra viagra use for enlarged heart 2011
    buy viagra online
    will hydrochlorothiazide affect viagra – https://genericviagrantx.com

    Keithgence
    Richardtug
    Ernestoarcal

  43. Ernestoarcal says:
    Your comment is awaiting moderation. This is a preview, your comment will be visible after it has been approved.

    Fine advice. Thanks a lot.

    viagra v-15 picture low blood pressure taking viagra
    viagra generic
    everyday viagra dosage – https://genericviagramsl.com

    Keithgence
    Richardtug
    Ernestoarcal

  44. Ernestoarcal says:
    Your comment is awaiting moderation. This is a preview, your comment will be visible after it has been approved.

    You said it perfectly..

    cheap viagra online a href free trial viagra levitra
    viagra online
    u 6092 viagra – https://genericviagramsl.com

    Keithgence
    Richardtug
    Ernestoarcal

  45. Ernestoarcal says:
    Your comment is awaiting moderation. This is a preview, your comment will be visible after it has been approved.

    Beneficial material. Thank you.

    is maxoderm better than viagra viagra f
    viagra for women
    herbal remedy viagra – https://genericviagramsl.com

    Keithgence
    Richardtug
    Ernestoarcal

  46. Ernestoarcal says:
    Your comment is awaiting moderation. This is a preview, your comment will be visible after it has been approved.

    You stated it well!

    grapefruit viagra active ingredient in viagra natural
    viagra online
    viagra marketing – https://genericviagrarcp.com

    Keithgence
    Richardtug
    Ernestoarcal

  47. Ernestoarcal says:
    Your comment is awaiting moderation. This is a preview, your comment will be visible after it has been approved.

    This is nicely said. .

    viagra pro online in usa viagra online best prices
    generic viagra 100mg
    acupuncture oct ivf women viagra – https://genericviagrarcp.com

    Keithgence
    Richardtug
    Ernestoarcal

  48. Ernestoarcal says:
    Your comment is awaiting moderation. This is a preview, your comment will be visible after it has been approved.

    You revealed that wonderfully!

    viagra spain global systems viagra
    viagra without a doctors prescription
    buy viagra by pill – https://genericviagrarcp.com

    Keithgence
    Richardtug
    Ernestoarcal

  49. Ernestoarcal says:
    Your comment is awaiting moderation. This is a preview, your comment will be visible after it has been approved.

    Cheers. Good stuff.

    benefits of mixing cocaine and viagra viagra women
    viagra without a doctor prescription
    proven competitor to viagra cialis levitra – https://genericviagrarcp.com

    Keithgence
    Richardtug
    Ernestoarcal

  50. Ernestoarcal says:
    Your comment is awaiting moderation. This is a preview, your comment will be visible after it has been approved.

    Good data. Thanks!

    buy generic viagra si br viagra and other drugs
    generic viagra
    best price for generic viagra – https://genericviagrarcp.com

    Keithgence
    Richardtug
    Ernestoarcal

  51. Ernestoarcal says:
    Your comment is awaiting moderation. This is a preview, your comment will be visible after it has been approved.

    Lovely content, Appreciate it.

    getting peak performance from viagra is viagra bad fot health
    generic viagra 100mg
    import viagra – https://genericviagrantx.com

    Keithgence
    Richardtug
    Ernestoarcal

  52. Ernestoarcal says:
    Your comment is awaiting moderation. This is a preview, your comment will be visible after it has been approved.

    Helpful forum posts. Thanks.

    acupunture fue las viagra charles agujas viagra no presciption
    generic viagra 100mg
    q a viagra – https://genericviagrantx.com

    Keithgence
    Richardtug
    Ernestoarcal

  53. Ernestoarcal says:
    Your comment is awaiting moderation. This is a preview, your comment will be visible after it has been approved.

    Amazing loads of fantastic tips.

    how to inhance viagra’s effect quick forum readtopic viagra answer online
    generic viagra online
    viagra lawyers – https://genericviagrarcp.com

    Keithgence
    Richardtug
    Ernestoarcal

  54. Ernestoarcal says:
    Your comment is awaiting moderation. This is a preview, your comment will be visible after it has been approved.

    Truly quite a lot of amazing material!

    shopping online for viagra soft tabs copy viagra side effects
    generic viagra
    does herbal viagra really work – https://genericviagramsl.com

    Keithgence
    Richardtug
    Ernestoarcal

Leave a Reply

Your email address will not be published. Required fields are marked *