The Importance of Good Documentation

This entire past week I’ve been reading about the MPEG-2 specs. I’ve got some video files that have KLV data stored in the user_data extension of the MPEG stream. So, right off the bat, I tried using ffmpeg‘s avcodec library. Unfortunately, there is no documentation. Seriously, they have no explanation on how to use the API. Websearching found me two tutorials, one that uses img_convert (which is now so deprecated as to be completely removed), and a more recent one that actually implements a full video player, rather than a frame grabber. Both of these also comment on the lack of documentation; in fact that was the tutorial authors’ primary reason for writing the tutorial!

Though useful for their purposes, I’m not that interested in actually playing these videos; rather, I want raw access to particular pieces of the stream (user_data section). After much browsing of the ffmpeg source, and trying, through these tutorials, to understand how to use its undocumented API, I finally figured out that I can’t do what I really want to do. The libavcodec/mpeg12.c file, which contains the decoder code for MPEG-2, totally skips over the user_data sections!!

An entire week spent, all to figure out that I have to implement things myself. I’m going to try and see if I can’t work within the ffmpeg code and tweak it to do the tasks that I require, rather that re-implementing the wheel.

Honestly though, ffmpeg is used by so many projects that it really, really deserves to have much better documentation. It shouldn’t take a newbie the better portion of a week to discover what’s possible within the existing framework. And they shouldn’t have to go browsing around the internal portions of the code in order to gain understanding of how to use the API. They’ve been around long enough that there’s simply no excuse for a lack of explanatory documents regarding the API. I guess that I’m just spoiled after having grown accustomed to the excellence that is Trolltech’s documentation.