DOCS/tech/codecs.conf.txt

   1 Understanding MPlayer's etc/codecs.conf File
   2
   3 Introduction
   4 ------------
   5 MPlayer features a very flexible codec architecture which allows it to
   6 use its own open source codecs, as well as open source libraries, Win32
   7 codec DLLs and other binary codec modules. To the MPlayer user, the
   8 most visible piece of this architecture is the etc/codecs.conf file. This
   9 is a text-based configuration file that controls which MPlayer components
  10 are in charge of handling particular compressed data formats.
  11
  12 The codecs.conf file is stored either in a shared directory for all system
  13 users to access, or in the .mplayer directory in a user's home
  14 directory. When MPlayer starts, it first looks for a codecs.conf file in a
  15 user's home directory. Failing that, it searches for the shared file. If
  16 no codecs.conf file is found MPlayer falls back on its internal hardcoded
  17 configuration. If the file is present but has syntax errors, MPlayer will
  18 report the error.
  19
  20 The codecs.conf file is really quite simple. It is simply a collection of
  21 codec definition blocks that define how different media types should be
  22 handled. There are a number of keywords that can occur in a block. Not all
  23 of them are required and no particular order is enforced.
  24
  25 Editing codecs.conf
  26 -------------------
  27 You can edit codecs.conf using your favorite text editor. Anything that
  28 comes after a semicolon (;) on a line is regarded as a comment. For
  29 example:
  30 ; this is a comment
  31   format 0x34616d69  ; "ima4" (MOV files)
  32
  33 The codec blocks can be in any order; the file parser doesn't
  34 care. However, they are organized in a particular order for the benefit of
  35 human readers. For example, all of the open source decoders that MPlayer
  36 implements natively are grouped in one section.
  37
  38 Release Number
  39 --------------
  40 Your codecs.conf now requires a release number to avoid codec release
  41 incompatibilities. The format is simple: (YYYYMMDD)
  42
  43 release 20020520
  44
  45 Whenever changes are made to the codecs that *require* an updated
  46 codecs.conf, then MPlayer will no longer accept outdated versions.
  47 It is not recommended to change this line unless you know exactly
  48 what you are doing.
  49
  50 Video Codecs
  51 ------------
  52 Let's jump right in with an example. Here is an example video codec block:
  53
  54 videocodec indeo5ds
  55   info "Intel Indeo 5"
  56   status working
  57   fourcc IV50,iv50
  58   driver dshow
  59   dll "ir50_32.dll"
  60   guid 0x30355649, 0x0000, 0x0010, 0x80, 0x00, 0x00, 0xaa, 0x00, 0x38, 0x9b, 0x71
  61   out YV12
  62   out YUY2
  63   out BGR32,BGR24,BGR16,BGR15
  64
  65 This is a particularly full-featured video codec. The "videocodec" keyword
  66 identifies the fact that this is the start of a new video
  67 codec. "indeo5ds" is MPlayer's unique name for the codec. You have to use
  68 this name with the -vc/-ac option.
  69
  70 The next line has the keyword "info" which specifies a human-readable
  71 comment accompanying this codec. This is printed by -vc help / -ac help.
  72
  73 The "status" keyword carries information about the codec's functional
  74 status. MPlayer currently recognizes 4 status levels: working, buggy,
  75 crashing, and untested. When it gets to codec auto-selection, it tries
  76 untested first (to force users to test it for us and report results :)),
  77 then working and finally buggy ones. Codecs marked crashing won't be tried,
  78 unless explicitly (-vc/-ac) selected.
  79
  80 The next line lists 4-character codes (FOURCCs) that are associated with
  81 this codec. There can be more than one FOURCC specified on a fourcc line
  82 as long as they are separated with a comma. There can also be multiple
  83 fourcc lines in the codec. A second fourcc can also be given, separated
  84 with a space. MPlayer will replace the original fourcc in the headers with
  85 this one before opening the codec. It's useful for win32 codecs checking for
  86 the fourccs.
  87
  88 The "driver" keyword associates this codec with an internal MPlayer
  89 decoder module. MPlayer has a module named "dshow" that handles data
  90 encoded by the codec. See -vfm help / -afm help for the available module list.
  91
  92 The "dll" keyword specifies which Win32/XAnim/Real/Quicktime binary
  93 module needs to be loaded. It's also used to specify which FFmpeg codec
  94 to load. The list of FFmpeg codecs can be found in libavcodec/allcodecs.c.
  95
  96 The "guid" keyword identifies a 16-byte Microsoft GUID that some media
  97 files use to identify codecs. Used only for win32 dshow and DMO codecs.
  98
  99 The "out" keyword identifies which output format the decoder is known
 100 to provide. Just like the fourcc line, there can be multiple out lines or
 101 multiple comma-separated output formats on the same line. The output
 102 formats should be listed in order of preference.
 103
 104 The outfmt values can be followed by one or more flags, like flip, noflip,
 105 static, query. The flags are defined as follows:
 106
 107 "flip":
 108     If this flag is set for a given format, then o_bih->biHeight will NOT be
 109     set to -bih->biHeight, i.e. the image will be decoded upside-down.
 110     Used only by vfw and vfwex codecs.
 111
 112 "noflip":
 113     This flag is ignored (no effect) without "flip" being set!
 114     If this flag is set, it means the codec doesn't decode upside-down,
 115     although it's told to do so.
 116
 117 "yuvhack":
 118     This flag is required for the old win32 ms-mpeg4 vfw codecs, including
 119     MP42 and DIV3 (DivX 3.11). These DLLs actually support YUV formats,
 120     but the query/begin functions are buggy and don't accept YUV fourccs
 121     (the decode function accepts it and works well!)
 122     If this flag is set, then o_bih->biCompression will be set to 0 for
 123     the initialization for the YUV modes. Used only by vfw/vfwex codecs.
 124
 125 "query":
 126     This flag is used to control VDCTRL_QUERY_FORMAT for vfw/vfewx codecs.
 127     If this flag is set, the control() will query the codec for the csp
 128     support, otherwise it will assume a constant csp table. Required for
 129     some DLLs (like huffyuv, CRAM).
 130
 131 "static",
 132     This flag forces STATIC (instead of TEMP) buffer allocation for the codec.
 133     Used for some very old DLLs like Indeo 3 and for some XAnim codecs like
 134     cinepak. See dr-methods.txt for details on buffer types.
 135
 136 The "in" keyword -- UNDOCUMENTED
 137
 138 Audio Codecs
 139 ------------
 140 Here is an example of a rather full-featured audio codec block:
 141
 142 audiocodec mp3
 143   info "MPEG layer-2, layer-3"
 144   status working
 145   comment "Optimized to MMX/SSE/3Dnow!"
 146   format 0x50
 147   format 0x55
 148   format 0x33706d2e  ; ".mp3" CBR/VBR MP3 (MOV files)
 149   format 0x5500736d  ; "ms\0\x55" older mp3 fcc (MOV files)
 150   driver mp3lib
 151   dll "mp3lib (mpglib)"
 152   flags seekable
 153
 154 Many of the keywords are the same as a video codec block. However, we see
 155 a few that we haven't seen before. The "comment" keyword identifies
 156 another human-readable note for this codec.
 157
 158 The "format" keyword performs a similar job as the fourcc line. However,
 159 since certain media file formats (notably AVI) identify audio formats with
 160 16-bit numbers rather than 32-bit FOURCCs, it's necessary to use this
 161 convention to accommodate them. However, as shown in this example, FOURCCs
 162 can also be specified with the format keyword as long as they're converted
 163 to their hex representation. It's important to note that this can be
 164 useful for video codecs as well if a FOURCC contains a space (such as
 165 Apple's "rle " codec).
 166
 167 The "flags" keywords identifies any additional abilities of this
 168 codec. Currently, seekable is the only supported flag.
 169
 170
 171 Adding FFmpeg Codecs
 172 -------------------
 173 example codec:
 174
 175 videocodec ffmdec
 176   info "FFmpeg Sony PlayStation MDEC (Motion DECoder)"
 177   status working
 178   fourcc MDEC ; internal MPlayer FourCC
 179   driver ffmpeg
 180   dll mdec
 181   out YV12
 182
 183 The "videocodec" name should start with ff to differentiate it from other
 184 libraries or binary codecs.
 185
 186 The "dll" name comes from the codec source file or the libavcodec/allcodecs.c
 187 file.
 188
 189 The "out" colorspace can be found in the codec source file in the PIX_FMT
 190 struct. Note that some codecs may have several pix_fmt structs.
 191 The pix_fmt can be converted to the codecs.conf "out" format by reading
 192 the fmt-conversion.c file.
 193
 194 If there are BE and LE versions of a pix_fmt, ignore them and use the short
 195 native format instead. e.g. 422P16_LE becomes out 422P16. also to note that
 196 underscores cause parse errors, so 422P16_LE becomes out 422P16LE.
 197
 198 libmpdemux/mp_taglists.c
 199 --------------
 200 Sometimes the lavf demuxer will not pass on a fourcc (mostly video game
 201 formats or other containers that do not support isom/riff tags). You will have
 202 to make one based on the codec_id listed in the codec source file.
 203
 204 Note that it is a good idea to mark any fourcc you create as
 205 ' ; internal MPlayer FourCC'. In case another codec uses that fourcc,
 206 you can easily change the internal one. Also this will stop other projects
 207 from thinking of the internal tag as a real fourcc found in the wild.
 208
 209 libmpdemux/demuxer.c
 210 --------------
 211 Some audio codecs require a parser, you can see which ones do
 212 by reading the parsers section in libavcodec/allcodecs.c.
 213
 214 EOF