4
\section intro Introduction
5
This is the API documentation for the Gmerlin audio video library,
6
a library for handling and conversion of uncompressed audio- and video data.
8
Click Modules (on top of the page) to get to the main API index.
9
Here, you find just some general blabla :)
11
\section why Why gavl?
12
\subsection problem The problem
14
If you start to write some software, which has any kind of audio-, video- or image-support,
15
you'll soon be confronted with the fact, that the method for storing audio and image data in
16
memory is by no means standardized. In the audio area, we have different ways to store
17
multichannel sound (interleaved or all channels separate) and different sample sizes.
18
Furthermore, it can happen, that a cheap soundcard isn't happy with the 5.1 channel sound
19
and the 48 kHz samplerate, so you'll need to convert it to 44.1 kHz/Stereo.
20
In the video and image area, the situation is not better. Images can be planar or packed,
21
have different colorspaces, color orderings and chroma subsampling modes.
23
So you can learn how to read images in 24 bit RGB and display them with GTK or SDL. Handling
24
interleaved 16 bit audio samples is also no major problem. But if your program becomes
25
popular, people want to have 24 bit audio, RGB images with 16 bit per color channel
26
(or even floating point),
27
and they are not longer satisfied with your bilinear video scaler. If you want to support
28
a large number of formats, you'll want to convert each format into each other without any
29
intermediate conversion (to save time and preserve accuracy).
31
Now you can do some simple mathematics to find out, that for N formats, the number of
32
conversions from every format to every other is N*(N-1). Assuming, you want to support
33
26 pixelformats (like gavl does at the time, this file was written), you end up with
34
a theoretical number of 650 conversion routines. After removing redundant conversions,
35
you still have to write more than 600 functions. Since these are for pixelformats only,
36
and you also want to do audio mixing for all sample formats and lots of other conversions,
37
the total number of routines will soon exceed 1000.
39
These numbers are probably the reason, why up to now, no universal solution for the
40
problems described above, was written.
42
\subsection solution The solution
44
Programming universal audio/video converters is a painful process. 1000s of conversion
45
routines must be written, debugged, tested and optimized.
46
For this reason, a decision was made to do this madness once and make it available for other
47
programmers who can afford to write GPL software. Gavl handles mainly the following tasks:
49
- Definition of audio/video formats. This is done by having several enums and
50
structures, which contain all information necessary for unambiguous definition of an
51
Audio/Video format. A gavl enabled application will automatically have support for the
52
same range of formats as gavl.
53
- Containers for audio- and video-frames. These can carry A/V data in all supported
54
formats. Basic routines are available to allocate/free/copy frames and some utilities.
55
- Conversion among all formats. There are generic audio and video converters available,
56
which have a configurable quality level. Higher quality always means lower speed.
57
This means, that you can use gavl, if you must handle 100 audio streams simultaneously
58
at telephone quality as well as for High Definition video production.
60
A development goal of gavl is to have a complete set of conversions. You'll never get
61
black images or silent audio frames because of missing conversion routines or speed losses
62
because intermediate conversions are invoked. After this goal is reached, sometimes alternate
63
routines are implemented, which focus either on more speed or higher accuracy. These can
64
be selected by choosing a quality other than 3.
66
\subsection advantages Advantages
68
Using gavl in your application brings lots of advantages:
70
- The most ugly tasks of multimedia programming are already done for you, so you
71
can concentrate on your application
72
- If you nevertheless find ways to improve the quality and/or speed of gavl, then do so.
73
Making and sending a patch will still be less work, than writing such a library from scratch.
74
- Without any additional labor, you handle all formats, which are supported by gavl.
75
Impress your audience with 32 bit audio or floating point RGB processing.
76
- Gavl fits smoothly to all existing Audio/Video and image APIs. You'll find lots of examples
77
in the sourcetrees of gmerlin and gmerlin_avdecoder.
78
- APIs (for codecs, hardware access, effects etc.), which are based on gavl, can
79
nicely interact with each other. You can, for example, easily write an import module for
80
gmerlin_avdecoder, which will decode most important Audio/Video formats.