mirror of https://github.com/mpv-player/mpv
initial commit of "Guide To Codec Hacking"
git-svn-id: svn://svn.mplayerhq.hu/mplayer/trunk@3863 b3059339-0415-0410-9bf9-f77b7e298cf2
This commit is contained in:
melanson
parent
3edb7775ee
commit
b02168a9f5
|
|
@ -0,0 +1,191 @@
|
|||
A Guide To Developing MPlayer Codecs
|
||||
by Mike Melanson (melanson at pcisys dot net)
|
||||
|
||||
Introduction
|
||||
------------
|
||||
I've developed a number of open source decoders for the MPlayer project,
|
||||
for both audio and video data. As such, I feel I'm qualified to document a
|
||||
few notes about developing new codecs for the codebase.
|
||||
|
||||
As always, the best way to learn how to incorporate a new codec is to
|
||||
study a bunch of existing code. This document is supplementary material to
|
||||
the code, meant to give some tips, pointers, and a general roadmap.
|
||||
|
||||
A note about terminology: "Codec" stands for coder/decoder (or
|
||||
compressor/decompressor, if you prefer). The term refers to a module that
|
||||
can both encode and decode data. However, this document focuses primarily
|
||||
on incorporating decoders. Still, the terms "decoder" and "codec" are
|
||||
often used interchangeably.
|
||||
|
||||
Necessary Materials
|
||||
-------------------
|
||||
So you've decided that you want to implement a new decoder for
|
||||
MPlayer. There are a few things you will need:
|
||||
|
||||
- Knowledge of the codec to be implemented: You will need to know the data
|
||||
format of the chunks that MPlayer will pass to you. You will need to know
|
||||
how to take apart the data structures inside. You will need to know the
|
||||
algorithmic operations that need to be performed on the data in order to
|
||||
reconstruct the original media.
|
||||
|
||||
- Sample media: Preferably, lots of it. You will need media encoded in
|
||||
your data format and stored in a media file format that MPlayer knows how
|
||||
to parse (these include AVI, ASF, MOV, RM, VIVO, among others). If the
|
||||
encoded data is stored in a media file format that MPlayer doesn't
|
||||
understand, then you will either need to somehow convert the format to a
|
||||
media file format that the program does understand, or write your own
|
||||
MPlayer file demuxer that can handle the data. Writing a file demuxer
|
||||
is beyond the scope of this document.
|
||||
Try to obtain media that stresses all possible modes of a
|
||||
decoder. If an audio codec is known to work with both mono and stereo
|
||||
data, search for sample media of both types. If a video codec is known to
|
||||
work at 7 different bit depths, then, as painful as it may be, do what you
|
||||
can to obtain sample media encoded for each of the 7 bit depths.
|
||||
|
||||
- Latest CVS snapshot: It's always useful to develop code for the very
|
||||
latest development version of MPlayer. Be sure to update your local CVS
|
||||
copy often.
|
||||
|
||||
- General programming knowledge, working Linux development environment: I
|
||||
would hope that these items would go without saying, but you never know.
|
||||
|
||||
Typical Development Cycle
|
||||
-------------------------
|
||||
1) Set up basic infrastructure
|
||||
First things first, there's a big song and dance to go through in order to
|
||||
let the MPlayer program know that you have a new codec to incorporate.
|
||||
|
||||
MPlayer does not feature what some would term a "clean" codec plugin
|
||||
architecture. Some log this as a complaint. Personally, I think it's
|
||||
necessary to allow MPlayer the type of flexibility to incorporate so many
|
||||
open- and closed-source codecs.
|
||||
|
||||
First, modify your local copy of codecs.conf. It may be system-shared or
|
||||
in your home directory. Add a new entry for your codec. If it's an open
|
||||
source codec, it would be a good idea to place the new entry with the rest
|
||||
of the open source codecs. When you're confident that you have the entry
|
||||
right, be sure to add it to etc/codecs.conf in your workspace. See the
|
||||
file codecs.conf.txt for a detailed description of the format of this
|
||||
file. Create a new audiocodec or videocodec block with the proper info,
|
||||
FOURCCs/format numbers, output formats, and a unique driver name. Remember
|
||||
the driver name.
|
||||
|
||||
Next, edit the file codec-cfg.h. You will find a list of #define's that
|
||||
map names like AFM_MSADPCM and VFM_MSVIDC to numbers. The definitions that
|
||||
begin with AFM_ are audio drivers. The definitions that begin with VFM_
|
||||
are video drivers. If you want to implement a new audio driver, go to the
|
||||
end of the AFM_ list and create a new AFM_ definition for your decoder
|
||||
using the next available number in the list. If you want to make a new
|
||||
video decoder, do the same thing to the VFM_ list.
|
||||
|
||||
Next, edit the file codec-cfg.c. You will find an array of audio driver
|
||||
names and video driver names. If you are implementing a new audio codec,
|
||||
add your new driver name (the one you entered into the codecs.conf
|
||||
file) between the last non-NULL entry and the NULL at the end of the
|
||||
audio driver array. If you are implementing a new video codec, do the
|
||||
same in the video driver array.
|
||||
|
||||
Next, create a new source file which contains the main decoding function
|
||||
that MPlayer will call to decode data. Eventually, you may have multiple
|
||||
files which comprise your decoder, but let's start simple here. Create the
|
||||
skeleton function for your decoder. Since you will also have to write the
|
||||
code to invoke the function, you can make the decoding function look
|
||||
however you want, with whatever parameters you feel will be
|
||||
necessary. Here's an example video decoder:
|
||||
|
||||
void some_video_decoder(
|
||||
char *encoded, // buffer of encoded data
|
||||
int encoded_size, // length of encoded buffer
|
||||
char *decoded, // buffer where decoded data is written
|
||||
int width, // width of decoded frame in pixels
|
||||
int height, // height of decoded frame in pixels
|
||||
int bytes_per_pixel) // bytes/pixel in output image
|
||||
|
||||
Here's an example audio decoder:
|
||||
|
||||
int some_audio_decoder(
|
||||
unsigned short *output, // buffer where decoded 16-bit PCM samples go
|
||||
unsigned char *input, // encoded data
|
||||
int channels) // mono = 1, stereo = 2
|
||||
|
||||
Next, modify the Makefile so that it will compile your new source
|
||||
file.
|
||||
|
||||
Next, modify either dec_audio.c or dec_video.c, depending on whether
|
||||
you're writing an audio or video decoder. You'll probably put the new
|
||||
decoder function header at the top of the file unless you've created a
|
||||
header file to handle it, in which case, you'll include the new header
|
||||
file. The dec_*.c functions are in charge of initializing codecs and then
|
||||
passing encoded data to the proper decoder function. The init and decode
|
||||
functions are big switch statements that key off of the codec definition
|
||||
numbers from codec-cfg.h. Your best bet in here is to examine some simple
|
||||
other simple decoders and clone relevant portions of the case blocks.
|
||||
|
||||
Next, compile the project and see if you have everything correct so far.
|
||||
|
||||
Next, you want to make sure that the encoded data is making it to your
|
||||
decoding function in the first place. This may sound like a trivial
|
||||
exercise, but there are a lot of things that can go wrong (and I've
|
||||
watched most of them go wrong in my experience). At the beginning of your
|
||||
skeleton decoder function, enter the following code:
|
||||
int i;
|
||||
for (i = 0; i < 16; i++)
|
||||
printf ("%02X ", input[i]);
|
||||
printf ("\n");
|
||||
When you compile and run MPlayer, your decoder function will print the
|
||||
first 16 bytes of each data chunk that it receives. Open the sample media
|
||||
in a hex editor and reconcile what you see on the screen with what
|
||||
you find in the file. If the decoder is printing the first 16 bytes of
|
||||
each block, that's a good sign that you're ready to move on to step
|
||||
2. Otherwise, you need to figure out why the data isn't getting to your
|
||||
decoder. Is your decoder even being invoked? If not, why not?
|
||||
|
||||
2) Develop the decoder
|
||||
Go for it. Remember to make it work, first, then make it work fast.
|
||||
|
||||
3) Debug and test the decoder
|
||||
If you're extremely lucky, the decoder will work the first time. If you're
|
||||
very lucky, it will work after you've reviewed your code a few times and
|
||||
corrected a few obvious programming mistakes. Realistically, you will
|
||||
write the decoder, review it many times and fix many obvious and subtle
|
||||
programming errors, and still have to go through an elaborate debug
|
||||
process in order to get the decoder to a minimally functional state.
|
||||
|
||||
Big hint: Ask for all warnings. You know, the -Wall option in
|
||||
gcc? It's very useful to develop your codec while running in debug
|
||||
mode. In order to compile MPlayer with debug support (which includes -Wall
|
||||
for all gcc operations), use the --enable-debug option when configuring
|
||||
the project. Pay attention to all warnings and make it a goal to get
|
||||
rid of every single one. I'll never forget when the compiler warned me
|
||||
that there was no point in clamping a signed 16-bit variable within a
|
||||
signed 16-bit range (the calculation to be clamped was supposed to be
|
||||
stored in a signed 32-bit variable and then stored in the signed 16-bit
|
||||
variable). I sat stunned for a moment, feeling like I had just dodged a
|
||||
bullet as I knew that would have taken me hours to debug that kind of
|
||||
mistake.
|
||||
|
||||
4) Contribute decoder to codebase
|
||||
Create a patch with the "diff -u" format and email it to the MPlayer
|
||||
development team for approval. You will likely need to diff the following
|
||||
files:
|
||||
- Makefile
|
||||
- etc/codecs.conf
|
||||
- codec-cfg.c
|
||||
- codec-cfg.h
|
||||
- dec_audio.c -OR- dec_video.c
|
||||
Of course, you will need to include your newly-created file(s). If you
|
||||
contribute enough decoders, the development team may even grant you write
|
||||
privileges to the CVS repository.
|
||||
|
||||
5) Wait for bug reports to start rolling in
|
||||
You may think you're finished when you release the codec and if you're
|
||||
extremely lucky, you will be right. However, it's more likely that people
|
||||
will start throwing all kinds of oddball media at your decoder that it
|
||||
never counted on. Cheer up; take comfort in knowing that people are
|
||||
testing your code and attempting to use it as a real world
|
||||
application. Download the problem media that people upload to the MPlayer
|
||||
FTP site and get back to work, implementing fixed code that addresses the
|
||||
issues. Contribute more patches and encourage people to hammer on your
|
||||
decoder even more. This is how you make your decoder rock-solid.
|
||||
|
||||
EOF
|
||||
Loading…
Reference in New Issue