gavl Documentation

Introduction

This is the API documentation for the Gmerlin audio video library, a library for handling and conversion of uncompressed audio- and video data.

Click Modules (on top of the page) to get to the main API index. Here, you find just some general blabla :)

Why gavl?

The problem

If you start to write some software, which has any kind of audio-, video- or image-support, you'll soon be confronted with the fact, that the method for storing audio and image data in memory is by no means standardized. In the audio area, we have different ways to store multichannel sound (interleaved or all channels separate) and different sample sizes. Furthermore, it can happen, that a cheap soundcard isn't happy with the 5.1 channel sound and the 48 kHz samplerate, so you'll need to convert it to 44.1 kHz/Stereo. In the video and image area, the situation is not better. Images can be planar or packed, have different colorspaces, color orderings and chroma subsampling modes.

So you can learn how to read images in 24 bit RGB and display them with GTK or SDL. Handling interleaved 16 bit audio samples is also no major problem. But if your program becomes popular, people want to have 24 bit audio, RGB images with 16 bit per color channel (or even floating point), and they are not longer satisfied with your bilinear video scaler. If you want to support a large number of formats, you'll want to convert each format into each other without any intermediate conversion (to save time and preserve accuracy).

Now you can do some simple mathematics to find out, that for N formats, the number of conversions from every format to every other is N*(N-1). Assuming, you want to support 26 pixelformats (like gavl does at the time, this file was written), you end up with a theoretical number of 650 conversion routines. After removing redundant conversions, you still have to write more than 600 functions. Since these are for pixelformats only, and you also want to do audio mixing for all sample formats and lots of other conversions, the total number of routines will soon exceed 1000.

These numbers are probably the reason, why up to now, no universal solution for the problems described above, was written.

The solution

Programming universal audio/video converters is a painful process. 1000s of conversion routines must be written, debugged, tested and optimized. For this reason, a decision was made to do this madness once and make it available for other programmers who can afford to write GPL software. Gavl handles mainly the following tasks:

• Definition of audio/video formats. This is done by having several enums and structures, which contain all information necessary for unambiguous definition of an Audio/Video format. A gavl enabled application will automatically have support for the same range of formats as gavl.
• Containers for audio- and video-frames. These can carry A/V data in all supported formats. Basic routines are available to allocate/free/copy frames and some utilities.
• Conversion among all formats. There are generic audio and video converters available, which have a configurable quality level. Higher quality always means lower speed. This means, that you can use gavl, if you must handle 100 audio streams simultaneously at telephone quality as well as for High Definition video production.

A development goal of gavl is to have a complete set of conversions. You'll never get black images or silent audio frames because of missing conversion routines or speed losses because intermediate conversions are invoked. After this goal is reached, sometimes alternate routines are implemented, which focus either on more speed or higher accuracy. These can be selected by choosing a quality other than 3.

Advantages

Using gavl in your application brings lots of advantages:

• The most ugly tasks of multimedia programming are already done for you, so you can concentrate on your application
• If you nevertheless find ways to improve the quality and/or speed of gavl, then do so. Making and sending a patch will still be less work, than writing such a library from scratch.
• Without any additional labor, you handle all formats, which are supported by gavl. Impress your audience with 32 bit audio or floating point RGB processing.
• Gavl fits smoothly to all existing Audio/Video and image APIs. You'll find lots of examples in the sourcetrees of gmerlin and gmerlin_avdecoder.
• APIs (for codecs, hardware access, effects etc.), which are based on gavl, can nicely interact with each other. You can, for example, easily write an import module for gmerlin_avdecoder, which will decode most important Audio/Video formats.