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