Mercurial > mplayer.hg
annotate DOCS/tech/codec-devel.txt @ 26883:a365271c97a5
Revert commit r26897.
XviD is the correct spelling of the codec.
You can see it written in the codec own
documentation and header files.
Prefered name capitalization confirmed
in conversation with XviD developer (prunedtree).
author | iive |
---|---|
date | Wed, 28 May 2008 23:04:41 +0000 |
parents | 4df11ac927fc |
children | bddae697e10d |
rev | line source |
---|---|
3862 | 1 A Guide To Developing MPlayer Codecs |
2 by Mike Melanson (melanson at pcisys dot net) | |
7349 | 3 updated to libmpcodecs arch by A'rpi |
3862 | 4 |
7399 | 5 SEE ALSO: libmpcodecs.txt !!! |
6 | |
25880
4df11ac927fc
clarify comments/docs about lav* being the preferred place to implement new
ivo
parents:
25872
diff
changeset
|
7 NOTE: If you want to implement a new native codec, please add it to |
4df11ac927fc
clarify comments/docs about lav* being the preferred place to implement new
ivo
parents:
25872
diff
changeset
|
8 libavcodec. libmpcodecs is considered mostly deprecated, except for wrappers |
4df11ac927fc
clarify comments/docs about lav* being the preferred place to implement new
ivo
parents:
25872
diff
changeset
|
9 around external libraries and codecs requiring binary support. |
25872
3eeaf9d4c65a
note on new demuxers and codecs, add them to lav* instead of libmp*
ivo
parents:
7399
diff
changeset
|
10 |
3862 | 11 Introduction |
12 ------------ | |
13 I've developed a number of open source decoders for the MPlayer project, | |
14 for both audio and video data. As such, I feel I'm qualified to document a | |
15 few notes about developing new codecs for the codebase. | |
16 | |
17 As always, the best way to learn how to incorporate a new codec is to | |
18 study a bunch of existing code. This document is supplementary material to | |
19 the code, meant to give some tips, pointers, and a general roadmap. | |
20 | |
21 A note about terminology: "Codec" stands for coder/decoder (or | |
22 compressor/decompressor, if you prefer). The term refers to a module that | |
23 can both encode and decode data. However, this document focuses primarily | |
24 on incorporating decoders. Still, the terms "decoder" and "codec" are | |
25 often used interchangeably. | |
26 | |
27 Necessary Materials | |
28 ------------------- | |
29 So you've decided that you want to implement a new decoder for | |
30 MPlayer. There are a few things you will need: | |
31 | |
32 - Knowledge of the codec to be implemented: You will need to know the data | |
33 format of the chunks that MPlayer will pass to you. You will need to know | |
34 how to take apart the data structures inside. You will need to know the | |
35 algorithmic operations that need to be performed on the data in order to | |
36 reconstruct the original media. | |
37 | |
38 - Sample media: Preferably, lots of it. You will need media encoded in | |
39 your data format and stored in a media file format that MPlayer knows how | |
40 to parse (these include AVI, ASF, MOV, RM, VIVO, among others). If the | |
41 encoded data is stored in a media file format that MPlayer doesn't | |
42 understand, then you will either need to somehow convert the format to a | |
43 media file format that the program does understand, or write your own | |
44 MPlayer file demuxer that can handle the data. Writing a file demuxer | |
45 is beyond the scope of this document. | |
46 Try to obtain media that stresses all possible modes of a | |
47 decoder. If an audio codec is known to work with both mono and stereo | |
48 data, search for sample media of both types. If a video codec is known to | |
49 work at 7 different bit depths, then, as painful as it may be, do what you | |
50 can to obtain sample media encoded for each of the 7 bit depths. | |
51 | |
52 - Latest CVS snapshot: It's always useful to develop code for the very | |
53 latest development version of MPlayer. Be sure to update your local CVS | |
54 copy often. | |
55 | |
56 - General programming knowledge, working Linux development environment: I | |
57 would hope that these items would go without saying, but you never know. | |
58 | |
59 Typical Development Cycle | |
60 ------------------------- | |
61 1) Set up basic infrastructure | |
62 First things first, there's a big song and dance to go through in order to | |
63 let the MPlayer program know that you have a new codec to incorporate. | |
64 | |
65 First, modify your local copy of codecs.conf. It may be system-shared or | |
66 in your home directory. Add a new entry for your codec. If it's an open | |
67 source codec, it would be a good idea to place the new entry with the rest | |
68 of the open source codecs. When you're confident that you have the entry | |
69 right, be sure to add it to etc/codecs.conf in your workspace. See the | |
70 file codecs.conf.txt for a detailed description of the format of this | |
71 file. Create a new audiocodec or videocodec block with the proper info, | |
72 FOURCCs/format numbers, output formats, and a unique driver name. Remember | |
73 the driver name. | |
74 | |
75 Next, create a new source file which contains the main decoding function | |
76 that MPlayer will call to decode data. Eventually, you may have multiple | |
7349 | 77 files which comprise your decoder, but let's start simple here. |
78 For audio codecs, see ad_sample.c skeleton. For video, choose one of the | |
79 existing vd_*.c files which you think is close to your codec in behaviour. | |
3862 | 80 |
7349 | 81 Next, modify the Makefile so that it will compile your new source file. |
82 Also, add your codec to the array in ad.c (for audio) or vd.c (for video). | |
3862 | 83 |
84 Next, compile the project and see if you have everything correct so far. | |
85 | |
86 Next, you want to make sure that the encoded data is making it to your | |
87 decoding function in the first place. This may sound like a trivial | |
88 exercise, but there are a lot of things that can go wrong (and I've | |
89 watched most of them go wrong in my experience). At the beginning of your | |
90 skeleton decoder function, enter the following code: | |
91 int i; | |
92 for (i = 0; i < 16; i++) | |
93 printf ("%02X ", input[i]); | |
94 printf ("\n"); | |
95 When you compile and run MPlayer, your decoder function will print the | |
96 first 16 bytes of each data chunk that it receives. Open the sample media | |
97 in a hex editor and reconcile what you see on the screen with what | |
98 you find in the file. If the decoder is printing the first 16 bytes of | |
99 each block, that's a good sign that you're ready to move on to step | |
100 2. Otherwise, you need to figure out why the data isn't getting to your | |
101 decoder. Is your decoder even being invoked? If not, why not? | |
102 | |
103 2) Develop the decoder | |
4630 | 104 Go for it. Remember to make it work, first, then make it work fast. Some |
105 specific tips: | |
106 | |
107 What output formats should you support in your decoder? Whatever makes | |
108 sense. YUV output is always preferable over RGB output. Generally, if a | |
109 codec uses a YUV data as its source data, you will be able to decode a | |
110 frame of YUV data. If a codec takes RGB data as its input, as many older | |
111 video codecs do, then there's no point in supporting YUV output; just | |
112 output as many RGB formats as possible. | |
113 | |
114 The most preferred output format for video data is YV12. This is because | |
115 MPlayer supports a multitude of hardware devices that can display, scale, | |
116 and filter this type of data directly. MPlayer also has a bunch of | |
117 optimized conversion functions that can convert YV12 data to any other | |
118 type of output data. | |
119 | |
120 If you do take the RGB output route, you should be aware that MPlayer | |
121 actually orders packed RGB data as BGR. If you're decoding into a BGR24 | |
122 buffer, the output will look like: | |
123 B G R B G R B G R B ... | |
124 If you're decoding into a BGR32 buffer, there will need to be an | |
125 additional (unused) byte after each BGR triplet: | |
126 B G R - B G R - B G ... | |
127 | |
128 Make liberal use of sanity checks. Start by including the file mp_msg.h at | |
129 the start of your decoder. Then you can use the mp_msg() function as you | |
130 would a normal printf() statement. Whenever your decoder notices a strange | |
131 bit of data or an odd condition, print a message such as: | |
132 mp_msg(MSGT_DECVIDEO, MSGL_WARN, "Odd data encountered: %d\n", data); | |
133 Obviously, you should make the message a little more | |
134 descriptive, for your benefit. MSGL_WARN is a good message level for this | |
135 type of information. Look in mp_msg.h for all of the error levels. You can | |
136 even make MPlayer bail out completely by using MSGL_FATAL, but that should | |
137 never be necessary at the data decoder level. | |
138 | |
139 What conditions should trigger a warning? Anything, and I mean *anything* | |
140 out of the ordinary. Many chunks of compressed video data contain headers | |
141 with data such as width, height, and chunk size. Reconcile these fields | |
142 with the parameters passed into the decoding function (if you set it up to | |
143 take those parameters). Such data should match up. If it doesn't, issue a | |
144 warning and make an executive decision in the code about which data to | |
145 believe (personally, I always lend more weight to the data that was passed | |
146 into the decoder function, the data that comes from the container file's | |
147 header). If there's supposed to be a magic number embedded in, or computed | |
148 from, the chunk's header, issue a warning if it isn't correct. | |
149 | |
150 Whenever you're about the index into a memory array with an index that | |
151 could theoretically be out of range, then test that the index is in range, | |
152 no matter how tedious it seems. Accessing outside of your memory range is, | |
153 after all, the number 1 cause of segmentation faults. Never trust that all | |
154 the data passed to you will be correct. If an array index suddenly winds | |
155 up out of range, it's probably best to issue a warning about it and bail | |
156 out of the decoder (but not the whole application). | |
157 | |
158 Writing all of these warning statements may seem insipid, but consider | |
159 that if you don't do it when you start writing your decoder, you'll | |
160 probably end up doing it later on when your decoder isn't working properly | |
161 and you need to figure out why (believe me, I know). | |
3862 | 162 |
163 3) Debug and test the decoder | |
164 If you're extremely lucky, the decoder will work the first time. If you're | |
165 very lucky, it will work after you've reviewed your code a few times and | |
166 corrected a few obvious programming mistakes. Realistically, you will | |
167 write the decoder, review it many times and fix many obvious and subtle | |
168 programming errors, and still have to go through an elaborate debug | |
169 process in order to get the decoder to a minimally functional state. | |
170 | |
171 Big hint: Ask for all warnings. You know, the -Wall option in | |
172 gcc? It's very useful to develop your codec while running in debug | |
173 mode. In order to compile MPlayer with debug support (which includes -Wall | |
174 for all gcc operations), use the --enable-debug option when configuring | |
175 the project. Pay attention to all warnings and make it a goal to get | |
176 rid of every single one. I'll never forget when the compiler warned me | |
177 that there was no point in clamping a signed 16-bit variable within a | |
178 signed 16-bit range (the calculation to be clamped was supposed to be | |
179 stored in a signed 32-bit variable and then stored in the signed 16-bit | |
180 variable). I sat stunned for a moment, feeling like I had just dodged a | |
181 bullet as I knew that would have taken me hours to debug that kind of | |
182 mistake. | |
183 | |
184 4) Contribute decoder to codebase | |
185 Create a patch with the "diff -u" format and email it to the MPlayer | |
186 development team for approval. You will likely need to diff the following | |
187 files: | |
188 - Makefile | |
189 - etc/codecs.conf | |
7349 | 190 - ad.c or vd.c |
191 Of course, you will need to include your newly-created file(s): | |
192 vd_<name>.c -OR- ad_<name>.c. If you contribute enough decoders, the | |
193 development team may even grant you write privileges to the CVS repository. | |
3862 | 194 |
195 5) Wait for bug reports to start rolling in | |
196 You may think you're finished when you release the codec and if you're | |
197 extremely lucky, you will be right. However, it's more likely that people | |
198 will start throwing all kinds of oddball media at your decoder that it | |
199 never counted on. Cheer up; take comfort in knowing that people are | |
200 testing your code and attempting to use it as a real world | |
201 application. Download the problem media that people upload to the MPlayer | |
202 FTP site and get back to work, implementing fixed code that addresses the | |
203 issues. Contribute more patches and encourage people to hammer on your | |
204 decoder even more. This is how you make your decoder rock-solid. | |
205 | |
206 EOF |