annotate DOCS/tech/codecs.conf.txt @ 35193:e5f3eeacf75f

Fix off-by-one error in check.

Understanding MPlayer's etc/codecs.conf File

Introduction
------------
MPlayer features a very flexible codec architecture which allows it to
use its own open source codecs, as well as open source libraries, Win32
codec DLLs and other binary codec modules. To the MPlayer user, the
most visible piece of this architecture is the etc/codecs.conf file. This
is a text-based configuration file that controls which MPlayer components
are in charge of handling particular compressed data formats.

The codecs.conf file is stored either in a shared directory for all system
users to access, or in the .mplayer directory in a user's home
directory. When MPlayer starts, it first looks for a codecs.conf file in a
user's home directory. Failing that, it searches for the shared file. If
no codecs.conf file is found MPlayer falls back on its internal hardcoded
configuration. If the file is present but has syntax errors, MPlayer will
report the error.

The codecs.conf file is really quite simple. It is simply a collection of
codec definition blocks that define how different media types should be
handled. There are a number of keywords that can occur in a block. Not all
of them are required and no particular order is enforced.

Editing codecs.conf
-------------------
You can edit codecs.conf using your favorite text editor. Anything that
comes after a semicolon (;) on a line is regarded as a comment. For
example:
; this is a comment
  format 0x34616d69  ; "ima4" (MOV files)

The codec blocks can be in any order; the file parser doesn't
care. However, they are organized in a particular order for the benefit of
human readers. For example, all of the open source decoders that MPlayer
implements natively are grouped in one section.

Release Number
--------------
Your codecs.conf now requires a release number to avoid codec release
incompatibilities. The format is simple: (YYYYMMDD)

release 20020520

Whenever changes are made to the codecs that *require* an updated
codecs.conf, then MPlayer will no longer accept outdated versions.
It is not recommended to change this line unless you know exactly
what you are doing.

Video Codecs
------------
Let's jump right in with an example. Here is an example video codec block:

videocodec indeo5ds
  info "Intel Indeo 5"
  status working
  fourcc IV50,iv50
  driver dshow
  dll "ir50_32.dll"
  guid 0x30355649, 0x0000, 0x0010, 0x80, 0x00, 0x00, 0xaa, 0x00, 0x38, 0x9b, 0x71
  out YV12
  out YUY2
  out BGR32,BGR24,BGR16,BGR15

This is a particularly full-featured video codec. The "videocodec" keyword
identifies the fact that this is the start of a new video
codec. "indeo5ds" is MPlayer's unique name for the codec. You have to use
this name with the -vc/-ac option.

The next line has the keyword "info" which specifies a human-readable
comment accompanying this codec. This is printed by -vc help / -ac help.

The "status" keyword carries information about the codec's functional
status. MPlayer currently recognizes 4 status levels: working, buggy,
crashing, and untested. When it gets to codec auto-selection, it tries
untested first (to force users to test it for us and report results :)),
then working and finally buggy ones. Codecs marked crashing won't be tried,
unless explicitly (-vc/-ac) selected.

The next line lists 4-character codes (FOURCCs) that are associated with
this codec. There can be more than one FOURCC specified on a fourcc line
as long as they are separated with a comma. There can also be multiple
fourcc lines in the codec. A second fourcc can also be given, separated
with a space. MPlayer will replace the original fourcc in the headers with
this one before opening the codec. It's useful for win32 codecs checking for
the fourccs.

The "driver" keyword associates this codec with an internal MPlayer
decoder module. MPlayer has a module named "dshow" that handles data
encoded by the codec. See -vfm help / -afm help for the available module list.

The "dll" keyword specifies which Win32/XAnim/Real/Quicktime binary
module needs to be loaded. It's also used to specify which FFmpeg codec
to load. The list of FFmpeg codecs can be found in libavcodec/allcodecs.c.

The "guid" keyword identifies a 16-byte Microsoft GUID that some media
files use to identify codecs. Used only for win32 dshow and DMO codecs.

The "out" keyword identifies which output format the decoder is known
to provide. Just like the fourcc line, there can be multiple out lines or
multiple comma-separated output formats on the same line. The output
formats should be listed in order of preference.

The outfmt values can be followed by one or more flags, like flip, noflip,
static, query. The flags are defined as follows:

"flip":
    If this flag is set for a given format, then o_bih->biHeight will NOT be
    set to -bih->biHeight, i.e. the image will be decoded upside-down.
    Used only by vfw and vfwex codecs.

"noflip":
    This flag is ignored (no effect) without "flip" being set!
    If this flag is set, it means the codec doesn't decode upside-down,
    although it's told to do so.

"yuvhack":
    This flag is required for the old win32 ms-mpeg4 vfw codecs, including
    MP42 and DIV3 (DivX 3.11). These DLLs actually support YUV formats,
    but the query/begin functions are buggy and don't accept YUV fourccs
    (the decode function accepts it and works well!)
    If this flag is set, then o_bih->biCompression will be set to 0 for
    the initialization for the YUV modes. Used only by vfw/vfwex codecs.

"query":
    This flag is used to control VDCTRL_QUERY_FORMAT for vfw/vfewx codecs.
    If this flag is set, the control() will query the codec for the csp
    support, otherwise it will assume a constant csp table. Required for
    some DLLs (like huffyuv, CRAM).

"static",
    This flag forces STATIC (instead of TEMP) buffer allocation for the codec.
    Used for some very old DLLs like Indeo 3 and for some XAnim codecs like
    cinepak. See dr-methods.txt for details on buffer types.

The "in" keyword -- UNDOCUMENTED

Audio Codecs
------------
Here is an example of a rather full-featured audio codec block:

audiocodec mp3
  info "MPEG layer-2, layer-3"
  status working
  comment "Optimized to MMX/SSE/3Dnow!"
  format 0x50
  format 0x55
  format 0x33706d2e  ; ".mp3" CBR/VBR MP3 (MOV files)
  format 0x5500736d  ; "ms\0\x55" older mp3 fcc (MOV files)
  driver mp3lib
  dll "mp3lib (mpglib)"
  flags seekable

Many of the keywords are the same as a video codec block. However, we see
a few that we haven't seen before. The "comment" keyword identifies
another human-readable note for this codec.

The "format" keyword performs a similar job as the fourcc line. However,
since certain media file formats (notably AVI) identify audio formats with
16-bit numbers rather than 32-bit FOURCCs, it's necessary to use this
convention to accommodate them. However, as shown in this example, FOURCCs
can also be specified with the format keyword as long as they're converted
to their hex representation. It's important to note that this can be
useful for video codecs as well if a FOURCC contains a space (such as
Apple's "rle " codec).

The "flags" keywords identifies any additional abilities of this
codec. Currently, seekable is the only supported flag.


Adding FFmpeg Codecs
-------------------
example codec:

videocodec ffmdec
  info "FFmpeg Sony PlayStation MDEC (Motion DECoder)"
  status working
  fourcc MDEC ; internal MPlayer FourCC
  driver ffmpeg
  dll mdec
  out YV12

The "videocodec" name should start with ff to differentiate it from other
libraries or binary codecs.

The "dll" name comes from the codec source file or the libavcodec/allcodecs.c
file.

The "out" colorspace can be found in the codec source file in the PIX_FMT
struct. Note that some codecs may have several pix_fmt structs.
The pix_fmt can be converted to the codecs.conf "out" format by reading
the fmt-conversion.c file.

If there are BE and LE versions of a pix_fmt, ignore them and use the short
native format instead. e.g. 422P16_LE becomes out 422P16. also to note that
underscores cause parse errors, so 422P16_LE becomes out 422P16LE.

libmpdemux/mp_taglists.c
--------------
Sometimes the lavf demuxer will not pass on a fourcc (mostly video game
formats or other containers that do not support isom/riff tags). You will have
to make one based on the codec_id listed in the codec source file.

Note that it is a good idea to mark any fourcc you create as
' ; internal MPlayer FourCC'. In case another codec uses that fourcc,
you can easily change the internal one. Also this will stop other projects
from thinking of the internal tag as a real fourcc found in the wild.

libmpdemux/demuxer.c
--------------
Some audio codecs require a parser, you can see which ones do
by reading the parsers section in libavcodec/allcodecs.c.

EOF