Mercurial > mplayer.hg
annotate DOCS/tech/codec-devel.txt @ 35253:48db1b241757
Try to do something sensible when malloc fails instead
of continuing which is sure to crash.
author | reimar |
---|---|
date | Mon, 05 Nov 2012 20:45:40 +0000 |
parents | 0ad2da052b2e |
children |
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. | |
30990 | 46 Try to obtain media that stresses all possible modes of a |
3862 | 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 | |
28167 | 52 - Latest Subversion snapshot: It's always useful to develop code for the very |
53 latest development version of MPlayer. Be sure to update your local Subversion | |
3862 | 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 | |
29263
0f1b5b68af32
whitespace cosmetics: Remove all trailing whitespace.
diego
parents:
28167
diff
changeset
|
77 files which comprise your decoder, but let's start simple here. |
7349 | 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 | |
28158 | 146 into the decoder function, than the data that comes from the container file's |
4630 | 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 |
29263
0f1b5b68af32
whitespace cosmetics: Remove all trailing whitespace.
diego
parents:
28167
diff
changeset
|
191 Of course, you will need to include your newly-created file(s): |
7349 | 192 vd_<name>.c -OR- ad_<name>.c. If you contribute enough decoders, the |
28167 | 193 development team may even grant you write privileges to the Subversion |
194 repository. | |
3862 | 195 |
196 5) Wait for bug reports to start rolling in | |
197 You may think you're finished when you release the codec and if you're | |
198 extremely lucky, you will be right. However, it's more likely that people | |
199 will start throwing all kinds of oddball media at your decoder that it | |
200 never counted on. Cheer up; take comfort in knowing that people are | |
29263
0f1b5b68af32
whitespace cosmetics: Remove all trailing whitespace.
diego
parents:
28167
diff
changeset
|
201 testing your code and attempting to use it as a real world |
3862 | 202 application. Download the problem media that people upload to the MPlayer |
203 FTP site and get back to work, implementing fixed code that addresses the | |
204 issues. Contribute more patches and encourage people to hammer on your | |
205 decoder even more. This is how you make your decoder rock-solid. | |
206 | |
207 EOF |