initial commit for codecs.conf.txt documentation

git-svn-id: svn://svn.mplayerhq.hu/mplayer/trunk@3861 b3059339-0415-0410-9bf9-f77b7e298cf2

1 files changed, 122 insertions, 0 deletions

diff --git a/DOCS/tech/codecs.conf.txt b/DOCS/tech/codecs.conf.txt
new file mode 100644
index 0000000000..0b91922c6e
--- /dev/null
+++ b/DOCS/tech/codecs.conf.txt
@@ -0,0 +1,122 @@
+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 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