[MPlayer-dev-eng] Documentation for codecs.conf file

[Mike Melanson]

Hi team
	I cobbled together a little document describing the specifics of
the etc/codecs.conf file. Please look it over and give some feedback on
format, details, anything. I think it would be useful for it to become
part of the MPlayer technical documentation. Some questions about
documentation:
1) Should it be included with the MPlayer documentation, or should I
maintain it on my own website?
2) If it is included in MPlayer, will I be able to access the file in CVS
in order to modify it?

	Thanks...
--
	-Mike Melanson

-------------- next part --------------
Understanding MPlayer's etc/codecs.conf File
by Mike Melanson (melanson at pcisys dot net)
v0.1: December 28, 2001

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 XAnim 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
it can't find a codecs.conf file, MPlayer will refuse to run.

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 there is no particular order 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.

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
  cpuflags mmx

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.

The next line has the keyword "info" which specifies a human-readable
comment accompanies this codec.

The "status" keyword carries information about the codec's functional
status. MPlayer currently recognizes 4 status levels: working, buggy,
crashing, and untested.

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're separated with a comma. There can also be multiple
fourcc lines in the codec.

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.

The "dll" keyword specifies which Win32 or XAnim binary module needs to be
loaded in order to handle the specific media type. This keyword is usually
only used in conjunction with the dshow, vfw, acm, and xanim drivers since
they all manage communication with binary-only modules.

The "guid" keyword identifies a 16-byte Microsoft GUID that some media
files use to identify codecs.

The "out" keyword identifies which output format that the decoder is known
to output. 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 "cpuflags" identifies special operating parameters that this codec
requires. For example, this video codec is known to use MMX
instructions. Currently, valid strings for this keyword include mmx, sse,
and 3dnow.

Audio Codecs
------------
Here is an example 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 accomodate 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 flag supported.

EOF