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

[Alex Beregszaszi]

Hi,

On Fri, Dec 28, 2001 at 02:51:34PM -0700, Mike Melanson wrote:
> 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?

Commit it under DOCS/tech, you've got write access to tech, and you will
able to modify it.

> 
> 	Thanks...
> --
> 	-Mike Melanson
> 

> 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